Guide d’utilisation de sslTrusJarsigner

Préparation

Avant utilisation, veuillez préparer :

• JDK 8 ou version ultérieure.
• sslTrusJarsigner-<version>.jar.
• Access Key, Access Secret et le numéro du certificat.
• Le fichier JAR à signer ou le fichier XML TIMS/1E.

Veuillez remplacer <version>, les identifiants, le numéro du certificat et le chemin du fichier dans cet article par les valeurs réelles.

Téléchargement

Téléchargez le dernier package publié via la page suivante :

Télécharger le dernier package

Après avoir téléchargé et décompressé le fichier ZIP, vous obtiendrez :

• sslTrusJarsigner-<version>.jar
• Fichier de somme de contrôle SHA-256

Il est recommandé de vérifier l’intégrité du fichier JAR à l’aide du fichier de somme de contrôle avant utilisation.

Vérification de l’environnement d’exécution

Exécutez la commande suivante pour confirmer que Java, jarsigner et le fichier de l’outil sont disponibles :

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

Afficher les informations d’aide :

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

Configurer les identifiants

Linux et 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 le personnel de service a fourni une adresse de service dédiée, il est également nécessaire de configurer :

Linux et macOS :

export SSLTRUS_JARSIGNER_URL="YOUR_SERVICE_URL"

Windows PowerShell :

$env:SSLTRUS_JARSIGNER_URL = "YOUR_SERVICE_URL"

Ne définissez pas cette variable si aucune adresse de service dédiée n’est fournie.

Signature

L’exemple suivant signe app-unsigned.jar et l’enregistre sous app-signed.jar. Utilisez les paramètres fixes tels quels, comme indiqué dans l’exemple.

JDK 9 ou version ultérieure

Linux et 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

Veuillez d'abord confirmer que JAVA_HOME pointe vers un JDK 8 complet.

Linux et 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"

Remarque

• Le numéro de certificat à la fin de la commande doit correspondre à SSLTRUS_JARSIGNER_CERT_CODE.
• Il est recommandé de toujours utiliser -signedjar pour générer un nouveau fichier, afin d’éviter d’écraser le JAR d’origine.
• Si l’horodatage n’est pas nécessaire, vous pouvez supprimer -tsa et l’adresse qui suit.

Signature XML (XMLDSig)

Le XML TIMS/1E utilise la commande sign-xml pour générer une signature XML Digital Signature (XMLDSig) enveloppée. La clé privée reste uniquement conservée dans le service de signature distant ; l’outil génère localement le condensé et la structure de signature requis par XMLDSig, puis le service distant effectue la signature RSA.

Linux et 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"

Format de signature

La signature générée utilise l’espace de noms standard XMLDSig http://www.w3.org/2000/09/xmldsig#, le nœud Signature est écrit comme dernier nœud enfant du nœud racine dans le fichier de sortie. Le profil de signature actuel est fixé comme suit :

Élément	Valeur fixe
Type de signature	Signature enveloppée (Enveloped signature)
Portée de la signature	L’ensemble du document XML, Reference URI=""
Reference Transform	Enveloped Signature Transform
Canonicalisation	Inclusive Canonical XML 1.0
Algorithme de résumé	SHA-256
Algorithme de signature	RSA-SHA256
KeyInfo	X509Data, inclut par défaut le certificat feuille

L’appelant n’a pas besoin de calculer lui-même le résumé ni de construire le SignatureValue. L’outil utilisera le certificat feuille du certificat distant pour remplir le KeyInfo/X509Data et écrira dans le XML le SignatureValue final.

Inclusion de la chaîne de certificats complète

Par défaut, la sortie ne contient que le certificat feuille, afin de réduire la taille du XML et de rester cohérente avec les fichiers TIMS/1E courants. Si le destinataire exige que le XML inclue la chaîne de certificats intermédiaires, veuillez ajouter --full-chain à la fin de la commande :

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

--full-chain affecte uniquement la liste des certificats dans KeyInfo/X509Data, sans modifier la portée de la signature, l’algorithme de résumé ni l’algorithme de signature. Cette option peut être placée avant ou après le numéro de certificat ; si aucun numéro de certificat n’est fourni, SSLTRUS_JARSIGNER_CERT_CODE est utilisé.

