Integración de Java

sslTrus ofrece sslTrusJarsigner Java Provider, que se puede utilizar junto con la herramienta jarsigner incluida en el JDK para firmar archivos JAR de Java mediante el servicio remoto de firma de código.

Durante el proceso de firma, la clave privada de firma de código permanece siempre almacenada en el HSM en la nube. El equipo local se encarga de generar los datos a firmar y la estructura de la firma, y llama al servicio remoto a través del sslTrusJarsigner Provider para completar la firma con la clave privada.

Además de la firma de JAR, sslTrusJarsigner también ofrece capacidad de firma XMLDSig, que puede utilizarse en escenarios de firma digital XML.

Preparación

Antes de usarlo, prepare lo siguiente:

• JDK 8 o superior.
• sslTrusJarsigner-<version>.jar.
• Access Key.
• Access Secret.
• Número de certificado (Cert Code).
• Archivo JAR o XML a firmar.

En los ejemplos de este artículo, <version>, las credenciales de acceso, el número de certificado y las rutas de archivo deben reemplazarse por los valores reales.

Descargar sslTrusJarsigner

Descargue el paquete de la última versión desde la página de lanzamiento de sslTrusJarsigner y descomprímalo.

El paquete de lanzamiento incluye:

sslTrusJarsigner-<version>.jar
SHA-256 校验文件

Se recomienda verificar la integridad del archivo sslTrusJarsigner-<version>.jar mediante el checksum SHA-256 antes de usarlo.

Comprobar el entorno de ejecución

Primero, confirme que Java y el jarsigner incluido en el JDK funcionan correctamente:

java -version
jarsigner -help

Verifique la versión de sslTrusJarsigner:

java -jar sslTrusJarsigner-<version>.jar --version

Ver ayuda:

java -jar sslTrusJarsigner-<version>.jar --help

Si el comando jarsigner no existe, confirme que está instalado un JDK completo y no un entorno de ejecución que solo incluye Java Runtime.

Configurar credenciales de acceso

sslTrusJarsigner lee las credenciales de acceso y el número de certificado del servicio remoto de firma de código a través de variables de entorno.

Linux y macOS

export SSLTRUS_JARSIGNER_ACCESS_KEY="YOUR_ACCESS_KEY"
export SSLTRUS_JARSIGNER_ACCESS_SECRET="YOUR_ACCESS_SECRET"
export SSLTRUS_JARSIGNER_CERT_CODE="YOUR_CERT_CODE"

Windows PowerShell

$env:SSLTRUS_JARSIGNER_ACCESS_KEY = "YOUR_ACCESS_KEY"
$env:SSLTRUS_JARSIGNER_ACCESS_SECRET = "YOUR_ACCESS_SECRET"
$env:SSLTRUS_JARSIGNER_CERT_CODE = "YOUR_CERT_CODE"

Si el personal de servicio proporciona una dirección de servicio dedicada, también es necesario configurar SSLTRUS_JARSIGNER_URL.

Linux y macOS:

export SSLTRUS_JARSIGNER_URL="YOUR_SERVICE_URL"

Windows PowerShell:

$env:SSLTRUS_JARSIGNER_URL = "YOUR_SERVICE_URL"

Si no se proporciona una dirección de servicio dedicada, no es necesario configurar esta variable.

Access Secret es una credencial confidencial y no debe escribirse en el código fuente, en archivos de configuración públicos ni en los registros de compilación. En entornos de automatización, se recomienda inyectarla mediante CI/CD Secret u otros mecanismos de gestión de credenciales.

Firma de JAR

sslTrusJarsigner se integra con la herramienta estándar jarsigner mediante el mecanismo de Java Security Provider.

El siguiente ejemplo:

app-unsigned.jar

Después de firmar, la salida es:

app-signed.jar

JDK 9 o posterior

Linux y macOS:

jarsigner \
  -keystore NONE \
  -storetype SSLTRUS \
  -storepass SSLTRUS \
  -providerPath "sslTrusJarsigner-<version>.jar" \
  -providerClass com.racent.codesign.SSLTrusProvider \
  -sigalg SHA256withRSA \
  -tsa http://timestamp.sectigo.com \
  -signedjar "app-signed.jar" \
  "app-unsigned.jar" \
  "$SSLTRUS_JARSIGNER_CERT_CODE"

Windows PowerShell:

jarsigner `
  -keystore NONE `
  -storetype SSLTRUS `
  -storepass SSLTRUS `
  -providerPath "sslTrusJarsigner-<version>.jar" `
  -providerClass com.racent.codesign.SSLTrusProvider `
  -sigalg SHA256withRSA `
  -tsa http://timestamp.sectigo.com `
  -signedjar "app-signed.jar" `
  "app-unsigned.jar" `
  "$env:SSLTRUS_JARSIGNER_CERT_CODE"

