ctkmu
Key Management Utility for the ProtectToolkit-C environment, used for ProtectToolkit-C token management. This includes operations required by a token’s SO, such as setting user PINs and re-initializing tokens, as well as those operations required by the normal User, such as object management.
A number of commands can be used with the ctkmu utility to help with key creation, deletion, import, export, as well as PIN change, token initialization and replication.
NOTE When operating in WLD/HA mode, this utility should only be utilized to view the configuration. Any changes to the configuration should be made when operating in NORMAL mode.
Syntax
Create key from entered components
ctkmu c -t<type> -n<name> -a<attribute> -k<num> [-s<slot>] [-z<size>] [-i<hex_string>] [-p]
Create key with components
ctkmu c -t<type> -n<name> -a<attribute> -k<num> -g [-s<slot>] [-z<size>] [-i<hex_string>]
Create key without components
ctkmu c -t<type> -n<name> -a<attribute> [-s<slot>] [-z<size>] [-i<hex_string>] [-C<curve_name>]
Delete object
ctkmu d -n<name> [-s<slot>]
Erase smart card
ctkmu e -c<slot>
Import key(s) from single-custodian smart card
ctkmu i -w<name> -c<slot> [-s<slot>]
Import key(s) from multi-custodian smart cards
ctkmu i -c<slot> [-s<slot>]
Import key(s) from console
ctkmu i -a<attribute> -n<name> -t<type> -w<name> -y [-s<slot>] [-i<hex_string>] [-m] [-z<size>]
Import key(s) from file
ctkmu i -w<name> <filename> [-s<slot>] [-2]
Import domain parameters
ctkmu idp -n<name> -t<type> -a<attribute> <filename> [-s<slot>]
Import token
ctkmu it <filename> [-s<slot>]
Import from PKCS #12 file
ctkmu j -n<name> -a<attribute> <filename> [-s<slot>] [-i<hex_string>]
List objects on token(s)
ctkmu l -s<slot> [-v] [-n<name>]
Modify attributes
ctkmu m -n<name> -a<attribute> [-s<slot>]
Initialize or change PINs
ctkmu p [-s<slot>] [-O]
Replicate token
ctkmu rt -d <slotlist> [-s <slot>]
Smart card status
ctkmu s -c<slot>
Initialize/re-initialize token
ctkmu t [-s<slot>] [-l<label>]
Export key(s) to single-custodian smart card
ctkmu x -w<name> -c<slot> [-s<slot>] [-3] [-4] [-n<name>]
Export key(s) to multi-custodian smart card
ctkmu x -c<slot> [-s<slot>] [-3] [-4] [-n<name>] [-M]
Export key(s) to file
ctkmu x -w<name> <filename> [-s<slot>] [-3] [-4] [-n<name>]
Export key(s) to console
ctkmu x -n<name> -w<name> -y [-s<slot>] [-m]
Export key(s) to PKCS #12 file
ctkmu x [-s<slot>] -j --pkLabel --keyCertLabel [--certalgo] [--pkalgo] <filename>
Export token
ctkmu xt -S<serial> <filename> [-s<slot>]
Commands
| Command | Description |
|---|---|
| c |
Create Key This command is used to generate new keys on the specified token. The -a parameter is used to specify the attributes, the -n parameter specifies the key’s label and the -t parameter the new key type. PKCS #11 Attributes contains further information on key attributes. Common uses for this command are generation of a random key, import of a split custodian key (using the -k flag), or creation of a split custodian key (using the -g and -k flags). When importing a split custodian key, optionally, a supported PIN pad device can be used (using the -p flag) to ensure that the key components are entered directly to the device. |
| d |
Delete Key This command is used to delete a key on the specified token. This command will permanently destroy the key with the label specified with the -n parameter. |
| e |
Erase Smart Card This command is used to erase a smart card in the specified slot and will leave the smart card in an uninitialized state. |
| i |
Import Key This command is used to import keys previously exported with the export command (see below). |
| idp |
Import Domain Parameters This command is used to store Domain Parameters objects onto a Token. The -s option indicates the slot e.g. -s1 for slot 1 - default is slot 0. The -n option indicates the label of the new object. The -t option specifies the key type, it may be ec or dsa or dh but only ec is supported. The -a option allows attributes to be specified. Only the ‘P’ private and ‘M’ Modifiable attributes are allowed. The default attribute if -a option is missing is CKA_PRIVATE=false and CKA_MODIFIABLE=false. The <filename> option specifies a test file that contains the information required to construct the domain parameters. |
| it |
Import Token This command is used to import a token image into the specified token. The -s parameter identifies the token that will be replaced with the imported token image, by default slot 0 is used. The <filename> parameter specifies the token image file to import. To complete this operation, ctkmu will prompt for the user PIN of the destination token. When importing into an un-initialized token, ctkmu will prompt for the SO PIN of the destination token. If the device is running in FIPS mode, ctkmu will prompt for the device administrator PIN of the destination token. |
| j |
Import Private Key This command is used to import a Private Key and a Certificate from a PKCS #12 file format. |
| l |
List Information This command is used to display information on the objects stored on the token in the specified slot. This command will list the actual keys, certificates and other objects, or, if the token is a smart card token previously used with the key export function information on that key backup set. |
| m |
The Modify Attributes command ‘m’ is used to toggle the specified attributes. That is, change from TRUE to FALSE and vice versa or add the attribute if it does not exist. |
| p |
The Pin command ‘p’ is used to initialize the User PIN or to change an existing PIN (either the User or SO PIN) the command will prompt. 'Cannot change the pin for the token in slot 1 as it is not initialized. You can use the command "ctkmu t -s 1" to initialize this token.' If the PIN is initialized the current PIN will be prompted for before the new PIN may be specified. To change the SO PIN, specify the -O option. |
| rt |
The replicate token command 'rt' is used to replicate a source token to one or more destination tokens. The -s parameter identifies the source token to be replicated, by default slot 0 is used. The -d parameter specifies one or more destination tokens to replicate the source token to. If an error occurs replicating to a particular token, an error will be reported and that token will be skipped. This prevents offline or faulty devices from spoiling the replication process for other tokens. To complete this operation, ctkmu will prompt for the user PIN of the source token. When replicating to an uninitialized token, ctkmu will prompt for the SO PIN of the destination token. If the device is running in FIPS mode, ctkmu will prompt for the device administrator PIN of the destination token. |
| s | The Smart Card status command ‘s’ is used to display information on the smart card token currently inserted in the specified slot. Details of the keys exported to the token will be displayed. |
| t | The Initialize/Reset Token command ‘t’ allows for existing tokens to be initialized or re-initialized. If the specified token contains an initialized token the current SO PIN will be prompted for before a new Token label may be specified and the token re-initialized. If the token is uninitialized this command will only operate if the ‘No clear PINs’ flag is not specified for the HSM (otherwise only the Administrator may initialize tokens with the ctconf utility). In this case the new SO PIN and label may be specified. Once the token has been reset or initialized a new user PIN may also be set. |
| x |
The Export Key command ‘x’ allows for keys to be exported to one or more smart cards or to a file or to the screen. Keys exported to the screen are wrapped with standard algorithm and are suitable for transport to foreign systems. Keys wrapped for smart card or file backup use proprietary algorithms and can only be restored to compliant ProtectToolkit-based HSMs. The main difference between the standard and proprietary methods is that the proprietary method wraps all the attributes of the key so that when a key is restored it must contain the same attributes as the original. Please note that if the -j parameter is used to export a private key and certificate to a PKCS#12 file format the following considerations need to be made. Exportable private key types are: RSA, DSA, and ECDSA. >If the private key being exported is marked CKA_EXPORTABLE=TRUE and CKA_EXTRACTABLE=FALSE, the toolkit will prompt for Security Officer (SO) to login to perform the export operation. >User performing the PKCS#12 private key export will be asked to provide two (2) passwords (one for Payload and one for HMAC). At this stage, the user must take into account which 3rd party tools will be used to extract the PKCS#12 file. For example, Microsoft Windows requires that the Payload and HMAC passwords be identical. OpenSSL, however, will extract Key and Certificate exported by ctkmu using two different passwords. The user needs to decide which password policy best suits their needs. >The RC family of encryption algorithms (and others) are prohibited in FIPS mode. ctkmu shall reject the command and display a warning message if they are used under this security policy. NOTE When logging in to a smart card, the card is locked after 7 consecutive incorrect PIN attempts. You must re-initialize the card to set a new PIN. |
| xt | The export token command 'xt' is used to export a token for later import to a specific device. The -s <slot> parameter identifies the source token to be exported, by default slot 0 is used. The -S parameter specifies the serial number of the intended device where token import will be later performed. The <filename> parameter specifies the output token image file. To complete this operation, ctkmu will prompt for the user PIN of the source token. |
Options
| Option |
Description |
||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| -a<attributes> |
--attributes =<attributes> Specifies attributes for an object / key. Valid attributes are:
NOTE You can only set CKA_EXPORTABLE to TRUE if you are using firmware 5.06.04 or newer and have set the Weak PKCS#11 Mechanisms security flag. For more information about CKA_EXPORTABLE and setting the Weak PKCS#11 Mechanisms security flag, seeCKA_EXPORT, CKA_EXPORTABLE and Weak PKCS#11 Mechanisms, respectively. |
||||||||||||||||||||||||||||||||
| -c<slot> |
--sc-slot-num =<slot> Specifies the Smart Card slot to export to or import from. |
||||||||||||||||||||||||||||||||
| -C<curve_name> |
--curve-name =<label> Specifies which curve to use. Valid values are: >brainpoolP160r1 >brainpoolP160t1 >brainpoolP192r1 >brainpoolP192t1 >brainpoolP224r1 >brainpoolP224t1 >brainpoolP256r1 >brainpoolP256t1 >brainpoolP320r1 >brainpoolP320t1 >brainpoolP384r1 >brainpoolP384t1 >brainpoolP512r1 >brainpoolP512t1 >c2tnb191v1 >c2tnb191v1e >curve25519 >ed25519 >P-192 (also known as prime192v1 and secp192r1) >P-224 (also known as secp224r1) >P-224K1 (also known as secp224k1) >P-256 (also known as prime256v1 and secp256r1) >P-384 (also known as secp384r1) >P-521 (also known as secp521r1) >secp256k1 >or any valid ECC Domain Parameter object label If -tec is specified, the -C parameter must be included in the command otherwise ctkmu will exit with an error message. |
||||||||||||||||||||||||||||||||
| -d<slotlist> |
--dest =<slotlist> Specifies a comma-separated list of tokens identified by slot number. The special value all denotes all initialized tokens with a token label identical to the source token label and where trust has been established between the devices. |
||||||||||||||||||||||||||||||||
| <filename> |
Specifies a file to be created for export or used to import a key, certificate, token, or set of domain parameters. |
||||||||||||||||||||||||||||||||
| -g |
--gen-comp Generate key components. |
||||||||||||||||||||||||||||||||
| -h, -? |
--help Display usage information. |
||||||||||||||||||||||||||||||||
| -j |
--pkcs12 Export to PKCS#12 format. -pkLabel Private Key to be exported to PKCS#12 file. -keyCertLabel Certificate Label to be exported to PKCS#12 file. -pkalgo Private Key Encryption Algorithms. This parameter is optional. The default setting is DES3. Possible settings are: RC4_128, RC4_40, DES3, DES2, RC2_128, RC2_40. Note that if FIPS mode is ON, then none of the algorithms in the RC family are allowed. -certalgo Certificate Encryption Algorithm. This parameter is optional. In FIPS mode the default setting is DES3. If FIPS mode is OFF, the default setting is RC2_40. Possible settings are: RC4_128, RC4_40, DES3, DES2, RC2_128, RC2_40. |
||||||||||||||||||||||||||||||||
| -k<numb> |
--num-comp =<numb> Number of key components required to be entered or number to be generated (when -g parameter is specified). |
||||||||||||||||||||||||||||||||
| -l<label> |
--label =<label> Specify label. |
||||||||||||||||||||||||||||||||
| -m |
--multi-part Do a multi-part key entry for console import/export. |
||||||||||||||||||||||||||||||||
| -M |
--NofM Causes the N of M scheme to be used for a multiple-custodians backup. This means that the key is split in such a way that the original key may be recovered with the co-operation of any of the custodians with a user specified, minimum number of custodians being required. |
||||||||||||||||||||||||||||||||
| -n<name> |
--name =<name> Name of the object to operate on. |
||||||||||||||||||||||||||||||||
| -O |
--SO-PIN Change the Security Officer PIN. Used with the change PIN command. |
||||||||||||||||||||||||||||||||
| -o <userpin> | Specifies the Security Officer PIN in the command line along with the command, instead of prompting for it afterwards. Useful for automation, but not recommended for use in production environments since the password is exposed in plaintext. Can be specified with all commands that require SO login. | ||||||||||||||||||||||||||||||||
| -p |
--pinpad Use a supported PIN pad device for entering key components. See Key Entry via PIN Pad for complete PIN pad instructions. |
||||||||||||||||||||||||||||||||
| -s<slot> |
--slot-num =<slot> Specifies the slot to operate on. Default is 0 (zero), however must be specified when using the l command and -v option for Slot 0. |
||||||||||||||||||||||||||||||||
| -S<serial> |
--serial =<serial> Specifies the device serial number. |
||||||||||||||||||||||||||||||||
| -t<type> |
--type=<type> The type of key to create. Options are: aes | des | des2 | des3 | rc2 | rc4 | cast | idea | seed | rsa | dsa | ec |
||||||||||||||||||||||||||||||||
| -u <userpin> | Specifies the slot user PIN in the command line along with the command, instead of prompting for it afterwards. Useful for automation, but not recommended for use in production environments since the password is exposed in plaintext. Can be specified with all commands that require token login. | ||||||||||||||||||||||||||||||||
| -v |
--verbose Displays the attributes that ctkmu may change. |
||||||||||||||||||||||||||||||||
| -w<name> |
--wrap-key =<name> Name of the key used to wrap or unwrap. NOTE If you are specifying a DES3 key as the wrapping key for an export key operation (with the x command), you must also include the -3 option. If -3 is not included, the operation fails and an |
||||||||||||||||||||||||||||||||
| -y |
--console Import/Export using the console. |
||||||||||||||||||||||||||||||||
| -z<size> |
--size=<size> Size of the key to create/import (for AES, RC2, RC4, CAST, RSA, DSA and generic secret). NOTE If the FIPS Mode security policy is enabled, the cryptographic operations of RSA, DSA, DH, and EC algorithms are restricted to key sizes within a specified range. For more information about the size limitations of keys that are created or imported in FIPS Mode, see FIPS Mode Operational Restrictions. |
||||||||||||||||||||||||||||||||
| -2 |
--Cprov2 Import keys from a Cprov 2 formatted file. This is used when migrating keys from an older Cprov 2 key format to the current format |
||||||||||||||||||||||||||||||||
| -3 |
--PTKC3 Generate export to smart card and file using the ProtectToolkit-C version 3 format (CKM_WRAPKEY_DES3_CBC), instead of the default wrapping mechanism (CKM_WRAPKEY_AES_KWP). Used when exporting keys to be sent to older style HSMs. NOTE Wrapping and unwrapping operations using this option will fail in FIPS mode. |
||||||||||||||||||||||||||||||||
| -4 |
--PTKC4 Generate export to smart card and file using the ProtectToolkit-C version 4 format (CKM_WRAPKEY_AES_CBC), instead of the default wrapping mechanism (CKM_WRAPKEY_AES_KWP). Used when exporting keys to be sent to older style HSMs. NOTE Wrapping operations using this option will fail in FIPS mode. |
Exit Status
The ctkmu utility will return a zero(0) exit status when successful. A non-zero exit status is returned on an error. Warnings are not treated as errors.