Entrées et restrictions d’utilisation

• L’entrée doit être un XML correctement formé et contenir un nœud racine.
• Le fichier d’entrée ne doit pas déjà contenir de nœud XMLDSig Signature ; l’outil refuse une double signature afin d’éviter de produire un fichier dont la portée de signature ne peut pas être confirmée.
• Actuellement, seule la signature enveloppée de l’ensemble du document est prise en charge ; la signature détachée, la signature par ID d’élément ou un profil XMLDSig personnalisé ne sont pas pris en charge.
• L’outil désactive le chargement des entités externes XML et des DTD externes ; il n’accepte donc pas un XML dont l’expansion dépend d’entités externes.
• Une fois la signature terminée, ne modifiez plus la structure, le texte, les attributs ou les espaces de noms du XML ; toute modification de ce type entraînera l’échec de la validation XMLDSig. Conservez toujours le fichier d’entrée d’origine et écrivez le résultat de la signature dans un nouveau fichier de sortie.

Générer le fichier de validation

Après la signature, vous pouvez générer le fichier JKS nécessaire à la validation :

Linux et 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 sert uniquement à vérifier la signature et ne peut pas être utilisé pour signer.

Vérifier la signature

Utilisez le verify.jks généré pour vérifier le JAR signé :

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

Si vous avez seulement besoin de consulter les informations de signature du JAR :

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

FAQ

Message indiquant l’absence d’Access Key, d’Access Secret ou du numéro de certificat

Veuillez confirmer que les variables d’environnement suivantes sont bien définies dans le terminal actuel :

• SSLTRUS_JARSIGNER_ACCESS_KEY
• SSLTRUS_JARSIGNER_ACCESS_SECRET
• SSLTRUS_JARSIGNER_CERT_CODE

Après avoir défini les variables d’environnement, exécutez la commande de signature dans la même fenêtre de terminal.

Message Option illégale : -providerPath

Vous utilisez actuellement JDK 8. Veuillez utiliser la commande de signature pour JDK 8 présentée dans cet article.

Message indiquant l’impossibilité de charger com.racent.codesign.SSLTrusProvider

Veuillez vérifier :

• si le chemin de sslTrusJarsigner-<version>.jar est correct.
• si le numéro de version dans le nom de fichier correspond bien au fichier réel.
• si le JAVA_HOME de JDK 8 pointe vers un JDK complet.

Message indiquant que le certificat ou l’alias est introuvable

Veuillez vérifier :

• si le numéro de certificat est correct.
• si le numéro de certificat à la fin de la commande correspond à la variable d’environnement.
• si les informations d’identification actuelles autorisent l’utilisation de ce certificat.

Échec de la demande de signature

Veuillez vérifier :

• la connexion réseau, le proxy et les paramètres du pare-feu.
• si les informations d’identification et le numéro de certificat sont corrects.
• si l’adresse du service dédié est configurée conformément aux informations fournies par le personnel de service.

Si le problème persiste, conservez le message d’erreur complet et contactez le support technique. Avant d’envoyer le message d’erreur, supprimez ou masquez les informations d’identification.

Échec de l’horodatage

Veuillez confirmer que le réseau actuel peut accéder à l’adresse d’horodatage indiquée dans la commande. Si les conditions métier le permettent, vous pouvez supprimer temporairement -tsa et l’adresse qui suit, puis exécuter à nouveau la signature afin d’identifier le problème.

Consignes de sécurité

• Ne conservez pas le véritable Access Secret dans le code source, la documentation, les scripts partagés ou les images.
• Ne partagez pas de lignes de commande, d’historiques de terminal ou de journaux de pipeline contenant des informations d’identification.
• Dans un environnement automatisé, injectez les informations d’identification via des variables secrètes protégées.
• Téléchargez les outils depuis des canaux de publication fiables et vérifiez l’intégrité des fichiers avant utilisation.
• Il est recommandé de conserver le fichier JAR original non signé.