JARs and Security

JAR s and Security

As mentioned earlier, one of the main benefits of a JAR file is that it can be digitally signed. This allows potential users of the JAR file to inspect it and verify that it is a valid JAR file from one of the user 's "trusted" sources. This gives JAR files a little more freedom to access system resource that normally would not be allowed.

By signing the JAR file with your particular signature, users that trust you will be able to inspect the signature and see that it came from you and then trust the JAR file. This is called verification.

It is possible to detect deliberate corruption of the files in a JAR archive. To do so, the JAR archive must be signed digitally. A digital signature is stronger than a physical one; it is harder to forge , the signer cannot repudiate it, and the signed document cannot be modified.

Private Keys, Public Keys, and Certificates

To sign a JAR archive, you must first create a private key, a public key, and a certificate. The public and private keys are paired pieces of data used to create digital signatures and to encrypt data. A certificate is a guarantee by one entity, usually a trusted public organization, that another entity's public key is valid. (In this case, more specifically , a certificate conforms to the X.509 standard. The combination of a public key and a certificate can be used confidently to verify a digital signature.)

keytool

keytool handles the creation and management of identities, public and private keys, and certificates. The details of key and certificate creation and management are beyond the scope of this chapter.

The keytool program creates files called keystore databases. These databases are actually files that reside on the machine creating them and contain the certificates that you have created or used.

keytool itself has a variety of parameters, used to specify the manipulation of a key. However, this section just looks at one scenario, generating a key. To do this, you need to know several things. First, you need an alias by which this key will be known. For this example, use myalias. Next, you need a distinguishing name by which you will be known. This name is part of the X.509 standard for specifying your name and follows this format:

 CN=commonName OU=organizationUnit O=organizationName L=locality, Name S=stateName  C=country 

Each of these fields helps spell out who you are; for example, my distinguishing name might be

 "CN=Chuck Cavaness, OU=QUE, O=Macmillan Publishing, L=Atlanta, S=Georgia, C=US" 

Now you can use both of these values to generate a new key:

 C:\jdk1.3se_book>keytool -genkey -dname "CN=Chuck Cavaness, OU=QUE, O=Macmillan  Publishing, L=Atlanta, S=Georgia, C=US" -alias myalias 

As you probably already guessed, the “genkey command tells keytool that you are generating a new key, -dname specifies distinguishing name, and “alias specifies the alias you will be using. Note that the alias is case sensitive, so myalias is not the same alias as MyAlias.

When you run keytool like this, you are prompted to enter a password for the keystore and a password for your new key. These passwords will be required each time you use the key later down the road. The following examples use foobar for both passwords.

Note

The keytool may take some time to complete. It could be as long as 30 seconds. Give it enough time to complete.

Caution

Don't forget, you should write down the password somewhere that is secure. You must remember the password or you will have to generate a new key. This could be a problem if you have JAR files signed and need to change them later.

You could also have specified the key password on the command line using the “storepass “keypass parameters

In general, the parameters for generating a key are

 keytool -genkey { -alias alias}  { -keyalg keyalg}  { -keysize keysize}  { -sigalg sigalg}  [-dname dname] [-keypass keypass] { -validity valDays}  { -keystore keystore}  [-storepass storepass] { -v} 

jarsigner

Now that you have generated a key, you can digitally sign your JAR file. Signing a file is useful so that you and users of the file can be sure that you are the person who sent the file and that it hasn't been tampered with.

Before you can sign the JAR file, you need to know a couple of details. First, you need to know the alias for the key you want to use. Next, you need to know the -keystore password and the private key password for the key you will be using. Finally, you optionally need to know the location of the keystore file. If you've left it in the default location, you don't need this, but if you've moved it elsewhere, you need to specify that information. See Appendix B for more information on the jarsigner options. Do a search on the name " keystore " and see where it put the key database file.

Using the key that you created under the keytool section, you can now sign a JAR file. Use the ourtest.jar file from the earlier example. If you deleted that JAR file, recreate it or create a new one using the methods that were discussed before. Here's an example of signing the JAR file:

Note

The jarsigner may take some time to complete. It could be as long as 30 seconds. Give it enough time to complete.

 C:\jdk1.3\demo\applets\TicTacToe>jarsigner -storepass foobar -keypass foobar our test.jar  myalias 

When you sign the JAR file, it adds two files to the manifest for the file. The first file is an .SF file. The .SF file contains information similar to the manifest file that is always included with a JAR file. However, the .SF file's digest doesn't include the hash of the binary data in the file (as the manifest's does), but rather a hash of the data in the manifest. This locks in the manifest information.

The second file is a .DSA file. The .DSA file contains a signature of the .SF file and also contains, encoded inside it, a copy of the .SF file and a certificate authenticating the public key corresponding to the private key used for signing.

Fortunately, you should never have to know any of those details. However, you should know that both files, by default, are named via the first eight characters in the alias; so in this case, you would have Myalias.DSA and Myalias.SF. Using the alias allows you to sign a JAR file more than once and chain these signatures together, resulting in an .SF and .DSA file for each person who signed the file.

jarsigner has a number of additional options that you can use, depending on your particular situation, as outlined in Table 25.1.

Table 25.1. jarsigner Options

Option	Description
-keystore file	Specifies the keystore (database file) location. By default, this file refers to .keystore in the user's home directory. This directory is specified by the user.home system property. For Windows systems, user.home is the path specified by concatenating the HOMEDRIVE and HOMEPATH environment variables if they produce a valid path; otherwise , it is the root of the SDK installation directory.
-storepass password	Specifies the keystore password. You need this password only when signing a JAR file, not when verifying it. If you fail to specify this command option, you are prompted to enter it. Normally, you should not specify this password on the command line for security reasons.
-keypass password	Specifies the password for the individual key entry. You need this password only when signing a JAR file, not when verifying it. If you fail to specify this command option, you will be prompted to enter it. Normally, you should not specify this password on the command line for security reasons.
	Note: The keypass password can be the same as the keystore password. If it is, the keypass is not required.
-sigfile file	Specifies the base filename for the .SF and .DSA files. If none is specified, the first eight characters of the alias (converted to uppercase) are used.
-signedjar file	Specifies the name to be used for the signed JAR file (output). If this is not specified, the new JAR file contains the same name as its source (and overwrites it).
-verify	Specifies that you want to verify the signatures in the file. This is basically the opposite of signing the file.
	Assuming the verification was successful, jar verified will be displayed.
	If an unsigned JAR file is verified, or one is signed with an unsupported algorithm (for example, RSA when you don't have an RSA provider installed), the following is displayed: jar is unsigned. (signatures missing or not parsable).
-ids	This option can be used only if the “verify and “verbose options are also used. If they are, the distinguished names of the JAR file signer(s) and the alias name for the keystore entry are also displayed.
-verbose idOrSigner	Puts jarsigner into verbose mode. In this mode, the signer outputs additional information as the signing or verification progresses.