This document was updated on 22 March 2024.

Introduction

P6R has implemented the PKCS 11 Version 2.40 and Version 3.0 specifications. Our library meets the requirements for conformance of a PKCS 11 Extended Provider and Authentication Token (see PKCS11 Cryptographic Token Interface Profiles Version 2.40, 16-Sep-2014, OASIS Committee Specification 01). Currently, our library supports eleven types of tokens: a KMIP server, a Software token, a Thales Luna HSM (SafeNet/Gemalto), a Utimaco CryptoServer HSM, a Entrust nShield Connect HSM (formerly nCipher), a FutureX HSM, a DocuSign HSM, a Utimaco Atalla AT1000 HSM, a YubiHSM 2.0, a AWS CloudHSM, and the Marvell LiquidSecurity HSM. Our library also allows a customer to provide their own token types via a plugin interface. One of the benefits of the PKCS 11 API is that it provides a standard based Keystore API.

Supporting these different types of tokens in one PKCS 11 library facilitates some interesting applications. For example, an application could store millions of keys in a KMIP server (along with extensive meta data) yet use an HSM to perform all encryption operations. In fact, the keys stored in the KMIP server could all be wrapped and only unwrapped once moved into an HSM. This can be done from a single PKCS 11 API instance. Another example is to use a KMIP server instead of an existing HSM vendor for Oracle TDE integration.

P6R’s PKCS 11 library is contained in both P6R’s Secure KMIP Client (SKC) and P11 products.

The KMIP Token

The KMIP token uses the facilities of a remote KMIP server to implement the features of the PKCS 11 Version 2.40 API. This token type uses P6R’s Secure KMIP Client (SKC) SDK to communicate with a configured KMIP server. As of this writing, SKC works with all known commercially available KMIP servers. Our PKCS 11 library allows the definition of any number of KMIP tokens all pointing to the same or different KMIP servers.

An important benefit of this token is that it allows developers familiar with PKCS 11 to store their keys on a KMIP server without having to learn about the KMIP protocol or KMIP SDKs. All that is required is that this token be properly configured to make a valid TLS connection to a remote KMIP server, which is a process an installer program can help with.

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

The KMIP token currently implements the following PKCS 11 API 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_SignUpdate, C_SignFinal, C_VerifyInit, C_Verify, C_VerifyUpdate, C_VerifyFinal, 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_DeriveKey, C_WrapKey, C_UnwrapKey (if the KMIP server supports unwrapping), C_GetInterfaceList, C_GetInterface, C_LoginUser, C_SessionCancel, C_MessageEncryptInit, C_MessageEncryptFinal, C_EncryptMessage, C_EncryptMessageBegin, C_EncryptMessageNext, C_MessageDecryptInit, C_MessageDecryptFinal, C_DecryptMessage, C_DecryptMessageBegin, C_DecryptMessageNext, C_MessageSignInit, C_MessageSignFinal, C_SignMessage, C_SignMessageBegin,C_SignMessageNext, C_MessageVerifyInit, C_MessageVerifyFinal, C_VerifyMessage, C_VerifyMessageBegin, and C_VerifyMessageNext.

This token supports the following PKCS 11 objects: CKO_DATA, CKO_CERTIFICATE, CKO_PUBLIC_KEY, CKO_PRIVATE_KEY, CKO_SECRET_KEY, CKO_DOMAIN_PARAMETERS and CKO_PROFILE.

This token supports the PKCS 11 CKA_UNIQUE_ID attribute in both Versions 2.40 and 3.0. This attribute provides a token assigned unique identifier for any object residing on a token.

The Software Token

The Software 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/C++ object wrapper around OpenSSL’s C language API.

The Software token currently implements the following PKCS 11 API 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_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 and C_DigestFinal.

This token also supports the new PKCS#11 CKA_UNIQUE_ID attribute. This new attribute provides a token assigned unique identifier for any object residing on a token.

The Thales Luna HSM Token (SafeNet/Gemalto)

