Summaries

Tools Summary

Below is a brief summary of the security tools, with links to the more detailed documentation.

The keytool, jar, jarsigner, and policytool tools are available in JDK 1.2 to facilitate various security-related operations. (Note: the jar tool was also available in JDK 1.1.)

The keytool and jarsigner tools replace javakey, which was an interim tool introduced 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 signed JAR files in addition to generating them. The new keystore architecture replaces the identity database that javakey created and managed. It is possible to import the information from an identity database into a keystore, via a keytool command.

Key and Certificate Management Tool (keytool)

Use the Key and Certificate Management Tool (invoked by using the keytool command) to create public/private key pairs, issue certificate requests (which you send to the appropriate Certification Authority), import certificate replies (obtained from the Certification Authority you contacted), designate public keys belonging to other parties as trusted, and to manage your keystore.

Keys and certificates are used to digitally sign your applications and applets (see jarsigner below). A keystore is a protected database that holds keys and certificates for an enterprise. Access to a keystore is guarded by a password (defined at the time the keystore is created, by the person who creates the keystore, and changeable only when providing the current password). In addition, each private key in a keystore can be guarded by its own password.

The basic format of the command for invoking keytool is:

    keytool command options

Sample commands are:

• -certreq - Generate a Certificate Signing Request (CSR) to be sent to a Certification Authority (CA) so they'll authenticate your public key.
• -delete - Remove the specified keystore entry.
• -export - Export the public key certificate in the specified entry to a file.
• -genkey - Create a keystore entry containing a newly generated private key and corresponding public key. The latter is placed in a self-signed certificate.
• -import - Import either a certificate to be treated as a "trusted certificate" or a certificate reply returned by a CA. The latter will be used to replace the corresponding self-signed certificate in the keystore.
• -keypasswd - Assign a password to a private key in a key/certificate entry.
• -list - List the keystore entries.
• -printcert - Print out the information in a specified file containing a certificate.
• -storepasswd - Assign a password to the keystore.

Each command has a number of options, some of which are required, and some of which have default values if not specified.

There are three options that may appear for all commands operating on a keystore:

• -storetype storetype - this specifies the type of keystore to be instantiated.
• -keystore keystore The name (and optionally path) of the keystore. Defaults to the file .keystore in the user's home directory, as determined by the "user.home" system property.
• -storepass storepass - this specifies the password which is used to protect the integrity of the keystore.
• -v storepass - this specifies verbose output. If this appears, it signifies "verbose" mode; detailed certificate information will be output.

Other sample options are:

• -alias aliasName - this specifies the alias used to refer to a particular keystore entry.
• -validity numDays - this specifies the length of time during which the enclosed certificate should be considered valid (default: 90 days).
• -keypass keypass - this specifies the password which is used to protect the integrity of the private key in a keystore entry.

Examples of the use of keytool are shown in the Signing Code and Granting It Permissions [Tools] and Exchanging Files [Tools] lessons.

Java Archive Tool (jar)

Use the Java Archive Tool (invoked by using the jar command) to create JAR files.

The Java Archive (JAR) file format enables you to bundle multiple files into a single archive file. Typically a JAR file will contain the class files and auxiliary resources associated with applets and applications. When you want to "digitally sign" code, you use the jar tool to place it in a JAR file and the jarsigner tool to sign the JAR file (after generating or importing appropriate keys into your keystore using keytool).

The basic format of the command for creating a JAR file is:

    jar cf jar-file input-file(s)

Let's look at the options and arguments used in this command:

• The c option indicates that you want to create a JAR file.
• The f option indicates that you want the output to go to a file rather than to stdout.
• jar-file is the name that you want the resulting JAR file to have. You can use any filename for a JAR file. By convention, JAR filenames are usually given a .jar extension, though this is not required.
• The input-file(s) argument is a space-delimited list of one or more files that you want to be placed in your JAR file. The input-file(s) argument can contain the wildcard * symbol. If any of the "input-files" are directories, the contents of those directories are added to the JAR archive recursively.

The c and f options can appear in either order, but there must not be any space between them.

You can add a number of additional options to the cf options of the basic command. One we'll use in our lessons is the v option:

• v - produces verbose output on stdout while the JAR file is being built. The verbose output tells you the name of each file as it's added to the JAR file.

See the The Java Archive (JAR) File Format trail for more information about JAR files and the jar tool. Also see the Signing Code and Granting It Permissions [Tools] and Exchanging Files [Tools] lessons for examples of the use of the jar tool.

JAR Signing and Verification Tool (jarsigner)

Use the JAR Signing and Verification Tool (invoked by using the jarsigner command) to sign JAR files, or to verify signatures on signed JAR files.

The jarsigner tool accesses a keystore that is created and managed by keytool, when it needs to find the private key and its associated certificate chain to use when signing a JAR file. Since accesses to the keystore and to private keys are protected by passwords, only people who know the passwords will be able to access a key and use it to sign a JAR file. The jarsigner tool prompts for needed passwords.

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

    jarsigner options jar-file alias

In this command:

• options are optional specifications, some of which are described below.
• 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 (chain).

The jarsigner tool will prompt you for the passwords for the keystore and for the private key whose keystore entry is referenced by the 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 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 the following options, which must precede the jar-file pathname:

• -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.
• -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.

See the Signing and Verifying JAR Files lesson of the Java Archive (JAR) File Format trail for more information about the JAR Signing and Verification Tool. Also see the Exchanging Files [Tools] lessons for examples of the use of the jarsigner tool.

Policy Tool (policytool) GUI tool

Use the Policy Tool (invoked by using the policytool command) to create and modify the external policy configuration files that define your installation's security policy.

This tool has a Graphical User Interface, so you select buttons and other options rather than type in commands as for the other tools. See the Quick Tour of Controlling Applets , Quick Tour of Controlling Applications , and Signing Code and Granting It Permissions [Tools] lessons for examples of the use of the policytool.

Online Tools Documentation

Complete documentation for the security tools is available on the public java.sun.com web site:

• jar documentation with Windows examples
• jar documentation with Solaris examples

• jarsigner documentation with Windows examples
• jarsigner documentation with Solaris examples

• keytool documentation with Windows examples
• keytool documentation with Solaris examples

• policytool documentation with Windows examples
• policytool documentation with Solaris examples

Summaries