Chapter 12   Key Database Tool


Key Database Tool is a command-line utility that can modify the key database file (key3.db) of iPlanet Certificate Management System (CMS). You can use the utility to create or change the database password, generate new public and private key pairs, display the contents of the database, or delete key pairs from the database.

Key database management tasks are part of a process that typically also involves managing client certificate databases (cert7.db file). The key and certificate management process generally begins with creating keys in the key database, then generating and managing certificates in the certificate database.

This chapter discusses key database management. For information on certificate database and security module database management, see Chapter 11 "Certificate Database Tool" and Chapter 16 "Security Module Database Tool."

This chapter has the following sections:

• Availability

• Syntax

• Usage

• Examples

Availability

---

This tool is available for AIX 4.3, OSF/1 v4.0D, Solaris 2.6 (SunOS 5.6),
Solaris 8, and Windows NT 4.0.

Syntax

---

To run Key Database Tool, type the command

keyutil option [arguments]

where option and arguments are combinations of the options and arguments listed in the following section. Each command takes one option. Each option may take zero or more arguments. To see a usage string, issue the command without options, or with the -H option.

Options and Arguments

Options specify an action and are uppercase. Option arguments modify an action and are lowercase. Key Database Tool options and their arguments are defined as follows:

Table 12-1    Description of options and arguments  

Option	Description
-N	Create a new key database and set its password. Use the -h tokenname argument to specify a specific hardware or software token in which to create the new database.
-C	Change the password to a key database.
-G	Generate a new public and private key pair within a database. The key database should already exist; if one is not present, this option will initialize one by default. Some smart cards (for example, the Litronic card) can store only one key pair. If you create a new key pair for such a card, the previous pair is overwritten.
-L	List the keyID of keys in the key database. A keyID is the modulus of the RSA key or the publicValue of the DSA key. IDs are displayed in hexadecimal ("0x" is not shown). You can identify keys by a shortkeyID. The shortkeyID is the first few bytes of the keyID, starting from the second byte, with a length sufficient to identify it uniquely. Use the -a argument to list keys of all tokens. Otherwise the list will contain only keys in the default (internal) slot. Use the -l argument to list DSA as well as RSA keys.
-P	Display public key information on the screen.
-D	Delete a private key from a key database. Specify the key to delete with the -k argument. Specify the database from which to delete the key with the -d argument. Use the -t argument to specify explicitly whether to delete a DSA or an RSA key. If you do not use the -t argument, the option looks for an RSA key matching the shortkeyID. When you delete keys, be sure to also remove any certificates associated with those keys from the certificate database, by using the Certificate Database Tool. Some smart cards (for example, the Litronic card) do not let you remove a public key you have generated. In such a case, only the private key is deleted from the key pair. You can display the public key with the command keyutil -L -h tokenname.
-H	Display a list of the options and arguments used by Key Database Tool.
Argument	Description
-a	List the RSA keys of all tokens when listing keys in the database.
-d keydir	Specify a directory containing a key database file. On Unix Key Database Tool defaults to $HOME/.netscape (that is, ~/.netscape), and on Windows NT the default is the current directory. The key3.db and cert7.db database files must reside in the same directory.
-e exp	Set an alternate exponent value to use in generating a new RSA public key for the database, instead of the default value of 65537. The available alternate values are 3 and 17.
-f noise-file	Read a seed value from the specified binary file to use in generating a new RSA private and public key pair. This argument makes it possible to use hardware-generated seed values and unnecessary to manually create a value from the keyboard. The minimum file size is 20 bytes.
-h tokenname	Specify the name of a token to act on. Unless otherwise specified, the default token is an internal slot (specifically, internal slot 2). An internal slot is a virtual slot maintained in software, rather than a hardware device. Internal slot 2 is used by key and certificate services. Internal slot 1 is used by cryptographic services. Use the Module Database Tool (modutil -list) to get a list of token names in the module database.
-k shortkeyID	Specify a private key by using the key identifier. You can use the complete keyID (as shown by the -L option), or the shortkeyID. The shortkeyID is the first few bytes of the keyID, starting from the second byte, with a length sufficient to identify it uniquely. If you specify a shortkeyID that is not unique, the first private key that matches the shortkeyID is found.
-l	List DSA as well as RSA keys when listing keys in the key database.
-q pqgfile	Read an alternate PQG value from the specified file when generating DSA key pairs. If this argument is not used, Key Database Tool generates its own PQG value. PQG files are created with a separate DSA utility.
-s size	Set a key size to use when generating new public and private key pairs. The minimum is 256 bits and the maximum is 1024 bits. The default is 1024 bits. Any size between the minimum and maximum is allowed.
-t rsa|dsa	Specify the type of a key, either RSA or DSA. The default value is rsa. By specifying the type of key you can avoid mistakes caused by duplicate shortkeyIDs.
-w password-file	Specify a file to automatically supply the password necessary to access a key database. This is a plain-text file containing one password. You should not use this argument if you are accessing an internal slot and hardware tokens that use different passwords. Be sure to prevent unauthorized access to this file.

Usage

---

Key Database Tool's capabilities are grouped as follows, using these combinations of options and arguments. The specifications in square brackets are optional, those without square brackets are required.