The Thales Luna HSM can be configured to look like another token. We map one slot of a Thales Luna HSM into one slot of our P6R PKCS 11 library. To use this token requires the proper setup and configuration of a Luna HSM both on the hardware server and client machine as documented in the Thales product literature. Also the proper configuration of the P6R’s PKCS 11 library is required, which is described in detail in the SKC product documentation.

Utimaco Atalla AT1000 HSM Token (formerly HPE, Micro focus)

The Atalla AT1000 HSM (formerly Network Security Processor – NSP) can be configured to look like another token. We map each NSP and Virtual NSP into a separate slot of our P6R PKCS 11 library. We have written a special token for the NSP so that we could put a PKCS 11 API around it. Basically we added parts of our Software Token to build an NSP token that allows us to store all NSP generated keys into our Keystore. In addition, all PKCS 11 attributes, none of which are natively supported by the NSP, are also maintained in our Keystore. The P6R Keystore can use either a local Sqlite database or a local or remote Postgres database. Thus using our NSP token its generated keys and PKCS 11 attributes can be managed in a client local or networked centralized database.

This token supports the following PKCS 11 mechanisms: CKM_AES_KEY_GEN, 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_RSA_PKCS, CKM_SHA1_RSA_PKCS, CKM_SHA224_RSA_PKCS, CKM_SHA256_RSA_PKCS, CKM_SHA384_RSA_PKCS, CKM_SHA512_RSA_PKCS, CKM_RSA_X_509, CKM_DES_CBC, CKM_DES_CBC_PAD, CKM_DES_CFB8, CKM_DES_CFB64, CKM_DES_OFB64, CKM_DES3_CBC, CKM_AES_CBC, CKM_AES_CBC_PAD, 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.

This token currently implements the following PKCS 11 API functions: C_Initialize, C_Finalize, C_GetSlotInfo, C_InitToken, C_GetTokenInfo, C_GetMechanismList, C_GetMechanismInfo, C_OpenSession, C_CloseSession, C_GetSessionInfo, C_InitPIN, C_SetPIN, C_Login, C_Logout, C_CreateObject (objects stored in the P6R Keystore), C_DestroyObject, C_GetAttributeValue, C_SetAttributeValue, C_FindObjectsInit, C_FindObjects, C_FindObjectsFinal, C_GenerateRandom (uses NSP hardware random number generator), C_SignInit, C_Sign, C_SignUpdate, C_SignFinal, C_VerifyInit, C_Verify, C_VerifyUpdate, C_VerifyFinal, C_EncryptInit, C_Encrypt, C_EncryptUpdate, C_EncryptFinal, C_DecryptInit, C_Decrypt, C_DecryptUpdate, C_DecryptFinal, C_DigestInit, C_Digest, C_DigestUpdate, C_DigestFinal, C_GenerateKey, C_GenerateKeyPair, C_WrapKey, and C_UnwrapKey.

For this and all 3rd party tokens the PKCS 11 API functions: C_GetInfo, C_GetFunctionList, C_GetSlotList, and C_CloseAllSessions are handled by the PKCS 11 provider module that dynamically loads all tokens (i.e., the green box in the picture above).

This token also supports the new PKCS#11 CKA_UNIQUE_ID attribute. This new attribute provides a token assigned unique identifier for any object residing on a token.

The Utimaco HSM Token

The Utimaco CryptoServer HSM can be configured to look like another token. We map one slot of a Utimaco HSM into one slot of our P6R PKCS 11 library. This integration supports all existing Utimaco PKCS 11 vendor extensions. To use this token requires the proper setup and configuration of a network-attached HSM both on the hardware server and client machine as documented in the Utimaco product literature. Also the proper configuration of both the Utimaco and P6R’s PKCS 11 libraries is required, which is described in detail in the SKC product documentation.

Entrust (formerly nCipher)

