Developer's Guide
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
PKCS 11 Command Line Tool Reference Guide

Introduction

P6R's PKCS11 library comes with a command line tool that can be used to manage tokens. For example, the p6pkcs11tool can initialize a token, set its user PIN, and generate keys on a token. Below is a list of all currently provided functions the p6pkcs11tool can perform:

* USAGE: p6pkcs11Tool [-D i|w|d|a] <options>
* " -attributes" get a list of all non-key material attributes and their values for the specified object
* " -attribute-name" one of: 'CKA_LABEL','CKA_ID','CKA_APPLICATION','CKA_ENCRYPT','CKA_SIGN','CKA_VERIFY','CKA_DERIVE',
* 'CKA_WRAP','CKA_UNWRAP','CKA_EXTRACTABLE','CKA_SENSITIVE','CKA_SIGN_RECOVER','CKA_VERIFY_RECOVER'
* " -attribute-value" string value of {'true' | 'false'} for boolean attributes, otherwise a string value
* " -config-add-slot" add the next slot & token definition from the p6pkcs11.conf file
* " -delete" delete a key on a token
* " -export" export a certificate or symmetric key in PEM format to a file
* " -genkey" generate a symmetric key
* " -genkeypair" generate an asymmetric key pair
* " -h" get detailed help
* " -import" load a symmetric key or certificate into the selected token
* " -ip" initialize CKO_USER PIN
* " -it" (re-)initialize a token
* " -lc" list a token's P6R configuration information
* " -list" list keys, certifcates stored in a token
* " -lm" list mechanisms supported by a token
* " -lp" list slot identifiers defined by an attached HSM
* " -ls" list defined slots with details
* " -lt" list all token details
* " -print" print a certificate in text format to a file
* " -rk" replace KMIP TLS credentials, for KMIP tokens only
* " -sign" generate a signature over the provided file
* " -sp" modify the CKO_USER PIN
* " -test" test that a token can be accessed
* " -vacuum" delete any left over session objects because application did not call C_CloseSession
* " -verify" verify an existing signature of a provided file
*

For the most up to date list of commands and options type "p6pkcs11tool" or "p6pkcs11tool -h" on the command line to get the complete usage description.

PKCS 11 Attributes

The "-genkey", "-genkeypair", "-list", and "-import" commands will often need to specify the value of several PKCS 11 attributes. It is not possible to add these attributes all on the command line so a special configuration file is associated with our p6pkcs11tool. The "p6p11templates.conf" file defines tables of PKCS 11 attributes to be used with a tool command.

The user can specify the optional '-t <number>' onto the "-genkey", "-genkeypair", "-list", and "-import" commands. This option allows the user to select one out of many defined template files to apply to the operation. For example, '-t 5' selects the "p6p11templates5.conf" file. Thus the number specified as part of the '-t' option is appended to the end of the file name to select a template file. Note that 'number' can have the value {1..n}, where zero maps to the default "p6p11templates.conf" file.

Here is an example of a p6p11templates.conf file.

* # Based on the type of PKCS11 objects what default attributes
* # should be set
* #
* CKA_ENCRYPT = true
* CKA_DECRYPT = true
* CKA_TOKEN = true
* CKA_PRIVATE = false
*
* CKA_SIGN = true
* CKA_TOKEN = true
* CKA_PRIVATE = true
* CKA_SENSITIVE = true
* CKA_EXTRACTABLE = false
*
* CKA_VERIFY = true
* CKA_TOKEN = true
* CKA_PRIVATE = false
*
* CKA_TOKEN = true
*
* [FIND_OBJECTS]
* # CKA_CLASS = CKO_PRIVATE_KEY --- commented out
* # CKA_TOKEN = true
* # CKA_PRIVATE = true
*
*
* # The command line "-alias" value defaults to setting both the CKA_LABEL and CKA_ID PKCS#11 attributes to the same value.
* # To override this default behavior set the "alias" property below to the PKCS#11 value of the attribute you want to use instead.
* # Setting this property will result in only one PKCS#11 attribute being set. Note, only the following attributes are currently
* # supported. Uncomment the "alias" property to set its value.
* #
* # CKA_LABEL 0x00000003UL which is 3
* # CKA_APPLICATION 0x00000010UL which is 16
* # CKA_ID 0x00000102UL which is 258
* #
* [GEN_PARAMETERS]
* # alias = 3
*

