Herramientas de cliente

sslTrus ofrece un cliente de línea de comandos y un cliente de escritorio para conectarse al servicio remoto de firma de código y completar la firma de archivos.

Entre ellos, SignTool CLI es adecuado para escenarios de línea de comandos, scripts y automatización; los usuarios de macOS también pueden instalar y actualizar SignTool CLI o el cliente de escritorio mediante Homebrew.

SignTool CLI

SignTool CLI es el cliente de línea de comandos de firma de código remota proporcionado por sslTrus. El nombre del archivo ejecutable después de la instalación es signtool.

Ofrece principalmente las siguientes capacidades:

Función	Comando	Descripción
Firma de archivos	signtool sign	Realiza la firma de código remota en archivos locales
Cuota de firma	signtool quota	Consulta la cuota de firma restante y total del certificado
Actualización del cliente	signtool update	Consulta e instala la última versión del cliente para la plataforma actual
Windows KSP	signtool ksp	Instala y administra Windows Key Storage Provider
Windows CSP	signtool csp	Instala y administra Windows Cryptographic Service Provider

KSP y CSP pertenecen al método de integración de Windows Provider. Para conocer los métodos de uso específicos, consulte Windows Provider.

Descargar el cliente

SignTool CLI se puede descargar desde la página de lanzamiento del cliente de sslTrus:

Página de lanzamiento del cliente de sslTrus

La página de lanzamientos ofrece los paquetes de instalación más recientes del cliente para cada plataforma. En escenarios de automatización, también puede consultar la información de la versión más reciente a través del índice de versiones latest.json.

Los usuarios de macOS también pueden instalarlo directamente a través de Homebrew; consulte macOS Homebrew a continuación.

Ver la información del cliente

Una vez completada la instalación, puede ejecutar:

signtool --help

Vea la ayuda del comando.

Compruebe la versión actual del cliente:

signtool --version

Información de versión incluye versión del cliente, revisión de compilación, plataforma de ejecución y tiempo de compilación, entre otros.

Credenciales de acceso

Antes de usar el servicio de firma de código remota, es necesario preparar:

• Access Key
• Access Secret
• Número de certificado (Cert Code)

El Access Key y el Access Secret se utilizan para acceder al servicio de firma de código remota, y el número de certificado se utiliza para especificar el certificado de firma de código que realmente ejecutará la firma.

SignTool CLI puede proporcionar las credenciales mediante parámetros de comando, o también puede leerlas desde variables de entorno:

export ACCESS_KEY="your-access-key"
export ACCESS_SECRET="your-access-secret"

Se recomienda proporcionar el Access Secret prioritariamente mediante variables de entorno, CI/CD Secret u otros métodos seguros de gestión de credenciales.

No haga lo siguiente con el Access Secret:

• Subirlo a un repositorio Git.
• Escribirlo en scripts públicos.
• Imprimirlo en los registros de compilación.
• Enviarlo a sistemas de terceros no confiables.

Dirección del servicio remoto

De forma predeterminada, SignTool CLI utiliza la dirección del servicio de producción de sslTrus, sin necesidad de configuración adicional.

Si utiliza el entorno NICSRS (www.nicsrs.com), debe añadir --address nicsrs al comando:

signtool sign \
  --address nicsrs \
  --cert-code CERT_CODE \
  --file app.exe

signtool quota y signtool update también admiten --address nicsrs.

Firma de archivos

Puede usar signtool sign para realizar directamente la firma de código remota en archivos locales.

Comando de firma más básico:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe

Si ya está configurado:

ACCESS_KEY
ACCESS_SECRET

SignTool CLI leerá automáticamente las credenciales de acceso correspondientes.

De forma predeterminada, se utiliza SHA-2 para ejecutar la firma.

Especificar el archivo de salida

De forma predeterminada, el cliente no sobrescribe directamente el archivo original.

Puede especificar el archivo de salida después de la firma mediante --out：

signtool sign \
  --cert-code CERT_CODE \
  --file app-unsigned.exe \
  --out app-signed.exe

Sobrescribir el archivo original

Si necesita modificar directamente el archivo original, puede usar:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --override=true

Después de habilitar --override, el resultado de la firma se escribirá directamente en el archivo de entrada.

Al utilizarlo en un entorno de compilación automatizada, debe confirmar si los pasos siguientes requieren el archivo original o el archivo firmado.

Especificar la descripción del programa

Puede escribir la descripción del programa y la URL en la firma Authenticode:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --desc "Example Application" \
  --url "https://example.com"

SHA-1 y SHA-2

SHA-2 está habilitado por defecto:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe

Solo usar SHA-1:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --sha1=true \
  --sha2=false

Habilite SHA-1 y SHA-2 al mismo tiempo:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --sha1=true \
  --sha2=true

SHA-1 se utiliza principalmente para la compatibilidad con sistemas antiguos; los proyectos nuevos generalmente deberían priorizar SHA-2.

Marca de tiempo

En la firma de código, normalmente se recomienda añadir también una marca de tiempo confiable.

SignTool CLI configura automáticamente el servicio de marca de tiempo para la firma de forma predeterminada, aunque también se puede especificar el servidor de marca de tiempo mediante parámetros:

• --timestamp-rfc3161: servidor de marca de tiempo RFC 3161 utilizado para firmas SHA-2.
• --timestamp: servidor de marca de tiempo Authenticode utilizado para firmas SHA-1.

