Instrucciones de uso de CSP

Descripción general

Esta guía se utiliza para configurar sslTrus Cryptographic Service Provider (CSP) en Windows y completar la firma de código mediante el HSM en la nube a través del signtool.exe de Microsoft del SDK de Windows.

El signtool csp de este proyecto se encarga de instalar, configurar y mantener el proveedor; al momento de firmar realmente, se utiliza el signtool.exe del SDK de Windows. No son el mismo programa.

sslTrus Cryptographic Service Provider es un CSP CryptoAPI tradicional, adecuado para flujos de firma en Windows que necesiten integrarse mediante /csp y /kc. La clave privada de firma permanece siempre en el HSM en la nube; en el equipo local solo se guardan la DLL del CSP, el certificado de firma y la configuración de acceso protegida mediante Windows DPAPI.

Preparación antes del uso

• Sistema Windows x64.
• Terminal ejecutada como administrador, para instalar o desinstalar el proveedor.
• CLI de este proyecto signtool, que incluye el subcomando csp.
• Windows SDK instalado y capaz de usar Microsoft signtool.exe.
• Access Key, Access Secret y número de certificado válidos (CERT_CODE).
• 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 hay dos programas con el mismo nombre en el directorio actual o en el PATH, asegúrese de confirmar el destino de llamada real mediante la ruta completa o where.

Inicio rápido

Ejecute en orden en una terminal de administrador:

signtool csp install
signtool csp add
signtool csp list

csp add solicitará la entrada de forma interactiva:

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

Tras la configuración exitosa, use el signtool.exe de Microsoft del SDK de Windows para firmar:

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"

En el ejemplo, reemplace CERT_CODE y app.exe por el número de certificado real y el archivo pendiente de firma.

Instalar el Provider

Ejecute:

signtool csp install

该命令会：

• 将 sslTrusCSP.dll 写入 %ProgramData%\sslTrusKSP 并复制到系统目录。
• 注册 sslTrus Cryptographic Service Provider（Provider 类型为 PROV_RSA_AES）。
• 安装配套 KSP DLL，并注册 sslTrus Key Storage Provider 与 CSP 同名的 CNG Provider alias。
• 创建或保存 %ProgramData%\sslTrusKSP\config.dat；文件使用本机 Windows DPAPI 加密。

安装会修改系统级 Provider 注册，通常必须在管理员终端执行。若系统目录内的 CSP DLL 版本与内嵌版本一致，CLI 会跳过 CSP DLL 复制，但仍会执行 Provider 注册流程。

添加证书配置

执行：

signtool csp add

Si necesita utilizar la dirección del servicio NICSRS:

signtool csp add --address nicsrs

--address no es un parámetro de paso directo por URL. Actualmente nicsrs utilizará el servicio NICSRS; un valor vacío, racent u otros valores utilizarán el servicio predeterminado.

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

%ProgramData%\sslTrusKSP\CERT_CODE.crt

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

Si se añade un número de certificado ya existente, la CLI preguntará si se desea sobrescribir: introduce y para reemplazar la configuración anterior; si pulsas directamente Enter o introduces otro valor, se mantendrá la configuración original.

Ver y eliminar configuraciones

Ver la configuración actual:

signtool csp list

La salida contiene el número de certificado, el tipo de servicio, la Access Key y el Access Secret enmascarado. No cargue la salida de comandos, los archivos de configuración ni los registros en lugares públicos.

Eliminar una configuración:

signtool csp del

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

Uso de la firma de 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 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 sellado de tiempo RFC 3161.
/td SHA256	Especifica el algoritmo de resumen del sellado de tiempo.

Actualmente, CSP admite los algoritmos de resumen de archivos SHA1, SHA256, SHA384 y SHA512; para las nuevas firmas se suele recomendar SHA-256 o superior. La dirección del sello de tiempo debe determinarse según tu política de certificados y la compatibilidad con la plataforma de destino.

Añadir firma SHA-1

Cuando exista un requisito real de compatibilidad con sistemas antiguos, se puede añadir SHA-1 sobre 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 significa agregar la firma, evitando sobrescribir la firma existente. La necesidad de SHA-1 debe seguir las políticas del sistema de destino y del certificado; no debería 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"

Si necesita verificar todas las firmas, puede seleccionar la opción de verificación correspondiente según la versión y la descripción de los parámetros del SDK de Windows signtool.exe.

Desinstalar el proveedor

Ejecute en una terminal de administrador:

signtool csp uninstall

Este comando cancela el registro del CSP, así como el alias del CNG Provider con el mismo nombre del CSP, y elimina las copias del DLL del CSP en ProgramData y en el directorio del sistema. No elimina el directorio completo %ProgramData%\sslTrusKSP ni desinstala automáticamente el registro y el DLL del sslTrus Key Storage Provider correspondiente; si ese KSP solo se utiliza en el proceso de instalación del CSP, límpielo con precaución según el estado real de la implementación.

Si después de la desinstalación necesita eliminar los datos confidenciales locales, confirme primero que ya no los utilicen el KSP u otros procesos de firma y, a continuación, elimine manualmente la configuración, los certificados y los registros de %ProgramData%\sslTrusKSP.

Preguntas frecuentes

Fenómeno	Sugerencia de tratamiento
cryptographic service provider is only supported on windows	Ejecute el comando de administración del CSP en Windows.
Error de permisos o de escritura en el directorio del sistema durante la instalación	Utilice una terminal de administrador para ejecutar signtool csp install.
no csp configuration	Ejecute primero signtool csp install y después signtool csp add.
no such certificate code	Primero use signtool csp list para verificar el número del certificado.
Microsoft signtool.exe no encuentra el Provider	Confirme que el comando de instalación se haya ejecutado correctamente, que la herramienta actual y el Provider sean ambos x64, y vuelva a abrir la terminal antes de intentarlo de nuevo.
No se encuentra el archivo del certificado al firmar	Confirme que la ruta de /f coincida con el CERT_CODE.crt descargado desde csp add.
Error al invocar la firma	Verifique el número del certificado, las credenciales del servicio y la conectividad de red; luego revise %ProgramData%\sslTrusKSP\sslTrusCSP.log.
Al usar una dirección de servicio personalizada pero la solicitud es anormal	La CSP fija la ruta de solicitud del servicio /v1/codesign/sign; la dirección de servicio configurada solo debe proporcionar http(s)://host[:port].

Notas de seguridad

• El Access Secret, config.dat, los archivos de certificado y los registros de la 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, y no debe copiarse directamente a otros usuarios o máquinas para su reutilización.
• La CSP no guarda la clave privada; no intente importar la clave privada en %ProgramData%\sslTrusKSP.
• La firma de la CSP requiere acceso al servicio remoto; los tiempos de espera de red, el rechazo del servidor o la indisponibilidad del servicio de sello de tiempo pueden provocar el fallo de la firma.

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