jarsigner - JAR Signing and Verification Tool

Generates signatures for Java ARchive (JAR) files, and verifies the signatures of signed JAR files.

SYNOPSIS

jarsigner [ options ] jar-file alias

DESCRIPTION

The jarsigner tool is used for two purposes:
  1. to sign Java ARchive (JAR) files, and

  2. to verify the signatures and integrity of signed JAR files.

The JAR feature enables the packaging of class files, images, sounds, and other digital data in a single file for faster and easier distribution. A tool named jar enables developers to produce JAR files.

A digital signature is a string of bits that is computed from some data (the data being "signed") and the private key of an entity (a person, company, etc.). Like a handwritten signature, a digital signature has many useful characteristics:

In order for an entity's signature to be generated for a file, the entity must first have a public/private key pair associated with it, and also one or more certificates authenticating its public key. A certificate is a digitally signed statement from one entity, saying that the public key of some other entity has a particular value.

jarsigner uses key and certificate information from a keystore to generate digital signatures for JAR files. A keystore is a database of private keys and their associated X.509 certificate chains authenticating the corresponding public keys. The keytool utility is used to create and administer keystores.

jarsigner uses an entity's private key to generate a signature. The signed JAR file contains, among other things, a copy of the certificate from the keystore for the public key corresponding to the private key used to sign the file. jarsigner can verify the digital signature of the signed JAR file using the certificate inside it (in its signature block file).

At this time, jarsigner can only sign JAR files created by the JDK jar tool.

The default jarsigner behavior is to sign a JAR file. Use the -verify option to instead have it verify a signed JAR file.

Please note: the keytool and jarsigner tools completely replace the javakey tool provided in JDK 1.1. These new tools provide more features than javakey, including the ability to protect the keystore and private keys with passwords, and the ability to verify signatures in addition to generating them. There is no backwards compatibility between the keystore format and the database format used by javakey in 1.1.

Keystore Aliases

All keystore entities are accessed via unique aliases.

When using jarsigner to sign a JAR file, you must specify the alias for the keystore entry containing the private key needed to generate the signature. For example, the following will sign the JAR file named "MyJarFile.jar", using the private key associated with the alias "duke" in the keystore named "mystore" in the "working" directory. Since no output file is specified, it overwrites MyJarFile.jar with the signed JAR file. 

    jarsigner -keystore /working/mystore -storepass myspass
      -keypass dukekeypasswd MyJarFile.jar duke

Keystores are protected with a password, so the store password (in this case "myspass") must be specified. You will be prompted for it if you don't specify it on the command line. Similarly, private keys are protected in a keystore with a password, so the private key's password (in this case "dukekeypasswd") must be specified, and you will be prompted for it if you don't specify it on the command line and it isn't the same as the store password.

Keystore Location

jarsigner has a -keystore option for specifying the name and location of the keystore to be used. The keystore is by default stored in a file named .keystore in the user's home directory, as determined by the "user.home" system property. On Solaris systems "user.home" defaults to the user's home directory.

Keystore Implementation

A keystore implementation is a concrete implementation of the KeyStore abstract class provided in the java.security package. This class supplies well-defined interfaces to access and modify the information in a keystore.

Currently, there are two command-line tools that make use of KeyStore: keytool and jarsigner, and also a GUI-based tool named policytool. Since KeyStore is publicly available, JDK users can write additional security applications that use it.

The default KeyStore implementation, provided by Sun Microsystems, implements the keystore as a file. It protects private keys with a password.

A client may, if desired, write their own KeyStore implementation, for example if they would like to protect their private keys using a more powerful algorithm, or if they'd like to use a different (not file-based) keystore format. Keystores with different formats are not compatible; for example, a non-file-based Keystore implementation would not be able to load a Sun keystore. However, such an implementation could still use the keytool and jarsigner tools on its own keystores.

To have the tools utilize a KeyStore implementation other than the default, change the value of the keystore property in the security properties file. The keystore property value is assumed to specify the fully qualified class name of the KeyStore implementation. The security properties file is called java.security, and it resides in the JDK security properties directory, java.home/lib/security, where java.home is the JDK installation directory.

Thus, to change to a KeyStore implementation other than the default, change the line 

	keystore=sun.security.tools.JavaKeyStore
in the security properties file to point to the different keystore implementation.

For example, if the KeyStore implementation is provided in a file named SecureKeys.class, and that file resides in the keymgmtsolutions.tools package, change the line to: 

    keystore=keymgmtsolutions.tools.SecureKeys

The above sets the value of the "keystore" property to "keymgmtsolutions.tools.SecureKeys".

Supported Algorithms and Key Sizes

At this time, jarsigner can sign a JAR file using either

That is, if the signer's public and private keys are DSA keys, jarsigner will sign the JAR file using the SHA-1/DSA algorithm. If the signer's keys are RSA keys, jarsigner will sign the JAR file using the MD5/RSA algorithm. This is only possible if there is a statically installed provider supplying an implementation for the MD5/RSA algorithm. (There is always a SHA-1/DSA algorithm available, from the default "SUN" provider.)

The Signed JAR File

When jarsigner is used to sign a JAR file, the output signed JAR file is exactly the same as the input JAR file, except that it has two additional files placed in the META-INF directory:

The base file names for these two files come from the value of the -sigFile option. For example, if the option appears as 
  -sigFile MKSIGN
the files are named "MKSIGN.SF" and "MKSIGN.DSA".

If no -sigfile option appears on the command line, the base file name for the .SF and .DSA files will be the first 8 characters of the alias name specified on the command line, all converted to upper case. If the alias name has fewer than 8 characters, the full alias name is used.

The Signature (.SF) File

