Instrucciones de uso de CSP

Resumen

Estas instrucciones se utilizan para configurar sslTrus Cryptographic Service Provider (CSP) en Windows y utilizar el HSM en la nube a través del Microsoft signtool.exe del SDK de Windows para completar la firma de código.

El signtool csp de este proyecto es responsable de instalar, configurar y mantener el Proveedor; para la firma real se utiliza el signtool.exe del SDK de Windows. Ambos no son el mismo programa.

sslTrus Cryptographic Service Provider es un CSP de CryptoAPI tradicional, adecuado para procesos de firma de Windows que requieren acceso a través de /csp y /kc. La clave privada de firma siempre se mantiene en el HSM en la nube; el equipo local solo almacena el DLL de CSP, el certificado de firma y la configuración de acceso protegida por DPAPI de Windows.

Preparación antes del uso

• Sistema Windows x64.
• Terminal ejecutado como administrador, para instalar o desinstalar el Proveedor.
• La CLI signtool de este proyecto, que incluye el subcomando csp.
• Tener instalado Windows SDK y poder utilizar Microsoft signtool.exe.
• Access Key, Access Secret y un identificador de certificado (CERT_CODE) válidos.
• Acceso de red al servicio de firma de código y al servicio de sellado de tiempo seleccionado.

Confirme que ambas herramientas estén disponibles por separado:

REM 本项目 CLI
signtool csp --help

REM Windows SDK 工具；必要时请使用其完整路径
signtool.exe sign /?

Si el directorio actual o la ruta PATH contiene dos programas con el mismo nombre, asegúrese de confirmar el destino real de la llamada mediante la ruta completa o where.

Inicio rápido

En la terminal de administrador, ejecute secuencialmente:

signtool csp install
signtool csp add
signtool csp list

csp add solicitará interactivamente que ingreses:

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

Una vez completada la configuración, firme utilizando signtool.exe de Microsoft del Windows SDK:

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

Reemplace los CERT_CODE y app.exe del ejemplo por el número de certificado real y el archivo a firmar.

Instalación del Proveedor

Ejecute:

signtool csp install

El comando:

• Escribirá sslTrusCSP.dll en %ProgramData%\sslTrusKSP y lo copiará al directorio del sistema.
• Registrará sslTrus Cryptographic Service Provider (tipo de Provider PROV_RSA_AES).
• Instalará el DLL KSP complementario y registrará sslTrus Key Storage Provider como alias del CNG Provider con el mismo nombre que el CSP.
• Creará o guardará %ProgramData%\sslTrusKSP\config.dat; el archivo se cifra con DPAPI de Windows de la máquina local.

La instalación modifica el registro de Providers a nivel de sistema, por lo que normalmente debe ejecutarse en un terminal de administrador. Si la versión del DLL CSP en el directorio del sistema coincide con la versión integrada, el CLI omitirá la copia del DLL CSP, pero aún así ejecutará el proceso de registro del Provider.

Agregar configuración de certificado

Ejecute:

signtool csp add

Si necesita utilizar la dirección del servicio NICSRS:

signtool csp add --address nicsrs

--address no es un parámetro de transmisión de URL. Actualmente, nicsrs utilizará el servicio NICSRS; los valores vacíos, racent u otros valores usarán el servicio predeterminado.

Al añadirlo, la CLI obtendrá el certificado del servicio remoto y lo escribirá en:

%ProgramData%\sslTrusKSP\CERT_CODE.crt

Al mismo tiempo, escriba la dirección del servicio, las credenciales, el número del certificado y la ruta del certificado en el archivo de configuración cifrado. CERT_CODE es tanto el identificador del certificado remoto como el valor de /kc en el posterior Microsoft signtool.exe.

Si se agrega un número de certificado que ya existe, la CLI preguntará si desea sobrescribirlo: ingrese y para reemplazar la configuración anterior; presione Enter directamente o ingrese otro valor para mantener la configuración original sin cambios.

Ver y eliminar configuración

Ver la configuración actual:

signtool csp list

El resultado incluye el número de certificado, el tipo de servicio, la Access Key y el Access Secret enmascarado. Por favor, no suba la salida de comandos, archivos de configuración o registros a ubicaciones públicas.

Eliminar una configuración:

signtool csp del

Introduzca el número de certificado según las indicaciones. Esta operación solo elimina la entrada correspondiente en la configuración de cifrado, no elimina el archivo de certificado .crt con el mismo nombre; si ya no se utiliza, elimine manualmente dicho archivo.

