Developer's Guide
 All Files Variables Pages
PKCS11 Basic Configuration

Basic Configuration Parameters

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

* [p6pkcs11-gen]
* baseKeyPath="/var/PKCS11/baseKey.txt"
* customerKeyPath="/var/PKCS11/customer1key.txt"
* keystore="/var/PKCS11/keys"
* logDir="/var/log/pkcs11"
* disabled="/var/PKCS11/disabled.txt"
* initialSessions=100
* pkcs11LibFlags=3
*
* [p6pkcs11-slots-gen]
* slotCount=5
*
* [p6pkcs11-tokens]
* UtimacoVersion220 = "{3367270E-43E6-4fed-B57A-0711FAE20CCA}"
* ThalesVersion201 = "{73BED027-BBE5-44dc-ACCE-302647D9E7BD}"
* Entrust = "{7DFB0F94-811D-409D-9062-73E4AD9FE1B6}"
* FuturexVersion22 = "{D6EBC68A-9D3E-4998-B587-C68B6BD3169C}"
* DocuSign220 = "{3A55CD57-71DE-495a-A172-43B604C241C0}"
* SafeNetLuna = "{AB0258D5-7CC1-422a-916F-9D57F7E70808}"
* AWSCloudHSM = "{8845FCDF-44C1-48FD-846F-153186B50E7B}"
* YubicoHSM20 = "{2A41B9D6-CF96-45BD-BB7C-AA398DC0CB56}"
* Cavium = "{4B913DB7-368B-478B-9B66-501B85BB8BFA}"
*
* [p6pkcs11-slot-0]
* slotDescription="KMIP SLOT1"
* slotFlags=5
* slotManufacturer="P6R"
* slotType="P6R-KMIP"
* tokenFirmwareVersion="1.60"
* tokenHardwareVersion="1.1"
* tokenKMIPCertPEM="/var/PKCS11/PKCS11/slot0/CR_P6R_cert_kmip1.pem"
* tokenKMIPInitFlags=0x040C
* tokenKMIPPort=5696
* tokenKMIPPrivPEM="/var/PKCS11/slot0/CR_P6R_privkey_kmip1.pem"
* tokenKMIPPrivSize=2048
* tokenKMIPRootPEM="/var/PKCS11/slot0/CR_root_kmip1.pem"
* tokenKMIPServer=interop.cryptsoft.com
* tokenKMIPMaxVersion="1.2"
* tokenKMIPUseFlags=1
* tokenManufacturer="Cryptsoft"
* tokenMaxSession="0"
* tokenModel="KMIP C Server"
* # disable mechanisms: CKM_EC_KEY_PAIR_GEN, CKM_RC4_KEY_GEN
* tokenDisabledMechs = 4160,272
*
* [p6pkcs11-slot-1]
* slotDescription="P6R's Keystore & Crypto"
* slotFlags=1
* slotManufacturer="P6R"
* slotType="P6R-keystore"
* tokenFirmwareVersion="1.00"
* tokenManufacturer="P6R"
* tokenModel="KEYSTORE 1.3"
* tokenSoftKeystore="/var/PKCS11/keystore"
*
* [p6pkcs11-slot-2]
* slotDescription="KMIP SLOT2"
* slotFlags=5
* slotManufacturer="P6R"
* slotType="P6R-KMIP"
* tokenFirmwareVersion="1.2"
* tokenHardwareVersion="1.1"
* tokenKMIPCertPEM="/var/PKCS11/slot2/LP_dev_kmip2.cer"
* tokenKMIPInitFlags=0x040C
* tokenKMIPsslOptions=612
* tokenKMIPPort=5696
* tokenKMIPMaxVersion="1.2"
* tokenKMIPPrivPEM="/var/PKCS11/slot2/LP_dev_kmip2.key"
* tokenKMIPPrivSize=2048
* tokenKMIPRootPEM="/var/PKCS11/slot2/LP_dev_root_kmip2.ca"
* tokenKMIPServer=kmiptest01.p6r.com
* tokenManufacturer="LP"
* tokenMaxSession="0"
* tokenModel="LP KServer 3.0"
*
* [p6pkcs11-slot-3]
* slotType="UtimacoVersion220"
* slotFlags=5
* vendorSlotId=0
* vendorVerifyPIN=true
* vendorPreInitToken=true
*
* [p6pkcs11-slot-4]
* slotType="Entrust"
* slotFlags=5
* vendorSlotId=492971158
* vendorVerifyPIN=true
* vendorPreInitToken=true
* vendorCompat=1
*
* # Cavium slots start at 1
* # Cavium HSMs do not support CKA_COPYABLE (see vendorCompat property)
* [p6pkcs11-slot-5]
* slotType="Cavium"
* vendorSlotId=1
* vendorVerifyPIN=true
* vendorPreInitToken=true
* vendorCompat=3
*

