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

Registrar el certificado

Una vez configurado el KSP, debe registrar el certificado de firma de código en el almacén de certificados de Windows y asociarlo al proveedor KSP.

Ejecute:

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"

Parámetros principales:

Parámetro	Descripción
/csp	Especifica el proveedor KSP de sslTrus
/kc	Especifica el contenedor de claves correspondiente al identificador del certificado
/f	Especifica el certificado de firma de código
/fd	Especifica el algoritmo de resumen del archivo
/tr	Especifica el servidor de sellado de tiempo RFC 3161
/td	Especifica el algoritmo de resumen del sello de tiempo

Para añadir una firma SHA-1 a una firma existente, puede utilizar el parámetro /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

Eliminar la configuración:

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

Instale también la DLL del proveedor en el sistema Windows.

El tipo del proveedor CSP es:

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

Añadir la configuración del certificado

Ejecute:

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 se utiliza tanto como identificador del certificado remoto como nombre del contenedor de claves que Microsoft SignTool utilizará posteriormente.

Si utiliza el entorno NICSRS (www.nicsrs.com), debe añadir --address nicsrs:

signtool csp add --address nicsrs

Registrar el certificado

De forma predeterminada, el certificado se registra en el almacén personal del usuario actual:

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"

Parámetros principales:

Parámetro	Descripción
/csp	Especifica el proveedor CSP de sslTrus
/kc	Especifica el contenedor de claves correspondiente al identificador del certificado
/f	Especifica el certificado de firma de código
/fd	Especifica el algoritmo de resumen del archivo
/tr	Especifica el servidor de sellado de tiempo RFC 3161
/td	Especifica el algoritmo de resumen del sello de tiempo

La API actual de firma remota admite los algoritmos de resumen SHA1 y SHA256. Para firmas nuevas debe darse prioridad a SHA256; utilice SHA1 únicamente para mantener la compatibilidad con sistemas antiguos.

Verificar la firma

Una vez completada la firma, puede verificarla con 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.