Intégration Java

sslTrus fournit un fournisseur Java sslTrusJarsigner qui peut être utilisé avec l’outil jarsigner intégré au JDK pour signer des fichiers JAR Java via un service de signature de code à distance.

Pendant le processus de signature, la clé privée de signature de code est conservée en permanence dans le HSM cloud. En local, les données à signer et la structure de signature sont générées, puis le fournisseur sslTrusJarsigner est utilisé pour appeler le service distant afin d’effectuer la signature avec la clé privée.

En plus de la signature JAR, sslTrusJarsigner offre également la signature XMLDSig, adaptée aux scénarios de signature numérique XML.

Préparation

Avant utilisation, préparez :

• JDK 8 ou version ultérieure.
• sslTrusJarsigner-<version>.jar.
• Access Key.
• Access Secret.
• Numéro de certificat (Cert Code).
• Le fichier JAR ou XML à signer.

Dans les exemples de cet article, le <version>, les identifiants d’accès, le numéro de certificat et les chemins de fichiers doivent être remplacés par les valeurs réelles.

Télécharger sslTrusJarsigner

Téléchargez la dernière version depuis la page de publication de sslTrusJarsigner et décompressez-la.

Le package de publication contient :

sslTrusJarsigner-<version>.jar
SHA-256 校验文件

Il est recommandé de vérifier l’intégrité de sslTrusJarsigner-<version>.jar à l’aide du hachage SHA-256 avant utilisation.

Vérifier l’environnement d’exécution

Commencez par confirmer que Java et l’outil jarsigner fourni avec le JDK fonctionnent correctement :

java -version
jarsigner -help

Vérifiez la version de sslTrusJarsigner :

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

Consultez l’aide :

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

Si la commande jarsigner n'existe pas, vérifiez que vous avez installé un JDK complet et non un simple environnement d'exécution Java.

Configurer les identifiants d'accès

sslTrusJarsigner lit les identifiants d'accès et le numéro de certificat du service de signature de code à distance via les variables d'environnement.

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 définir SSLTRUS_JARSIGNER_URL.

Linux et macOS :

export SSLTRUS_JARSIGNER_URL="YOUR_SERVICE_URL"

Windows PowerShell :

$env:SSLTRUS_JARSIGNER_URL = "YOUR_SERVICE_URL"

Si aucune adresse de service dédiée n’est fournie, il n’est pas nécessaire de définir cette variable.

L’Access Secret est une information d’identification sensible et ne doit pas être écrit dans le code source, les fichiers de configuration publics ou les journaux de build. Dans les environnements d’automatisation, il est recommandé de l’injecter via un Secret CI/CD ou un autre mécanisme de gestion des informations d’identification.

Signature JAR

sslTrusJarsigner s’intègre à l’outil standard jarsigner via le mécanisme Java Security Provider.

L’exemple suivant va :

app-unsigned.jar

Après signature, le résultat est :

app-signed.jar

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

Le chargement du Provider sous JDK 8 diffère de celui de JDK 9 et des versions ultérieures.

Vérifiez d’abord :

JAVA_HOME

Vers le répertoire d’installation complet 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"

Points à noter lors de l’utilisation :

• Le numéro de certificat à la fin de la commande doit correspondre à celui de SSLTRUS_JARSIGNER_CERT_CODE.
• Il est recommandé d’utiliser -signedjar pour générer un nouveau fichier afin d’éviter d’écraser le JAR d’origine.
• L’exemple utilise SHA256withRSA pour effectuer la signature du code.
• Lorsque l’horodatage n’est pas nécessaire, vous pouvez supprimer -tsa ainsi que l’adresse du serveur d’horodatage qui suit.

Horodatage

Il est recommandé d’ajouter un horodatage de confiance à la signature des JAR destinés à une publication officielle.

Utilisé dans l’exemple :

http://timestamp.sectigo.com

Paramètre correspondant :

-tsa http://timestamp.sectigo.com

L'horodatage sert à prouver le moment où la signature a eu lieu, sans téléverser le fichier JAR original vers le serveur d'horodatage.

Si vous devez utiliser un autre service d'horodatage, vous pouvez remplacer l'adresse après -tsa par une adresse TSA conforme à la politique de signature réelle.

Pour en savoir plus sur les différents services d'horodatage et le choix en environnement de production, veuillez consulter les références.

Signature XML

sslTrusJarsigner offre également des capacités de signature numérique XML.

Les fichiers XML peuvent générer une signature enveloppée XMLDSig via la commande sign-xml.

Pendant le processus de signature, le résumé et la structure de signature requis par XMLDSig sont générés localement, tandis que la signature réelle avec la clé privée RSA est effectuée par le service distant de signature de code.

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"

Par défaut, le KeyInfo généré ne contient que le certificat feuille. Si le destinataire exige que le XML comporte la chaîne de certificats complète, ajoutez le paramètre --full-chain à la fin de la commande.

Une fois l’exécution terminée :

input.xml