The "-genkey" tool command maps to the C_GenerateKey() PKCS 11 API function. The section "[CKO_SECRET_KEY]" is used to define default attributes that will be passed to the call to C_GenerateKey(). The following PKCS 11 attributes can be added to this section: CKA_ENCRYPT, CKA_DECRYPT, CKA_SIGN, CKA_VERIFY, CKA_WRAP, CKA_UNWRAP, CKA_TOKEN, CKA_PRIVATE, CKA_EXTRACTABLE, and CKA_SENSITIVE.

The "-import" tool command maps to the C_CreateObject() PKCS 11 API function. The sections "[CKO_SECRET_KEY]", "[CKO_CERTIFICATE]", and are used to define default attributes that will be passed to the call to C_CreateObject(). The following PKCS 11 attributes can be used for a CKO_SECRET_KEY section are: CKA_ENCRYPT, CKA_DECRYPT, CKA_SIGN, CKA_VERIFY, CKA_WRAP, CKA_UNWRAP, CKA_TOKEN, CKA_PRIVATE, CKA_EXTRACTABLE, and CKA_SENSITIVE. The following PKCS 11 attribute can be used for a CKO_CERTIFICATE section: CKA_TOKEN.

The "-genkeypair" tool command maps to the C_GenerateKeyPair() PKCS 11 API function. The sections "[CKO_PRIVATE_KEY]" and "[CKO_PUBLIC_KEY]" are used to define default attributes that will be passed to the call to C_GenerateKey(). The following PKCS 11 attributes can be added to each of these sections: CKA_ENCRYPT, CKA_DECRYPT, CKA_SIGN, CKA_VERIFY, CKA_WRAP, CKA_UNWRAP, CKA_TOKEN, CKA_PRIVATE, CKA_EXTRACTABLE, and CKA_SENSITIVE.

The "-list" tool command maps to the C_FindObjectsInit(), C_FindObjects(), and C_FindObjectsFinal() API functions. If no attributes are defined in the "[FIND_OBJECTS]" section then information about all objects in the token are displayed to the user. Otherwise, any attributes defined in the "[FIND_OBJECTS]" section can be used to narrow the returned results. For example, if the attribute "CKA_CLASS = CKO_PRIVATE_KEY" is set, then only information about private key objects would be displayed to the user. The following PKCA 11 attributes can be added to this section: CKA_CLASS, CKA_TOKEN, CKA_PRIVATE, CKA_ENCRYPT, CKA_DECRYPT, CKA_SIGN, CKA_VERIFY, CKA_WRAP, CKA_UNWRAP, CKA_TOKEN, CKA_PRIVATE, CKA_EXTRACTABLE, and CKA_SENSITIVE. In addition, the "-list" command looks at the "alias" parameter in the "[GEN_PARAMETERS]" section to see what PKCS 11 attribute it should use as an object's alias (the default is CKA_LABEL).

SO and User PINs

The PKCS#11 version 2.40 standard allows PIN values to contain any valid UTF8 character, but the token may impose subset restrictions. Also each token can define its own mimimum and maximum PIN supported lengths. PIN lengths can be determined by the list token (or "-lt") command.

An Object's Alias

