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

  1. Obtain internal the PIN required to access the TKS security databases:
    # cat /var/lib/pki/pki-tomcat/tks/conf/password.conf
    internal=649713464822
    internaldb=secret12
    replicationdb=-752230707
    
  2. Open the alias/ directory of the TKS instance:
    # cd /var/lib/pki/pki-tomcat/alias
  3. Generate a new master key using the tkstool utility. For example:
    # 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
    
  4. Verify that the keys have been properly added to the database:
    # 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
    

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

  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