Guía de uso de sslTrusJarsigner

Preparación

Antes de usarlo, prepare lo siguiente:

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

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

Descargar

Descarga el paquete de la última versión 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 según el archivo de suma de comprobación antes de usarlo.

Comprobar el entorno de ejecución

Ejecute los siguientes comandos 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 le ha proporcionado 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"

Si no se proporciona 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 exactamente como en el ejemplo.

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

Primero confirme que JAVA_HOME apunta a un 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 usar 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 XML (XMLDSig)

TIMS/1E XML 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 requeridos por 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 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 se fija de la siguiente manera:

Elemento	Valor fijo
Tipo de firma	Enveloped signature
Alcance de la firma	Todo el documento XML, Reference URI=""
Transformación de referencia	Enveloped Signature Transform
Canonicalización	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 llamante no necesita calcular el resumen por sí misma ni construir SignatureValue.La herramienta rellenará KeyInfo/X509Data con el certificado hoja del certificado remoto y escribirá el SignatureValue final en el XML.

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 destinatario requiere que el XML incluya la cadena de certificados intermedios, añada --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, sin modificar el alcance 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 el número de certificado, se utiliza SSLTRUS_JARSIGNER_CERT_CODE.

Entrada y restricciones de uso

• La entrada debe ser XML bien formado 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 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 se aceptan archivos XML que dependan de la expansión de entidades externas.
• No modifique la estructura, el texto, los atributos ni los espacios de nombres del XML después de completar la firma; cualquier cambio de este tipo provocará el fallo de 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 validació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 se utiliza únicamente para verificar la firma y no puede emplearse 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 la firma del JAR:

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

Preguntas frecuentes

Aviso: falta la clave de acceso, el secreto de acceso o el número de certificado

Confirme que el terminal actual ya tiene 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.

Indicación Opción no válida: -providerPath

Actualmente se utiliza JDK 8.Utilice el comando de firma de JDK 8 descrito en este artículo.

Mensaje: No se puede cargar com.racent.codesign.SSLTrusProvider

Revise:

• ¿Es correcta la ruta sslTrusJarsigner-<version>.jar?
• ¿Coincide el número de versión en el nombre del archivo con el archivo real?
• Para JDK 8, ¿JAVA_HOME apunta al JDK completo?

Aviso: 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 la credencial actual tiene permiso para usar ese certificado.

Error en la solicitud de firma

Compruebe:

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

Si el problema persiste, conserve el mensaje de error completo y contacte al 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 puede acceder a la dirección de marca de tiempo del comando.Si el negocio lo permite, puede eliminar temporalmente -tsa y las direcciones posteriores, y ejecutar la firma nuevamente para localizar el problema.

Consideraciones de seguridad

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