6.13. Setting Up a New Master Key This section will describe the procedures and configuration required to set up a new master key in the Token Key Service (TKS). See the Red Hat Certificate System Planning, Installation, and Deployment Guide for background information. Procedure 6.1. Creating a New Master Key Obtain internal the PIN required to access the TKS security databases: Open the alias/ directory of the TKS instance: Generate a new master key using the tkstool utility. For example: Verify that the keys have been properly added to the database: 6.13.1. Generating and Transporting Wrapped Master Keys (Key Ceremony) If a master key is going to be used on an external token or in multiple locations, then it must be wrapped so that it can be safely transported to the hardware tokens. The tkstool utility can be used to generate transport keys, which are then used to send the master key to the facility where the tokens are generated. The process of transferring wrapped master keys is commonly called a Key Ceremony . Note Transport keys can only be used with the master key they were generated with. Procedure 6.2. Generating and Transporting Wrapped Master Keys Obtain the internal PIN required to access the Token Key Service security databases: Open the TKS instance alias/ directory: Create a transport key named transport : Note The tkstool utility prints out the key shares and KCV values for each of the three session keys generated. Save them to a file as they are necessary to regenerate the transport key in new databases later in this procedure, and to regenerate the key if lost. When prompted, fill in the database password. Then, follow on-screen instructions to generate a random seed. The prompt will generate a series of session keys. Follow on-screen instructions until the final message: Use the transport key to generate and wrap a master key and store it in a file named file : Copy the wrapped master key over to the appropriate locations or facility. If necessary, generate new security databases on the HSM or at the facility: Alternatively, add the -I option to produce a key identical to the one generated originally in a the new database. Regenerating the transport key in this way requires that you input the session key share and KCV for each of the session keys generated earlier in this procedure. Use the transport key to unwrap the master key stored in the file. Provide the security database PIN when prompted: Verify that the keys have been added to the database properly:

Commands:
cat /var/lib/pki/pki-tomcat/tks/conf/password.conf internal=649713464822 internaldb=secret12 replicationdb=-752230707
cd /var/lib/pki/pki-tomcat/alias
tkstool -M -n new_master -d /var/lib/pki/pki-tomcat/alias -h <token_name> Enter Password or Pin for "NSS Certificate DB": Generating and storing the master key on the specified token . . . Naming the master key "new_master" . . . Computing and displaying KCV of the master key on the specified token . . . new_master key KCV: CA5E 1764
tkstool -L -d . slot: NSS User Private Key and Certificate Services token: NSS Certificate DB Enter Password or Pin for "NSS Certificate DB": <0> new_master
cat /var/lib/pki/pki-tomcat/tks/conf/password.conf internal=649713464822 internaldb=secret12 replicationdb=-752230707
cd /var/lib/pki/pki-tomcat/alias
tkstool -T -d . -n transport
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. 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. Type the word "proceed" and press enter
Successfully generated, stored, and named the transport key!
tkstool -W -d . -n new_master -t transport -o file Enter Password or Pin for "NSS Certificate DB": Retrieving the transport key (for wrapping) from the specified token . . . Generating and storing the master key on the specified token . . . Naming the master key "new_master" . . . Successfully generated, stored, and named the master key! Using the transport key to wrap and store the master key . . . Writing the wrapped data (and resident master key KCV) into the file called "file" . . . wrapped data: 47C0 06DB 7D3F D9ED FE91 7E6F A7E5 91B9 master key KCV: CED9 4A7B (computed KCV of the master key residing inside the wrapped data)
tkstool -N -d <directory>
tkstool -I -d <directory> -n verify_transport
tkstool -U -d directory -n new_master -t verify_transport -i file Enter Password or Pin for "NSS Certificate DB": Retrieving the transport key from the specified token (for unwrapping) . . . Reading in the wrapped data (and resident master key KCV) from the file called "file" . . . wrapped data: 47C0 06DB 7D3F D9ED FE91 7E6F A7E5 91B9 master key KCV: CED9 4A7B (pre-computed KCV of the master key residing inside the wrapped data) Using the transport key to temporarily unwrap the master key to recompute its KCV value to check against its pre-computed KCV value . . . master key KCV: CED9 4A7B (computed KCV of the master key residing inside the wrapped data) master key KCV: CED9 4A7B (pre-computed KCV of the master key residing inside the wrapped data) Using the transport key to unwrap and store the master key on the specified token . . . Naming the master key "new_master" . . . Successfully unwrapped, stored, and named the master key!
tkstool -L -d slot: NSS User Private Key and Certificate Services token: NSS Certificate DB Enter Password or Pin for "NSS Certificate DB": <0> transport <1> new_master