InfoCenter Home >
5: Securing applications -- special topics >
5.5: Certificate-based authentication >
5.5.6: Tools for managing certificates and keys >
5.5.6.3: Understanding how the Keytool utility works

5.5.6.3: Understanding how the Keytool utility works

The Keytool utility is a Java-based key-and-certificate management utility. The following categories cover the administration tasks that are handled by the utility:

Options used with the keytool command provides reference information about the options used with the keytool command, and this article covers the following conceptual and overview topics:


Rules for using the keytool commands

Options are used in combination with the keytool command to perform the administration tasks needed to implement and maintain a keystore database. See Options used with the keytool command for the full list of options.

The following rules apply to all options:

  • All options are preceded by the minus sign (-).

  • The options are case insensitive, so aliases of ruth and Ruth refer to the same entry.

  • Commands must be entered on a single line. (When a command example in these topics is shown on multiple lines, it is done only to accommodate limitation in the width of the screen or page.

  • The order in which the option occurs in the command string is irrelevant.

  • If no password is provided on the command line, the Keytool utility issues a prompt for the password when it is required to complete the keytool command.

  • If the value for an option contains a blank space, the value must be enclosed in quotation marks (" ").

  • When the keytool command is issued with no options, the keytool help is activated. (The -help option also activates the help facility.)

Files that are used by the Keytool utility

The Keytool utility interacts with several files while it accomplishes its security functions. This topic examines these files and the function they serve when used with the Keytool utility.

The .keystore file

The Keytool utility stores its key pair entries and trusted certificate entries in a keystore database. The keystore database is a file that has the default name of .keystore and is located by default in the user's home directory. The keystore database uses other files to interact with certificate authorities (CAs) and to hold its trust base, which is its list of trusted certificates.

See Administering a keystore database for more information on the keystore database.

The cacerts files

The cacerts file holds the CA certificates, which are the list of trusted certificates managed by the Keytool utility. This file resides in the JDK security properties directory in the run-time environment directory.

When a new certificate is imported into the keystore, the Keytool utility verifies that the certificate has integrity (that is, the contents are intact), and that it is authentic (that is, the entity claiming to have sent the data is actually the entity it claims to be). The Keytool utility attempts this verification by building a chain of trust from that certificate to the self-signed certificate that belongs to the root CA. Because the list of trusted certificates held in the cacerts file are already trusted, the Keytool utility uses the certificates in that file as its basis for comparison.

The Keytool utility supplies five VeriSign root certificates in the cacerts file. The Distinguished Names associated with the VeriSign root CA certificates are as follows:

  • OU=Class 1 Primary Certification Authority, O="VeriSign, Inc.", C=US

  • OU=Class 2 Primary Certification Authority, O="VeriSign, Inc.", C=US

  • OU=Class 3 Primary Certification Authority, O="VeriSign, Inc.", C=US

  • OU=Class 4 Primary Certification Authority, O="VeriSign, Inc.", C=US

  • OU=Secure Server Certification Authority, O="RSA Data Security, Inc.", C=US

See Security considerations for maintaining the cacerts file for information on keeping the cacerts file secure.

See Administering trusted certificates for more information on certificate management by the Keytool utility.

Keytool files used by a CA

The Keytool utility uses the -certreq option to generate an authentication request for a self-signed certificate from a Certificate Authority (CA). The -certreq option creates a Certificate Signing Request (CSR) for the certificate and places the CSR in a file named certreq_file.csr, where certreq_file.csr is the name of the file that is to be sent to the CA for authentication. If a CA considers the certificate to be valid, it issues a certificate reply and places the reply in a file named cert_reply.cer, where cert_reply.cer is the file returned by the CA which holds the results of the CSR authorizations that were submitted in the certreq_file.csr file. The Keytool utility uses the -import option to read the *.cer file into the keystore.


Default values

The Keytool utility supplies default values with many of its options. Table 1 identifies the default value when the option has a default associated with it.

In addition to the option-related default values, the Keytool utility takes its implementation type from the keystore.type property which is located in the security properties file. Java supplies JKS as the default implementation type for use with the Keytool utility. Customizing a keystore implementation type discusses how to enable the JKS type or how to specify a customized type.


Standards

The Keytool utility uses the following certificate standards:

X.509 Certificates

The Keytool utility uses the X.509 certificate standard to define what information is to be included in a certificate and what data format is to be used for the information. The information in the X.509 certificate is encoded using Abstract Syntax Notation1 (ASN.1) standard to describe data and the Definite Encoding Rules (DER) standard to identify how the information is to be stored and transmitted. The X.509 certificates takes the values for its The values subject and issuer fields from the X.500 Distinguished Name (DN) standard.

X.500 Distinguished Names

The Keytool utility uses -dname option to supply the following subcomponents of the X.500 Distinguished Name standard:

  • CN (common name)

  • OU (organization unit)

  • O (organization name)

  • L (city)

  • S (state)

  • C (country code)

The choice of including the subcomponent optional; however, if a subcomponent is included, its order of occurrence is mandatory. The utility is case insensitive to the abbreviations used for the subcomponents; so, for example, CN, cn, Cn, and cN are all identified as the common name subcomponent for the X.500 DN. The Keytool utility prompts for missing subcomponents when a DN is required.

Internet RFC 1421 printable encoding standard

The Keytool utility uses the Internet RFC 1421 standard to define its printable encoding format. This certificate format is also known as Base 64 encoding. This format is enclosed by begin and end tagging. However, the -export option defaults to displaying the output in binary encoding. If the printable encoding format is desired, include the -rfc option with the -export command.


Security considerations

The security provided by the Keytool utility relies on passwords and certificate authentication. This section provides suggestions for ensuring security.

Security considerations for passwords

Passwords can be specified on the command line or in a script when the -storepass or -keypass option is supplied. However, prudent security procedures discourage this practice, unless you are in a testing environment or on a secure system.

When a required password is not supplied, a prompt is issued. Take care when supplying the password at the prompt because the entry is echoed (displayed as typed) on the screen.

When an identity database is migrated into a keystore database, all private keys are encrypted to the same password. The system administrator must reassign a unique password to each entry. See Migrating an identity database into a keystore database for instructions on performing this task.

Security considerations for importing trusted certificates

Before importing a trusted certificate into your list of trusted certificates, view its fingerprint by using the -printcert option and compare the output with a secure source. A fingerprint is a hash value that is calculated by using a message digest function to encrypt a digital signature. By making a visual comparison between the fingerprint of the received certificate with that of the sent certificate, you can ensure that the certificate was not tampered with in transit. Unless the -import option is issued with the -noprompt option included, the -printcert option is automatically invoked to ensure verification prior to including the certificate in your list of trusted certificates. (If the -noprompt option is issued, no interaction with the user occurs.)

Security considerations for maintaining the cacerts file

The cacerts keystore file has an initial password of changeit. Administrators need to change this password. In addition, the JDK installation grants default access permission to the cacerts file. Administrators need to change the access permission for this file.

Go to previous article: Making key store and trust store files accessible Go to next article: Administering a keystore database

 

 
Go to previous article: Making key store and trust store files accessible Go to next article: Administering a keystore database