11.2. Usage

  1. Check the version of tkstool by running the following command:
    tkstool -V
    
    This should return output similar to the following:
    tkstool: Version 1.0
    
  2. Create new software databases.
    tkstool -N -d .
    Enter a password which will be used to encrypt your keys.
    The password should be at least 8 characters long,
    and should contain at least one non-alphabetic character.
    
    Enter new password:
    Re-enter password:
    

    Note

    A hardware HSM can be used instead of the software database if the modutil utility is first used to insert the HSM slot and token into the secmod.db database.
    If an HSM is used, then the option -h hsm_token must be added to each of commands below.
  3. List the contents of the local software key database.
    tkstool -L -d .
     
    slot: NSS User Private Key and Certificate Services
    token: NSS Certificate DB
    
    Enter Password or Pin for "NSS Certificate DB":
    tkstool: the specified token is empty
    
  4. Create a transport key called transport.
    tkstool -T -d . -n transport
    
  5. When prompted, fill in the database password, then type in some noise to seed the random number generator.
  6. The session key share and corresponding KCV are displayed. Write down both of these.
  7. Run the following command to produce an identical transport key; this is generally used within another set of databases which need to use identical transport keys. When this is run, multiple session key shares and KCVs are generated. Write down all of this information.
    tkstool -I -d . -n verify_transport
    
    Responses similar to the following appear:
    Generating first symmetric key . . .
    Generating second symmetric key . . .
    Generating third symmetric key . . .
    Extracting transport key from operational token . . .
         transport key KCV: A428 53BA
    Storing transport key on final specified token . . .
    Naming transport key "transport" . . .
    Successfully generated, stored, and named the transport key!
    
  8. List the contents of the key database again.
    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
    
  9. Use the transport key to generate and wrap a master key, and store the master key in a file called file.
    tkstool -W -d . -n wrapped_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 "wrapped_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)
    
  10. List the contents of the software key database again.
    tkstool -L -d .
    
     slot: NSS User Private Key and Certificate Services
    token: NSS Certificate DB
    
    Enter Password or Pin for "NSS Certificate DB":
     0 wrapped_master
     1 transport
    

    Note

    The order of the keys is not important, and some systems may display the keys in a different order.
  11. Use the transport key to generate and unwrap a master key called unwrapped_master stored in a file called file.
    tkstool -U -d . -n unwrapped_master -t 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 "unwrapped_master" . . .
    Successfully unwrapped, stored, and named the master key!
    
  12. List the contents of the key database to show all keys.
    tkstool -L -d .
    
     slot: NSS User Private Key and Certificate Services
    token: NSS Certificate DB
    
    Enter Password or Pin for "NSS Certificate DB":
     0 unwrapped_master
     1 wrapped_master
     2 transport
    
  13. Delete a key from the database.
    tkstool -D -d . -n wrapped_master
    
    Enter Password or Pin for "NSS Certificate DB":
    tkstool: 1 key(s) called "wrapped_master" were deleted
    
  14. List the contents of the key database again to show all keys.
    tkstool -L -d .
    
    slot: NSS User Private Key and Certificate Services
    token: NSS Certificate DB
    
    Enter Password or Pin for "NSS Certificate DB":
     0 unwrapped_master
     1 transport