Other possible slot and token configuration items:

* pkcs11LibFlags
* applicationCompat
* tokenDefaultGroup
* tokenKMIPconnectTimeout
* tokenKMIPsendTimeout
* tokenKMIPreceiveTimeout
* tokenKMIPMaxBufSize
* tokenKMIPInitialBufCount
* tokenKMIPGrowBufsBy
* tokenKMIPPrvKeyEncode
* tokenKMIPPubKeyEncode
* tokenKMIPSymKeyEncode
* tokenKMIPcompatibility1
* tokenKMIPAsynch
* tokenKMIPVersion
* tokenKMIPUserName
* tokenKMIPPassword
* tokenKMIPSerialNum
* tokenKMIPDeviceId
* tokenKMIPNetworkId
* tokenKMIPMachineId
* tokenKMIPMediaId
* tokenMinPinLen
* tokenMaxPinLen
* tokenKMIPsslCiphers
* tokenKMIPVerifyBytes
* tokenKMIPUseVersion
* tokenKMIPCustomize
* tokenKMIPKeepAlive
* tokenKMIPMaxRetries
*

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.

The [p6pkcs11-gen] Config Section*

This contains the following PKCS 11 wide configuration parameters:

"baseKeyPath" Config Variable (string Value)

The "baseKeyPath" configuration parameter (string value), is the symmetric key protecting the PKCS 11 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. Either this parameter OR the "customerKeyPath" parameter is defined. If both are defined, then the customerKeyPath parameter will be used.

"customerKeyPath" Config Variable (string Value)

The "customerKeyPath" configuration parameter (string value), is the symmetric key protecting the PKCS 11 keystore. The difference between this parameter and the "baseKeyPath" is that the baseKeyPath key is generated by this command line tool while the customerKeyPath key is provided by the customer. The customer must provide an AES 256 bit PEM encoded file.

"keystore" Config Variable (string value)

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.

"logdir" Config Variable (string value)

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.

"disabled" Config Variable (string value)

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.

"initialSessions" Config Variable (positive numeric value)

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.

"pkcs11LibFlags" Config Variable (positive numeric value)

The "pkcs11LibFlags" configuration parameter (numeric 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:

* 0x0001 for Recover PKCS11 keystore from Signature Mismatch error (i.e., 0x80040011),
* 0x0002 force PKCS ll library to use internally created multi-threading locking if no locking already set.
* 0x0004 return CKR_OK for extra calls to C_Initialize instead of returning the error code CKR_CRYPTOKI_ALREADY_INITIALIZED.
* This puts the PKCS 11 library in reference counting mode. This means that each call to C_Initialize must have a matching
* call to C_Finalize and that only the last call to C_Finalize will actually do anything. This does not match the defined
* PKCS 11 standard behavior.
*

(For example, if all 3 flags where set then "pkcs11LibFlags=7" would be the correct value.)

The [p6pkcs11-slots-gen] Config Section

The "[p6pkcs11-slots-gen]" section contains the following PKCS 11 configuration parameters global across all defined slots:

"slotCount" Config Variable (positive decimal integer)

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] Config Section

The "[p6pkcs11-tokens]" section contains third party token implementations via the p6tokenimpl.h interface definition.

<tokenname> Config Variable (string GUID)

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. For example, these values for PKCS#11 Version 2.40:

* CKF_TOKEN_PRESENT 0x00000001
* CKF_REMOVABLE_DEVICE 0x00000002
* CKF_HW_SLOT 0x00000004
*

