Complete Contents
About This Guide
PART 1: Netscape Certificate Management System
Chapter 1: Introduction to Certificate Management System
Chapter 2: Administration Tasks and Tool
Chapter 3: Configuration
PART 2: Managing Certificate Management System
Chapter 4: Installing and Uninstalling Instances
Chapter 5: Starting and Stopping Instances
PART 3: System-Level Configuration
Chapter 6: Configuring Ports, Database, and SMTP Settings
Chapter 7: Managing Privileged Users and Groups
Chapter 8: Keys and Certificates
PART 4: Authentication
Chapter 9: Introduction to Authentication
Chapter 10: Using the PIN Generator Tool
Chapter 11: Configuring Authentication for End Entities
Chapter 12: Developing Authentication Plug-ins
PART 5: Job Scheduling and Notification
Chapter 13: Introduction to Job Scheduling and Notifications
Chapter 14: Configuring Jobs
PART 6: Policies
Chapter 15: Introduction to Policies
Chapter 16: Configuring Policies
PART 7: LDAP Publishing
Chapter 17: Introduction to LDAP Publishing
Chapter 18: Configuring Subsystems for LDAP Publishing
Chapter 19: Publishing CRLs
PART 8: Agent and End-Entity Interfaces
Chapter 20: Introduction to End-Entity and Agent Interfaces
Chapter 21: Customizing End-Entity and Agent Interfaces
PART 9: Logs
Chapter 22: Introduction to Logs
Chapter 23: Managing Logs
PART 10: Issuance and Management of End-Entity Certificates
Chapter 24: Issuing and Managing End-Entity Certificates
Chapter 25: Recovering Encrypted Data
PART 11: Appendixes
Appendix A: Distinguished Names
Appendix B: Backing Up and Restoring Data
Appendix C: Command-Line Utilities
Appendix D: Certificate Database Tool
Appendix E: Key Database Tool
Appendix F: Netscape Signing Tool
Appendix G: SSL Strength Tool
Appendix H: SSL Debugging Tool
Previous Next Contents Index Bookshelf


Appendix E Key Database Tool

Key Database Tool is a command-line utility that can modify the key database file (key3.db) of Netscape 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 appendix discusses key database management. For information on certificate database and security module database management, see "Certificate Database Tool" and the section "modultil" in Appendix B of Managing Servers with Netscape Console.

This appendix has the following sections:
Availability
This tool is available for Solaris 2.5.1 (SunOS 5.5.1) 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:

Options

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

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


Examples
Includes the following:

 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.

 

© Copyright 1999 Netscape Communications Corp., a subsidiary of America Online, Inc. All rights reserved.