The Entrust nShield Connect HSM can be configured to look like another token. We map one slot of an Entrust HSM into one slot of our P6R PKCS 11 library. This integration supports existing Entrust PKCS 11 vendor extensions (e.g., C_LoginBegin()). To use this token requires the proper setup and configuration of a nShield network-attached HSM both on the hardware server and client machine as documented in the Entrust product literature. The last step is the proper configuration of the P6R’s PKCS 11 library, which is described in detail in the SKC product documentation along with working examples.

The FutureX HSM Token

The FutureX HSM can be configured to look like another token. We map one slot of a FutureX HSM into one slot of our P6R PKCS 11 library. This integration supports most of the existing FutureX PKCS 11 vendor extensions (e.g., C_FX_GetLogFile()). To use this token requires the proper setup and configuration of a network-attached HSM both on the hardware server and client machine as documented in the FutureX product literature. The last step is the proper configuration of both the FutureX and P6R’s PKCS 11 libraries, which is described in detail in the SKC product documentation along with working examples.

The DocuSign HSM Token

The DocuSign HSM can be configured to look like another token. We map one slot of a DocuSign HSM into one slot of our P6R PKCS 11 library. To use this token requires the proper setup and configuration of a network-attached HSM both on the hardware server and client machine as documented in the DocuSign product literature. The last step is the proper configuration of both the DocuSign and P6R’s PKCS 11 libraries, which is described in detail in the SKC product documentation along with working examples.

YubiHSM 2.0 Token

The YubiHSM 2.0 can be configured to look like another token. We map one slot of a YubiHSM into one slot of our P6R PKCS 11 library. To use this token requires the proper setup of a YubiHSM using the software tools that come with the product. The form factor of this HSM makes for a set of interesting use cases (e.g., encrypting the keys used to protect a local P6R keystore).

AWS CloudHSM

The AWS CloudHSM can be configured to look like another token. We map one slot of a CloudHSM into one slot of our P6R PKCS 11 library. To use this token requires the proper setup of a CloudHSM using the software tools that AWS provides. Additionally, the P6R’s PKCS#11 library has to run on an AWS CloudHSM EC2 client instance.
P6R’s KSG product, which uses this PKCS#11 library, is listed under AWS CloudHSM Integrations.
Both P6R’s PKCS 11 and KSG products have been tested with AWS CloudHSM PKCS#11 SDK5 library.

Marvell LiquidSecurity HSM

The Marvell HSM can be configured to look like another token. We map one slot of a Marvell HSM into one slot of our P6R PKCS 11 library. To use this token requires the proper setup of a Marvell HSM using the software tools that Marvell provides. The Marvell HSM version that we tested with had slot identifiers starting at 1.

Slot & Token definition

P6R’s Provider allows any number of slots to be defined and in each slot any 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 configuration file. This configuration file allows the definition of any P6R or customer specific behavior since the PKCS 11 interface allows for vendor extensions. 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.

Oracle TDE Integration

P6R’s PKCS 11 Provider can be installed to work as an HSM with Oracle TDE. (See Section 8.2.6 Using Hardware Security Modules [HSM] with TDE.) Depending on how our PKCS 11 library is configured it can use anyone of the several supported token types: a KMIP Server, Utimaco HSM, Thales nShield HSM, or other market available HSM. In addition, via the supported plugin interface a customer could write their own token types and have it work with Oracle TDE (just as long as the required ciphers are supported by that token). Now a customer no longer needs a PKCS 11 library from each vendor but instead can simplify their development efforts with just one.

PrimeKey’s SignServer Integration

Both the KMIP and Micro Focus Atalla HSM tokens can be configured to work with PrimeKey’s SignServer. For a KMIP token all keys can be created and stored in the KMIP server and all encryption can be performed on a KMIP server. This integration requires a KMIP server with KMIP protocol version 1.3 and greater with streaming capability supported.

PDFlib Integration

The Micro Focus Atalla HSM token can be configured to work with the PDFlib PLOP DS. This integration supports document signing.

Java Security Provider

