The jarsigner Tool (Java Security)

A.2. The jarsigner Tool

The next tool we'll look at is the jarsigner tool; this tool creates signed JAR files. The jarsigner tool uses the information in a keystore to look up information about a particular entity and uses that information either to sign or to verify a JAR file. As we discussed in the section on keytool, the keystore that jarsigner uses is subject to the KeyStore class that has been installed into the virtual machine; if you have your own keystore implementation, jarsigner will be able to use it. Similarly, if you use the standard keystore implementation, but hold the keys in a file other than the default .keystore file, jarsigner will allow you to use that other file as well.

A signed JAR file is identical to a standard JAR file except that a signed JAR file contains two additional entries:

SIGNER.SF--A file containing an SHA message digest for each class file in the archive. The digest is calculated from the three lines in the manifest for the class file. The base of this name (SIGNER) varies; it is typically based upon the alias of the keystore entry used to sign the archive.
SIGNER.DSA--A file containing the digital signature of the .SF file. The base of this name matches the first part of the .SF file; the extension is the algorithm used to generate the signature. This file also contains the certificate of the entity that signed the archive.

The algorithm used to generate the signature depends upon the type of the key found in the keystore: if the key is a X509 (DSA) key, a DSA signature will be generated. If the key is an RSA key, an RSA signature will be generated (assuming you have installed a security provider capable of producing such signatures). If you have a keystore that contains other types of keys, jarsigner will be unable to use them to sign the JAR file.

These entries are held in the META-INF directory of the JAR file.

A.2.1. Creating a Signed JAR File

The simplest command to sign a JAR file is:

Class Definition

piccolo% jarsigner xyz.jar sdo

This command takes the existing JAR file xyz.jar and signs it using the private key of the given alias (sdo). The private key is obtained by searching for the given alias from the default keystore (which will be the .keystore file in the user.home directory unless a command-line argument is given). The signature files in this example will be named SDO.SF and SDO.DSA and will be added to the existing JAR file.

A JAR file can be signed by any number of entities simply by executing this command multiple times with different aliases. Each act of signing the JAR file creates a new set of .SF and .DSA files in the archive.

There are a number of options that can be used in conjunction with this command:

-keystore keystore: Specify the filename that the KeyStore class should use as the keystore.
-storepass storepass: Specify the global password that should be used to open the keystore. If this value is not provided, you will be prompted for it (which, as always, is the more secure way to enter a password).
-keypass password: Specify the password for the key entry of the given alias. If this value is not provided, you will be prompted for it.
-sigfile file: Specify the base name to be used for the .SF and .DSA files. The default for this value is the alias specified on the command line translated to all uppercase letters (e.g., SDO in the example above). If the alias name has more than eight letters, only the first eight letters are used. The file argument in this option can only contain uppercase letters, the digits 0-9, and an underscore; it must contain eight or fewer letters.
-signedjar file: Write the signed JAR file to the named file instead of adding the signature entries to the existing JAR file.
-verbose: Print out information as jarsigner progresses.

A.2.2. Verifying a JAR File

In the process of verifying a JAR file, jarsigner will use the public key of the certificate embedded in the JAR file to verify that the signature is valid. The simplest command to verify a JAR file is:

Class Definition

piccolo% jarsigner -verify xyz.jar
jar verified.

If the signature in the JAR file is not valid, jarsigner will produce this output:

Class Definition

jar is unsigned. (signatures missing or not parsable)

Verification accepts the following options:

-sigfile file

Use the given base name to look up the .SF and .DSA files. This option is useful when the JAR file has been signed by multiple entities.

-verbose

Provide verbose output for the verification, indicating for each file if it was signed and whether or not the signer of the file has been found in the keystore. Sample output from this command might appear like this:

Class Definition

piccolo% jarsigner -verify -verbose xyz.jar

        402 Mon Jan 26 19:25:52 EST 1998 META-INF/SDO.SF
       1395 Mon Jan 26 19:25:52 EST 1998 META-INF/SDO.DSA
smk     596 Sat Jan 24 22:18:22 EST 1998 XYZKey.class
smk     814 Sat Jan 24 22:17:46 EST 1998 XYZKeyPairGenerator.class
smk    1155 Sat Jan 24 21:56:40 EST 1998 XYZProvider.class
smk     900 Sat Jan 24 22:11:22 EST 1998 XYZSignature.class

  s = signature was verified
  m = entry is listed in manifest
  k = at least one certificate was found in keystore

jar verified.

Note the legend for each file that is printed by this command. We know if the file was signed, whether or not it was listed in the JAR file's manifest, and whether or not the signer of the file was found in the keystore.

In the vast majority of cases, the information for each file will be the same: JAR files are usually signed all at once by the same person. However, there's nothing to prevent someone from adding a new class to a signed JAR file (in which case the class would appear as unsigned), or for a JAR file to contain multiple signers (some of whom may have signed some of the classes, while others may have signed only a few of the classes).

In order to determine whether the certificate was found in the keystore, jarsigner opens the default instance of the KeyStore class and loads it. Note that no password is required for this operation. As we mentioned in Chapter 11, "Key Management", reading the public information out of the keystore does not require a password (at least in the Sun implementation of the KeyStore class).

-ids

In conjunction with the -verbose option, print out the distinguished name and alias of the certificate (if any) that is found with each class. With this option, the output for a particular class looks like this:

Class Definition

smk     900 Sat Jan 24 22:11:22 EST 1998 XYZSignature.class
	CN=Scott Oaks, OU=SMCC, O=Sun Microsystems, L=NY, S=NY, C=US (sdo)

In this case, the class was signed by the given distinguished name; the name of the alias associated with the certificate is shown in parentheses (sdo).

This option has no effect unless the -verbose option is specified.

-keystore keystore

Use the given file as the name of the keystore to load. The default for this option is to use the .keystore file in the directory specified by the user.home property. This name is only used for the -verbose option to look up the certificates of the signer.