Integración con Java

sslTrus proporciona sslTrusJarsigner Java Provider, que puede utilizarse junto con la herramienta jarsigner integrada 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 lado local se encarga de generar los datos a firmar y la estructura de firma, e invoca el 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 capacidades de firma XMLDSig, que pueden 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 su suma de comprobación SHA-256 antes de usarlo.

Comprobar el entorno de ejecución

Primero, confirme que Java y la herramienta jarsigner incluida en el JDK funcionan correctamente:

java -version
jarsigner -help

Verificar la versión de sslTrusJarsigner:

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

Consulte la ayuda:

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

Si el comando jarsigner no existe, confirme que tiene instalado un JDK completo y no solo un entorno de ejecución que contenga únicamente el Java Runtime.

Configurar las credenciales de acceso

sslTrusJarsigner lee las credenciales de acceso al servicio remoto de firma de código y el número de certificado mediante 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 soporte le proporciona una dirección de servicio dedicada, también deberá 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.

El Access Secret es una credencial confidencial y no debe escribirse en el código fuente, archivos de configuración públicos ni registros de compilación. En entornos automatizados, se recomienda inyectarlo mediante CI/CD Secrets u otro mecanismo 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

Firma de salida:

app-signed.jar

JDK 9 o superior

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 un archivo nuevo y evitar sobrescribir el JAR original.
• El ejemplo utiliza SHA256withRSA para completar la firma de código.
• Si no necesita marca de tiempo, puede eliminar -tsa y la dirección de marca de tiempo que le sigue.

Marca de tiempo

Se recomienda agregar 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ámetros correspondientes:

-tsa http://timestamp.sectigo.com

El sello de tiempo se utiliza para demostrar el momento en que se realizó la firma y no sube el archivo JAR original al servidor de sellado de tiempo.

Si necesita utilizar otro servicio de sellado 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 sellado de tiempo y la selección en entornos de producción, consulte Referencias.

Firma XML

sslTrusJarsigner también ofrece la capacidad de firma digital XML.

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

Durante el proceso de firma, el equipo local se encarga de generar el resumen y la estructura de firma requeridos por XMLDSig; la firma real con la clave privada RSA la realiza 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"

La salida predeterminada de KeyInfo solo incluye el certificado hoja. Si el receptor requiere que el XML contenga la cadena de certificados completa, puede agregar el parámetro --full-chain al final del comando.

Después de completar 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 el 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"

Genera:

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 del 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 existente en el JAR, puede ejecutar:

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

Verificar 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 realmente completadas con éxito.

Normalmente:

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 en el mismo JAR	Se añade 1 vez más
jarsigner -verify Verificar la 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 Referencia.

Preguntas frecuentes

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

Confirme que la terminal actual ya esté configurada:

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

Suele indicar que se está utilizando JDK 8.

JDK 8 no usa el parámetro -providerPath de los ejemplos de JDK 9 y versiones posteriores; use 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

Por favor, compruebe:

• Si la ruta 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 el entorno JDK 8 apunta a un JDK completo.

No se encuentra el certificado o el alias

Por favor, compruebe:

• 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 la Access Key y el Access Secret actuales tienen permiso para usar este certificado.

Fallo en la solicitud de firma remota

Por favor, compruebe:

• Si la red actual puede acceder al servicio de firma de código remota.
• Si la configuración del proxy, el cortafuegos y el DNS es correcta.
• Si la 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á configurado 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 error, debe eliminar u ocultar credenciales sensibles como el Access Secret.

Fallo de la marca de tiempo

Confirme que la red actual puede 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 de código remota 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 credenciales de acceso a repositorios Git.
• No imprima el Access Secret completo en los registros.
• verify.jks solo se utiliza para verificación y no contiene ninguna clave privada que pueda usarse para la firma remota.
• El Provider local sslTrusJarsigner no guarda claves privadas de firma de código.
• Las operaciones de firma con clave privada siempre las realiza el servicio remoto de firma de código.
• En entornos automatizados, se recomienda inyectar las credenciales de acceso mediante CI/CD Secrets o un sistema dedicado de gestión de credenciales.

Métodos de integración relacionados

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

Escenario	Método de integración
Firma directa mediante línea de comandos de 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
Desarrollo propio de un cliente de firma remota	Integración API