pour le fichier XML d’origine,

signed.xml

Pour le fichier de sortie contenant la signature numérique XML.

La clé privée de signature de code n'est pas écrite dans le fichier XML, ni enregistrée sur l'ordinateur local.

Générer le fichier de vérification

Une fois la signature terminée, vous pouvez générer un fichier JKS pour vérifier la signature.

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"

Générer :

verify.jks

Ce fichier est uniquement utilisé pour la vérification de la signature et ne peut pas être utilisé pour exécuter la signature de code.

La clé privée de signature de code reste stockée dans le HSM distant et n'est pas écrite dans verify.jks.

Vérifier la signature JAR

Utilisez le verify.jks généré pour vérifier la signature :

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

Si vous avez uniquement besoin de consulter les informations de signature déjà présentes dans le JAR, vous pouvez exécuter :

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

La vérification de la signature se contente de contrôler les signatures existantes et ne rappelle pas la clé privée distante pour effectuer une signature.

Nombre de signatures

Le nombre de signatures de Jarsigner est calculé en fonction des opérations de signature à distance réellement abouties.

En règle générale :

Opération	Nombre de signatures
Signature réussie d’un JAR	1 fois
Signature séparée de 3 JAR	3 fois
Nouvelle signature du même JAR	+1 fois supplémentaire
jarsigner -verify vérification de la signature	0 fois
Génération de verify.jks	0 fois

Par conséquent, le nombre de signatures dépend principalement du nombre d’opérations de signature réellement abouties, et non du nombre de fichiers de code source du projet Java.

Pour les règles détaillées, veuillez consulter la documentation de référence.

Questions fréquentes

Absence de l’Access Key, de l’Access Secret ou du numéro de certificat

Vérifiez que le terminal actuel a bien été configuré :

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 session de terminal.

Invalid option: -providerPath

Si le message suivant apparaît :

Invalid option: -providerPath

Cela indique généralement que vous utilisez actuellement JDK 8.

JDK 8 n'utilise pas le paramètre -providerPath des exemples de JDK 9 et versions ultérieures. Veuillez utiliser les commandes JDK 8 fournies dans cet article.

Impossible de charger SSLTrusProvider

Si un message indique qu'il est impossible de charger :

com.racent.codesign.SSLTrusProvider

Veuillez vérifier :

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

Certificat ou alias introuvable

Veuillez vérifier :

• Si le numéro du certificat est correct.
• Si le numéro du certificat spécifié en dernier dans la commande correspond à SSLTRUS_JARSIGNER_CERT_CODE.
• Si l’Access Key et l’Access Secret actuels disposent de l’autorisation d’utilisation de ce certificat.

Échec de la demande de signature à distance

Veuillez vérifier :

• Si le réseau actuel peut accéder au service de signature de code à distance.
• Si la configuration du proxy, du pare-feu et du DNS est normale.
• Si l’Access Key et l’Access Secret sont corrects.
• Si le numéro du certificat est correct.
• En cas d’utilisation d’une adresse de service dédiée, si SSLTRUS_JARSIGNER_URL est configurée conformément aux informations effectivement livrées.

Lors du diagnostic, il est possible de conserver le message d’erreur complet, mais avant de soumettre des journaux ou des captures d’écran d’erreur, supprimez ou masquez les identifiants sensibles tels que l’Access Secret.

Échec de l’horodatage

Confirmez que le réseau actuel peut accéder au serveur d’horodatage désigné par -tsa.

Si votre activité le permet, vous pouvez temporairement supprimer :

-tsa <URL>

Exécutez à nouveau la signature pour déterminer si le problème se situe au niveau de la signature de code à distance ou de la requête d’horodatage.

Consignes de sécurité

Points d’attention lors de l’intégration Java :

• L’Access Secret doit être conservé comme une information d’identification sensible.
• Ne soumettez pas les informations d’identification d’accès à un dépôt Git.
• N’affichez pas l’Access Secret complet dans les journaux.
• verify.jks sert uniquement à la validation et ne contient aucune clé privée utilisable pour la signature à distance.
• Le Provider local sslTrusJarsigner ne conserve pas la clé privée de signature de code.
• L’opération de signature avec clé privée est toujours effectuée par le service de signature de code à distance.
• Dans un environnement automatisé, il est recommandé d’injecter les informations d’identification d’accès via les secrets CI/CD ou un système dédié de gestion des informations d’identification.

Méthodes d’intégration associées

Si les fichiers à signer ne sont pas des fichiers Java JAR ou XML, vous pouvez choisir d’autres méthodes d’intégration selon le scénario réel :

Scénario	Méthode d’intégration
Signature directe en ligne de commande de fichiers EXE, DLL, MSI, etc.	Outil client
Outils Windows tels que Microsoft SignTool, Visual Studio, etc.	Windows Provider
Builds automatisés avec GitHub Actions, Electron Builder, etc.	CI/CD et outils de build
Développement d’un client de signature à distance en interne	Intégration API