Especificar el servidor de marca de tiempo RFC 3161:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --timestamp-rfc3161=http://timestamp.acs.microsoft.com

Especifique el servidor de sellado de tiempo Authenticode:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --timestamp=http://timestamp.sectigo.com

Si necesita desactivar la marca de tiempo correspondiente, puede dejar el valor del parámetro vacío:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --timestamp-rfc3161= \
  --timestamp=

Para conocer el protocolo de marca de tiempo, la dirección del servidor y las recomendaciones de selección, consulte Recursos de referencia.

Consultar el saldo de firmas

Uso:

signtool quota

Puede consultar la cuota de certificados de firma de código visibles para la credencial de acceso actual.

El contenido de salida incluye:

• Número de certificado.
• Información del certificado.
• Número restante de firmas.
• Número total de firmas.

Si se necesita salida en formato JSON:

signtool quota --json

También se puede utilizar la forma abreviada:

signtool quota -j

La forma específica de calcular el número de firmas puede variar según cómo se invoque la CLI, KSP, Jarsigner o la herramienta de compilación. Para conocer las reglas detalladas, consulte Explicación del cálculo del número de firmas.

Actualizar el cliente

SignTool CLI permite consultar e instalar la versión más reciente para la plataforma actual:

signtool update

Durante el proceso de actualización, se verificará el tamaño y el SHA-256 del archivo descargado para confirmar la integridad del archivo del cliente.

Si SignTool CLI se instaló mediante Homebrew, se recomienda continuar gestionando las versiones a través de Homebrew, en lugar de combinar dos métodos de actualización al mismo tiempo.

macOS Homebrew

Los usuarios de macOS pueden instalar SignTool CLI o el cliente de escritorio a través del Homebrew Tap oficial de sslTrus.

Instalar Homebrew Tap

Ejecute:

brew tap ssltrus-official/tap
brew trust ssltrus-official/tap

Una vez completado, puede instalar el cliente correspondiente.

Instalar SignTool CLI

Ejecute:

brew install ssltrus-official/tap/code-sign-cli

Después de completar la instalación, puede ejecutar:

signtool --version

Confirme que el cliente se ha instalado correctamente.

El nombre del paquete en Homebrew es:

code-sign-cli

El nombre del programa de línea de comandos que se instala realmente es:

signtool

Instalar el cliente de escritorio

Instale el cliente de escritorio de firma de código sslTrus:

brew install --cask ssltrus-official/tap/code-sign-gui

El nombre del Cask de Homebrew correspondiente es:

code-sign-gui

Actualizar el cliente

Si el cliente se instaló mediante Homebrew, se recomienda actualizarlo con Homebrew.

Primero, actualice la información de los paquetes de Homebrew:

brew update

Actualice SignTool CLI:

brew upgrade ssltrus-official/tap/code-sign-cli

Actualizar el cliente de escritorio:

brew upgrade --cask ssltrus-official/tap/code-sign-gui

Así, la instalación local se mantiene coherente con los metadatos del paquete de Homebrew.

Windows Provider

Si tu escenario no consiste en invocar directamente la CLI de SignTool, sino que deseas que Microsoft SignTool, Visual Studio, MSBuild, Advanced Installer u otro software de Windows utilice directamente la clave privada de firma de código remota, debes usar Windows Provider.

sslTrus ofrece:

• KSP (Key Storage Provider): orientado a Windows CNG.
• CSP (Cryptographic Service Provider): orientado a la CryptoAPI tradicional de Windows.

Consulta Windows Provider.

Firma automática en CI/CD

Si necesitas ejecutar la firma durante la integración continua o el proceso de compilación automática, no es necesario instalar e invocar manualmente la CLI de SignTool.

Por ejemplo, GitHub Actions puede usar directamente sslTrus Code Sign Action:

- name: Sign files
  uses: ssltrus-official/code-sign-action@v1
  with:
    access-key: ${{ secrets.SSLTRUS_ACCESS_KEY }}
    access-secret: ${{ secrets.SSLTRUS_ACCESS_SECRET }}
    cert-code: ${{ secrets.SSLTRUS_CERT_CODE }}
    files: build/app.exe

GitHub Action es compatible con runners de Linux, macOS y Windows, y permite realizar la firma de código remota directamente sobre los archivos especificados dentro del flujo de compilación.

Para la configuración completa, consulte CI/CD y herramientas de compilación.

Cómo elegir

Puede seleccionar el cliente o método de integración adecuado según su forma de uso:

Escenario	Método recomendado
Firmar archivos manualmente en la terminal	SignTool CLI
Usar scripts para invocar la firma en lote	SignTool CLI
Consultar el saldo de firma de código	SignTool CLI
Instalar y actualizar la CLI en macOS	Homebrew
Usar el cliente de escritorio en macOS	Homebrew
Software de Windows como Microsoft SignTool que invoca directamente la clave privada remota	KSP
Software tradicional de CryptoAPI	CSP
Firma automática en GitHub Actions	GitHub Actions
Desarrollar su propio cliente de firma	API de firma de código remota

Si su aplicación ya es compatible con Windows KSP, CSP u otros proveedores estándar, normalmente debe priorizar el uso del método de integración estándar correspondiente; si necesita controlar directamente el flujo de firma, puede usar SignTool CLI o la API de firma de código remota.