We have been improving our integration with Java. At first we worked on integration with Keytool and Jarsigner, now our PKCS#11 library, with the KMIP token, can be used by plain old Java. With straightforward configuration the following examples of Java call our PKCS#11 library and our KMIP token. The result is that a Java programmer can use KMIP without having to learn anything about KMIP. No KMIP company specific APIs to learn. Its even possible that existing Java programs can be converted (with the occasional tweak) to use KMIP this way.
Code example 1:

KeyGenerator keyGen = KeyGenerator.getInstance("AES", "SunPKCS11-P6RPKCS11");
keyGen.init(128);
Key key = keyGen.generateKey();

// replace an older key
if (ks.containsAlias("symmetric_aes_128_key")) ks.deleteEntry("symmetric_aes_128_key");
ks.setKeyEntry("symmetric_aes_128_key", key, null, null);

Don’t see any KMIP calls here right? The magic is in the specification of the provider:
“SunPKCS11-P6RPKCS11″. The result is that the above code calls the KMIP server to generate the AES key. Then that key can be found later by calls to the keystore.

Code example 2:

// the "12345678" is the keystore's password (i.e., the PKCS#11 token's PIN)
KeyStore ks = KeyStore.getInstance("PKCS11", "SunPKCS11-P6RPKCS11");
ks.load(null, "12345678".toCharArray());
Key secretKey = ks.getKey("symmetric_aes_128_key", null);

The three lines above actually do a KMIP Locate call for a key with a custom KMIP attribute set to “symmetric_aes_128_key”. In Java, “symmetric_aes_128_key” is referred to as the
alias. (Actually the code above first makes PKCS#11 C_FindObjects() calls which our KMIP token maps to KMIP Locate. Still all that is done for the Java programmer and totally hidden from them.)

Code example 3:

private static byte[] encryptData(Key secretKey, byte[] iv, String handling, byte[] clearText) { 
  byte[] cipherText = null;
  try {
      // with a security provider do the encrypt on the remote server
      Cipher encryptCipher = Cipher.getInstance(handling, "SunPKCS11-P6RPKCS11");
      IvParameterSpec IV = new IvParameterSpec(iv);
      encryptCipher.init(Cipher.ENCRYPT_MODE, secretKey, IV);
      cipherText = encryptCipher.doFinal(clearText);
   } catch (Exception e) {
       e.printStackTrace();
   }
   return cipherText;
}

Again see any KMIP calls here? The parameter “secretKey” was created in example 1 above. This code example shows that the encryption will be done on the KMIP server. We have also tested streaming encryption (requiring KMIP 1.3), with the call sequence encryptCipher.init(), encryptCipher.update() multiple calls of updates, and then encryptCipher.doFinal(), allowing encryption (and decryption) of large chunks of data. We have also done testing with public/private keys.

Other Applications

Customers have integrated our PKCS 11 library using the KMIP token with the following: Hashicorp Vault (https://www.vaultproject.io/docs/vs/hsm.html, https://www.vaultproject.io/docs/configuration/seal/pkcs11.html) and OpenSC.

We have integrated our PKCS 11 library with our SSH server product that is described in the article: Integrating KMIP, PKCS 11, and SSH. While that article focuses on the KMIP token our SSH server implementation can use any of the tokens types defined above and any we add in the future.

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 NSP tokens.

Vendor Extensions

P6R defines the following vendor defined attribute:

CKA_P6R_GROUP 0x80001000UL
Data Type: RFC 2279 string                                       
MUST be specified when object is created with C_CreateObject.
MUST be specified when object is created with C_GenerateKey or C_GenerateKeyPair.

The purpose of this extension is to provide basic support for KMIP groups. CKA_P6R_GROUP maps into the KMIP “Object Group” attribute. Without the CKA_P6R_GROUP attribute defined the “default” KMIP 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.

References

1. PKCS 11 OASIS standard
2. KMIP OASIS standard
3. P6R’s Secure KMIP Client SDK
4. Key Management with a Powerful Keystore