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

启用 --override 后，签名结果会直接写回输入文件。

在自动化构建环境中使用时，应确认后续步骤需要的是原始文件还是签名后的文件。

指定程序描述

可以将程序描述和 URL 写入 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=

有关时间戳协议、服务器地址及选择建议，请参阅 参考资料。

查询签名额度

使用：

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

安装桌面客户端

安装 sslTrus 代码签名桌面客户端：

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

El nombre correspondiente del Cask de Homebrew es:

code-sign-gui

更新客户端

如果客户端通过 Homebrew 安装，建议使用 Homebrew 进行升级。

先更新 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

这样可以使本地安装版本与 Homebrew 软件包元数据保持一致。

Windows Provider

如果你的场景不是直接调用 SignTool CLI，而是希望 Microsoft SignTool、Visual Studio、MSBuild、Advanced Installer 或其他 Windows 软件直接使用远程代码签名私钥，应使用 Windows Provider。

sslTrus 提供：

• KSP（Key Storage Provider）：面向 Windows CNG。
• CSP（Cryptographic Service Provider）：面向传统 Windows CryptoAPI。

请参阅 Windows Provider。

CI/CD 自动签名

如果需要在持续集成或自动构建过程中执行签名，不一定需要手动安装和调用 SignTool CLI。

例如 GitHub Actions 可以直接使用 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.