CTKMU

Key Management Utility for the SafeNet ProtectToolkit-C environment, used for SafeNet 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. Refer to Operation in WLD Mode and Operation in HA Mode for further details.

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] [–n<name>]

Export key(s) to multi–custodian smart card

ctkmu x –c<slot> [–s<slot>] [–3] [–n<name>] [–M]

Export key(s) to file

ctkmu x –w<name> <filename> [–s<slot>] [–3] [–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>] ––pkLabel––keyCertLabel [––certalgo] [––pkalgo]

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 SafeNet 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.
Keys wrapped for smart card backup may use one of two basic methods; keys may be exported as split custodian in which case they will be encrypted using a randomly generated key which is then split and distributed to a number of smart card tokens.  Alternatively a key wrapping key may be specified which will then be used to encrypt the key specified for backup.  This encrypted data can then be written to a smart card token or to a file. 

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.

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:

P CKA_PRIVATE=1
M CKA_MODIFIABLE=1
T CKA_SENSITIVE=1
W CKA_WRAP=1
w CKA_EXPORT=1
I

CKA_IMPORT=1

U CKA_UNWRAP=1
X CKA_EXTRACTABLE=1
x CKA_EXPORTABLE=1
R CKA_DERIVE=1
E CKA_ENCRYPT=1
D CKA_DECRYPT=1
S CKA_SIGN=1
V CKA_VERIFY=1
L CKA_SIGN_LOCAL_CERT=1
C CKA_USAGE_COUNT=1 (can only be used with c command)

–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:

>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

>c2nb191v1

>c2tnb191v1e

>brainpoolP160r1

>brainpoolP160t1

>brainpoolP192r1

>brainpoolP192t1

>brainpoolP224r1

>brainpoolP224t1

>brainpoolP256r1

>brainpoolP256t1

>brainpoolP320r1

>brainpoolP320t1

>brainpoolP384r1

>brainpoolP384t1

>brainpoolP512r1

>brainpoolP512t1

>or any valid ECC Domain Parameter object label

If –tec is specified, the –C parameter must be included in the command otherwise ctcert 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.

–p ––pinpad

Use a supported PIN pad device for entering key components.

–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

–v ––verbose

Displays the attributes that ctkmu may change.

–w<name>

––wrap–key =<name>

Name of the key used to wrap or unwrap.

–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).

–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 (see Key Migration from SafeNet ProtectToolkit-C V4.1).

–3 ––PTKC3

Generate export to smart card and file using the SafeNet ProtectToolkit-C version 3 format. Used when exporting keys to be sent to older style HSMs.

NOTE   If option -3 is not present in the ctkmu command line, by default the utility will use the CKM_WRAPKEY_AES_KWP mechanism.

-4

---PTKC4

Generate export to smart card and file using the SafeNet ProtectToolkit-C version 4 format. Used when exporting keys to be sent to older style HSMs.

NOTE   If option -4 is not present in the ctkmu command line, by default the utility will use the CKM_WRAPKEY_AES_KWP mechanism.

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.