• Creating a new key3.db file and setting its password:

  -N [-d keydir] [-w password-file]

• Changing the password to a key database file:

  -C [-d keydir]

• Generating new RSA key pairs in a key database file:

  -G [-h tokenname] [-t rsa] [-s num] [-e exp] [-d keydir]
  [-f noise-file] [-w password-file]

• Generating new DSA key pairs in a key database file:

  -G [-h tokenname] -t dsa [-q pqgfile -s num]
  [-d keydir] [-w password-file]

• Listing the keyIDs of the keys in a database:

  -L [-a] [-l] [-t rsa|dsa] [-h tokenname] [-d keydir]

• Displaying public key information from the database:

  -P -k shortkeyID [-t rsa|dsa] [-h tokenname]
  [-d keydir] [-w password-file]

• Deleting private keys from a key database file:

  -D -k shortkeyID [-t rsa|dsa] [-h tokenname]
  [-d keydir] [-w password-file]

• Displaying a list of the options and arguments used by Key Database Tool:

  -H

Examples

---

Includes the following:

• Creating a Key Database

• Generating a New Key

• Displaying Public Key Information

• Listing Key IDs

• Deleting a Private Key

Creating a Key Database

This example creates new key database files (key3.db and secmod.db) in the specified directory:

keyutil -N -d keydir

Key Database Tool prompts you as follows:

Creating a brand new key database:keydir/key3.db
Database not initialized. Setting password.
Enter new password:
Re-enter password:

After you enter the password, Key Database Tool creates new key3.db and secmod.db files in the specified directory.

Generating a New Key

This example generates a new key in a key database:

keyutil -G -d keydir

Key Database Tool then displays the following:

----------------------------------------------------
Netscape Communications Corporation
Key Generation
--------------------------------------------------------

Welcome to the key generator. With this program, you can
generate the public and private keys that you use for secure
communications.

A random seed must be generated that will be used in the
creation of your key. One of the easiest ways to create a random
seed is to use the timing of keystrokes on a keyboard.

You have specified the name 'mykey' for your key

If this is correct, press enter:

To begin, type keys on the keyboard until this progress meter is
full. DO NOT USE THE AUTOREPEAT FUNCTION ON YOUR KEYBOARD!

Continue typing until the progress meter is full:

|************************************************************|

Finished. Press enter to continue:

Generating key. This may take a few moments...

Password:

generated public/private key pair

Note that if you do not specify a token name, the key is generated on the internal slot. This is equivalent to the -h internal argument.

If you use the -f noise-file argument, Key Database Tool does not ask for keyboard input.

If you use the -w password-file argument, Key Database Tool reads the password from the file instead of asking for keyboard input. Avoid using this argument when you are accessing both the internal slot and tokens that have different passwords.

Displaying Public Key Information

This example prints the public key's information:

keyutil -P -k e95c -d keydir

The public key information appears after you give the correct password:

Password:

It's the first key found.
RSA Public-Key:
modulus:
00:e9:5c:4a:73:74:39:22:6d:c6:da:4e:b3:1f:01:26:9d:be:
d1:74:ae:cd:c7:7d:65:f9:1d:31:1f:71:fb:60:d0:45:46:5f:
5a:19:e7:61:1e:e7:ce:9f:4a:13:4e:d6:e9:06:90:2a:ba:bd:
0b:5f:7b:a3:28:21:1e:0f:1c:f4:3a:ba:3a:8f:0b:e1:99:91:
cc:e8:fd:17:d2:1c:66:13:6b:95:27:b1:eb:bc:9c:e6:7b:f0:
3a:b9:44:dc:24:a6:f8:83:9a:9e:80:3f:74:48:09:6b:3f:a6:
46:51:be:e0:1b:51:87:8c:44:94:f0:fe:41:fe:b4:9f:4c:0a:
04:a9:a1
publicExponent: 65537 (0x10001)

Listing Key IDs

This command lists the key IDs in the key database:

keyutil -L -d keydir

After you enter the password, Key Database Tool displays the following:

RSA Public-Key:
modulus:
00:e9:5c:4a:73:74:39:22:6d:c6:da:4e:b3:1f:01:26:9d:be:
d1:74:ae:cd:c7:7d:65:f9:1d:31:1f:71:fb:60:d0:45:46:5f:
5a:19:e7:61:1e:e7:ce:9f:4a:13:4e:d6:e9:06:90:2a:ba:bd:
0b:5f:7b:a3:28:21:1e:0f:1c:f4:3a:ba:3a:8f:0b:e1:99:91:
cc:e8:fd:17:d2:1c:66:13:6b:95:27:b1:eb:bc:9c:e6:7b:f0:
3a:b9:44:dc:24:a6:f8:83:9a:9e:80:3f:74:48:09:6b:3f:a6:
46:51:be:e0:1b:51:87:8c:44:94:f0:fe:41:fe:b4:9f:4c:0a:
04:a9:a1

When unmodified, this command lists all the RSA keys in the default (internal) slot. You can refine this command's output with the -a, -h, and -l arguments.

Deleting a Private Key

This example deletes a private key from the key database:

keyutil -D -k e95c -d keydir

When you delete keys, be sure to remove any certificates associated with those keys from the certificate database by using the Certificate Database Tool.