signtool ksp e integración con Windows KSP

signtool ksp gestiona el sslTrus Key Storage Provider de Windows (KSP). Una vez completada la instalación y configuración del KSP, Microsoft signtool.exe puede invocar el servicio de firma remota a través del CNG Provider, sin necesidad de almacenar la clave privada localmente.

Nota

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

---

Descripción general de los subcomandos

signtool ksp [command]

Subcomando	Uso
install	Instalar y registrar la DLL de KSP
uninstall	Anular el registro de KSP y eliminar la DLL
list	Listar las configuraciones de claves KSP guardadas
add	Agregar una nueva configuración de clave KSP (interactivo)
del	Eliminar una configuración de clave KSP especificada (interactivo)

Nota

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

---

Instalar KSP

signtool ksp install

Tras la ejecución:

1. Escriba el sslTrusKSP.dll incrustado en ProgramData/sslTrusKSP/sslTrusKSP.dll.
2. Si la versión de la DLL en ProgramData difiere de la de System32, copie la DLL a System32.
3. Registre el proveedor CNG: sslTrus Key Storage Provider.
4. Guarde el archivo de configuración KSP ProgramData/sslTrusKSP/config.dat (cifrado DPAPI).

Nota

install modificará el registro del proveedor CNG a nivel del 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 devolverá directamente.

---

Desinstalación de KSP

signtool ksp uninstall

Después de la ejecución:

1. Cancele el registro del proveedor CNG: sslTrus Key Storage Provider.
2. Elimine ProgramData/sslTrusKSP/sslTrusKSP.dll.
3. Elimine sslTrusKSP.dll en System32.

Nota

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

---

Ver la configuración de claves

signtool ksp list

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

Nota

• Si no hay archivo de configuración, devuelve no ksp configuration.

• Si la configuración existe pero la lista de claves está vacía, regístrela como no ksp key.
• AccessSecret se muestra con enmascaramiento, pero el archivo de configuración en sí debe gestionarse como un archivo sensible. :::

---

Añadir configuración de claves

signtool ksp add

Especificar la dirección NICSRS:

signtool ksp add --address nicsrs

El comando es interactivo, ingrese 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 la ejecución:

1. Llame al remoto /v1/codesign/cert para obtener el PEM del certificado.
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á un aviso:

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

Introduzca y para sobrescribir; con cualquier otro valor o pulsando directamente Enter se cancelará.

Nota

ksp add es un comando interactivo y actualmente no admite parámetros no interactivos como --access-key o --cert-code. Al añadir la configuración se accederá a la API remota y se escribirá el PEM del certificado en el directorio local ProgramData.

---

Eliminar configuración de clave

signtool ksp del

Ingrese el número de certificado de forma interactiva:

Please enter the certificate code: CERT_CODE

Después de la ejecución, elimina la configuración de clave coincidente de config.dat y vuelve a guardar el archivo de configuración cifrado.

Nota

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

---

Uso de Microsoft signtool.exe a través de KSP

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

Advertencia

El signtool.exe en el siguiente comando es una herramienta incluida con Microsoft Windows SDK, no la CLI de sslTrus. Si ambos existen en el directorio actual o en el PATH, utilice la ruta completa de signtool.exe en el SDK de Windows 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 adición de firma SHA1:

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 KSP Provider 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 del archivo
/tr <url>	Servicio de marca de tiempo RFC3161
/td SHA256	Algoritmo de resumen de la marca de tiempo
/as	Añade la firma sin sobrescribir la existente

---

Referencia de solución de problemas

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

---

Precauciones de seguridad

• signtool ksp install y signtool ksp uninstall modificarán el directorio del sistema de Windows y el registro del proveedor CNG, lo que generalmente requiere privilegios de administrador.
• signtool ksp add accederá a la interfaz remota de certificados y escribirá los archivos de certificado y la configuración de cifrado en ProgramData/sslTrusKSP.
• Access Secret, los archivos de configuración de KSP y los registros locales deben tratarse como información confidencial y no deben escribirse en registros ni en repositorios de control de versiones.