Windows Provider

sslTrus ofrece dos métodos de integración con Windows Provider: KSP (Key Storage Provider) y CSP (Cryptographic Service Provider).

A través de Windows Provider, Microsoft SignTool, Visual Studio, MSBuild, herramientas de paquetes de instalación y otro software que admita las interfaces criptográficas de Windows pueden utilizar la capacidad de firma de código en la nube de sslTrus.

La clave privada de firma siempre se almacena en el HSM en la nube, sin necesidad de implementar el archivo de clave privada en la máquina local.

La instalación, configuración y mantenimiento de KSP y CSP se realizan mediante sslTrus SignTool CLI, que se puede descargar desde la página de versiones del cliente sslTrus.

KSP y CSP

KSP y CSP corresponden respectivamente a las dos generaciones de interfaces criptográficas de Windows:

Provider	Interfaz de Windows	Escenarios de uso
KSP	CNG (Cryptography API: Next Generation)	Aplicaciones modernas de Windows y herramientas de firma, opción preferente
CSP	CryptoAPI	Aplicaciones tradicionales o software que requiere explícitamente CSP

Para nuevos escenarios de integración con Windows, normalmente se prefiere usar KSP.

Solo cuando el software de destino no admite KSP, o requiere explícitamente el uso del CryptoAPI Provider tradicional, se debe usar CSP.

KSP

KSP es un Key Storage Provider basado en Windows CNG.

Después de instalar sslTrus KSP, las aplicaciones de Windows que admiten CNG pueden invocar el servicio de firma de código remoto mediante las interfaces estándar de claves de Windows.

El Provider local se encarga de recibir las solicitudes de firma iniciadas por las aplicaciones y enviar el resumen que necesita ser firmado al servicio de firma de código remoto; las operaciones reales con la clave privada se completan en el HSM en la nube.

Escenarios de aplicación

KSP es adecuado para:

• Microsoft SignTool.
• Visual Studio.
• MSBuild.
• Software de compilación y firma que admite Windows CNG.
• Aplicaciones que necesitan acceder a claves privadas remotas a través de Windows Provider estándar.

Instalación de KSP

Ejecute en un terminal con permisos de administrador:

signtool ksp install

El comando instalará y registrará:

sslTrus Key Storage Provider

La instalación de KSP implica el registro del Provider del sistema y los directorios del sistema de Windows, por lo que generalmente se requieren permisos de administrador.

Agregar configuración del certificado

Ejecute:

signtool ksp add

Introduzca la información según las indicaciones:

Access Key
Access Secret
Certificate Code

El cliente obtendrá el certificado correspondiente desde el servicio de firma de código remoto y guardará la dirección del servicio remoto, las credenciales de acceso y la configuración del certificado.

Si se utiliza el entorno NICSRS (www.nicsrs.com), es necesario agregar --address nicsrs:

signtool ksp add --address nicsrs

注册证书

完成 KSP 配置后，需要将代码签名证书注册到 Windows 证书库并关联 KSP Provider。

执行：

signtool ksp register

Se registrará de forma predeterminada en el almacén de certificados personales del usuario actual.

Si es necesario registrarlo en el almacén de certificados LocalMachine:

signtool ksp register --store local-machine

After registration is complete, Windows will recognize the corresponding certificate as having an available private key, but the actual private key remains stored in the cloud HSM.

Using Microsoft SignTool

Once the KSP configuration is complete, you can use the Microsoft signtool.exe provided by the Windows SDK to sign files.

For example:

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 ^
  ".\app.exe"

主要参数：

参数	说明
/csp	指定 sslTrus KSP Provider
/kc	指定证书编号对应的密钥容器
/f	指定代码签名证书
/fd	指定文件摘要算法
/tr	指定 RFC 3161 时间戳服务器
/td	指定时间戳摘要算法

如果需要在已有签名基础上追加 SHA-1 签名，可以使用 /as 参数：

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 ^
  ".\app.exe"

Microsoft signtool.exe realizará llamadas a sslTrus KSP a través de Windows CNG, y luego KSP completará la firma remota con la clave privada.

Administrar KSP

Ver los KSP ya configurados:

signtool ksp list

删除配置：

signtool ksp del

Eliminar la asociación del certificado con el KSP:

signtool ksp deregister

Desinstalar KSP:

signtool ksp uninstall

Antes de desinstalar el Provider, confirme que ninguna otra aplicación de Windows sigue dependiendo de dicho Provider.

CSP

CSP es el Cryptographic Service Provider utilizado por la CryptoAPI tradicional de Windows.

Se utiliza principalmente en flujos de firma de Windows que requieren especificar el Provider y el contenedor de claves mediante los parámetros /csp y /kc. El CSP de sslTrus es instalado y mantenido por el cliente; la firma real de los archivos la realiza el signtool.exe de Microsoft del SDK de Windows.

Escenarios aplicables

CSP es adecuado para:

• Software de Windows que solo admite la CryptoAPI tradicional.
• Herramientas de firma que exigen explícitamente especificar un CSP Provider.
• Entornos que necesitan firmar mediante los parámetros /csp y /kc de Microsoft SignTool.
• Aplicaciones heredadas que no pueden usar Windows CNG / KSP.

Para sistemas nuevos que pueden usar KSP correctamente, generalmente no es necesario usar CSP adicionalmente.

Instalación de CSP

Ejecute en una terminal de administrador:

signtool csp install

Durante la instalación se registrará:

sslTrus Cryptographic Service Provider

