6 Auxiliary Tools

This section briefly describes the usage of three tools that assist in the deployment of the new security features. These tools may be packaged together in the future.

More extensive documentation for the tools can be found in the

/docs/tooldocs/solaris

and

/docs/tooldocs/win32

subdirectories of the JDK release directory (where the directory separators are actually "\" on Windows systems).

For example, if the JDK is installed in a directory named "/jdk1.2" on a Solaris system, then the keytool documentation for Solaris and Windows users, respectively, can be found in

/jdk1.2/docs/tooldocs/solaris/keytool.html
/jdk1.2/docs/tooldocs/win32/keytool.html

If the JDK is installed in a directory named "C:\jdk1.2" on a Windows system, then the keytool documentation for Solaris and Windows users, respectively, can be found in

C:\jdk1.2\docs\tooldocs\solaris\keytool.html
C:\jdk1.2\docs\tooldocs\win32\keytool.html

6.1 The Key and Certificate Management Tool

keytool is a key and certificate management utility. It enables users to administer their own public/private key pairs and associated certificates for use in self-authentication (where the user authenticates himself/herself to other users/services) or data integrity and authentication services, using digital signatures. The authentication information includes both a sequence (chain) of X.509 certificates, and an associated private key, which can be referenced by a so-called "alias". This tool also manages certificates (that are "trusted" by the user), which are stored in the same database as the authentication information, and can be referenced by an "alias".

keytool stores the keys and certificates in a so-called keystore. The default keystore implementation implements the keystore as a file. It protects private keys with a password.

The chains of X.509 certificates are provided by organizations called Certification Authorities, or CAs. Identities (including CAs) use their private keys to authenticate their association with objects (such as with channels which are secured using SSL), with archives of code they signed, or (for CAs) with X.509 certificates they have issued. As a bootstrapping tool, certificates generated using the -genkey command may be used until a Certification Authority returns a certificate chain.

The private keys in this database are always stored in encrypted form, to make it difficult to disclose these private keys inappropriately. A password is required to access or modify the database. These private keys are encrypted using the "password", which should be several words long. If the password is lost, those authentication keys cannot be recovered.

In fact, each private key in the keystore can be protected using its own individual password, which may or may not be the same as the password that protects the keystore's overall integrity.

This tool is (currently) intended to be used from the command line, where one simply types "keytool" as a shell prompt. keytool is a script that executes the appropriate Java classes and is built together with the JDK.

The command line options for each command may be provided in any order. Typing an incorrect option or typing "keytool -help" will cause the tool's usage to be summarized on the output device (such as a shell window), as given below.

% keytool -help
KeyTool usage:
 
-certreq     [-v] [-alias <alias>] [-sigalg <sigalg>]
             [-file <certreq_file>] [-keypass <keypass>]
             [-keystore <keystore>] [-storepass <storepass>]
             [-storetype <i>storetype</i>]
 
-delete      [-v] -alias <alias>
             [-keystore <keystore>] [-storepass <storepass>]
             [-storetype <i>storetype</i>]
 
-export      [-v] [rfc] [-alias <alias>] [-file <cert_file>]
             [-keystore <keystore>] [-storepass <storepass>]
             [-storetype <i>storetype</i>]
 
-genkey      [-v] [-alias <alias>] [-keyalg <keyalg>]
             [-keysize <keysize>] [-sigalg <sigalg>]
             [-dname <distinguished_name>] [-validity <valDays>]
             [-keypass <keypass>] [-keystore <keystore>]
             [-storepass <storepass>]
             [-storetype <i>storetype</i>]
 
-help
  
-identitydb  [-v] [-file <idb_file>] [-keystore <keystore>]
             [-storepass <storepass>]
             [-storetype <i>storetype</i>]

-import      [-v] [-noprompt] [-alias <alias>]
             [-file <cert_file>] [-keypass <keypass>]
             [-keystore <keystore>] [-storepass <storepass>]
             [-storetype <i>storetype</i>]
 
-keyclone    [-v] [-alias <alias>] -dest <dest_alias>
             [-keypass <keypass>] [-new <new_keypass>]
             [-keystore <keystore>] [-storepass <storepass>]
             [-storetype <i>storetype</i>]
 
-keypasswd   [-v] [-alias <alias>]
             [-keypass <old_keypass>] [-new <new_keypass>]
             [-keystore <keystore>] [-storepass <storepass>]
             [-storetype <i>storetype</i>]
 
-list        [-v | -rfc] [-alias <alias>]
             [-keystore <keystore>] [-storepass <storepass>]
             [-storetype <i>storetype</i>]
 
-printcert   [-v] [-file <cert_file>]
 
-selfcert    [-v] [-alias <alias>] [-sigalg <sigalg>]
             [-dname <distinguished_name>] [-validity <valDays>]
             [-keypass <keypass>] [-keystore <keystore>]
             [-storepass <storepass>]
             [-storetype <i>storetype</i>]
 
-storepasswd  [-v] [-new <new_storepass>]
             [-keystore <keystore>] [-storepass <storepass>]
              [-storetype <i>storetype</i>]

6.2 Policy Tool

The Policy Tool is a graphical user interface (illustrated below with a screen shot) that assists a user (such as a system administrator) in specifying, generating, editing, exporting, or importing a security policy. The tool is invoked from the command line as "policytool". This again is a script built with the JDK that invokes the appropriate (non-public) implementation classes.

See the Policy Tool documentation for usage information and examples with up-to-date screen shots. The documentation can be found in the policytool.html file in the

/docs/tooldocs/solaris/

or

/docs/tooldocs/win32/

directory in the directory in which the JDK was installed (where the file separators are actually backslashes on Windows systems).

6.3 The JAR Signing and Verification Tool

The jarsigner tool can be used to digitally sign Java archives (JAR files), and to verify such signatures. This tool, like the policytool, depends on the keystore that is managed by the keytool. Its usage is quickly summarized below.

% jarsigner
Usage: jarsigner [options] jar-file alias
       jarsigner -verify [options] jar-file
  [-keystore <url>]         keystore file location
  [-storepass <password>]   password for keystore integrity
  [-keypass <password>]     password for private key (if different)
  [-sigfile <file>]         name of .SF/.DSA file
  [-signedjar <file>]       name of signed JAR file
  [-verify]                 verify a signed JAR file
  [-verbose]                verbose output when signing/verifying
  [-certs]          display certificates when verbose and verifying
  [-internalsf]             include .SF file inside signature block
  [-sectionsonly]           don't compute hash of entire manifest

Again, this tool is a script built with the JDK. Note that it is expected that this tool and the existing jar tool script may be merged in the near future to form a single command-line primitive to create JARs, either signed or unsigned.