The "-genkey", "-genkeypair", and "-import" functions all take the "-alias" parameter. This parameter is meant to associate a moniker (or nickname) to the key or certificate object being stored on the token. However, PKCS 11 does not currently define a unique identifier attribute. So this library default behavior is to store the value passed in for alias into the CKA_LABEL and CKA_ID PKCS 11 attributes. We do this because we have noticed that these are the popular attributes that applications seem to use for a unique identifier (e.g., Oracle TDE uses CKA_LABEL, and Java uses CKA_ID). This way keys and certificates created / loaded by this tool can be seen by various applications.

The above described default behavior can be overridden by setting the "alias" property in the "{Gen_Parameters]" section. The "alias" property can be set to the numeric value of the PKCS 11 attribute to map the matching command line value to. Currently, the following PKCS 11 attributes are supported: CKA_LABEL, CKA_ID, and CKA_APPLICATION. When set only one of these attributes will be used.

Note that as a recent change a new CKA_UNIQUE_ID attribute has been added to PKCS 11 but since it is new most tokens will not support it. All P6R tokens currently support this attribute and can be used on the command line instead of the "-alias" command line parameter.

Adding and Modifying Slots

Some of the information defined in the p6pkcs11tool.conf file is loaded into a secure P6R keystore. The PKCS 11 tool uses the information out of its keystore to process commands. When the PKCS 11 command line tool starts it checks to see if its keystore exists and if not then automatically creates it from the information defined in the p6pkcs11tool.conf file.

One way to modify the values stored in the PKCS 11 keystore is to delete it, modify the p6pkcs11tool.conf file, and then re-run the command line tool (e.g., p6pkcs11tool -h will do it). This update method will allow the user to remove existing slots, and update an existing slot's parameters (i.e., TLS certificates and private key). However, any keys also stored in the local keystore(s) will be lost and so should be exported before performing this step. (Some slots create their own keystores in "..\db\" and would also have to be deleted. For example this is what the HPE NSP token does.)

Another way to achieve the same effect is to first use the "-config-delete-slot" command, after exporting any existing keys, certificates, etc, and then modify the p6pkcs11.conf file and the list of disabled slots (i.e., pkcs11disabled.txt). Afterwards the slot can be added back into the running instance of the PKCS 11 library by using the "-config-add-slot" command. However, if all the user wants to do is to add another slot, then the next slot in the list is defined in the p6pkcs11.conf file (all slots must have consecutive numbers) and the "-config-add-slot" is run. Finally, the "slotCount" parameter in the "[p6pkcs11-slots-gen]" has to be incremented by one before using the PKCS 11 library again.

Some slots will create their own P6R keystore under the directory path "..\db\" (for example, files "p6pkcs11-slot-3" and "p6pkcs11-slot-3.sig" for slot 3). If the users executes the "-config-delete-slot" command then he also needs to delete the left over keystore files since this command line tool will not do so.

C_GetTokenInfo() on an HPE NSP Token

When running the command line "p6pkcs11tool -lt 0", where 0 is for slot zero that holds an NSP token the PKCS#11 command line tool should output something like the following.

* ------- Token Details -------
*
* Slot Id: 0
* Label: [ ]
* Manufacter Id: [HPE 0.65 10 SEP 2010 10:54:29 ]
* Model: [A10160 ]
* Serial Number: [JL07M4 ]
* Flags: 1
* Flag set: CKF_RNG
* Max Session Count: 0
* Session Count: 0
* Max RW Session Count: 0
* RW Session Count: 0
* Max PIN length: 19
* Min PIN length: 8
* Total Public Memory: FFFFFFFF
* Free Public Memory: FFFFFFFF
* Total Private Memory: FFFFFFFF
* Free Private Memory: FFFFFFFF
* Hardware Version: 1.0
* Firmware Version: 1.0
* UTC time: [ ]
*

Note the values displayed for the fields Manufacter Id, Model, and Serial Number. All these values come directly from a response from the NSP command 1120. Part of the execution of the "-lt" command is for the PKCS#11 tool to call C_GetTokenInfo() which on the NSP token makes command 1120 to the configured NSP.