|
Developer's Guide
|
|
|
Developer's Guide
|
|
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:
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.
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.
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).
Currently supported values for "-sigalg" are:
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.
In the "-genkeypair" function, the "-curve <curve name>" parameter can be used to generate an elliptical curve key pair. The curve name is a character string taken from the following list:
The "-encrypt" function can encrypt symmetric keys, RSA and EC private keys. In the future, this feature will be expanded to encrypt general files. The "-decrypt" function requires that the "-keysize" parameter be provided so that the missing key meta data can be provided in the resulting key PEM file. Private keys are encrypted in the PKCS#8 encoding. One additional note, the mechanism (i.e, -m) used to encrypt private keys may require the use of padding due to their PKCS#8 encoding.
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.
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.
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.
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.
