This library supports 2.40 Version of PKCS 11 (see https://www.oasis-open.org/committees/pkcs11/). It currently supports two types of "fixed" tokens. The first token is a KMIP server (see https://www.oasis-open.org/committees/kmip/). The second token is P6R's software token which uses P6R's Powerful Keystore (see https://www.p6r.com/articles/2011/06/05/key-management-with-a-powerful-keystore/) to store all PKCS 11 objects (e.g., CKO_SECRET_KEY, CKO_PUBLIC_KEY, CKO_PRIVATE_KEY, CKO_CERIFICATE, CKO_DOMAIN_PARAMTERS, CKO_DATA). Any number of slots can be defined and in each slot either type of token can be configured. For example, it is possible to have a PKCS 11 installation that points to several different KMIP servers and several different P6R software token instances each separate from the others. One of the benefits of the PKCS 11 API is that it provides a standard based Keystore API.
The current library meets the requirements for conformance of a PKCS #11 Baseline and Extended Provider (see PKCS #11 Cryptographic Token Interface Profiles Version 2.40, 16-Sep-2014, OASIS Committee Specification 01, http://docs.oasis-open.org/pkcs11/pkcs11-profiles/v2.40/cs01/pkcs11-profiles-v2.40-cs01.doc).
In a future release, this library will allow the user to define their own token types by defining a "plugin" component to extended its function.
An introduction to this product can also be found at: P6R's PKCS 11 Provider, https://www.p6r.com/articles/2014/11/22/p6rs-pkcs-11-provider/.
P6R's PKCS 11 client follows the standards defined in the following documents.
1) OASIS, PKCS #11 Cryptofraphic Token Interface Base Specification Version 2.40, Candidate OASIS Standard 01, 23 December 2014.
2) OASIS, PKCS #11 Cryptographic Token Interface Current Mechanisms Specification Version 2.40, Candidate OASIS Standard 01, 23 December 2014.
3) OASIS, PKCS #11 Cryptographic Token Interfaces Historical Mechamisms Specification Version 2.40, Candidate OASIS Standard 01, 23 December 2014.
This library ships with the standard set of PKCS 11 Version 2.40 ".h" files as defined by the OASIS PKCS 11 Technical committee. These include the files pkcs11.h, pkcs11f.h, and pkcs11t.h. The pkcs11p6r.h file contains P6R vendor defined extensions. The file p6tokenimpl.h defines our token plugin interface for 3rd party tokens.
Note, the pkcs11.h file is meant to be slightly modified for the particular library and platform and we have made such modifications for use with our library.
The KMIP token uses the facilities of a remote KMIP server to implement the features of the PKCS 11 Version 2.40 API. A KMIP token is defined by a set of configuration parameters defined in the p6pkcs11.conf file (see Section "Basic Configuration Parameters"). This token type uses P6R's Secure KMIP Client (SKC) SDK (see https://www.p6r.com/software/skc.html) to communicate with the defined KMIP servers. As of this writing, SKC works with all known commercially available KMIP servers. Our PKCS11 library allows the definition of any number of KMIP tokens all pointing to the same or different KMIP servers.
The KMIP token has the following limitations with object attributes. CKA_ENCRYPT, CKA_DECRYPT, CKA_SIGN, CKA_SIGN_RECOVER, CKA_VERIFY, CKA_VERIFY_RECOVER, CKA_WRAP, CKA_UNWRAP, and CKA_DERIVE CANNOT be changed after an object (i.e., key, certificate, data, domain parameters) is created. This is because the KMIP protocol does not allow a client to modify the KMIP equivalent attributes after a KMIP object is created. However, this token implementation does support the modification of a CKO_DATA object’s CKA_VALUE attribute after the object has been created on a KMIP server.
If logging is turned on (see the Basic Configuration Parameters section below), then a directory will be created under the defined log path with the KMIP server's fully qualified domain (FQDN) name as the directory name (e.g., "../log/kmip01.corp.p6r.com" is created). Under the FQDN directory another directory is also created with the following format: "p6pkcs11-slot-X", where 'X' is replaced with the slot number starting at zero.
The following is a list of all supported PKCS 11 functions: C_Initialize, C_Finalize, C_GetInfo, C_GetFunctionList, C_GetSlotList, C_GetSlotInfo, C_GetTokenInfo, C_GetMechanismList, C_GetMechanismInfo, C_InitToken, C_InitPIN, C_SetPIN, C_OpenSession, C_CloseSession, C_CloseAllSessions, C_GetSessionInfo, C_Login, C_Logout, C_CreateObject, C_CopyObject, C_DestroyObject, C_GetAttributeValue, C_SetAttributeValue, C_FindObjectsInit, C_FindObjects, C_FindObjectsFinal, C_GenerateKey (not including domain parameters), C_GenerateKeyPair, C_SeedRandom, C_GenerateRandom, C_SignInit, C_Sign, C_VerifyInit, C_Verify, C_EncryptInit, C_Encrypt, C_EncryptUpdate, C_EncryptFinal, C_DecryptInit, C_Decrypt, C_DecryptUpdate, C_DecryptFinal, C_DigestInit, C_Digest, C_DigestUpdate, C_DigestKey, C_DigestFinal, C_WrapKey, and C_UnwrapKey.
Note, that not all KMIP servers will support the C_UnwrapKey function. In some cases, the KMIP token will detect this and then return the error code CKR_FUNCTION_NOT_SUPPORTED. In other cases, the C_UnwrapKey call will succeeded but subsequent attempts to retrieve the unwrapped key via calls to C_GetAttributeValue will fail, since the key remains in its wrapped format on the KMIP server.
Note, that not all KMIP servers support streaming operations such as C_EncryptUpdate, C_EncryptFinal, C_DecryptUpdate, C_DecryptFinal, C_DigestUpdate, C_DigestKey, C_DigestFinal. These streaming operations where added to KMIP 1.3 and are optional. When a server does not support these, or the KMIP version in use is not 1.3, then the error code CKR_FUNCTION_NOT_SUPPORTED will be returned for these PKCS 11 functions. In addition, our KMIP token uses several features that where defined starting with KMIP 1.2. Using a KMIP server without adaquate KMIP 1.2 support will disable several PKCS11 features.
Currently, C_WrapKey ignores the CKA_WRAP_TEMPLATE attribute, and C_UnwrapKey ignores the CKA_UNWRAP_TEMPLATE attribute. These should be supported in the near future.
For the CKM_RSA_PKCS_KEY_PAIR_GEN mechanism C_GenerateKeyPair() only works if the attribute CKA_PUBLIC_EXPONENT is not included in the call. Thus for the KMIP token RSA key generation only needs the CKA_MODULUS_BITS attribute.
The implementation of C_CopyObject will copy keys, certificates, data objects, and domain parameter objects. In addition, the pTemplate parameter to the C_CopyObject function supports the following attributes: CKA_TOKEN, CKA_PRIVATE, CKA_ID, CKA_SUBJECT, CKA_MODIFIABLE, CKA_DESTROYABLE, CKA_SENSITIVE, CKA_EXTRACTABLE, CKA_START_DATE, CKA_END_DATE, CKA_ENCRYPT, CKA_DECRYPT, CKA_SIGN, CKA_VERIFY, CKA_DERIVE, CKA_WRAP, CKA_UNWRAP, CKA_VERIFY_RECOVER, CKA_SIGN_RECOVER, and CKA_PUBLIC_KEY_INFO. The use of any other attributes will result in a CKR_TEMPLATE_INCONSISTENT returned.
P6R's software token (or "soft token") uses P6R’s cryptographic API and Keystore to implement the features of the PKCS 11 Version 2.40 API. Both the cryptographic API and Keystore are included as part of the SKC product. Our PKCS 11 library allows the definition of any number of Software tokens where each token gets its own separate secure Keystore to manage PKCS 11 objects (e.g,. keys, certificates, domain parameters, data). P6R’s cryptographic API is a C++ object wrapper around OpenSSL’s C language API.
The location of each token's keystore id defined in configuration (see the Basic Configuration Parameters section below). The keystore's file created follows the format: "p6pkcs11-slot-X" where 'X' is replaced with the slot number starting at zero. The file 'p6pkcs11-slot-X.sig' is also created as long as the keystore in use is a local database.
The following is a list of all supported PKCS 11 functions: C_Initialize, C_Finalize, C_GetInfo, C_GetFunctionList, C_GetSlotList, C_GetSlotInfo, C_GetTokenInfo, C_GetMechanismList, C_GetMechanismInfo, C_InitToken, C_InitPIN, C_SetPIN, C_OpenSession, C_CloseSession, C_CloseAllSessions, C_GetSessionInfo, C_Login, C_Logout, C_CreateObject, C_DestroyObject, C_GetAttributeValue, C_SetAttributeValue, C_FindObjectsInit, C_FindObjects, C_FindObjectsFinal, C_GenerateKey (not including domain parameters), C_GenerateKeyPair, C_GenerateRandom, C_SignInit, C_Sign, C_VerifyInit, C_Verify, C_EncryptInit, C_Encrypt, C_EncryptUpdate, C_EncryptFinal, C_DecryptInit, C_Decrypt, C_DecryptUpdate, C_DecryptFinal, C_DigestInit, C_Digest, C_DigestUpdate, and C_DigestFinal.
A third party can create their own token types by implementing the p6tokenimpl.h interface in a P6R component.
The following are unsupported PKCS 11 features of P6R's KMIP and Software tokens and do not define any limits on third party provided tokens.
The following object attributes are unsupported in the current release: CKA_PRIME_BITS, CKA_SUBPRIME_BITS, CKA_SECONDARY_AUTH, CKA_AUTH_PIN_FLAGS, CKA_WRAP_TEMPLATE, CKA_UNWRAP_TEMPLATE, CKA_HW_FEATURE_TYPE, CKA_PIXEL_X, CKA_PIXEL_Y, CKA_RESOLUTION, CKA_CHAR_ROWS, CKA_CHAR_COLUMNS, CKA_COLOR, CKA_BITS_PER_PIXEL, CKA_CHAR_SETS, CKA_ENCODING_METHODS, CKA_MIME_TYPES, CKA_MECHANISM_TYPE, CKA_REQUIRED_CMS_ATTRIBUTES, CKA_DEFAULT_CMS_ATTRIBUTES, CKA_SUPPORTED_CMS_ATTRIBUTES, CKA_RESET_ON_INIT, and CKA_HAS_RESET.
The following objects are unsupported in the current release for the KMIP and Software tokens: CKO_HW_FEATURE, CKH_MONOTONIC_COUNTER, CKH_CLOCK, and CKH_USER_INTERFACE.
The CKA_TOKEN attribute defaults to false, and the CKA_PRIVATE attribute defaults to true if not defined in a template to an API function for the KMIP and Software tokens.
P6R’s Provider allows any number of slots to be defined and in each slot either type of token can be configured. For example, it is possible to have a PKCS 11 installation that points to several different KMIP servers and several different software token instances each separate from the others. All slots and tokens are defined via a the p6pkcs11.conf configuration file. This configuration file allows the definition of any P6R or customer specific behavior since the PKCS 11 interface is fixed by the OASIS Technical Committee. All keys and certificates required to communicate with a KMIP server or to encrypt/sign a Keystore’s contents are themselves securely stored in a PKCS 11 wide Keystore once the library is initialized.
The current KMIP token library supports the following mechanisms: CKM_AES_KEY_GEN, CKM_CAST5_KEY_GEN, CKM_BLOWFISH_KEY_GEN, CKM_TWOFISH_KEY_GEN, CKM_CAMELLIA_KEY_GEN, CKM_RC2_KEY_GEN, CKM_RC4_KEY_GEN, CKM_RC5_KEY_GEN, CKM_IDEA_KEY_GEN, CKM_SKIPJACK_KEY_GEN, CKM_DES_KEY_GEN, CKM_DES3_KEY_GEN, CKM_RSA_PKCS_KEY_PAIR_GEN, CKM_EC_KEY_PAIR_GEN, CKM_MD2_RSA_PKCS, CKM_MD5_RSA_PKCS, CKM_SHA1_RSA_PKCS, CKM_SHA224_RSA_PKCS, CKM_SHA256_RSA_PKCS, CKM_SHA384_RSA_PKCS, CKM_SHA512_RSA_PKCS, CKM_DSA_SHA1, CKM_DSA_SHA224, CKM_DSA_SHA256, CKM_ECDSA_SHA1, CKM_AES_CBC, CKM_BLOWFISH_CBC, CKM_BLOWFISH_CBC_PAD, CKM_TWOFISH_CBC, CKM_CAMELLIA_ECB, CKM_CAMELLIA_CBC, CKM_DES_ECB, CKM_DES_CBC, CKM_DES_CBC_PAD, CKM_IDEA_ECB, CKM_IDEA_CBC_PAD, CKM_CAST5_ECB, CKM_CAST5_CBC, CKM_CAST5_CBC_PAD, CKM_AES_OFB, CKM_AES_CFB8, CKM_AES_CFB64, CKM_AES_CFB128, CKM_SHA_1_HMAC, CKM_SHA224_HMAC, CKM_SHA256_HMAC, CKM_SHA384_HMAC, CKM_SHA512_HMAC, CKM_AES_CMAC, CKM_SHA_1, CKM_SHA224, CKM_SHA256, CKM_SHA384, CKM_SHA512, CKM_SHA512_224, CKM_SHA512_256, CKM_MD2, CKM_MD5, CKM_RIPEMD160, CKM_RC2_ECB, CKM_RC2_CBC, CKM_RC2_CBC_PAD, CKM_DES3_ECB, CKM_DES3_CBC, CKM_RC4, CKM_SKIPJACK_ECB64, CKM_SKIPJACK_CBC64, CKM_SKIPJACK_OFB64 and CKM_SKIPJACK_CFB64.
If a specific KMIP server does not support one of the above mechanisms (e.g., CKM_EC_KEY_PAIR_GEN), then it can be "disabled" via an entry in the p6pkcs11.conf file for the specific slot (see the description of the tokenDisabledMechs configuration parameter in Section "Basic Configuration Parameters").
The current Software token library supports the following mechanisms: CKM_MD2_RSA_PKCS, CKM_MD5_RSA_PKCS, CKM_SHA1_RSA_PKCS, CKM_SHA224_RSA_PKCS, CKM_SHA256_RSA_PKCS, CKM_SHA384_RSA_PKCS, CKM_SHA512_RSA_PKCS, CKM_DSA_SHA1, CKM_DSA_SHA224, CKM_DSA_SHA256, CKM_ECDSA_SHA1, CKM_SHA_1_HMAC, CKM_SHA224_HMAC, CKM_SHA256_HMAC, CKM_SHA384_HMAC, CKM_SHA512_HMAC, CKM_BLOWFISH_CBC, CKM_DES_ECB, CKM_DES_CBC, CKM_CAST5_ECB, CKM_CAST5_CBC, CKM_IDEA_ECB, CKM_AES_ECB, CKM_AES_CBC, CKM_AES_OFB, CKM_AES_CFB8, CKM_AES_CFB64, CKM_AES_CFB128, CKM_AES_CTR, CKM_DES3_ECB, CKM_DES3_CBC, CKM_SHA_1, CKM_SHA224, CKM_SHA256, CKM_SHA384, CKM_SHA512, CKM_SHA512_224, CKM_SHA512_256, CKM_MD2, CKM_MD5, and CKM_RIPEMD160.
P6R defines the following vendor defined attributes:
The purpose of this extension is to provide basic support for KMIP groups and it maps into the KMIP "Object Group" attribute. Without the CKA_P6R_GROUP attribute defined the standard "default" group is used. P6R's Keystore has the concept of namespaces. These are similar to groups in that they provide collections of objects. When CKA_P6R_GROUP is used for the Software token its value is mapped into the Keystore's namespace parameter. Without the CKA_P6R_GROUP attribute defined the Software token uses "PKCS11" namespace by default.
P6R defines the following vendor defined method:
P6R_DestroyToken() frees all contents in the token and disables its containing slot. This method is added so that a PKCS 11 application can remove a token programmatically.
Only the SO can make this call. The call cannot be made on a token that currently has any in-progress sessions (otherwise the CKR_SESSION_EXISTS error is returned). This function deletes all the stored content on a token and disables the token and slot from use. The slot is disabled by writing the slot identifier into the file specified in the "disabled" configuration parameter (see Section "Basic Configuration Parameters" below). Once a slot is disabled it will not be able to be used or (re-)initialized. Also calls to C_GetSlotInfo() and C_GetTokenInfo() will not return previous slot/token information.
To reuse the slot the SO must enable the slot again by removing its slot identifier from the file defined by the "disabled" configuration parameter, and then redefine (as desired) its token configuration in the p6pkcs11.conf file. Once completed the token can then be initialized as if new.
Return values: CKR_CRYPTOKI_NOT_INITIALIZED, CKR_ARGUMENTS_BAD, CKR_SLOT_ID_INVALID, CKR_SESSION_EXISTS, CKR_PIN_INCORRECT, CKR_DEVICE_ERROR, CKR_GENERAL_ERROR, CKR_FUNCTION_FAILED, CKR_OK
A slot is defined by a section in the p6pkcs11.conf file of the form: "[p6pkcs11-slot-X]". where "X" is replaced with the slot number. An example of such a configuration file with 3 slots where 2 are KMIP tokens and the 3rd is P6R's software token. Many of the configuration items match to standard slot and token information returned by the C_GetSlotInfo() and C_GetTokenInfo() PKCS 11 API functions. In addition to the configuration defined in this section, change to the p6kmip.conf file for KMIP logging is recommended (see the SKC documentation).
Other possible token configuration items:
Restrictions: 1) Each KMIP token must point to a different KMIP server. A KMIP server is defined by the "tokenKMIPServer" configuration parameter and is a fully qualified domain name with an optional port (e.g., "kmiptest01.p6r.com", "kmiptest01.p6r.com:5696"). Thus each slot "contains" a unique token. Note that multiple sessions are supported for each KMIP token. This restriction also prevents one slot from re-initializing its token out from under another slot with the same KMIP token definition.
This contains the following PKCS 11 wide configuration parameters:
The "baseKeyPath" configuration parameter (string value), is the symmetric key protecting the PKCS 11 wide keystore is to be written to after it is generated by the library. This parameter can be either a full path to the key file or just the name of the key file. If it is just a file name then it will be treated as relative to the directory the library runs out of. Essentially, this is the one key that is kept in the clear.
The "keystore" configuration parameter (string value), is optional and can be either the full path to a directory where the PKCS 11 library wide keystore is to be created or a database URI of the standard for: "postgresql8://..." (see Keystore documentation). When this parameter is not provided then a default location is used. Otherwise, when using the full path to a local directory then a Sqlite database will be used. This keystore holds all the keys and certificates used to communicate to KMIP servers and all keys used to protect all other keystores created for software tokens.
The "logDir" configuration parameter (string value), is optional and when not provided a default location is used. Otherwise, the parameter must be a full path to the diretory where PKCS 11 log statements output should be written to.
The "disabled" configuration parameter (string value), is the full path to a file to create that holds all disabled slots as a result of executing the P6R_DestroyToken() extension method. The path must be to a writtable directory. This parameter is optional and is only required if the P6R_DestroyToken() method is to be used.
The "initialSessions" configuration paramter (positive numeric value), is optional and defines the number of possible, concurrent PKCS 11 library wide sessions to start with. This number will be used to pre-allocate sonme of the client memory to support those initial number of sessions. Note that the total number of open sessions is dynamic and will grow as need and as memory permits. This paramter defaults to 200. Note that each active session requires a chunk of memory to maintain its state.
The "pkcs11LibFlags" configuration parameter (bit mask), is optional and defines special library wide handling or features. Represented as an unsigned integer. The current set of valid bit flags are:
(For example, if all 3 flags where set then "pkcs11LibFlags=7" would be the correct value.)
The "[p6pkcs11-slots-gen]" section contains the following PKCS 11 configuration parameters global across all defined slots:
The "slotCount" configuration paramter (positive numeric value), defines the number of slots defined by the p6pkcs11.conf file. Each defined slot gets its own configuration file section such as "[p6pkcs11-slot-X]" where 'X' is replaced with a positive integer starting at zero. With a slotCount of 3 the following configuration file sections should exist: "[p6pkcs11-slot-0]", "[p6pkcs11-slot-1]", "[p6pkcs11-slot-2]".
The "[p6pkcs11-tokens]" section contains third party token implementations via the p6tokenimpl.h interface definition.
Each item in this section consists of a token "name" with its component GUID. For example: UtimacoVersion220 = "{3367270E-43E6-4fed-B57A-0711FAE20CCA}", defines a token named "UtimacoVersion220" with a component GUID of "{3367270E-43E6-4fed-B57A-0711FAE20CCA}". This section can contain any number of token implemenation definitions. In the configuration example above, the "[p6pkcs11-slot-3]" section defines its token implementation via the parameter: slotType="UtimacoVersion220". Several 3rd party tokens are included in the SKC product which are implemented in the component: p6pkcs11tokens.dll on Windows, and p6pkcs11tokens.so on Linux files.
When the "[p6pkcs11-slot-X]" section defines a Software token the following configuration parameters apply:
The "slotDescription" configuration parameter (string value), maps to the "slotDescription" field of the CK_SLOT_INFO PKCS 11 API structure. This field is limited to a maximum of 64 characters.
The "slotFlags" configuration parameter (positive numeric value), maps to the "flags" field of the CK_SLOT_INFO PKCS 11 API structure. Valid values of this flag field are defined in the specification: PKCS #11 Cryptographic Token Interface Base Specification Version 2.40, Section 3.2 Slot and token types, Table 5, Slot Information Flags.
The "slotManufacturer" configuration parameter (string value), maps to the "manufacturerID" field of the CK_SLOT_INFO PKCS 11 API structure. This field is limited to a maximum of 32 characters.
The "slotType" configuration parameter (string value), this is a P6R defined configuration value which defines the token type that runs out of the defined slot. Current valid P6R token names are: { "P6R-keystore", "P6R-KMIP" } where the first value is used to define a Software token and the second value is used for a KMIP token. This parameter can be used to specify a 3rd party token implementation defined in the "[p6pkcs11-tokens]" section. The token name indicates which token type is to be used by the slot and the PKCS 11 library ensures that the proper implementation is used.
The "tokenFirmwareVersion" configuration parameter (string value), maps to the "firwareVersion" field of the CK_TOKEN_INFO PKCS 11 API structure. For software tokens we use this field to define the version of the PKCS 11 library itself since the Software token is built into the library.
The "tokenManufacturer" configuration parameter (string value), maps to the "manufacturerID" field of the CK_TOKEN_INFO PKCS 11 API structure. For software tokens we use this field to define P6R as the manufacturer.
The "tokenModel" configuration parameter (string value), maps to the "model" field of the CK_TOKEN_INFO PKCS 11 API structure. Again for software tokens we use this field to define the value "KEYSTORE 1.3".
The "tokenSoftKeystore" configuration parameter (string value), is optional and can either the full path to a directory where the slot's keystore is to be created or a database URI of the standard for: "postgresql8://..." (see Keystore documentation). When this parameter is not provided then a default location is used. Otherwise, When using the full path to a local directory then a Sqlite database will be used. This keystore holds all the PKCS 11 defined objects for this token (e.g., CKO_SECRET_KEY, CKO_PUBLIC_KEY, CKO_PRIVATE_KEY, CKO_CERIFICATE, CKO_DOMAIN_PARAMTERS, CKO_DATA).
The "tokenDefaultGroup" configuration parameter (string value), can be used instead of the CKA_P6R_GROUP vendor attribute extension. For the KMIP Token this parameter maps to the KMIP "Object Group" attribute. For the Software Token is parameter maps to the P6R's Keystore namespace parameter. When not specified the library uses "PKCS11" as the built in default group.
The "tokenMinPinLen" configuration parameter (postive numeric value), defines the smallest number of bytes of length that a PIN is allowed to be for a token. The defailt value is 8.
The "tokenMaxPinLen" configuration parameter (positive numeric value), defined the largest number of bytes of length that a PIN is allowed to be for a token. The default value is 25.
When the "[p6pkcs11-slot-X]" section defines a KMIP token the following configuration parameters apply:
slotDescription, slotFlags, slotManufacturer, slotType, tokenFirmwareVersion, tokenManufacturer, tokenModel, tokenDefaultGroup, tokenMinPinLen, and tokenMaxPinLen all are the same as described above.
The "tokenHardwareVersion" configuration parameter (string value), maps to the "hardwareVersion" field of the CK_TOKEN_INFO PKCS 11 API structure. This and the tokenFirmwareVersion can be used to define versions of the remote KMIP server.
The "tokenMaxSession" configuration parameter (string value), maps to both the "ulMaxSessionCount" and "ulMaxRwSessionCount" fields of the CK_TOKEN_INFO PKCS 11 API structure. If this string is set to "-1", then the default value of 100 is used for both of these fields. If this string is set to "0" that maps to the constant CK_EFFECTIVELY_INFINITE, then the only limit that will be checked is the maximum number of total sessions that the PKCS 11 library can handle at once.
The "tokenKMIPServer" configuration parameter (string value), is the fully quallified domain name (FQDN) of the remote KMIP server. It is passed to P6R's Secure KMIP Client (SKC) library.
The "tokenKMIPort" configuration parameter (positive numeric value), is optional with the default value of 5696 defined. It is passed to the SKC library.
The "tokenKMIPMaxVersion" configuration parameter (string value), this parameter defines the maximum KMIP protocol that PKCS 11 should use to communicate with a remote KMIP server. This is an optional field with its default value of "1.2" defined. This library calls the KMIP Discover Version operation to select a protocol version to use.
The "tokenKMIPVersion" configuration parameter (string value), is optional and defines the KMIP protocol version that PKCS 11 should use to start communicatation with a remote KMIP server. This has a default value of "1.2".
The "tokenKMIPsslOptions" configuration parameter (bit mask), is optional and maps to the SKC setSSLOptions( const P6WCHAR* pCiphers, P6SECURESOCKETFLAGS fSecureFlags ) API call's fSecureFlags parameter (see file p6kmpclient.h). This allows the caller to customize how it makes an TLS connection to a remote KMIP server. The default setting for this parameter is (P6SSF_METHOD_NEGOTIATE | P6SSF_SECURE_CLIENT | P6SSF_SECURE_CLIENT_AUTH | P6SSF_LOG_X509SUBJECTLOOKUPS) (see file p6net.h).
The "tokenKMIPInitFlags" configuration parameter (bit mask), is optional and maps to the SKC initialize( P6KMIPFLAGS flags, p6IKeystore* pCerts, P6KMIP_PREF preferences ) API calls's flags parameter (see file p6kmipclient.h. This has the default value of P6KMIPFLG_NOFLAGS. Note, that this parameter is how the user can control KMIP message logging (e.g., using the P6KMIPFLG_TRACE_MSGS flag value). See SKC documentation on the possible values for this parameter.
The "tokenKMIPCertPEM" configuration parameter (string value), is the full path to a client side certificate (in PEM format) that was issued by a KMIP server to allow a KMIP client to authenticate itself. This certificate is copied into the PKCS 11 wide keystore for use by SKC to create a TLS connection to a KMIP server.
The "tokenKMIPPrivPEM" configuration parameter (string value), is the full path to the client's private key (in PEM format) that was issued by a KMIP server to allow a KMIP client to authenticate itself. This key is copied into the PKCS 11 wide keystore for use by SKC to create a TLS connection to a KMIP server.
The "tokenKMIPPrivSize" configuration parameter (positive numeric value), is the number of bits of the private key defined by the tokenKMIPPrivPEM configuration parameter.
The "tokenKMIPRootPEM" configuration parameter (string value), is the full path to the KMIP server's root certificate that was provided by a KMIP server to allow the Secure KMIP Client to create a TLS connection to the remote KMIP server.
The "tokenKMIPconnectTimeout", "tokenKMIPsendTimeout", "tokenKMIPreceiveTimeout", "tokenKMIPMaxBufSize", "tokenKMIPInitialBufCount", "tokenKMIPGrowBufsBy", "tokenKMIPPrvKeyEncode", "tokenKMIPPubKeyEncode", "tokenKMIPSymKeyEncode", and "tokenKMIPcompatibility1" configuration parameters (positive numeric values), are all optional and maps to the SKC initialize( P6KMIPFLAGS flags, p6IKeystore* pCerts, P6KMIP_PREF preferences ) API calls's P6KMIP_PREF parameter (see file p6kmipclient.h and SKC documentation). PKCS 11 library has a reasonable set of default values for each parameter.
The "tokenKMIPUserName" and "tokenKMIPPassword" configuration parameters (string values), are optional and map to KMIP user credentials (see SKC documentation p6kmipclient.h P6KMIP_CREDENTIAL definition).
The "tokenKMIPPassword", "tokenKMIPSerialNum", "tokenKMIPDeviceId", "tokenKMIPNetworkId", "tokenKMIPMachineId", and "tokenKMIPMediaId" configuration parameters (string values), are optional and map to KMIP device credentials (see SKC documentation p6kmipclient.h P6KMIP_CREDENTIAL definition).
The "tokenDisabledMechs" configuration parameter (list of positive integers base 10) contains a set of PKCS 11 mechanism identifier constants (e.g., 4160 for the constant CKM_EC_KEY_PAIR_GEN, and 272 CKM_RC4_KEY_GEN [see pkcs11t.h]) which are to be disabled for the token. Here disabled means that the mechanisms will not be provided in the output of the C_GetMechanismList() and C_GetMechanismInfo() calls. This configuration item is optional.
When the "[p6pkcs11-slot-X]" section defines a 3rd party token the following configuration parameters apply:
The "vendorSlotId" configuration parameter (postive numeric value), is the slot identifier to be used for the 3rd party's token. This is used when the 3rd party token exposes its own PKCS#11 API and will have its own slot numbers to be mapped to.
The "vendorVerifyPIN" configuration parameter (boolean "true/false"), indicates whether the vendor's 3rd party token verifies the user PIN itself or depends on the P6R PKCS11 library to verify the user and SO PINs. The default value is "false".
The "vendorPreInitToken" configuration parameter (boolean "true/false"), indicates whether the vendor's 3rd party token has initialized its token via external means (e.g., a separate application). The default value is "false".
The "vendorFlags" optional configuration parameter (postive numeric value), is passed into the vendors implementation for the "libWibFlags" parameter of the method p6ITokenImpl::initialize( CK_RV* pRV, P6PKCS11PLUGFLAGS libWideFlags, P6BWCSTR* pTokenType ). The vendor can define their own values or use those defined in the p6tokenimpl.h file.
The "vendorCompat" (compatibility) optional configuration parameter (positive numberic value), is used to control behavior of the P6R PKCS#11 library as it interacts with 3rd party tokens. The currently defined values are: (0x0001) disable CKA_DESTROYABLE. The CKA_DESTROYABLE attribute was added in the PKCS#11 Version 2.40 standard documents. PKCS#11 versions prior to V2.40 will consider this attribute as unknown. This flag disables its use in the P6R library.
The library provides a very low-level debug logging mechanism and a higher level debug logging mechanism that allows the diagnosis of startup and other library issues. This mechanism does not log protocol related information. See the Basic Configuration Parameters section for details on configuring protocol logging. This mechanism is intended to help debug library startup and other non-protocol related issues.
The low level logging is a failsafe log to provide diagnostics for log creation. If the debug log is not being created, then this is the place to look for information on why that may be. When the library loads, it will always create this file in the temp directory and it will be named "p6cryptoki-startup.log". On most Llinux systems it will be created the "/tmp" directory. If you system does not have a "/tmp", then it will try "/usr/tmp" and then "/var/tmp". This file is overwritten each time the library is loaded.
Debug logging is enabled by placing a file in the same directory as the pksc11 shared library. When the library is first loaded and starts up, it will look for this file and if found will begin sending log output to it. The filename itself controls what is logged. For example, if the pkcs11 shared library is located in "/opt/product/bin" then a file named "p6cryptoki-info.log" will enable logging of "info" and "errors" level log messages into that file.
To disable logging, the pkcs11 shared library will need to be unloaded and the log file deleted or renamed to something that does not start with "p6cryptoki".
To change what information is logged, the log filename is changed by adding dash separated log-level qualifiers to the filename to indicate which log-levels are to be included in the log output. The allowable log-level qualifiers are "debug", "info", "warn" and "all". Errors are always logged.
The following table illustrates the naming convention that is used:
Filename | Description |
---|---|
p6cryptoki.log | If no qualifiers are added, then only errors will be logged. |
p6cryptoki-debug.log | Since errors are always logged, this would log "debug" and "error" log messages. |
p6cryptoki-info.log | Since errors are always logged, this would log "info" and "error" log messages. |
p6cryptoki-warn.log | Since errors are always logged, this would log "warn" and "error" log messages. |
p6cryptoki-all.log | This is shorthand for enabling all log-levels. |
p6cryptoki-info-warn.log | Multiple qualifiers can be used. Since errors are always logged, this would log "info", "warn" and "error" log messages. |
P6CRYPTOKI-waRn-Info.lOg | Multiple qualifiers can be used and are case insenitive. This is identical in function to the previous example. |
Note that qualifiers can be specified in any order and are case-insensitive.
P6R’s PKCS 11 library also ships with a command line tool. This executable is a PKCS 11 application in that it dynamically loads our library and calls C_GetFunctionList in order to obtain the API function pointers. A user can use this command line tool to initialize a token, set the SO or User’s PIN, list all configured slots, list information on a token, generate keys, import and export some certificates and keys, and list the contents of a token. We have been using this command line tool to manage our KMIP, Software, and HPE Atalla HSM tokens.
The command line tool is an executable that can be found in the "bin" directory in a SKC release. Executing it without any parameters (or with "-h" for help) will display usage documentation showing its current set of functionality.
A Utimaco HSM can be configured to look like another token. Actually we map one slot of the Utimaco HSM into one slot of our P6R PKCS#11 library. In the example below, P6R slot number 5 is mapped to Utimaco HSM slot number 0 (see the vendorSlotId parameter).
This is easily done by the following two steps. First, define the Utimaco slot in the p6pkcs11.conf file. An example of how to do this is above in the section Basic Configuration Parameters and is repeated below:
Any slot number will work so the section header of "[p6pkcs11-slot-5]" above is arbitrary. The value under the "[p6pkcs11-tokens]" section above defines the GUID of the P6R plugin DLL (.so file for Linux) for Utimaco HSMs.
The second step is to copy the Utimaco provided files: cs_pkcs11_R2.dll (on Windows), cs_pkcs11_R2.so (on Linux), and cs_pkcs11_R2.cfg into the P6R "components" directory so that they can be found and loaded. Then modify the Utimaco configuration file "cs_pkcs11_R2.cfg" based on Utimaco documentation for use of their PKCS#11 API library depending on the Utimaco hardware present. One such document is the Utimaco CryptoServer PKCS11#11 R2 Developer Guide, Document Number 2012-0007, Date May 2014.
A Thales nShield Connect HSM can be configured to look like another token. Actually we map one slot of the Thales HSM into one slot of our P6R PKCS#11 library. In the example below, P6R slot number 6 is mapped to Thales HSM slot number 492971158 (0x1d622496) (see the vendorSlotId parameter).
This is easily done by the following two steps. First, define the Thales slot in the p6pkcs11.conf file. An example of how to do this is above in the section Basic Configuration Parameters and is repeated below:
Any slot number will work so the section header of "[p6pkcs11-slot-6]" above is arbitrary. The value under the "[p6pkcs11-tokens]" section above defines the GUID of the P6R plugin DLL (.so file for Linux) for Thales HSMs.
The second step is to copy the Utimaco provided files: cknfast-64.dll (64 bit) or cknfast-32.dll (32 bit) (on Windows), and libcknfast.so (on Linux) into the P6R "components" directory so that they can be found and loaded. Then set up and configure the Thales nShield Connect HSM as defined in the Thales Quick Start Guide (N-030140X).
Note, when the nShield is in strict FIPS mode a call to C_GenerateKey() needs the attributes CKA_SENSITIVE and CKA_PRIVATE has to be set to CKA_TRUE. In addition, calls to C_CreateObject() where the calling application is trying to place a key onto the HSM will fail since strict FIPS mode does not allow keys of unknown origin from being loaded into the HSM.
A Futurex HSM can be configured to look like another token. Actually we map one slot of the Futurex HSM into one slot of our P6R PKCS#11 library. In the example below, P6R slot number 7 is mapped to Futurex HSM slot number 0 (see the vendorSlotId parameter).
This is easily done by the following two steps. First, define the Futurex slot in the p6pkcs11.conf file. An example of how to do this is above in the section Basic Configuration Parameters and is repeated below:
Any slot number will work so the section header of "[p6pkcs11-slot-7]" above is arbitrary. The value under the "[p6pkcs11-tokens]" section above defines the GUID of the P6R plugin DLL (.so file for Linux) for Futurex HSMs.
The second step is to copy the Futurex provided files: fxpkcs11x64.dll or fxpkcs11x86.dll (on Windows), libfxpkcs11.so (on Linux) into the P6R "components" directory so that they can be found and loaded. Then set up the Futurex directory with the required SSL certificates and PKCS#11 configuration file. On Windows this directory is "C:\Futurex" and it contains fxpkcs11.cfg configuration file which defines the HSM to connect to and the path to find the required SSL certificates.
A DocuSign ARX PrivateServer HSM can be configured to look like another token. Actually we map one slot of the DocuSign HSM into one slot of our P6R PKCS#11 library. In the example below, P6R slot number 8 is mapped to DocuSign HSM slot number 1 (see the vendorSlotId parameter). It appears that valid slot identifiers on this HSM start at one.
This is easily done by the following two steps. First, define the DocuSign slot in the p6pkcs11.conf file. An example of how to do this is above in the section Basic Configuration Parameters and is repeated below:
Any slot number will work so the section header of "[p6pkcs11-slot-8]" above is arbitrary. The value under the "[p6pkcs11-tokens]" section above defines the GUID of the P6R plugin DLL (.so file for Linux) for DocuSign HSMs.
The DocuSign PKCS#11 library is installed in a fixed location on Windows in the "C:\Windows\System32" directory. The library files are: sadaptor64.dll for 64 bit code and sadaptor.dll for 32 bit code. DocuSign provides a Windows application (i.e., PrivateServer Management) that supports the configuration of their HSM client libraries and of PKCS#11 slots on the HSM. See the PrivateServer Installation and Operation Guide, Copyright 2011, Pub. No. CSV.INS.V4.8.1211.
For Linux follow the instructions from the PrivateServer Installation and Operation Guide, Chapter 7, Section "PrivateServer Client Installation for Unix/Linux". In doing so first create a "docusign" directory under the P6R installation in its "components" directory. Then copy the DocuSign csv, ckit, modules, and java directories under the "../components/docusign", directory. The DocuSign PKCS#11 library file on linux is: ../csv/libshare/libcs_pkcs.so. This works for both 32 and 64 bit library code. This is where the P6R PKCS#11 library expects to find the DocuSign libraries.
In configuring the DocuSign PKCS#11 library to run on Linux we need modify the "../csv/utils/cs_pkcs.env" file before running it. This file is a script used to set required environment variables. In modifying this file we suggest the use of full path names instead of the relative path names that appear in the file. So for example, if the P6R component directory was installed in the path "/opt/p6r/components" then the fields in the cs_pkcs.env file would be changed as follows:
Also all paths that appear in the file "../csv/utils/cs_pkcs.ini" should also use full file paths.
An HPE's Atalla HSM (http://www8.hp.com/us/en/software-solutions/hardware-security-module-hsm-atalla-nsp/) can be configured to look like another token. We map one P6R's PKCS11 library slot to one NSP HSM. In the case where an NSP is configured with multiple Virtual NSPs then we map one P6R's PKCS11 library slot to one Virtual NSP. In the example below, both P6R slot numbers 2 and 3 are mapped to one physical HPE machine but to two virtual NSPs. In the example, each Virtual NSP is selected by the port (i.e., tokenNSPPort parameter).
Calls to C_EncryptUpdate and C_DecryptUpdate require the data to be encrypted / decrypted respectively to be a multiple of 8. If not then the error CKR_DATA_LEN_RANGE is returned. The NSP by default pads all data that is not a multiple of 8. Since these call represent a stream of data padding during one of the calls would result in an incorrect value. That is the PKCS 11 library does no internal buffering nor does the NSP and thus requires the calling application to manage this.
This token supports the following PKCS 11 mechanisms: CKM_DES_KEY_GEN, CKM_DES2_KEY_GEN, CKM_DES3_KEY_GEN, CKM_SHA_1_HMAC, CKM_SHA256_HMAC, CKM_RSA_PKCS_KEY_PAIR_GEN, CKM_SHA1_RSA_PKCS, CKM_SHA224_RSA_PKCS, CKM_SHA256_RSA_PKCS, CKM_SHA384_RSA_PKCS, CKM_SHA512_RSA_PKCS, CKM_DES_CBC, CKM_DES_CFB8, CKM_DES_CFB64, CKM_DES_OFB64, CKM_DES3_CBC, CKM_SHA_1, CKM_SHA224, CKM_SHA256, CKM_SHA384, CKM_SHA512, CKM_MD2, CKM_MD5, and CKM_RIPEMD160. All digest calculations are done in the PKCS 11 client with the use of OpenSSL, but all other calculations are done on the NSP.
The NSP has no notion of PKCS11 slots so we set the "vendorSlotId" parameter to the same slot number as the P6R slot number (e.g., "vendorSlotId=2" is set for "[p6pkcs11-slot-2]" above).
The "tokenNSPIP" parameter is used to configure the IP address of the NSP hardware.
The "tokenTLSRootPEM" parameter points to a file that contails the TLS root certificate of the NSP. This allows standard TLS network connection to be made to the NSP (see slot 3 above).
The "tokenNSPFlags" parameter defines token specific configuration options. This parameter is an unsigned integer bit mask of the following flags: { 0x0001 - log NSP messages, 0x0002 - use TLS for network connections }. This parameter has a default value of 0x0002 - use TLS.
The "tokenMaxBufSize" parameter defaults to "65556" bytes and defines the size of the NSP tokens buffers.
The "tokenConnectTimeout", "tokenSendTimeout", and "tokenReceiveTimeout" parameters pass to the NSP token network timeouts in milliseconds for TCP connection, send, and receive operations respectively. These parameters have a default value of 5000 milliseconds.