Herramientas del Cliente

sslTrus ofrece un cliente de línea de comandos y un cliente de escritorio para conectarse al servicio de firma de código remoto 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 para firma de código remoto proporcionado por sslTrus. Después de la instalación, el nombre del archivo ejecutable es signtool.

Principalmente ofrece las siguientes capacidades:

Función	Comando	Descripción
Firma de archivos	signtool sign	Realiza firma de código remoto en archivos locales
Cuota de firma	signtool quota	Consulta la cuota restante y total de firma del certificado
Actualización del cliente	signtool update	Consulta e instala el cliente más reciente para la plataforma actual
KSP de Windows	signtool ksp	Instala y gestiona el Proveedor de Almacenamiento de Claves de Windows
CSP de Windows	signtool csp	Instala y gestiona el Proveedor de Servicios Criptográficos de Windows

KSP y CSP pertenecen a los métodos de integración del Proveedor de Windows. Para instrucciones de uso específicas, consulte Windows Provider.

Descargar el cliente

SignTool CLI se puede descargar desde la página de publicación de clientes de sslTrus:

Página de publicación de clientes de sslTrus

La página de publicaciones ofrece los paquetes de instalación de clientes más recientes para cada plataforma. Los escenarios automatizados también pueden 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 mediante Homebrew, consulte macOS Homebrew a continuación.

Ver información del cliente

Una vez completada la instalación, puede ejecutar:

signtool --help

Ver la ayuda del comando.

Ver la versión actual del cliente:

signtool --version

La información de versión incluye la versión del cliente, la revisión de compilación, la plataforma de ejecución y la hora de compilación, entre otros datos.

Credenciales de acceso

Antes de utilizar el servicio de firma de código remoto, debe preparar:

• Access Key
• Access Secret
• Cert Code（Cert Code）

Entre ellos, Access Key y Access Secret se utilizan para acceder al servicio de firma de código remoto, y Cert Code se utiliza para especificar el certificado de firma de código que realmente ejecuta la firma.

SignTool CLI puede proporcionar credenciales mediante parámetros de comando o leerlas a través de variables de entorno:

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

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

No debe hacer lo siguiente con el Access Secret:

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

Dirección del servicio remoto

De forma predeterminada, la CLI de SignTool 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 agregar --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

Usando signtool sign se puede realizar la firma de código remota directamente en archivos locales.

El comando de firma más básico:

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

Si ya se ha configurado:

ACCESS_KEY
ACCESS_SECRET

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

De forma predeterminada, la firma se realiza con SHA-2.

Especificar archivo de salida

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

Se 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 utilizar:

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

Tras activar --override, el resultado de la firma se escribe directamente en el archivo de entrada.

Al utilizarlo en un entorno de compilación automatizada, confirme si los pasos posteriores necesitan el archivo original o el archivo firmado.

Especificar la descripción del programa

Puede incluir la descripción del programa y una 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 usa SHA-1:

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

Habilitando 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 compatibilidad con sistemas antiguos; en proyectos nuevos, normalmente debería priorizarse SHA-2.

Marca de tiempo

En la firma de código, se suele recomendar agregar también una marca de tiempo confiable.

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

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

Para especificar un servidor de marca de tiempo RFC 3161:

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

Especificar el servidor de sello 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 establecer el valor del parámetro en vacío:

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

Para obtener información sobre los protocolos de sellado de tiempo, las direcciones de los servidores y las recomendaciones de selección, consulte las Referencias.

Consultar la cuota de firmas

Utilice:

signtool quota

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

El contenido de salida incluye:

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

Si necesita salida en formato JSON:

signtool quota --json

También se puede usar la forma abreviada:

signtool quota -j

El número específico de cálculos de firmas puede variar según el método de invocación de CLI, KSP, Jarsigner o herramientas de compilación. Para obtener reglas detalladas, consulte Explicación del cálculo de firmas.

Actualizar el cliente

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

signtool update

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

Si SignTool CLI se instaló mediante Homebrew, se recomienda continuar gestionando la versión a través de Homebrew, en lugar de combinar ambos métodos de actualización.

macOS Homebrew

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

Repositorio público: ssltrus-official/homebrew-tap

Instalar el Tap de Homebrew

Ejecute:

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

Una vez completado, se podrá instalar el cliente correspondiente.

Instalación de SignTool CLI

Ejecute:

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

Una vez completada la instalación, puede ejecutar:

signtool --version

Verifique si el cliente está instalado correctamente.

El nombre del paquete en Homebrew es:

code-sign-cli

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

signtool

Instalar el cliente de escritorio

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

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

El nombre correspondiente del Cask de Homebrew 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

Actualice el cliente de escritorio:

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

De este modo, la versión instalada localmente se mantiene sincronizada con los metadatos del paquete de Homebrew.

Windows Provider

Si no desea invocar directamente la CLI de SignTool, sino permitir que Microsoft SignTool, Visual Studio, MSBuild, Advanced Installer u otro programa de Windows utilice directamente la clave privada remota de firma de código, debe utilizar Windows Provider.

sslTrus proporciona:

• KSP (Key Storage Provider): para Windows CNG.
• CSP (Cryptographic Service Provider): para la interfaz tradicional Windows CryptoAPI.

Consulte Windows Provider.

Firma automática en CI/CD

Para firmar durante la integración continua o las compilaciones automatizadas, no siempre es necesario instalar e invocar manualmente la CLI de SignTool.

Por ejemplo, GitHub Actions puede utilizar 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 admite runners de Linux, macOS y Windows, y puede realizar firmas remotas de código directamente sobre archivos específicos dentro del flujo de compilación.

Repositorio público: ssltrus-official/code-sign-action

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

Cómo elegir

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

Escenario	Método recomendado
Firmar archivos manualmente en la terminal	CLI de SignTool
Llamar a la firma en lote mediante scripts	CLI de SignTool
Consultar el saldo de firmas de código	CLI de SignTool
Instalar y actualizar el CLI en macOS	Homebrew
Usar el cliente de escritorio en macOS	Homebrew
Llamar directamente a la clave privada remota desde software de Windows como Microsoft SignTool	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 admite Windows KSP, CSP u otros proveedores estándar, normalmente debería priorizar el uso del método de integración estándar correspondiente; si necesita controlar directamente el flujo de firma, puede usar la CLI de SignTool o la API de firma de código remota.