A signature file (the .SF file) looks similar to the manifest file that is always included in a JAR file generated by the jar tool. That is, for each source file included in the JAR file, the .SF file has three lines, just as in the manifest file, listing the following:
  • the file name,

  • the name of the digest algorithm used (SHA), and

  • a SHA digest value.
In the manifest file, the SHA digest value for each source file is the digest (hash) of the binary data in the source file. In the .SF file, on the other hand, the digest value for a given source file is the hash of the three lines in the manifest file for the source file.

The Signature Block (.DSA) File

The .SF file is signed and the signature is placed in the .DSA file. The .DSA file also contains, encoded inside it, a copy of the .SF file that was signed, as well as a certificate authenticating the public key corresponding to the private key used for signing.

Multiple Signatures for a JAR File

A JAR file can be signed by multiple people simply by running the jarsigner tool on the file twice, specifying the alias for a different person each time, as in: 
  jarsigner myBundle.jar susan
  jarsigner myBundle.jar kevin

OPTIONS

The various jarsigner options are listed and described below. Note:

-keystore file
Specifies the keystore (database file) location. This is only needed when signing (not verifying) a JAR file, and defaults to the file .keystore in the user's home directory, as determined by the "user.home" system property. On Solaris systems "user.home" defaults to the user's home directory.

-storepass password
Specifies the password which is required to access the keystore. This is only needed when signing (not verifying) a JAR file. In that case, if a -storepass option is not provided at the command line, the user is prompted for the password.

Note: The password shouldn't be specified on the command line or in a script unless it is for testing purposes, or you are on a secure system. Also, when typing in a password at the password prompt, the password is echoed (displayed exactly as typed), so be careful not to type it in front of anyone.

-keypass password
Specifies the password used to protect the private key of the keystore entry addressed by the alias specified on the command line. The password is required when using jarsigner to sign a JAR file. If no password is provided on the command line, and the required password is different from the store password, the user is prompted for it.

Note: The password shouldn't be specified on the command line or in a script unless it is for testing purposes, or you are on a secure system. Also, when typing in a password at the password prompt, the password is echoed (displayed exactly as typed), so be careful not to type it in front of anyone.

-sigfile file
Specifies the base file name to be used for the generated .SF and .DSA files. For example, if file is "DUKESIGN", the generated .SF and .DSA files will be named "DUKESIGN.SF" and "DUKESIGN.DSA", and will be placed in the "META-INF" directory of the signed JAR file.

The characters in file must come from the set "A-Z0-9_-". That is, only letters, numbers, underscore, and hyphen characters are allowed.

If no -sigfile option appears on the command line, the base file name for the .SF and .DSA files will be the first 8 characters of the alias name specified on the command line, all converted to upper case. If the alias name has fewer than 8 characters, the full alias name is used.

-signedjar file
Specifies the name to be used for the signed JAR file.

If no name is specified on the command line, the name used is the same as the input JAR file name (the name of the JAR file to be signed); in other words, that file is overwritten with the signed JAR file.

-verify
If this appears on the command line, the specified JAR file will be verified, not signed. If the verification is successful, "jar verified" will be displayed. If you try to verify an unsigned JAR file, or a JAR file signed with an unsupported algorithm (e.g., RSA when you don't have an RSA provider installed), the following is displayed: "jar is unsigned. (signatures missing or not parsable)"

-ids
If this appears on the command line, along with the -verify and -verbose options, the output includes the distinguished names of the JAR file signer(s) and for each, in parentheses, the alias name for the keystore entry (if any) for that signer.

-verbose idOrSigner
If this appears on the command line, it indicates "verbose" mode, which causes jarsigner to output extra information as to the progress of the JAR signing or verification.

EXAMPLES

Signing a JAR File

Suppose you have a JAR file named "bundle.jar" and you'd like to sign it using the private key of the user whose keystore alias is "jane" in the keystore named "mystore" in the "working" directory. Suppose the keystore password is "myspass" and the password for jane's private key is "j638klm". You can use the following to sign the JAR file and name the signed JAR file "sbundle.jar": 

    jarsigner -keystore "/working/mystore" -storepass myspass
      -keypass j638klm -signedjar sbundle.jar bundle.jar jane

Note that there is no -sigfile specified in the command above, so the generated .SF and .DSA files to be placed in the signed JAR file will have default names based on the alias name. That is, they will be named JANE.SF and JANE.DSA.

If you want to be prompted for the store password and the private key password, you could shorten the above command to 

    jarsigner -keystore /working/mystore
      -signedjar sbundle.jar bundle.jar jane
If the keystore to be used is the default keystore (the one named ".keystore" in your home directory), you don't need to specify a keystore, as in: 
    jarsigner -signedjar sbundle.jar bundle.jar jane
Finally, if you want the signed JAR file to simply overwrite the input JAR file (bundle.jar), you don't need to specify a -signedjar option: 
    jarsigner bundle.jar jane

Verifying a Signed JAR File

To verify a signed JAR file, that is, to verify that the signature is valid and the JAR file has not been tampered with, use a command such as the following: 
    jarsigner -verify sbundle.jar

If the verification is successful, 

    jar verified.
is displayed. Otherwise, an error message appears.

You can get more information if you use the -verbose option. A sample use of jarsigner with the -verbose option is shown below, along with sample output: 

    jarsigner -verify -verbose sbundle.jar

           198 Fri Sep 26 16:14:06 PDT 1997 META-INF/MANIFEST.MF
           199 Fri Sep 26 16:22:10 PDT 1997 META-INF/JANE.SF
          1013 Fri Sep 26 16:22:10 PDT 1997 META-INF/JANE.DSA
    smk   2752 Fri Sep 26 16:12:30 PDT 1997 AclEx.class
    smk    849 Fri Sep 26 16:12:46 PDT 1997 test.class

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

    jar verified.

SEE ALSO