Uso de la firma Microsoft signtool.exe

Firma SHA-256

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

Descripción de los parámetros:

Parámetro	Descripción
/csp "sslTrus Cryptographic Service Provider"	Especifica el proveedor de CSP.
/kc CERT_CODE	Especifica el contenedor de claves correspondiente al número de certificado.
/f <证书路径>	Especifica el archivo de certificado descargado por csp add.
/fd SHA256	Especifica el algoritmo de resumen del archivo.
/tr <URL>	Especifica el servicio de marcas de tiempo RFC 3161.
/td SHA256	Especifica el algoritmo de resumen de la marca de tiempo.

El CSP actual admite los algoritmos de resumen de archivos SHA1, SHA256, SHA384 y SHA512; para nuevas firmas, generalmente se recomienda usar SHA-256 o versiones superiores. La dirección de la estampilla de tiempo debe determinarse según tu política de certificados y la compatibilidad con la plataforma de destino.

Agregar firma SHA-1

Cuando existan requisitos de compatibilidad con sistemas antiguos, se puede agregar SHA-1 a la firma existente:

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

/as indica agregar la firma, evitando sobrescribir firmas existentes. La necesidad de SHA-1 debe seguir el sistema de destino y la política de certificados; no debe ser la opción predeterminada para nuevos proyectos.

Verificar la firma

Después de firmar, puede usar Microsoft signtool.exe para verificar:

signtool.exe verify /pa /v ".\app.exe"

Para verificar todas las firmas, seleccione las opciones de verificación correspondientes según la versión y la documentación de parámetros de signtool.exe de Windows SDK.

Desinstalar el proveedor

Ejecute en una terminal con privilegios de administrador:

signtool csp uninstall

El comando dará de baja el CSP, así como el alias del Proveedor CNG con el mismo nombre, y eliminará las copias del DLL del CSP en ProgramData y en el directorio del sistema. No eliminará el directorio completo de %ProgramData%\sslTrusKSP, ni eliminará automáticamente el registro ni el DLL correspondiente a sslTrus Key Storage Provider; si dicho KSP se utiliza únicamente en el proceso de instalación del CSP, por favor límpielo con precaución según el estado real del despliegue.

Si después de la desinstalación necesita eliminar datos locales sensibles, confirme primero que ya no sean utilizados por el KSP u otros procesos de firma, y luego elimine manualmente la configuración, los certificados y los registros en %ProgramData%\sslTrusKSP.

Preguntas frecuentes

Fenómeno	Sugerencia de manejo
cryptographic service provider is only supported on windows	Ejecute el comando de gestión del CSP en Windows.
Error de permisos o fallo de escritura en el directorio del sistema durante la instalación	Use una terminal de administrador para ejecutar signtool csp install.
no csp configuration	Primero ejecute signtool csp install y luego signtool csp add.
no such certificate code	Primero verifica el número de certificado con signtool csp list.
Microsoft signtool.exe no encuentra el Proveedor	Confirma que el comando de instalación se ejecutó correctamente, que la herramienta actual y el Proveedor son ambos x64, y vuelve a abrir la terminal antes de reintentar.
No se encuentra el archivo de certificado al firmar	Asegúrate de que la ruta /f coincida con el csp add descargado desde CERT_CODE.crt.
Fallo en la llamada de firma	Revisa el número de certificado, las credenciales del servicio y la conectividad de red; luego consulta %ProgramData%\sslTrusKSP\sslTrusCSP.log.
Se utiliza una dirección de servicio personalizada, pero la solicitud falla	CSP solicita siempre la ruta /v1/codesign/sign del servicio; la dirección configurada debe contener únicamente http(s)://host[:port].

Consideraciones de seguridad

• Access Secret, config.dat, los archivos de certificados y los registros de CSP deben tratarse como información confidencial.
• config.dat está protegido por DPAPI del perfil del usuario actual de Windows que creó la configuración; no debe copiarse directamente para reutilizarlo con otros usuarios o equipos.
• CSP no almacena claves privadas; no intente importar una clave privada a %ProgramData%\sslTrusKSP.
• La firma con CSP requiere acceso al servicio remoto. Los tiempos de espera de red, el rechazo del servidor o la falta de disponibilidad del servicio de sellado de tiempo pueden hacer que la firma falle.

Para consultar más parámetros de la CLI y comandos de firma, consulte la Referencia del comando SignTool sign.