The JavaTM Tutorial

| Start of Tutorial > Start of Trail > Start of Lesson | Search Feedback Form

Trail: JAR Files
Lesson: Signing and Verifying JAR Files

## Signing JAR Files

> The JavaTM Development Kit contains the tools that you need to sign JAR files. Depending on which version of the Java Development Kit you're using, you will use either:
> - the JDK 1.2 JAR Signing and Verification Tool
> - the JDK 1.1 Java Security Tool

### The JDK 1.2 JAR Signing and Verification Tool

> The JAR Signing and Verification Tool is invoked by using the `jarsigner` command, so we'll refer to it as "Jarsigner" for short.

> To sign a JAR file, you must first have a private key. Private keys and their associated public-key certificates are stored in password-protected databases called keystores. A keystore can hold the keys of many potential signers. Each key in the keystore can be identified by an alias which is typically the name of the signer who owns the key. The key belonging to Rita Jones might have the alias "rita", for example.

> The basic form of the command for signing a JAR file is

> >     jarsigner jar-file alias

> In this command:
> - `jar-file` is the pathname of the JAR file that's to be signed.
> - `alias` is the alias identifying the private key that's to be used to sign the JAR file, and the key's associated certificate.

> The Jarsigner tool will prompt you for the passwords for the keystore and alias.

> This basic form of the command assumes that the keystore to be used is in a file named `.keystore` in your home directory. It will create signature and signature block files with names `x.SF` and `x.DSA` respectively, where `x` is the first eight letters of the alias, all converted to upper case. This basic command will overwrite the original JAR file with the signed JAR file.

> In practice, you may want to use this command in conjunction with one or more of these options, which must precede the `jar-file` pathname:

> Option | Description
> --- | ---
> `-keystore` url | Specifies a keystore to be used if you don't want to use the `.keystore` default database.
> `-storepass` password | Allows you to enter the keystore's password on the command line rather than be prompted for it.
> `-keypass` password | Allows you to enter your alias's password on the command line rather than be prompted for it.
> `-sigfile` file | Specifies the base name for the .SF and .DSA files if you don't want the base name to be taken from your alias. file must be composed only of upper case letters (A-Z), numerals (0-9), hyphen (-), and underscore (_).
> `-signedjar` file | Specifies the name of the signed JAR file to be generated if you don't want the original unsigned file to be overwritten with the signed file.

### Example

> Let's look at a couple of examples of signing a JAR file with the Jarsigner tool. In these examples we will assume:
> - your alias is "johndoe".
> - the keystore you want to use is in a file named "mykeys" in the current working directory.
> - the keystore's password is "abc123".
> - the password for your alias is "mypass".
> Under these assumptions, you could use this command to sign a JAR file named `app.jar`:

> >     jarsigner -keystore mykeys -storepass abc123
> >               -keypass mypass app.jar johndoe

> Because this command doesn't make use of the `-sigfile` option, the .SF and .DSA files it creates would be named `JOHNDOE.SF` and `JOHNDOE.DSA`. Because the command doesn't use the `-signedjar` option, the resulting signed file will overwrite the original version of `app.jar`.

> Let's look at what would happen if you used a different combination of options:

> >     jarsigner -keystore mykeys -sigfile SIG
> >               -signedjar SignedApp.jar app.jar johndoe

> This time, you would be prompted to enter the passwords for both the keystore and your alias because the passwords aren't specified on the command line. The signature and signature block files would be named `SIG.SF` and `SIG.DSA`, respectively, and the signed JAR file `SignedApp.jar` would be placed in the current directory. The original unsigned JAR file would remain unchanged.

### Jarsigner Reference Page

> Complete reference pages for the JAR Signing and Verification Tool are on-line:
> - Jarsigner reference page with Windows examples
> - Jarsigner reference page with Solaris examples

> The Java Development Kit provides the Key and Certificate Management Tool (Keytool) for managing keystores:

> - Keytool reference page for Windows
> - Keytool reference page for Solaris

### The JDK 1.1 Java Security Tool

> If you're working with version 1.1 of the Java Development Kit, you'll use the Java Security Tool to sign JAR files. You invoke the Java Security Tool with the `javakey` command, so we'll call it "Javakey" for short.

> The Javakey tool manages a database containing public/private key pairs and related certificates. In order to sign a JAR file with the Javakey tool, you need to have a public/private key pair in Javakey's database. The Javakey tool will look for the database at the location specified by the `identity.database` property in the security properties file, `java.security`, located in the `jre/lib/security` directory of the JDK software. The database typically holds key pairs for many different potential signers, each key pair being associated with the username of a signer.

> In addition to key pairs, Javakey's database contains certificates for the public keys. When a certificate is added to the database, Javakey assigns it a unique number for identification purposes.

> To sign a file, you must provide Javakey with several pieces of information:

> - the username of the key pair to use
> - the number of the certificate to use
> - the name that the signature and signature block files are to have
> - the name that the signed JAR file is to have

> You provide this information to Javakey by using a directive file, which is basically a property file that Javakey reads when signing a JAR file. Here's a sample directive file:

> >     # The signer property specifies the username corresponding to
> >     # the key pair that Javakey is to use to sign the JAR file.
> >     # In this example, Javakey will sign the file using the key pair
> >     # belonging to user "rita".

> >     signer=rita

> >     # The cert property tells Javakey which certificate to use. Each
> >     # certificate in Javakey's database is identified by a number.
> >     # To see a list of all the certificates and associated numbers in
> >     # the database, use the command 'javakey -ld'.

> >     cert=1

> >     # The signature.file property specifies the name that the signature
> >     # file and signature block file are to have.  In this example,
> >     # the files will be named SIGFILE.SF and SIGFILE.DSA, respectively.

> >     signature.file=sigfile

> >     # The out.file property specifies the name that Javakey should give
> >     # to the signed JAR file it produces.  This property is optional.
> >     # If it's not present, Javakey will give the signed file the name
> >     # of the original JAR file, but with a .sig filename extension.

> >     out.file=rita.jar

> Once your directive file is ready, you sign a JAR file by using a command of this form:

> >     javakey -gs directive-file jar-file

> In this command:

> - `-gs` is the option that tells Javakey to sign a JAR file.
> - `directive-file` is the pathname of the directive file that Javakey should use.
> - `jar-file` is the pathname of the JAR file that you want to sign.

> Javakey will place the signed JAR file in the current directory.

> Javakey can perform many other functions related to managing the key/certificate database. See the on-line JDK documentation for more information about Javakey:

> - Javakey reference page for Windows
> - Javakey reference page for Solaris

| Start of Tutorial > Start of Trail > Start of Lesson | Search Feedback Form

Copyright 1995-2001 Sun Microsystems, Inc. All rights reserved.