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 numéro de certificat.
• Le fichier JAR à signer ou le fichier XML TIMS/1E.

Veuillez remplacer <version>, les identifiants, le numéro de certificat et les chemins de fichiers mentionnés dans ce document par les valeurs réelles.

Téléchargement

Téléchargez la dernière version publiée via la page suivante :

Télécharger le dernier package

Après téléchargement et décompression du fichier ZIP, vous obtiendrez :

• sslTrusJarsigner-<version>.jar
• Fichier de vérification SHA-256

Il est recommandé de vérifier l'intégrité du fichier JAR à l'aide du fichier de vérification avant utilisation.

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

Exécutez les commandes suivantes pour confirmer que Java, jarsigner et les fichiers d'outils sont disponibles :

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

Afficher les informations d'aide :

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

Configuration des 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, vous devez également configurer :

Linux et macOS :

export SSLTRUS_JARSIGNER_URL="YOUR_SERVICE_URL"

Windows PowerShell :

$env:SSLTRUS_JARSIGNER_URL = "YOUR_SERVICE_URL"

Lorsqu’aucune adresse de service dédiée n’est fournie, veuillez ne pas définir cette variable.

Signature

L’exemple suivant signe app-unsigned.jar et l’enregistre sous app-signed.jar. Les paramètres fixes doivent être utilisés tels quels, comme 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 la version complète du JDK 8.

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 de nouveaux fichiers 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 le suit.

Signature XML (XMLDSig)

Le XML TIMS/1E est signé avec la commande sign-xml pour générer une signature enveloped XML Digital Signature (XMLDSig). La clé privée reste uniquement dans le service de signature à distance ; 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# et le nœud Signature est écrit comme dernier 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	Enveloped signature
Portée de la signature	Document XML entier, Reference URI=""
Reference Transform	Enveloped Signature Transform
Canonicalization	Inclusive Canonical XML 1.0
Algorithme de digest	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 digest ni de construire SignatureValue. L’outil remplit KeyInfo/X509Data avec le certificat feuille du certificat distant et écrit le SignatureValue final dans le XML.

Inclusion de la chaîne de certificats complète

La sortie par défaut ne contient que le certificat feuille, afin de réduire la taille du XML et de rester cohérent avec les fichiers TIMS/1E courants. Si le destinataire exige que la chaîne de certificats intermédiaires soit incluse dans le XML, ajoutez --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 n’affecte que la liste des certificats dans KeyInfo/X509Data, sans modifier la portée de la signature, l’algorithme de résumé ou l’algorithme de signature. Cette option peut être placée avant ou après l’identifiant du certificat ; lorsqu’aucun identifiant n’est fourni, SSLTRUS_JARSIGNER_CERT_CODE est utilisé.

Restrictions d’entrée et d’utilisation

• L’entrée doit être un XML bien formé incluant un nœud racine.
• Le fichier d’entrée ne doit pas déjà contenir de nœud XMLDSig Signature ; l’outil refusera une signature en double pour éviter des fichiers dont la portée de signature ne peut pas être confirmée.
• Actuellement, seule la signature enveloped de l’intégralité du document est prise en charge ; les signatures détachées, les signatures par ID d’élément ou les profils XMLDSig personnalisés ne sont pas pris en charge.
• L’outil désactive les entités externes XML et le chargement de DTD externes, donc les XML nécessitant l’expansion d’entités externes ne sont pas acceptés.
• Après la signature, 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 original et écrivez la signature dans un nouveau fichier de sortie.

Génération du 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 effectuer une signature.

Vérification de 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 d'un JAR :

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

Questions fréquentes

Message indiquant qu’il manque Access Key, Access Secret ou le numéro de certificat

Veuillez confirmer que les variables d’environnement suivantes sont 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, vous devez exécuter la commande de signature dans la même fenêtre de terminal.

Message Option non valide : -providerPath

Vous utilisez actuellement JDK 8. Veuillez utiliser la commande de signature JDK 8 décrite dans cet article.

Message indiquant que com.racent.codesign.SSLTrusProvider ne peut pas être chargé

Veuillez vérifier :

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

Message indiquant que le certificat ou l’alias est introuvable

Veuillez vérifier :

• Que le numéro de certificat est correct.
• Que le numéro de certificat à la fin de la commande correspond à la variable d’environnement.
• Que les informations d’identification actuelles sont autorisées à utiliser ce certificat.

Échec de la demande de signature

Veuillez vérifier :

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

Si le problème persiste, veuillez conserver le message d’erreur complet et contacter le support technique. Avant d’envoyer le message d’erreur, veuillez supprimer ou masquer 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 la politique de sécurité le permet, vous pouvez temporairement supprimer -tsa et l’adresse qui suit, puis réexécuter la signature pour localiser le problème.

Consignes de sécurité

• Ne conservez pas de véritables Access Secret dans le code source, la documentation, les scripts partagés ou les images.
• Ne partagez pas publiquement de lignes de commande, d’historique de terminal ou de journaux de pipeline contenant des informations d’identification.
• Dans les environnements automatisés, injectez les informations d’identification à l’aide de variables de clé protégées.
• Téléchargez les outils à partir de canaux de publication de confiance et vérifiez l’intégrité des fichiers avant utilisation.
• Il est recommandé de conserver le fichier JAR d’origine non signé.