6.13. Setting Up a New Master Key

Procedure 6.2. Generating and Transporting Wrapped Master Keys

1. Obtain the internal PIN required to access the Token Key Service security databases:

   # cat /var/lib/pki/pki-tomcat/tks/conf/password.conf
   
   internal=649713464822
   internaldb=secret12
   replicationdb=-752230707
   

2. Open the TKS instance alias/ directory:

   # cd /var/lib/pki/pki-tomcat/alias

3. Create a transport key named transport:

   # tkstool -T -d . -n 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.
4. When prompted, fill in the database password. Then, follow on-screen instructions to generate a random seed.

   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
   

5. The next prompt will generate a series of session keys. Follow on-screen instructions until the final message:

   Successfully generated, stored, and named the transport key!

6. Use the transport key to generate and wrap a master key and store it in a file named file:

   # 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)
   

7. Copy the wrapped master key over to the appropriate locations or facility.
8. If necessary, generate new security databases on the HSM or at the facility:

   # tkstool -N -d <directory>

   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.

   # tkstool -I -d <directory> -n verify_transport

9. Use the transport key to unwrap the master key stored in the file. Provide the security database PIN when prompted:

   # 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!
   

10. Verify that the keys have been added to the database properly:

    # 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