| Command Line Tools Guide Red Hat Certificate System |
| Previous |
Contents |
Index |
Next |
Chapter 12
TKS Tool
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:
- "Location," on page 403
- "Setting the Library Path Environment Variable," on page 403
- "Syntax," on page 404
- "Options," on page 405
- "Sample," on page 410
Location
The tool is located with the rest of the command-line tools in this directory: <server_root>/bin/cert/tools.
Setting the Library Path Environment Variable
Before using the TKS tool, set the Library Path environment variable so that it points to the NSPR and NSS libraries located in the CS. For example (in tcsh on Solaris):
setenv LD_LIBRARY_PATH <ca-server-root>/bin/cert/lib:$LD_LIBRARY_PATHSyntax
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 -H for 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 -R option). Also, transport keys residing on Chrysalis-ITS hardware tokens that were created by an earlier version of tksTool can NOT have their KCV values determined by utilizing the -K option of the tksTool due to the CKA_ENCRYPT and CKF_ENCRYPT bits not getting set during their creation by the previous tool.
Options
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 -R option). Also, transport keys residing on Chrysalis-ITS hardware tokens that were created by an earlier version of tksTool can NOT have their KCV values determined by utilizing the -K option of the tksTool due to the CKA_ENCRYPT and CKF_ENCRYPT bits not getting set during their creation by the previous tool.
Sample
- tksTool -V
- should produce this output:
- tksTool: Version 1.0
- 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 modutil tool 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.
- 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
- 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.
- 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_master and store it in a file called file by 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.
- 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_master stored in a file called file by 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.
- 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.
- 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
- 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.
| Previous |
Contents |
Index |
Next |