|
Command-Line Tools Guide Netscape Certificate Management System |
|
||
|
|
You can use the TKS tool to manipulate keys, including keys stored on tokens, the TKS master key, and related keys and databases.
This chapter has the following sections:
The tool is located with the rest of the command-line tools in this directory:
<server_root>/bin/cert/tools.Setting the LD_LIBRARY_PATH Environment Variable
Before using the TKS tool, set the
LD_LIBRARY_PATHenvironment variable so that it points to the NSPR and NSS libraries located in the CMS. For example (intcsh):setenv LD_LIBRARY_PATH <ca-server-root>/bin/cert/lib:$LD_LIBRARY_PATH
To run the TKS tool, type one of the following commands:
tksTool -D -n keyname -d DBDir [-h token_name]
[-p DBPrefix] [-f pwfile]
tksTool -I -n keyname -d DBDir [-h token_name]
[-p DBPrefix] [-f pwfile]
tksTool -K -n keyname -d DBDir [-h token_name]
[-p DBPrefix] [-f pwfile]
tksTool -L -d DBDir [-h all | -h token_name]
[-p DBPrefix] [-n keyname] [-f pwfile] [-x]
tksTool -M -n keyname -d DBDir [-h token_name]
[-p DBPrefix] [-f pwfile]
tksTool -N -d DBDir
[-p DBPrefix] [-f pwfile]
tksTool -P -d DBDir
[-p DBPrefix] [-f pwfile]
tksTool -R -n keyname -r new_keyname -d DBDir [-h token_name]
[-p DBPrefix] [-f pwfile]
tksTool -S -d DBDir
[-p DBPrefix] [-x]
tksTool -T -n keyname -d DBDir [-h token_name]
[-p DBPrefix] [-f pwfile] [-z noisefile]
tksTool -U -n keyname -d DBDir -t transport_keyname -i infile
[-h token_name] [-p DBPrefix] [-f pwfile]
tksTool -W -n keyname -d DBDir -t transport_keyname -o outfile
[-h token_name] [-p DBPrefix] [-f pwfile]Type
tksTool -Hfor more detailed descriptions.CAVEAT: Version 2.3 of the Chrysalis-ITS software is required to support version 1.0 of the
tksTool(to support the-Roption). Also, transport keys residing on Chrysalis-ITS hardware tokens that were created by an earlier version oftksToolcan NOT have their KCV values determined by utilizing the-Koption of thetksTooldue to theCKA_ENCRYPTandCKF_ENCRYPTbits not getting set during their creation by the previous tool.
This section shows the results of running
-D Delete a key from the token
-n keyname The name of the key to delete
[required]
-d DBDir Security module database directory (HSM);
Key database directory (software only)
[required]
-h token_name Name of token from which to remove key
[optional]
-p DBPrefix Security module database prefix
[optional]
-f pwfile Specify the password file
[optional]
-H Display this extended help for Usage
-I Input shares to generate a new transport key
-n keyname The name to assign to the generated
transport key
[required]
-d DBDir Security module database directory (HSM);|
Key database directory (software only)
[required]
-h token_name Name of token in which to generate
transport key
[optional]
-p DBPrefix Security module database prefix
[optional]
-f pwfile Specify the password file
[optional]
-K Display the KCV of the specified key
-n keyname The name of the key to perform a KCV on
[required]
-d DBDir Security module database directory (HSM);
Key database directory (software only)
[required]
-h token_name Name of token on which the named key
resides
[optional]
-p DBPrefix Security module database prefix
[optional]
-f pwfile Specify the password file
-L List out a specified key, or all keys
-d DBDir Security module database directory (HSM);
Key database directory (software only)
[required]
-h all | Look on all tokens OR
-h token_name Name of token in which to look for keys
[optional]
-p DBPrefix Security module database prefix
[optional]
-n keyname The name of the key to list
[optional]
-f pwfile Specify the password file
[optional]
-x Force the database to open R/W (software
only)
[optional]
-n keyname The name to assign to the generated master
key
[required]
-d DBDir Security module database directory (HSM);
Key database directory (software only)
[required]
-h token_name Name of token in which to generate master
key
[optional]
-p DBPrefix Security module database prefix
[optional]
-f pwfile Specify the password file
[optional]
-N Create a new key database (software only)
-d DBDir Key database directory (software only)
[required]
-p DBPrefix Key database prefix (software only)
[optional]
-f pwfile Specify the password file
[optional]
-P Change the key database password (software only)
-d DBDir Key database directory (software only)
[required]
-p DBPrefix Key database prefix (software only)
[optional]
-f pwfile Specify the password file
[optional]
-n keyname The original name assigned to a
pre-existing symmetric key
[required]
-r new_keyname The new name assigned to the original
pre-existing symmetric key
[required]
-d DBDir Security module database directory (HSM);
Key database directory (software only)
[required]
-h token_name Name of token in which to generate master
key
[optional]
-p DBPrefix Security module database prefix
[optional]
-f pwfile Specify the password file
[optional]
-d DBDir Security module database directory
[required]
-p DBPrefix Security module database prefix
[optional]
-x Force the database to open R/W (software
only)
[optional]
-T Generate a new transport key
-n keyname The name to assign to the generated
transport key
[required]
-d DBDir Security module database directory (HSM);
Key database directory (software only)
[required]
-h token_name Name of token in which to generate
transport key
[optional]
-p DBPrefix Security module database prefix
[optional]
-f pwfile Specify the password file
[optional]
-z noisefile Specify the noise file to be used
[optional]
-U Unwrap the wrapped master key
-n keyname The name to assign to the unwrapped
master key
[required]
-d DBDir Security module database directory (HSM);
Key database directory (software only)
[required]
-t transport_keyname The name of the
transport key (e. g. - unwrapping key)
[required]
-i infile The filename from which to input the
wrapped master key
[required]
-h token_name Name of token in which to store wrapped
master key
[optional]
-p DBPrefix Security module database prefix
[optional]
-f pwfile Specify the password file
[optional]
-V Display the version number of this tool
-W Wrap a newly generated master key
-n keyname The name to assign to the generated
master key
[required]
-d DBDir Security module database directory (HSM);
Key database directory (software only)
[required]
-t transport_keyname The name of the transport key
(e. g. - wrapping key)
[required]
-o outfile The filename in which to output the
wrapped master key
[required]
-h token_name Name of token in which to generate
master key
[optional]
-p DBPrefix Security module database prefix
[optional]
-f pwfile Specify the password file
[optional]CAVEAT: Version 2.3 of the Chrysalis-ITS software is required to support version 1.0 of the
tksTool(to support the-Roption). Also, transport keys residing on Chrysalis-ITS hardware tokens that were created by an earlier version oftksToolcan NOT have their KCV values determined by utilizing the-Koption of thetksTooldue to theCKA_ENCRYPTandCKF_ENCRYPTbits not getting set during their creation by the previous tool.
- Make sure you are using the correct version of
tksTool. Running the command
tksTool -V
- should produce this output:
tksTool: Version 1.0
- Create some software databases using
tksTool -N -d .
- and entering a database password twice.
- Note: A hardware HSM can be utilized instead of the software database for all of the following commands if the
modutiltool is first utilized to insert the HSM slot and token into the secmod.db database. An additional
-h <hsm token>
- must be added to each of command lines below.
- List the contents of the local software key database to show that it is empty by running
tksTool -L -d .
- which will display the following:
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
- Create a transport key called "transport" by running the command
tksTool -T -d . -n transport
- After prompting for the database password, the first screen asks the user to type in some noise to seed the random number generator. The next screen clears the contents of this noise to allow separation of the teams that record the "session key share" values from the user who enters the noise. The next screen contains the first "session key share" and its corresponding key check value (KCV). Both of these values should be written down so that the command
tksTool -I -d . -n verify_transport
- can be run to produce an identical transport key (generally used within another set of databases to produce an identical transport key). The next screen clears the contents of the first "session key share" ansd its KCV to allow separation of the teams that record this information. This is followed by a second "session key share"/KCV, separation screen, a third "session key share"/KCV, a separation screen, and finally something resembling the following:
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!
- Note: Obviously, the transport key KCV displayed above only represents sample output from
tksTool, and the value should not be taken to be a literal value.
- Once again, list the contents of the local software key database
to show this key by running
tksTool -L -d .
- which will display the following:
slot: NSS User Private Key and Certificate Services
token: NSS Certificate DB
Enter Password or Pin for "NSS Certificate DB":
<0> transport
- Use the transport key to generate and wrap a master key called
wrapped_masterand store it in a file calledfileby executing the command
tksTool -W -d . -n wrapped_master -t transport -o file
- resulting in something like this:
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)
- Note: Obviously, the key/KCV displayed above only represents sample output from
tksTool, and the value should not be taken to be a literal value.
- Once again, list the contents of the local software key database to show all keys by running
tksTool -L -d .
- which will display the following:
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 "numerical" order of the keys is not relevant, and on some systems may display in a different order.
- Use the transport key to generate and unwrap a master key called
unwrapped_masterstored in a file calledfileby executing the command
tksTool -U -d . -n unwrapped_master -t transport -i file
- resulting in something like this:
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!
- Note: Obviously, the key/KCV displayed above only represents sample output from
tksTool, and the value should not be taken to be a literal value.
- Once again, list the contents of the local software key database to show all keys by running
tksTool -L -d .
- which will display the following:
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
- Note: The "numerical" order of the keys is not relevant, and on some systems may display in a different order.
- To delete a key from the database, perform the command
tksTool -D -d . -n wrapped_master
- which will display the following:
Enter Password or Pin for "NSS Certificate DB":
tksTool: 1 key(s) called "wrapped_master" were deleted
- Once again, list the contents of the local software key database to show all keys by running
tksTool -L -d .
- which will display the following:
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
- Note: The "numerical" order of the keys is not relevant, and on some systems may display in a different order.
© 2001 Sun Microsystems, Inc. Portions copyright 1999, 2002-2004 Netscape Communications Corporation. All rights reserved.
Last Updated November 23, 2004