Integración de signtool ksp con Windows KSP

signtool ksp gestiona el sslTrus Key Storage Provider de Windows (KSP). Una vez que KSP está instalado y configurado, Microsoft signtool.exe puede invocar el servicio de firma remota a través del Proveedor CNG, sin necesidad de mantener la clave privada localmente.

Nota

Todos los subcomandos de signtool ksp solo son compatibles con la plataforma Windows. Ejecutar cualquier subcomando de ksp en una plataforma que no sea Windows devolverá: key storage provider is only supported on windows

---

Resumen de subcomandos

signtool ksp [command]

Subcomando	Uso
install	Instala y registra la DLL de KSP
uninstall	Anula el registro de KSP y elimina la DLL
list	Lista las configuraciones de claves KSP guardadas
add	Agrega una configuración de clave KSP (interactivo)
del	Elimina una configuración de clave KSP específica (interactivo)

Nota

El parámetro --address solo es válido cuando se usa ksp add, y se utiliza para obtener el PEM del certificado y guardar la dirección del servicio remoto.

---

Instalar KSP

signtool ksp install

Después de la ejecución:

1. Escribir el sslTrusKSP.dll incrustado en ProgramData/sslTrusKSP/sslTrusKSP.dll.
2. Si la versión de la DLL en ProgramData es diferente a la de System32, copiar la DLL a System32.
3. Registrar el Proveedor CNG: sslTrus Key Storage Provider.
4. Guardar el archivo de configuración KSP ProgramData/sslTrusKSP/config.dat (cifrado con DPAPI).

Nota

install modificará el registro del Proveedor CNG a nivel de sistema, se recomienda ejecutarlo en una terminal de administrador. Si se detecta que la versión de la DLL es la misma, se registrará ksp is already installed y se retornará directamente.

---

Desinstalar KSP

signtool ksp uninstall

Ejecutar lo siguiente:

1. Cancelar el registro del CNG Provider: sslTrus Key Storage Provider.
2. Eliminar ProgramData/sslTrusKSP/sslTrusKSP.dll.
3. Eliminar sslTrusKSP.dll de System32.

Nota

uninstall no eliminará todo el directorio ProgramData/sslTrusKSP. Los config.dat guardados, los archivos de certificado y los registros deben limpiarse manualmente.

---

Ver la configuración de claves

signtool ksp list

Descripción de los campos de salida:

Campo	Significado
No	Número de orden
CertCode	Identificador del certificado
ServerUrl	Se muestra como nicsrs o default
AccessKey	Access Key
AccessSecret	Access Secret enmascarado

Información

• Si no existe un archivo de configuración, se devuelve no ksp configuration.

• Si existe la configuración pero la lista de claves está vacía, se registra no ksp key.
• AccessSecret se muestra enmascarado, pero el propio archivo de configuración debe seguir tratándose como un archivo confidencial. :::

---

Añadir una configuración de clave

signtool ksp add

Especifique la dirección NICSRS:

signtool ksp add --address nicsrs

El comando es interactivo, ingrésalo en orden:

Please enter the access key: your-access-key
Please enter the access secret: your-access-secret
Please enter the certificate code: CERT_CODE

Después de ejecutar:

1. Llame al remoto /v1/codesign/cert para obtener el certificado PEM.
2. Guarde el certificado como ProgramData/sslTrusKSP/CERT_CODE.crt.
3. Escriba la configuración de la clave en ProgramData/sslTrusKSP/config.dat (cifrado DPAPI).

Si el número de certificado ya existe, se mostrará una notificación:

The certificate code already exists, do you want to override it? [y/N]

Ingrese y para sobrescribir; cualquier otro valor o presionar Enter directamente abandonará la operación.

Nota

ksp add es un comando interactivo; actualmente no admite parámetros no interactivos como --access-key、--cert-code. Agregar una configuración accederá a la API remota y escribirá el PEM del certificado en ProgramData local.

---

Eliminar configuración de clave

signtool ksp del

Ingrese interactivamente el número de certificado:

Please enter the certificate code: CERT_CODE

Tras la ejecución, elimine la configuración de la clave coincidente de config.dat y vuelva a guardar el archivo de configuración cifrado.

Nota

La implementación actual solo elimina los elementos de configuración, no elimina el archivo de certificado ProgramData/sslTrusKSP/CERT_CODE.crt.

---

Uso de Microsoft signtool.exe con KSP

Una vez completada la configuración de KSP, utilice Microsoft signtool.exe del Windows SDK para invocar al Proveedor.

Advertencia

signtool.exe en el siguiente comando es una herramienta incluida en el Microsoft Windows SDK, no el CLI de sslTrus. Si ambos existen en el directorio actual o en la ruta PATH, use la ruta completa de signtool.exe del Windows SDK para evitar confusiones.

Ejemplo de firma SHA256:

signtool.exe sign /v ^
  /csp "sslTrus Key Storage Provider" ^
  /kc CERT_CODE ^
  /f C:\ProgramData\sslTrusKSP\CERT_CODE.crt ^
  /fd SHA256 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  .\EXAMPLE.exe

Ejemplo de firma SHA1 adicional:

signtool.exe sign /v ^
  /csp "sslTrus Key Storage Provider" ^
  /kc CERT_CODE ^
  /f C:\ProgramData\sslTrusKSP\CERT_CODE.crt ^
  /fd SHA1 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  /as ^
  .\EXAMPLE.exe

Descripción de parámetros:

Parámetro	Significado
/csp "sslTrus Key Storage Provider"	Especifica el Proveedor KSP instalado por sslTrus
/kc CERT_CODE	Especifica el nombre de la clave KSP, que se acuerda como el número de certificado
/f C:\ProgramData\sslTrusKSP\CERT_CODE.crt	Especifica el archivo de certificado guardado por ksp add
/fd SHA256 o /fd SHA1	Algoritmo de resumen de archivo
/tr <url>	Servicio de marca de tiempo RFC3161
/td SHA256	Algoritmo de resumen de marca de tiempo
/as	Agregar firma, sin sobrescribir la firma existente

---

Referencia de solución de problemas

Mensaje de error	Causa posible	Sugerencia de manejo
key storage provider is only supported on windows	Se ejecutó el comando ksp en una plataforma que no es Windows.	Ejecute operaciones de KSP solo en Windows.
no ksp configuration	Aún no se ha creado el archivo de configuración de KSP.	Primero ejecute signtool ksp install y signtool ksp add.
no such certificate code	El número de certificado que se va a eliminar no existe.	Use signtool ksp list para confirmar el número de certificado.

---

Precauciones de seguridad

• signtool ksp install y signtool ksp uninstall modificarán los directorios del sistema de Windows y el registro del proveedor CNG, lo que generalmente requiere permisos de administrador.
• signtool ksp add accederá a la interfaz de certificados remotos y escribirá los archivos de certificado y la configuración cifrada en ProgramData/sslTrusKSP.
• Access Secret, archivos de configuración de KSP y registros locales deben tratarse como información sensible; no deben escribirse en registros ni en el repositorio de versiones.