Guía de uso de sslTrusJarsigner

Preparación

Antes de usarlo, prepare lo siguiente:

• JDK 8 o superior.
• sslTrusJarsigner-<version>.jar.
• Access Key, Access Secret y número de certificado.
• Archivo JAR a firmar o archivo XML TIMS/1E.

Reemplace <version>, las credenciales, el número de certificado y las rutas de archivo en este artículo por los valores reales.

Descarga

Descargue el paquete de versión más reciente desde la siguiente página:

Descargar el paquete más reciente

Después de descargar y descomprimir el archivo ZIP, obtendrá:

• sslTrusJarsigner-<version>.jar
• Archivo de verificación SHA-256

Se recomienda verificar la integridad del archivo JAR con el archivo de verificación antes de usarlo.

Comprobar el entorno de ejecución

Ejecute el siguiente comando para confirmar que Java, jarsigner y los archivos de herramientas estén disponibles:

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

Consulta la información de ayuda:

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

Configurar credenciales

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 deberá configurar:

Linux y macOS:

export SSLTRUS_JARSIGNER_URL="YOUR_SERVICE_URL"

Windows PowerShell：

$env:SSLTRUS_JARSIGNER_URL = "YOUR_SERVICE_URL"

Cuando no se proporcione una dirección de servicio dedicada, no configure esta variable.

Firma

El siguiente ejemplo firma app-unsigned.jar y lo guarda como app-signed.jar. Utilice los parámetros fijos tal como se muestran en el ejemplo.

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

Primero confirme que JAVA_HOME apunta al JDK 8 completo.

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"

Nota

• El número de certificado al final del comando debe coincidir con SSLTRUS_JARSIGNER_CERT_CODE.
• Se recomienda utilizar siempre -signedjar para generar un archivo nuevo y evitar sobrescribir el JAR original.
• Si no necesita la marca de tiempo, puede eliminar -tsa y la dirección que le sigue.

Firma de XML (XMLDSig)

El XML de TIMS/1E utiliza el comando sign-xml para generar una firma enveloped de XML Digital Signature (XMLDSig). La clave privada permanece únicamente en el servicio de firma remota; la herramienta genera localmente el resumen y la estructura de firma necesarios para XMLDSig, y luego el servicio remoto completa la firma RSA.

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"

Formato de firma

La firma generada utiliza el espacio de nombres del estándar XMLDSig http://www.w3.org/2000/09/xmldsig#, y el nodo Signature se escribe en el archivo de salida como el último nodo hijo del nodo raíz. El perfil de firma actual es fijo:

Elemento	Valor fijo
Tipo de firma	Enveloped signature
Alcance de la firma	Documento XML completo, Reference URI=""
Reference Transform	Enveloped Signature Transform
Canonicalization	Inclusive Canonical XML 1.0
Algoritmo de resumen	SHA-256
Algoritmo de firma	RSA-SHA256
KeyInfo	X509Data, incluye el certificado hoja por defecto

La parte que llama no necesita calcular el resumen ni construir el SignatureValue por sí misma. La herramienta utiliza el certificado hoja del certificado remoto para completar el KeyInfo/X509Data y escribe en el XML el SignatureValue final.

Incluir la cadena de certificados completa

De forma predeterminada, la salida solo incluye el certificado hoja, para reducir el tamaño del XML y mantener la coherencia con los archivos TIMS/1E comunes. Si el receptor requiere que el XML incluya la cadena de certificados intermedios, agregue --full-chain al final del comando:

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

--full-chain solo afecta a la lista de certificados en KeyInfo/X509Data, no cambia el ámbito de la firma, el algoritmo de resumen ni el algoritmo de firma. Esta opción puede colocarse antes o después del número de certificado; si no se proporciona un número de certificado, se utiliza SSLTRUS_JARSIGNER_CERT_CODE.

Limitaciones de entrada y uso

• La entrada debe ser XML con formato correcto y contener un nodo raíz.
• El archivo de entrada no puede contener ya un nodo XMLDSig Signature; la herramienta rechazará firmas duplicadas para evitar generar archivos cuyo ámbito de firma no pueda confirmarse.
• Actualmente solo se admite la firma enveloped de todo el documento; no se admiten firmas detached, firmas por ID de elemento ni perfiles XMLDSig personalizados.
• La herramienta desactiva la carga de entidades externas XML y DTD externos, por lo que no acepta XML que dependa de la expansión de entidades externas.
• Una vez completada la firma, no modifique la estructura, el texto, los atributos ni los espacios de nombres del XML; cualquier cambio de este tipo provocará un fallo en la verificación XMLDSig. Conserve siempre el archivo de entrada original y escriba el resultado de la firma en un nuevo archivo de salida.

Generar archivo de verificación

Después de firmar, puede generar el archivo JKS necesario para la verificación:

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"

verify.jks solo se utiliza para verificar la firma, no para ejecutar la firma.

Verificar la firma

Utilice el verify.jks generado para verificar el JAR firmado:

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

Si solo necesita ver la información de firma del JAR:

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

Preguntas frecuentes

Indica que faltan Access Key, Access Secret o número de certificado

Confirme que la terminal actual tenga configuradas las siguientes variables de entorno:

• 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 ventana de terminal.

Indica Opción no válida: -providerPath

Actualmente está utilizando JDK 8. Utilice el comando de firma para JDK 8 descrito en este artículo.

Indica que no se puede cargar com.racent.codesign.SSLTrusProvider

Compruebe 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 el JAVA_HOME de JDK 8 apunta a un JDK completo.

Indica que no se encuentra el certificado o el alias

Compruebe lo siguiente:

• Si el número de certificado es correcto.
• Si el número de certificado al final del comando coincide con la variable de entorno.
• Si las credenciales actuales tienen permiso para usar ese certificado.

Error en la solicitud de firma

Compruebe lo siguiente:

• La conexión de red, el proxy y la configuración del firewall.
• Si las credenciales y el número de certificado son correctos.
• Si la dirección del servicio dedicado está configurada según lo proporcionado por el personal de servicio.

Si el problema persiste, conserve el mensaje de error completo y póngase en contacto con el soporte técnico. Antes de enviar el mensaje de error, elimine u oculte las credenciales.

Error de marca de tiempo

Confirme que la red actual pueda acceder a la dirección de marca de tiempo indicada en el comando. Si el negocio lo permite, puede eliminar temporalmente -tsa y la dirección que le sigue, y volver a ejecutar la firma para localizar el problema.

Notas de seguridad

• No guarde el Access Secret real en código fuente, documentación, scripts compartidos ni imágenes.
• No comparta externamente líneas de comando, historial de terminal ni registros de pipeline que contengan credenciales.
• En entornos automatizados, inyecte credenciales mediante variables de secreto protegidas.
• Descargue las herramientas desde canales de publicación confiables y verifique la integridad de los archivos antes de usarlas.
• Se recomienda conservar los archivos JAR originales sin firmar.