JAR Signing

In Java version 1.2, users can prevent Java programs from accessing the filesystems of their local computers. This would include tasks like saving a file to disk, opening a file, or executing a program outside of the JAR. While users may want to restrict general access to their computers, they may also want to grant this access to programs they trust.

If you are writing a program that accesses files outside of the JAR, you should sign the JAR before distributing it. If users have put general restrictions on filesystem access, they will be presented with information about the program's source, enabling them to grant or deny your program access. Signing your JAR is also necessary if you are going to distribute your program using Java Web Start.

Generating keys

First, you must create a set of keys, a set of numbers that are used to sign the JAR and identify you as its source. These keys can be generated using the keytool command. The keys you generate (and any others you may create in the future), are stored in a keystore file. Each set of keys is associated with a unique name, known as its alias. To generate the keys, type:

keytool -genkey -alias alias-name -keystore keystore-name

The -alias alias-name and -keystore keystore-name parts are optional. If not included, the default alias is mykey and the default keystore is .keystore (stored in your home directory). If the specified keystore does not exist, it will be created. After typing this command, you will be asked for the keystore password (or to create one if the keystore does not yet exist). Then, you will be asked 7 questions about your identity. The bold type indicates the answers you should give:

    What is your first and last name?
      [Unknown]:  your name 
    What is the name of your organizational unit?
      [Unknown]:  Computer Science Dept. 
    What is the name of your organization?
      [Unknown]:  Princeton University 
    What is the name of your City or Locality?
      [Unknown]:  Princeton 
    What is the name of your State or Province?
      [Unknown]:  NJ 
    What is the two-letter country code for this unit?
      [Unknown]:  US 
    Is <CN=your name, OU=Computer Science, O=Princeton University,
        L=Princeton, ST=NJ, C=US> correct?
      [no]:  y

Then you be asked to choose a password for the keys you just created.

Keystore Configuration File

The process above involves a lot of typing, which can be tedious if you generate new keys often. To generate the keys with a single command, you can create a file containing the above information and send it to the standard input of the keytool command. For example, you could use the file keystore.conf, which contains

    password
    your name
    Computer Science Dept.
    Princeton University
    Princeton 
    NJ 
    US
    yes
    password

The last line must end with a newline.The first password is for the keystore, and the second is for the alias. Replace them with your own. Then, type the following command

   keytool -genkey -alias alias-name -keystore keystore-name < keystore.conf

The key generated by this tool will be valid for 90 days by default. You specify a longer period by including the -validity flag in the above command, followed by the number of days you would like the key to be valid.

Using Jarsigner

To sign the JAR file, type the following command (on one line):

         jarsigner -keystore keystore-name -storepass keystore-password 
                   -keypass key-password jar-file alias-name

The keystore-password is the first password you entered for the keytool command, and is used to open the keystore file. The key-password is the other password you entered, and is used to access a specific key within that file. Including these passwords on the command line is actually not very secure. If you don't want to include them on the command line, leave them out, and jarsigner will prompt you for them. You can still sign the JAR in a single command by creating a configuration file containing the keystore and key passwords (in that order, followed by newlines), and sending it to standard input, as we did before with keytool.

Your Java application can now be distributed, either as a JAR or via Java Web Start. As you can see, this method of signing a file is not totally secure (anyone can claim to be "COS 126" and distribute a program). A software company commercially producing an application would also need to purchase a certificate from a computer security firm, such as VeriSign. For this reason, users launching your program may be warned that the source of the code cannot be verified. This is fine for COS 126 purposes.

The information above applies to Java version 1.2 or higher. For more information about code signing and Java security, see http://java.sun.com/docs/books/tutorial/security1.2/index.html

Thomas P. Ventimiglia

Last modified: Thu Jul 31 09:40:23 EDT 2003