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 la signature, la clé privée de signature de code reste toujours stockée dans le HSM cloud. La machine locale est responsable de générer les données à signer et la structure de signature, puis appelle le service distant via le fournisseur sslTrusJarsigner pour effectuer la signature avec la clé privée.

En plus de la signature de JAR, sslTrusJarsigner offre également la capacité de signature XMLDSig, utilisable dans les scénarios de signature numérique XML.

Préparation

Avant utilisation, veuillez préparer :

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

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

Télécharger sslTrusJarsigner

Téléchargez le dernier paquet de version depuis la page de publication de sslTrusJarsigner et décompressez-le.

Le paquet de version contient :

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

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

Vérifier l'environnement d'exécution

Tout d'abord, confirmez que Java et le jarsigner fourni avec le JDK fonctionnent correctement :

java -version
jarsigner -help

Vérifiez la version de sslTrusJarsigner :

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

Voir l’aide :

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

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

Configurer les informations d'identification d'accès

sslTrusJarsigner lit les informations d'identification d'accès au service de signature de code à distance et le numéro du certificat via des 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 d’assistance a fourni une adresse de service dédiée, il faut également configurer 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 un identifiant sensible : il ne doit pas être écrit dans le code source, dans des fichiers de configuration publics ni dans les journaux de build. Dans un environnement d’automatisation, il est recommandé de l’injecter via un Secret CI/CD ou un autre mécanisme de gestion des identifiants.

Signature JAR

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

L’exemple suivant va :

app-unsigned.jar

Racent

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

JDK 8 charge les fournisseurs différemment des JDK 9 et versions ultérieures.

Tout d’abord, vérifiez :

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"

Lors de l’utilisation, veuillez noter :

• Le numéro de certificat à la fin de la commande doit correspondre à 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.
• Si l’horodatage n’est pas nécessaire, vous pouvez supprimer -tsa et 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ètres correspondants :

-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 l’adresse TSA conforme à la politique de signature réelle.

Pour plus d’informations sur les différents services d’horodatage et le choix en environnement de production, consultez Références.

Signature XML

sslTrusJarsigner fournit également la capacité de signature numérique XML.

Les fichiers XML peuvent générer une signature XMLDSig Enveloped 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 de signature de code à distance.

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, la sortie KeyInfo ne contient que le certificat feuille. Si le destinataire exige que le XML inclue la chaîne de certificats complète, vous pouvez ajouter 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 les fichiers de sortie contenant une signature numérique XML.

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

Générer un fichier de vérification

Une fois la signature terminée, vous pouvez générer un fichier JKS utilisé 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 utilisé uniquement 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 ne sera 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 seulement 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 ne fait que contrôler la signature existante ; elle ne rappelle pas la clé privée distante pour effectuer une signature.

Nombre de signatures

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

En général :

Opération	Nombre de signatures
Signature réussie d’un JAR une fois	1
Signature de 3 JAR séparément	3
Exécution d’une nouvelle signature sur le même JAR	+1
jarsigner -verify vérification de signature	0
Génération d’un verify.jks	0

Par conséquent, le nombre de signatures dépend principalement du nombre d’opérations de signature réellement réussies, 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 défini :

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

Indique généralement que JDK 8 est actuellement utilisé.

JDK 8 n'utilise pas le paramètre -providerPath présent dans les exemples de JDK 9 et versions ultérieures. Veuillez utiliser les commandes JDK 8 fournies dans ce document.

Impossible de charger SSLTrusProvider

Si une erreur indiquant l'impossibilité de charger s'affiche :

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 bien 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 fin de commande correspond bien à SSLTRUS_JARSIGNER_CERT_CODE.
• Si la clé d’accès (Access Key) et le secret d’accès (Access Secret) actuels disposent bien des autorisations d’utilisation de ce certificat.

Échec de la demande de signature à distance

Veuillez vérifier :

• Si le réseau actuel permet d’accéder au service de signature de code à distance.
• Si la configuration du proxy, du pare-feu et du DNS est correcte.
• Si la clé d’accès (Access Key) et le secret d’accès (Access Secret) sont corrects.
• Si le numéro du certificat est correct.
• Si une adresse de service dédiée est utilisée, vérifiez que SSLTRUS_JARSIGNER_URL est configurée conformément aux informations réellement fournies.

Lors du diagnostic, vous pouvez conserver les messages d’erreur complets. Toutefois, avant de transmettre des journaux ou des captures d’écran d’erreur, supprimez ou masquez les informations sensibles telles que le secret d’accès (Access Secret).

Échec de l’horodatage

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

Si l’activité le permet, vous pouvez temporairement supprimer :

-tsa <URL>

Exécutez à nouveau la signature pour déterminer si le problème survient lors de la signature de code à distance ou lors de la demande de cachet temporel.

Consignes de sécurité

Lors de l’intégration Java, il convient de respecter les points suivants :

• L’Access Secret doit être conservé comme un identifiant sensible.
• Ne soumettez pas les identifiants 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 fournisseur local sslTrusJarsigner n’enregistre pas la clé privée de signature de code.
• L’opération de signature avec clé privée est toujours réalisée par le service de signature de code à distance.
• Dans un environnement automatisé, il est recommandé d’injecter les identifiants d’accès via des secrets CI/CD ou un système dédié de gestion des identifiants.

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
Microsoft SignTool, Visual Studio et autres outils Windows	Fournisseur Windows
GitHub Actions, Electron Builder et autres builds automatisés	CI/CD et outils de build
Développement autonome d’un client de signature à distance	Intégration API