JDK 8

JDK 8 carga el Provider de manera diferente a JDK 9 y versiones posteriores.

Primero, confirme:

JAVA_HOME

Apunte al directorio completo de instalación del JDK 8.

Linux y macOS:

jarsigner \
  -J-cp \
  -J"$JAVA_HOME/lib/tools.jar:sslTrusJarsigner-<version>.jar" \
  -keystore NONE \
  -storetype SSLTRUS \
  -storepass SSLTRUS \
  -providerClass com.racent.codesign.SSLTrusProvider \
  -sigalg SHA256withRSA \
  -tsa http://timestamp.sectigo.com \
  -signedjar "app-signed.jar" \
  "app-unsigned.jar" \
  "$SSLTRUS_JARSIGNER_CERT_CODE"

Windows PowerShell：

jarsigner `
  -J-cp `
  "-J$env:JAVA_HOME\lib\tools.jar;sslTrusJarsigner-<version>.jar" `
  -keystore NONE `
  -storetype SSLTRUS `
  -storepass SSLTRUS `
  -providerClass com.racent.codesign.SSLTrusProvider `
  -sigalg SHA256withRSA `
  -tsa http://timestamp.sectigo.com `
  -signedjar "app-signed.jar" `
  "app-unsigned.jar" `
  "$env:SSLTRUS_JARSIGNER_CERT_CODE"

Al usarlo, tenga en cuenta lo siguiente:

• El número de certificado al final del comando debe coincidir con SSLTRUS_JARSIGNER_CERT_CODE.
• Se recomienda usar -signedjar para generar la salida en un archivo nuevo y evitar sobrescribir el JAR original.
• El ejemplo utiliza SHA256withRSA para completar la firma del código.
• Cuando no se necesite marca de tiempo, puede eliminar -tsa y la dirección de marca de tiempo que le sigue.

Marca de tiempo

Se recomienda añadir una marca de tiempo confiable a la firma de los JAR que se publiquen oficialmente.

En el ejemplo se utiliza:

http://timestamp.sectigo.com

Parámetro correspondiente:

-tsa http://timestamp.sectigo.com

Las marcas de tiempo se utilizan para demostrar el momento en que se realizó la firma y no suben el archivo JAR original al servidor de marca de tiempo.

Si necesita utilizar otro servicio de marca de tiempo, puede reemplazar la dirección después de -tsa por la dirección TSA que cumpla con la política de firma real.

Para obtener información sobre los diferentes servicios de marca de tiempo y la selección en entornos de producción, consulte Recursos de referencia.

Firma XML

sslTrusJarsigner también ofrece capacidades de firma digital XML.

Los archivos XML pueden generar una XMLDSig Enveloped Signature mediante el comando sign-xml.

Durante el proceso de firma, la generación del resumen y la estructura de firma requeridos por XMLDSig se realiza localmente, mientras que la firma real con la clave privada RSA la completa el servicio remoto de firma de código.

Linux y macOS

java -jar sslTrusJarsigner-<version>.jar \
  sign-xml \
  "input.xml" \
  "signed.xml" \
  "$SSLTRUS_JARSIGNER_CERT_CODE"

Windows PowerShell

java -jar sslTrusJarsigner-<version>.jar `
  sign-xml `
  "input.xml" `
  "signed.xml" `
  "$env:SSLTRUS_JARSIGNER_CERT_CODE"

De forma predeterminada, el KeyInfo generado solo contiene el certificado hoja. Si el receptor requiere que el XML incluya la cadena de certificados completa, puede agregar el parámetro --full-chain al final del comando.

Una vez completada la ejecución:

input.xml

Para el archivo XML original,

signed.xml

Para el archivo de salida que contiene la firma digital XML.

La clave privada de firma de código no se escribirá en el archivo XML ni se guardará en el equipo local.

Generar archivo de verificación

Una vez completada la firma, puede generar un archivo JKS para verificar la firma.

Linux y macOS:

java -jar sslTrusJarsigner-<version>.jar \
  generate-keystore \
  "$SSLTRUS_JARSIGNER_CERT_CODE" \
  "verify.jks" \
  "SSLTRUS"

Windows PowerShell:

java -jar sslTrusJarsigner-<version>.jar `
  generate-keystore `
  "$env:SSLTRUS_JARSIGNER_CERT_CODE" `
  "verify.jks" `
  "SSLTRUS"

Generar:

verify.jks

Este archivo solo se utiliza para la verificación de firmas y no puede usarse para ejecutar la firma de código.

La clave privada de firma de código permanece almacenada en el HSM remoto y no se escribirá en verify.jks.

Verificar la firma JAR

Utilice el verify.jks generado para verificar la firma:

jarsigner \
  -verify \
  -verbose \
  -certs \
  -keystore "verify.jks" \
  -storetype JKS \
  -storepass "SSLTRUS" \
  "app-signed.jar"

Si solo necesita ver la información de firma ya existente en el JAR, puede ejecutar:

jarsigner -verify -verbose -certs "app-signed.jar"

La verificación de la firma solo comprueba las firmas existentes y no vuelve a llamar a la clave privada remota para ejecutar la firma.

Número de firmas

El número de firmas de Jarsigner se calcula según las acciones de firma remota completadas con éxito.

Generalmente:

Operación	Número de firmas
Firmar con éxito un JAR una vez	1 vez
Firmar 3 JAR por separado	3 veces
Volver a ejecutar la firma sobre el mismo JAR	Se añade 1 vez más
jarsigner -verify Verificar firma	0 veces
Generar verify.jks	0 veces

Por lo tanto, el número de firmas depende principalmente de cuántas operaciones de firma exitosas se hayan ejecutado realmente, y no del número de archivos de código fuente del proyecto Java.

Para conocer las reglas detalladas, consulte Materiales de referencia.

Preguntas frecuentes

Falta Access Key, Access Secret o número de certificado

Confirme que la terminal actual ya tenga configurado:

SSLTRUS_JARSIGNER_ACCESS_KEY
SSLTRUS_JARSIGNER_ACCESS_SECRET
SSLTRUS_JARSIGNER_CERT_CODE

Después de configurar las variables de entorno, debe ejecutar el comando de firma en la misma sesión de terminal.

Invalid option: -providerPath

Si aparece:

Invalid option: -providerPath

Generalmente indica que se está utilizando JDK 8.

JDK 8 no utiliza el parámetro -providerPath que aparece en los ejemplos de JDK 9 y versiones posteriores; utilice en su lugar el comando para JDK 8 proporcionado en este artículo.

No se puede cargar SSLTrusProvider

Si aparece un aviso de que no se puede cargar:

com.racent.codesign.SSLTrusProvider

Revise lo siguiente:

• Si la ruta de sslTrusJarsigner-<version>.jar es correcta.
• Si el número de versión en el nombre del archivo coincide con el archivo real.
• Si JAVA_HOME en un entorno JDK 8 apunta a un JDK completo.

No se encuentra el certificado o el alias

Revise lo siguiente:

• Si el número de certificado es correcto.
• Si el número de certificado especificado al final del comando coincide con SSLTRUS_JARSIGNER_CERT_CODE.
• Si el Access Key y el Access Secret actuales tienen permiso para usar este certificado.

Error en la solicitud de firma remota

Revise lo siguiente:

• Si la red actual puede acceder al servicio de firma de código remota.
• Si la configuración del proxy, el firewall y el DNS es correcta.
• Si el Access Key y el Access Secret son correctos.
• Si el número de certificado es correcto.
• Si utiliza una dirección de servicio dedicada, si SSLTRUS_JARSIGNER_URL está configurada según la información de entrega real.

Al solucionar problemas, puede conservar el mensaje de error completo, pero antes de enviar registros o capturas de pantalla de errores, debe eliminar u ocultar credenciales confidenciales como el Access Secret.

Error de marca de tiempo

Confirme que la red actual pueda acceder al servidor de marca de tiempo especificado por -tsa.

Si el negocio lo permite, puede eliminarlo temporalmente:

-tsa <URL>

Vuelva a ejecutar la firma para determinar si el problema ocurre en la etapa de firma remota de código o en la etapa de solicitud de sello de tiempo.

Notas de seguridad

Durante la integración con Java, tenga en cuenta lo siguiente:

• El Access Secret debe guardarse como una credencial confidencial.
• No envíe las credenciales de acceso a un repositorio Git.
• No imprima el Access Secret completo en los registros.
• verify.jks solo se utiliza para verificación y no contiene una clave privada que pueda usarse para la firma remota.
• El sslTrusJarsigner Provider local no guarda la clave privada de firma de código.
• Las operaciones de firma con clave privada siempre las completa el servicio remoto de firma de código.
• En entornos automatizados, se recomienda inyectar las credenciales de acceso mediante CI/CD Secret o un sistema de gestión de credenciales dedicado.

Métodos de integración relacionados

Si lo que necesita firmar no son archivos Java JAR o XML, puede elegir otros métodos de integración según el escenario real:

Escenario	Método de integración
Firmar directamente mediante línea de comandos archivos EXE, DLL, MSI, etc.	Herramienta de cliente
Herramientas de Windows como Microsoft SignTool, Visual Studio, etc.	Windows Provider
Compilación automatizada con GitHub Actions, Electron Builder, etc.	CI/CD y herramientas de compilación
Desarrollar su propio cliente de firma remota	Integración API