Referencia del comando signtool sign

Nota

En este documento, signtool se refiere al cliente CLI de firma remota de código de sslTrus, no al signtool.exe incluido en el Windows SDK de Microsoft. Cuando se utiliza la herramienta del SDK de Windows, se indicará explícitamente como Microsoft signtool.exe.

signtool sign realiza la firma remota directamente sobre el archivo local. La CLI extrae los datos a firmar localmente, invoca el servicio remoto para completar la firma con la clave privada y, a continuación, escribe la firma, la marca de tiempo y la información del certificado en el archivo de salida.

signtool sign [flags]

Ver ayuda y versión:

signtool --help
signtool --version

---

Configuración de credenciales

El comando sign lee las credenciales de acceso de la siguiente manera:

Elemento de credencial	Parámetro	Variable de entorno	Descripción
Access Key	--access-key / -k	ACCESS_KEY	Cuando el parámetro está vacío, la variable de entorno se lee automáticamente
Access Secret	--access-secret / -s	ACCESS_SECRET	Cuando el parámetro está vacío, la variable de entorno se lee automáticamente

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

Dirección de servicio remoto está controlada por el parámetro --address y admite los siguientes valores:

Valor del parámetro	Dirección de servicio real
nicsrs	https://ssl.face.nicsrs.com
Valor vacío, racent u otro valor arbitrario	https://ssl.face.racent.com

Nota

• ACCESS_KEY y ACCESS_SECRET son los nombres de variables de entorno que se leen realmente; SIGNTOOL_ACCESS_KEY / SIGNTOOL_ACCESS_SECRET no se leen automáticamente por el CLI actual.
• No se recomienda escribir el Access Secret en el historial de shell o en el repositorio de scripts; priorice el uso de variables de entorno inyectadas en tiempo de ejecución o variables seguras de CI.

---

Descripción de parámetros

Parámetro	Abreviatura	Valor predeterminado	Descripción
--address	-a	Vacío	Identificador de la dirección del servicio remoto, no es un parámetro de transmisión de URL.
--access-key	-k	Vacío	Si está vacío, se lee ACCESS_KEY.
--access-secret	-s	Vacío	Si está vacío, se lee ACCESS_SECRET.
--cert-code	-c	Vacío	Requerido. Número de certificado.
--file	-f	空	Obligatorio. Ruta del archivo a firmar; no puede ser un directorio.
--out	-o	空	Ruta del archivo de salida; si está vacía y no se habilita la sobrescritura, se genera automáticamente un nombre de archivo predeterminado.
--override	—	false	Sobrescribe el archivo original con el archivo de salida.
--sha1	-1	false	Habilitar firma SHA1.
--sha2	-2	true	Habilitar firma SHA2.
--timestamp	—	auto	Dirección de sello de tiempo Authenticode SHA1. auto usa la dirección predeterminada; una cadena vacía la desactiva.
--timestamp-rfc3161	—	auto	Dirección de sello de tiempo RFC3161 SHA2. auto usa la dirección predeterminada; una cadena vacía la desactiva.
--desc	-n	Vacío	Texto de descripción del programa escrito en la firma.
--url	-u	空	URL de información del programa para escribir la firma.
--nest	—	true	Conserva la firma existente y agrega una firma anidada; cuando false, se elimina la firma existente.
--verify	—	false	Al agregar una firma, si el certificado no es de confianza, se devuelve un error.
--dry-run	—	false	Utiliza un certificado de prueba local para generar la firma, sin llamar a la interfaz de firma remota.

Formato de parámetros booleanos

Los parámetros booleanos deben usar el formato 参数=值, no se admite la separación por espacios:

• Correcto: --sha1=true --sha2=false
• Incorrecto: --sha1 true --sha2 false

Reglas obligatorias

Antes de la ejecución se verifican las siguientes condiciones; si alguna no se cumple, se reporta un error y se sale:

• --access-key o ACCESS_KEY deben existir.
• --access-secret o ACCESS_SECRET deben existir.
• --cert-code debe existir.
• --file debe existir y no puede ser un directorio.
• --sha1 y --sha2 deben estar habilitados al menos uno.

---

Reglas de archivos de salida

Cuando no se especifica --out:

--override	Comportamiento de salida
false（默认）	输出到输入文件同目录，文件名为 ${name}.signed.${yyyyMMdd.HHmmss}${ext}
true	直接覆盖输入文件

Ejemplo:

app.exe    → app.signed.20260611.153000.exe
driver.sys → driver.signed.20260611.153000.sys

注意

--override=true 覆盖原文件，执行前请确认已备份。签名失败时 CLI 会尽量删除未完成的输出文件。

---

Selección de algoritmo

Por defecto solo se habilita SHA2:

signtool sign -c CERT_CODE -f app.exe

Solo firma SHA1:

signtool sign -c CERT_CODE -f app.exe --sha1=true --sha2=false

Al mismo tiempo, firma SHA1 y SHA2:

signtool sign -c CERT_CODE -f app.exe --sha1=true --sha2=true

Nota

Cuando SHA1 y SHA2 están habilitados simultáneamente, el flujo procesa primero SHA1 y luego SHA2. SHA1 todavía es compatible, pero para nuevos escenarios de firma se prefiere SHA2.

---

Configuración de sello de tiempo

Los valores de auto en --timestamp y --timestamp-rfc3161 se reemplazan por la dirección predeterminada durante la fase de verificación:

Parámetro	Valor real de auto	Uso
--timestamp	http://timestamp.sectigo.com	Sello de tiempo SHA1 Authenticode
--timestamp-rfc3161	http://timestamp.sectigo.com	Sello de tiempo SHA2 RFC3161

Servicio personalizado de sello de tiempo SHA2:

signtool sign \
  -c CERT_CODE \
  -f app.exe \
  --timestamp-rfc3161=http://timestamp.acs.microsoft.com

Desactivar la marca de tiempo SHA2:

signtool sign -c CERT_CODE -f app.exe --timestamp-rfc3161=

关闭全部时间戳：

signtool sign -c CERT_CODE -f app.exe --timestamp= --timestamp-rfc3161=

说明

• 只有以 http 开头的时间戳地址才会被使用。
• SHA1 优先使用 --timestamp；若它不是 HTTP 地址，则尝试使用 --timestamp-rfc3161。
• SHA2 使用 --timestamp-rfc3161。
• SHA2 添加时间戳失败时，会在 Microsoft 和 Sectigo 默认地址之间自动重试一次。
• 时间戳失败不会必然导致签名失败，CLI 会记录错误并保留未加时间戳的签名结果。

---

Ejemplos comunes

Uso de variables de entorno para proporcionar credenciales, firma SHA2 predeterminada:

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

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

使用参数直接提供凭证：

signtool sign \
  --access-key "your-access-key" \
  --access-secret "your-access-secret" \
  --cert-code CERT_CODE \
  --file app-unsigned.exe \
  --out app-signed.exe

Usando la dirección NICSRS:

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

Escribir la descripción del programa y la URL del sitio web oficial:

signtool sign \
  -c CERT_CODE \
  -f app-unsigned.exe \
  -o app-signed.exe \
  --desc "Example Application" \
  --url "https://example.com"

Agregar firma anidada (conservar la firma existente):

signtool sign -c CERT_CODE -f app.exe --nest=true

覆盖原文件：

signtool sign -c CERT_CODE -f app.exe --override=true

dry-run prueba de firma local (sin llamar a la interfaz remota):

signtool sign \
  -k dummy \
  -s dummy \
  -c CERT_CODE \
  -f app.exe \
  --dry-run=true

说明

--dry-run no llama a la interfaz de firma remota, pero aún así leerá y escribirá archivos locales y llamará al certificado autofirmado local. Actualmente aún pasará por la validación de no vacío de las credenciales y el número de certificado, por lo que en el ejemplo se utilizan credenciales de marcador de posición.

---

Referencia de resolución de problemas

Mensaje de error	Causa posible	Sugerencia de manejo
access key is required...	No se pasó --access-key, ni se configuró ACCESS_KEY.	Configure la variable de entorno o use -k.
access secret is required...	No se pasó --access-secret ni se configuró ACCESS_SECRET.	Configure la variable de entorno o use -s.
cert code is required...	No se pasó el número de certificado.	Use -c CERT_CODE.
sha1 or sha2 is required...	SHA1 y SHA2 están desactivados al mismo tiempo.	Habilite al menos un algoritmo.
file <path> is a directory	--file apunta a un directorio en lugar de un archivo.	Cambie a la ruta del archivo a firmar.
La marca de tiempo falla pero el archivo de firma se ha generado	El servicio de marca de tiempo no está disponible o la verificación de la cadena de certificados falla.	Verifique la URL de marca de tiempo y, si es necesario, reemplace --timestamp-rfc3161.