Signing jar files with jarsigner

This article is a pragmatic tutorial to the  and   Java tools. Most of the information in this note can be found in the `help' section of the jarsigner and keytool utilities:

Status
Released 14/1/2008

Author
Pierre Parrend

Criteria for Signature Validity
The criteria of validity of a digital signature are the following:
 * No modification of the archive resources after the signature,
 * certificate not outdated (or not yet valid).

Moreover, the signer of the archive must be known, i.e. its public key certificate must be identified as trusted before the validation. Otherwise, any malicious third party can forge a similar certificate, potentially with the same signer name, and present a coherent signed archive.

Additional criteria of archive signature validity are defined in the context of the OSGi framework, that are specific to the deployment of components from third party repositories:
 * No resource removed from the archive after the signature,
 * No resource added from the archive after the signature,
 * The digital signature must immediately follow the Manifest file of the archive, to prevent caching malicious files.

This means that according to the security level you need, the Sun criteria of signature validity may not be sufficient.

Use of the JarSigner Tool
The Sun `Jarsigner' is a utility delivered along with Sun JDK. It has the ability to sign Java Archives (Jars), and to verify the validity their signature.

So as to test the jarsigner tool, you need to have a public/private key pair. The example are given with Bob's key pair.
 * The data used to conduce tests in this tutorial are found in the [[Media:jarsigner-test.zip]] file. Store it on you computer, and unzip the archive.

Following files are used:
 * the Keystore file, refArchive/testkeystore, contains the private and public key for Bob, and the public key for Alice
 * Bob's Public Key Certificate is stored in the file refArchive/bob.cert (it is also available directly from the keystore)
 * Alice's Public Key Certificate is stored in the file refArchive/alice.cert (it is also available directly from the keystore)
 * the archives fridgebundle-1.1.jar, fridgebundle-1.1.signed.jar, fridgebundle-1.1.unknownsigner.jar, bindex-manifestMainAttrsModified-1.0.jar, are various Jar Files, that are used for the test.

Sign a given jar archive
Sign the archive  with bob's private key:

Check that a signed jar is valid
Verify the signed archive  using the keystore  :

jarsigner -verify -keystore refArchive/testkeystore refArchive/fridgebundle-1.1.signed.jar

Verify a signed jar with unknown signer
Verify the signed archive  using the keystore  :

jarsigner -verify -keystore refArchive/testkeystore refArchive/fridgebundle-1.1.unknownsigner.jar

Some test with an invalid archive signature
Verify the signed archive  using the keystore  :

jarsigner -verify refArchive/bindex-manifestMainAttrsModified-1.0.jar jarsigner: java.lang.SecurityException: Invalid signature file digest for Manifest main attributes

Remark: No warning is issued by the Sun Jarsigner if the signer of the archive is unknow to you. No matter who has signed the archive, this latter will be considered as valid !

Use of the Keytool Utility
The Sun keytool utility supports the management of DSA and RSA asymetric key pairs, as well as the management of public key certificates of third party actors.

Option:

Example: the keystore file is named, and is accessible with the password
 * use an existing keystore file

If you specify a keystore that does not exist in the keytool options, it is automatically created and initialized with the given parameters (e.g. the password).

The default keystore in *nix systems is /home/user/.keystore. It is overridden by the  option.

You can perform following tests so as to learn how to use the keytool:

Create a new DSA Key Pair for Bob
Generate a new DSA Key Pair for the user Bob, using the keystore :

keytool -genkey -keystore refArchive/testkeystore -alias bob


 * The default algorithm for Key Pairs is DSA. The -sigalg option can be set to generate other types of keys, such as DSA ones.
 * The Distinguished Name for Bob is:

the password for accessing to the private key of Bob is:

Visualize the content of the keystore
Visualize the content of the keystore file :

keytool -list -keystore refArchive/testkeystore Enter keystore password: password


 * which will show something like this if the keystore has just been created:

Extract of the public key certificate of Bob for dissemination
Store the Public Key Certificate for Bob in the file, from the keystore file  :

keytool -export -keystore refArchive/testkeystore -alias bob > refArchive/bob2.cert


 * If Bob want that the world can check whether he is the one which signs Jar files, he has to make his public key available to them.

Visualize a certificate
Visualize the content of the Public Key Certificate for Bob, contained in the file :

keytool -printcert -file refArchive/bob.cert


 * which will sow you something like:

Import a certificate
Import the Public Key Certificate of Alice  in the keystore file  :

keytool -import -keystore refArchive/testkeystore -file refArchive/alice.cert -alias alice password: password Trust this certificate? [no]: yes


 * Bob may want to communicate with Alice. He needs to import her Public Key Certificate into his own keystore, and mark it as `trusted'.

Visualize again the content of the keystore
keytool -list -keystore refArchive/testkeystore Enter keystore password: password

Keystore type: jks Keystore provider: SUN Your keystore contains 2 entries alice, Jan 28, 2007, trustedCertEntry, Certificate fingerprint (MD5): 01:29:74:E3:51:9E:31:87:0E:AB:C4:5C:0B:6B:34:03 bob, Jan 28, 2007, keyEntry, Certificate fingerprint (MD5): 5C:B4:82:80:46:5D:C1:0B:48:DE:B6:50:F0:22:24:9D - a trustedCertEntry, which contains the Public Key Certificate of alice - a keyentry, which contains the public/private key pair of Bob.
 * Which shows you something like:
 * Two different types of entries are available:

= References =

You can find further informations here:


 * Sun Jarsigner page
 * Sun Keytool page
 * Jarsigner man page
 * Principles of OSGi bundles signature