InfoCenter Home >
5: Securing applications -- special topics >
5.5: Tools for managing keys >
5.5.6: Tools for managing certificates and keys >
5.5.6.3: Understanding how the Keytool utility works >
5.5.6.3.1: Administering a keystore database

5.5.6.3.1: Administering a keystore database

The Keytool utility administrates the storage of keys and certificates in a keystore file. A password protects access to the keystore, and within the keystore each private key has its own password. The KeyStore class, which is provided in the java.security package, contains well-defined interfaces to access and modify multiple types of keystore implementations. See Understanding how the Keytool utility works for conceptual information on the use of the Keytool utility. Options used with the keytool command provides reference information for the options used with the keytool command.

The administration tasks that you perform using the Keytool utility fall into the following categories:

Managing a keystore involves the following tasks:


Creating a keystore

Use the keytool command with the -keystore option to explicitly create a keystore. See Customizing the name or location of a keystore for information on this option.

In addition, to create a default keystore, issue the keytool command in combination with the -genkey, -import, or -identitydb options, without including the -keystore option. Using the options in this way creates a default file named .keystore and places it in the user's home directory.

For example,

  • On a Windows NT system, if a user's ID is sandra, then the user.home system property value is:
    C:\Winnt\Profiles\sandra
    

  • On a UNIX system, the default .keystore file is user.home property value translates to the user's home directory.

Adding entries to a keystore

An entry in a keystore can be either of two types:

  • A key entry. Typically, this is an entry which consists of a private key and a certificate chain. A certificate chain holds a linked set of certified authorizations that connect the public key back to its corresponding private key.

  • A trusted certificate entry. This is a certificate which holds the public key of another entity. The holder trusts in the authenticity of the certificate because the entity has vouched for the certificate by signing it.

For more information on keys, certificates and digital signatures, see 5.5: Introduction to certificate-based authentication.

Use the keytool command in combination with a -genkey, -import, or -identitydb option to add an entry to the keystore. See the following topics for information on these options:


Deleting a keystore database

To remove a keystore, use operating system commands to delete the keystore file.

See Deleting a keystore entry for information on removing an entry from the keystore.


Customizing the name or location of a keystore

When you include the -keystore option with the -genkey, -import, or -identitydb options, The keytool command uses the name and location supplied with -keystore option to override the default keystore name and location.

See Generating a key pair entry for an example of the -keystore option combined with -genkey option.


Changing the password for a keystore

To change the keystore password, combine the -storepasswd option with the keytool command. A prompt is issued for the existing password, if it is not provided. For example:

keytool -storepasswd -new newpassword -storepass oldpassword

In this example, the password for the default keystore is changed from oldpassword to newpassword.


Customizing a keystore implementation type

The KeyStore class, which is provided in the java.security package, contains well-defined interfaces to access and modify multiple types of keystore implementations. A keystore type defines the format of the data that is stored in the keystore. It also identifies the algorithms used to protect the private keys in the database. Sun Microsystems supplies a proprietary keystore format, JKS, for use as a built-in default keystore implementation type. The JKS type uses individual passwords to protect private keys. It also protects the keystore database with a password. The default type is identified by the following line in the security property file:

keystore.type=jks

Keystore type designations are case insensitive; so JKS is considered to be the same as jks.

In addition to the default JKS implementation type, the java.security package contains an abstract KeystoreSpi class, which enables other keystore formats to be implemented using Service Provider Interfaces (SPI). When an implementation type other than the default type is used to create the keystore, the client must provide an SPI and supply a KeystoreSpi subclass implementation type.

Each application that uses the keystore retrieves the value for the keystore.type property and compares the value to each installed provider until a match is located. Applications use a static method called getDefaultType, which is part of the KeyStore class, to retrieve the value of the keystore.type property. An instance of the default keystore type is created by the following line of code:

KeyStore keystore = KeyStore.getInstance(Keystore.getDefaultType())

Keystores having different implementation types are not compatible. Applications can choose different types of keystore implementations from different providers. The Keytool utility treats the keystore location that is passed to it on the command line as a file name. It reads in the keystore information and provides access to the file by converting the file name into a FileInputStream class object.

For information on implementing customized keystore types, see the Sun Microsystems web site:

http://java.sun.com/

Accessing and displaying keystore entries

The Keytool utility uniquely identifies a keystore entry by its alias. To access a specific entry, include the -alias option when issuing keytool commands.

Listing keystore entries

To display keystore entries, combine the -list option when you issue the keytool command. Include the -alias option with the -list option to display the entry associated with that alias. If the entry associated with the alias is a key pair, the first certificate in the certificate chain, which is the public key for the entry, is displayed. If the entry associated with the alias is a trusted certificate, then the MD5 fingerprint, in the default binary code format is displayed. (A fingerprint is a hash value that is calculated by using a message digest function to encrypt a digital signature.) You can display the output in printable encoding format, as defined by the Internet RFC 1421 standard, by including the -rfc option.

If you combine the -list option with the keytool command and do not include an alias, the entire content of the keystore is displayed.

Printing a keystore certificate

The -printcert option outputs the fingerprint of the certificate entry, using the MD5 binary code format. If the -rfc option is used with the -printcert option, the output is displayed in printable encoding format. The -printcert option enables a certificate's fingerprint to be compared to an entry from a trusted source.

The contents of a file can be sent to the -printcert option by supplying the file name with the -file option.

The -printcert option is automatically invoked when the -import option is issued. (The -noprompt option suppresses the -printcert output.)


Migrating an identity database into a keystore database

The -identitydb option reads the information from a JDK 1.1.x-style identity database and migrates it in to the keystore. The -file option is used to supply the file name of the identity database. If no file name is given, it reads the identity database from standard input. If a keystore does not already exist, it is created.

Only identities (database entries) labeled as trusted are migrated in to the keystore. An identity that is rejected is ignored. The trusted identity's name is used as the alias for the keystore entry. All private keys are encrypted under the same password, which is storepass. If a default keystore is being created to hold the entries from the identity database, this same password is automatically assigned to the keystore also. When the migration is complete, the system administrator must use the -keypasswd option to assign individual passwords to the private keys and the -storepass option to change the default password applied to the keystore.

In an identity database, it is possible to have multiple certificates associated with the same public key. In a keystore, each entry has a private key and a corresponding public key, which is stored in the first link of the certificate chain. When identities are migrated from the identity database into a keystore, only the first certificate in the identity is stored in the keystore. The name of the identity in the first certificate becomes the alias in the keystore, and an alias must be unique.

The following command is an example combining the -identitydb option with other options:

keytool -identitydb -file idb_file -storepass storepass -v

This command does the following:

  • It reads the information in the file named idb_file, stores it as a keystore entry that is identified by an alias, which is created by the name of the identity in the first certificate, and assigns the password storepass to all private keys in the identity database and also to the keystore itself.

  • The -v option provides a more detailed output.

The -identitydb option is combined with the following options:

  • -file

  • -J

  • -keystore

  • -storepass

  • -storetype

  • -v

These options are described in Options used with the keytool command.

Go to previous article: Using the Keytool utility Go to next article: Administering key pair entries

 

 
Go to previous article: Using the Keytool utility Go to next article: Administering key pair entries