并将 Provider DLL 安装到 Windows 系统中。

CSP Provider 类型为：

PROV_RSA_AES

La configuración local se guarda por defecto en:

%ProgramData%\sslTrusKSP

El archivo de configuración está protegido con DPAPI de Windows.

Si necesita instalar KSP al mismo tiempo, puede ejecutar:

signtool csp install --with-ksp

添加证书配置

执行：

signtool csp add

Introduzca la información según las indicaciones:

Access Key
Access Secret
Certificate Code

Una vez completada la adición, el cliente descargará el certificado correspondiente y lo guardará en:

%ProgramData%\sslTrusKSP\CERT_CODE.crt

其中 CERT_CODE 同时作为远程证书标识和后续 Microsoft SignTool 使用的密钥容器名称。

如果使用 NICSRS（www.nicsrs.com）环境，需要添加 --address nicsrs：

signtool csp add --address nicsrs

注册证书

默认将证书注册到当前用户的个人证书库：

signtool csp register

Si necesita registrarse en LocalMachine:

signtool csp register --store local-machine

Los almacenes de certificados compatibles incluyen:

Parámetro	Almacén de certificados de Windows
current-user	CurrentUser\My
local-machine	LocalMachine\My

Una vez completado el registro, el Administrador de certificados de Windows mostrará que el certificado correspondiente tiene una clave privada asociada, pero la clave privada en realidad permanece en el HSM en la nube.

Uso de Microsoft SignTool

Al firmar con CSP, debe especificar explícitamente el Proveedor, el contenedor de claves y el archivo de certificado:

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"

主要参数：

参数	说明
/csp	指定 sslTrus CSP Provider
/kc	指定证书编号对应的密钥容器
/f	指定代码签名证书
/fd	指定文件摘要算法
/tr	指定 RFC 3161 时间戳服务器
/td	指定时间戳摘要算法

当前远程签名接口支持 SHA1 和 SHA256 摘要算法。新签名场景应优先使用 SHA256；仅在兼容旧系统时使用 SHA1。

验证签名

签名完成后，可以使用 Microsoft SignTool 验证：

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

La verificación de firma no volverá a invocar la clave privada remota ni generará un nuevo recuento de firmas.

Gestionar CSP

Ver la configuración existente:

signtool csp list

Eliminar una configuración de certificado específica:

signtool csp del

Elimina la asociación de la clave privada entre el certificado y el CSP:

signtool csp deregister

Desinstalar el Provider：

signtool csp uninstall

Eliminar la configuración de CSP no elimina automáticamente los archivos de certificado ya descargados. Si el certificado y la configuración correspondientes ya no se utilizan, debe confirmar que no haya otros Providers que dependan de ellos antes de realizar la limpieza.

KSP o CSP

Si no hay requisitos especiales de compatibilidad, puede seleccionar de la siguiente manera:

Escenario	Recomendación
Nuevo entorno de firma de Windows	KSP
Compatibilidad con Windows CNG	KSP
Herramientas modernas de Windows como Microsoft SignTool	KSP
El software requiere explícitamente CSP	CSP
Aplicaciones tradicionales de CryptoAPI	CSP
La herramienta requiere usar /csp y /kc	CSP

La principal diferencia entre KSP y CSP radica en que Windows utiliza interfaces de Provider criptográfico diferentes, mientras que el modelo de seguridad de la clave privada remota se mantiene igual.

Ya sea que utilice KSP o CSP, la clave privada de firma de código no se guardará en el cliente local.

Número de firmas

El número de firmas del Windows Provider se calcula en función de las acciones de firma remota realmente completadas a nivel subyacente.

Por ejemplo:

SHA256 签名一次 = 1 次

Si se completa primero la firma SHA256 del mismo archivo y luego se agrega otra firma, se volverá a activar la operación de clave privada remota, por lo que es necesario calcularlas por separado.

En el escenario KSP, ejecutar una doble firma SHA256 y SHA1 en el mismo archivo generalmente produce dos llamadas de firma subyacentes.

Consulte las reglas específicas en Material de referencia.

Marca de tiempo

Para la firma Authenticode de Windows, generalmente se recomienda agregar una marca de tiempo confiable.

En los escenarios modernos de firma de código, se recomienda priorizar el uso de la marca de tiempo RFC 3161, por ejemplo:

http://timestamp.acs.microsoft.com

El entorno de producción real debe seleccionar la TSA adecuada según la versión objetivo de Windows, la política de certificados, el entorno de red y los requisitos del proveedor de sellos de tiempo.

Para obtener detalles específicos sobre los servidores de sellos de tiempo y los protocolos, consulte Materiales de referencia.

Notas de seguridad

Al usar el Proveedor de Windows, se debe tener en cuenta lo siguiente:

• Access Secret debe protegerse como una credencial sensible.
• No escriba las credenciales de acceso en scripts públicos o registros.
• El archivo de configuración del Proveedor no debe distribuirse públicamente.
• El archivo de certificado local no contiene la clave privada de firma de código.
• La clave privada de firma de código siempre se almacena en el HSM en la nube.
• Cuando KSP/CSP inicia la firma, necesita poder acceder al servicio de firma de código remoto.
• Al usar el almacén de certificados LocalMachine, se debe prestar especial atención a los permisos de usuario de Windows y al alcance de acceso de las credenciales.

El config.dat de CSP se protege utilizando el DPAPI del perfil de usuario actual de Windows; registrar el certificado en LocalMachine no cambia automáticamente el alcance de protección DPAPI de esta configuración.