So for example, our KMIP token should have the value '5' for this parameter since the token is present and its a Hardware slot. However, our software token should only have a value of '1' for this parameter.

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 "applicationCompat" configuration parameter (positive numeric value), is an optional parameter. It is a bit mask defining behavior that the calling application expects of the PKCS 11 library for the application to operate properly. The following values are currently defined: { 0x00 - no special actions required, 0x01 - create a default value for CKA_LABEL for calls to C_CreateObject(), C_GenerateKey(), and C_GenerateKeyPair() if no value of CKA_LABEL is provided, 0x02 - CKK Generic Hack, some applications use CKK_GENERIC_SECRET for CKA_KEY_TYPE instead of the actual value the object was created with (e.g., CKK_AES), this forces the KMIP token to set the x-P6R-Cryptoki-KEYTYPE attribute to the P11 value of CKK_GENERIC_SECRET to allow C_FindObject to locate the 0bject. }

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 (positive 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 "applicationCompat" configuration parameter (positive numeric value), is an optional parameter. It is a bit mask defining behavior that the calling application expects of the PKCS 11 library for the application to operate properly. The following values are currently defined:

* 0 - no special actions required,
* 1 - create a default value for CKA_LABEL for calls to C_CreateObject(),
* C_GenerateKey(), and C_GenerateKeyPair() if no value of CKA_LABEL is provided,
* 2 - CKK_GENERIC_SECRET hack for applications that use this key type in C_FindObjectsInit() but use a different
* key type on calls to C_GenerateKey() and C_GenerateKeyPair()
*

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 "tokenKMIPPort" 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 and if not set the code will select the largest supporting protocol version. This library automaically calls the KMIP Discover Version operation to select a protocol version to use. This parameter can be used alone or with the tokenKMIPMinVersion parameter.

The "tokenKMIPMinVersion" configuration parameter (string value), this parameter defines the mimium KMIP protocol that PKCS 11 should use to communicate with a remote KMIP server. This is an optional field and if not set the code will default to KMIP protocol version 1.2. This configuration item is useful if a KMIP server disables specific protocol versions and thus allows a successful call to the KMIP Discover Version operation to determine what a KMIP server supports. This parameter can be used alone or with the tokenKMIPMaxVersion parameter.

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". If both this paramter and tokenKMIPMaxVersion are set then this paramter will be used to start a session with a KMIP server and then may be changed by the value defined in tokenKMIPMaxVersion. If the tokenKMIPMinVersion parameter is used, then this parameter should not be used.

The "tokenKMIPUseVersion" configuration parameter (string value), this parameter defines the KMIP protocol version that will be used to communicate with a remote KMIP server. This parameter will override the values defined in the tokenKMIPMaxVersion, tokenKMIPMinVersion, and tokenKMIPVersion parameters. If this field is set the library will not invoke a KMIP Discover Version operation to select a protocol version to use.

The "tokenKMIPCustomize" configuration parameter (numeric bit mask), is optional and maps to the SKC KMIP_CUST_XXX configuration settings (see p6kmipencoder.h or SKC documentation). Two of the most useful settings are: { KMIP_CUST_DISABLE_MAXSIZE (0x01) – if set the Maximum Response Size optional field in a request header is not generated, KMIP_CUST_DISABLE_TIMESTAMP (0x02) – if set the Time Stamp optional field in a request header is not generated }

The "tokenKMIPKeepAlive" configuration parameter (positive numeric value), is optional and should be set to the number of seconds after which a call to any PKCS#11 API function will force the KMIP token to ping the, slot configured, KMIP server before performing any other KMIP operation. Setting this parameter also sets the P6KMIPFLG_REOPEN_CONNECTION flag on the KMIP Client which will force the client to reopen a connection to the KMIP server if it has closed. The purpose of this feature is to try to re-establish a KMIP TLS connection to the server before the requested PKCS#11 operation is started. The server ping is implemented as a simple KMIP Query operation. This feature is designed to support KMIP servers that drop client connections after a defined period of inactivity.

The "tokenKMIPMaxRetries" configuration parameter (positive numeric value), is optional and works with the tokenKMIPKeepAlive parameter. This parameter is meant to override the SKC default re-connection maximum attempt retries of 3.

The "tokenKMIPsslOptions" configuration parameter (numeric 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 "tokenKMIPsslCiphers" configuration parameter (string value), is optional and is used to override the default library's TLS cipher settings. This string contains the OpenSSL cipher command (see https://www.openssl.org/docs/man1.0.2/apps/ciphers.html). If not defined then the following secure default will be used: "TLSv1+HIGH:TLSv1.2+HIGH:!SSLv2:!aNULL:!eNULL:!3DES:@STRENGTH" which enables SSLv3 and TLSv1, disables SSLv2, disables ciphers that do not use authentication, disables 3DES, and prefers the strongest ciphers fist.

The "tokenKMIPInitFlags" configuration parameter (numeric 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). In addition, this parameter can also modify the KMIP client's behavior such as with the following values:

* P6KMIPFLG_REOPEN_CONNECTION - if the TLS connection to a KMIP server is lost, for whatever reason, automatically try to
* recreate it. If the first attempt fails this logic will retry a configured (or 3 times as default) number of times.
*
* P6KMIPFLAG_USE_SCHANNEL - only meaningful on Windows Operating Systems, ignored otherwise. By default SKC uses OpenSSL to create a TLS
* connection. However, if this flag is set then SKC will use Window's cChannel to create a TLS connection instead of OpenSSL.
*
* P6KMIPFLG_REOPEN_CONNECTION = 0x00040000
* P6KMIPFLG_USE_SCHANNEL = 0x00080000
*

See SKC documentation for all 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 "tokenKMIPAsynch" configuration paramter (positive numeric value), is optional and maps to the SKC initialize API call's P6KMIP_PREF parameter (see file p6kmipclient.h and SKC documentation). This field is used to enable / disable the SKC client asynchronous KMIP request option.

The "tokenKMIPUseFlags" configuration parameter (numeric bit mask), allows the user to modify how the KMIP client uses the KMIP protocol. If not defined the client has reasonable internal defaults. The following values can be used to create a bit mask value for this parameter.

* KMIP_USE_KEKKEYROLE - this enables the automatic setting of the "KEK" Key Role Type in the Cryptographic Parameters attribute
* for any keys that may be used in wrapping.
*
* KMIP_USE_LABELTONAME - this make the CKA_LABEL PKCS#11 attribute to be mapped to the KMIP attribute 'Name'. This is not
* default behavior since CKA_LABEL does not have to hold a unique value while the KMIP Name attribute does.
*
* KMIP_USE_SEEALLKEYS1 - default behavior is for the PKCS#11 KMIP token to only allow the caller to see keys and objects created by this library.
* This default bahavior prevents accidental deletion of pre-existing keys and other KMIP objects. This flag removes that restriction.
*
* KMIP_USE_P11LIKE - for KMIP 1.4 and greater use the KMIP attributes "Sensitive", "Always Sensitive", "Extractable", and "Never Extractable" instead of the
* KMIP custom attributes the library uses for easiler KMIP protocol versions (e.g., "x-P6R-Cryptoki-SENSITIVE"). These PKCS#11 like attributes where
* added to KMIP to match PKCS#11 functionality. For applications that already use the custom attributes there is a feature in the p6pkcs11tool command
* line tool (TBD) that performs conversion from the old custom to the new KMIP 1.4 defined attributes. Please perform a conversion before using this setting.
* Applications should only use this setting if they are sure their application will only run with KMIP protocol version 1.4 and greater.
*
* KMIP_USE_KEKKEYROLE = 0x00000001
* KMIP_USE_LABELTONAME = 0x00000002
* KMIP_USE_SEEALLKEYS1 = 0x00000004
* KMIP_USE_P11LIKE = 0x00000008
*

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 "tokenKMIPVerifyBytes" configuration paramter (positive numeric value), is optional and defines the number of memory that can be allocated per token session to support the KMIP implementation of C_VerifyUpdate and C_VerifyFinal (i.e., streaming signature verification). Because PKCS#11 and KMIP APIs have a basic incompatability our implementation has to cache all they bytes passed into C_VerifyUpdate to be passed to the KMIP server only during the C_VerifyFinal call. The default value of zero is unlimited. The units are in mega-bytes so that a value of '10' means 10,000,000 bytes.

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 (positive 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 (positive 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 numeric 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, (0x0002) disable CKA_COPYABLE, (0x0004) Discover Vendor Slots, (0x0008) fixed handles for wrapping keys, and (0x0010) AWS CloudHSM (which has several unique requirements). 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. "Discover Vendor Slots" is to be used when the value to be placed in "vendorSlotId" is not known. It is best used to determine the value to assign to the "vendorSlotId" parameter. Discover vendor slots will perform a C_GetSlotList() call on the vendor HSM, log all found slots and choose the first slot identifier to use overriding any value defined in the "vendorSlotId" parameter. Discover vendor slots will will run during C_OpenSession() (and will last for that session), and C_GetSlotList() automatically if it is enabled. If the proper vendor slot Id is not know then one or more of the PKCS#11 functions will fail. This flag is initially disabled in the P6R library.

Low-Level and Debug Logging Configuration

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.

Low-Level Logging

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

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".

Controlling What Is Logged In The Debug Log

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:

FilenameDescription
p6cryptoki.logIf no qualifiers are added, then only errors will be logged.
p6cryptoki-debug.logSince errors are always logged, this would log "debug" and "error" log messages.
p6cryptoki-info.logSince errors are always logged, this would log "info" and "error" log messages.
p6cryptoki-warn.logSince errors are always logged, this would log "warn" and "error" log messages.
p6cryptoki-all.logThis is shorthand for enabling all log-levels.
p6cryptoki-info-warn.logMultiple qualifiers can be used. Since errors are always logged, this would log "info", "warn" and "error" log messages.
P6CRYPTOKI-waRn-Info.lOgMultiple 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.