signtool ksp e integración con Windows KSP

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

Nota

Todos los subcomandos de signtool ksp solo son compatibles con la plataforma Windows. Si 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	Instala y registra la DLL de KSP
uninstall	Anula el registro de KSP y elimina la DLL
list	Enumera las configuraciones de claves de KSP guardadas
add	Agrega una configuración de clave de KSP (interactivo)
del	Elimina una configuración de clave de KSP especificada (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. Escriba el sslTrusKSP.dll incrustado en ProgramData/sslTrusKSP/sslTrusKSP.dll.
2. Si la versión de la DLL en ProgramData es diferente 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 igual, 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 configuración de claves

signtool ksp list

Descripción de los campos de salida:

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, registre no ksp key.
• AccessSecret se muestra enmascarado, pero el archivo de configuración en sí debe seguir gestionándose como un archivo confidencial. :::

---

Agregar configuración de claves

signtool ksp add

Especifique 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; cualquier otro valor o pulsar Enter directamente cancelará la operación.

Nota

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

---

Eliminar la configuración de la clave

signtool ksp del

Ingrese el número de certificado de forma interactiva:

Please enter the certificate code: CERT_CODE

Tras la ejecución, elimine la configuración de clave coincidente de config.dat y vuelva 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 mediante KSP

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

Advertencia

El signtool.exe en los siguientes comandos es una herramienta incluida en el SDK de Microsoft Windows, no la CLI de sslTrus. Si ambos existen en el directorio actual o en el PATH, utilice la ruta completa del signtool.exe del 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 de la instalación de sslTrus
/kc CERT_CODE	Especifica el nombre de la clave KSP, acordado 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 sello de tiempo RFC3161
/td SHA256	Algoritmo de resumen del sello de tiempo
/as	Agregar firma sin sobrescribir las firmas existentes

---

Referencia para resolución de problemas

Mensaje de error	Posible causa	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 de KSP únicamente en Windows.
no ksp configuration	Aún no se ha creado el archivo de configuración de KSP.	Ejecute primero signtool ksp install y signtool ksp add.
no such certificate code	El número de certificado a eliminar no existe.	Utilice signtool ksp list para confirmar el número de certificado.

---

Notas de seguridad

• signtool ksp install y signtool ksp uninstall modificarán el directorio del sistema Windows y el registro del CNG Provider, por lo que normalmente se requieren privilegios de administrador.
• signtool ksp add accederá a la interfaz remota de certificados y escribirá los archivos de certificado y la configuración cifrada en ProgramData/sslTrusKSP.
• El Access Secret, el archivo de configuración KSP y los registros locales deben tratarse como información confidencial y no deben escribirse en los registros ni en el repositorio de versiones.