Chapter 11. tkstool (Managing Token Keys)
The TKS utility,
tkstool, manages keys, including keys stored on tokens, the TKS master key, and related keys and databases.
11.1. Syntax
The
tkstool can be used to manage certificates and keys in several different ways. The syntax for these different operations is as follows:
- Deleting a key from a token.
tkstool -D -n keyname -d dbdir [-h token_name] [-p dbprefix] [-f pwfile]
- Inputting shares to generate a new transport key.
tkstool -I -n keyname -d dbdir [-h token_name] [-p dbprefix] [-f pwfile]
- Displaying the key check value (KCV) of the specified key.
tkstool -K -n keyname -d dbdir [-h token_name] [-p dbprefix] [-f pwfile]
- Listing a specified key or all keys.
tkstool -L -n keyname -d dbdir [-h all | -h token_name] [-p dbprefix] [-f pwfile] [-x]
- Generating a new master key.
tkstool -M -n keyname -d dbdir [-h token_name] [-p dbprefix] [-f pwfile]
- Creating a new key database.
tkstool -N -d dbdir [-p dbprefix] [-f pwfile]
- Changing the key database password.
tkstool -P -d dbdir [-p dbprefix] [-f pwfile]
- Renaming a symmetric key.
tkstool -R -n keyname -r new_keyname -d dbdir [-h token_name] [-p dbprefix] [-f pwfile]
- Listing all security modules.
tkstool -S -d dbdir [-p dbprefix] [-x]
- Generating a new transport key.
tkstool -T -n keyname -d dbdir [-h token_name] [-p dbprefix] [-f pwfile] [-z noiseFile]
- Unwrapping a wrapped master key.
tkstool -U -n keyname -d dbdir -t transport_keyname -i inputFile [-h token_name] [-p dbprefix] [-f pwfile]
- Wrapping a new master key.
tkstool -W -n keyname -d dbdir -t transport_keyname -o outputFile [-h token_name] [-p dbprefix] [-f pwfile]
Note
Chrysalis-ITS version 2.3 is required to support version 1.0 of the
-R option of the tkstool.
Transport keys residing on Chrysalis-ITS hardware tokens created by an earlier version of
tkstool cannot have their KCV values determined with the -K option of the tkstool because the CKA_ENCRYPT and CKF_ENCRYPT bits were not set when they were created by the previous tool.
The
tkstool options are as follows:
| Option | Description |
|---|---|
D | Deletes a key from the token. |
d | Required. Gives the security module database (HSM, if allowed for that operation) or the key database directory (software). |
f | Gives the path and filename of the password file, if one is used. |
h | Gives the token name for the toke which contains the key to be managed. Some operations allow an all option to manage all keys in the token. |
I | Inputs shares to generate a new transport key. |
i | Required with -U. Gives the path and filename of the input file which contains the wrapped master key. |
K | Displays the KCV of the specified key. |
L | Lists the specified key or all keys. |
M | Generates a new master key. |
N | Creates a new key database (software). |
n | Required for every operation except -N, -P, and -S. Gives the name of the key being managed. |
o | Required with -W. Gives the path and filename for the file to which to output the new wrapped master key. |
P | Changes the key database password (software). |
p | Gives the prefix to the key database directory. |
R | Renames a symmetric key. |
r | Required with -R. Gives the new key name. |
S | Lists all security modules. |
T | Generates a new transport key. |
t | Required with -U and -W. Gives the name of the transport key being managed. |
U | Unwraps the wrapped master key. |
W | Wraps the new master key. |
x | Forces the database to be read/write. |
z | Gives the path and filename of the noise file to generate the key. |
There are two additional options which can be used with
tkstool to get more information about the utility.
| Option | Description |
|---|---|
H | Displays the extended help information. |
V | Display the version number of the tkstool tool. |
