Home » Articles

The KMIP Bug Report: Db2 KMIP Client

By Mark Joseph - May 19, 2018 @ 12:20 pm

Recently a customer using the P6R’s KMIP Server Protocol Library (KSL) sent us a KMIP message that our parser pointed out as not valid KMIP. This customer was performing integration testing between their KMIP server and IBM’s Db2 Database (version 11.1 running on windows) (https://www.ibm.com/analytics/us/en/db2/). Db2 has some KMIP Client code so that it can obtain keys for database encryption from an outside KMIP server. This is what KMIP was designed for. We have no idea of the origin of the KMIP client code but assume that it was written internally.

[1] Incorrect Text String encoding

The KMIP message that was of issue was trying to execute a KMIP Activate operation and is encoded in TTLV (a binary format) KMIP 1.0 protocol version. The offending KMIP message is as follows:

42007801000000c04200770100000078420069010000002042006a0200000004
000000010000000042006b0200000004000000000000000042000c0100000038
4200230100000030420024050000000480000001000000004200250800000018
54000101000000105400040700000003444232000000000042000d0200000004
000000010000000042000f010000003842005c05000000040000001200000000
4200790100000020420094070000001841574d6b736570694a54625a49736f5f
30586f7200000000


The broken part of this message comes at the very end in the following bytes encoded in TTLV (which stands for Tag Type Length Value):

420094 07 00000018 41574d6b736570694a54625a49736f5f30586f7200000000

The first part “420094″ is the Tag which indicates that the data following is a unique identifier. The second part “07″ indicates the Type is a text string. The third part “00000018″ is the Length of the following data which is 24. The fourth part “41574d6b736570694a54625a49736f5f30586f7200000000″ is the Value and is the unique identifier of a key on the KMIP server to activate.

The problem is with the length part. It is set to 24 but should be set to 20 bytes. Text strings in KMIP are padded with zeros to make their length a multiple of 8 so the last 4 bytes are all padded zeros. But this padding must not be included in the length of the text string value. In the above message the Db2 KMIP client did include the padding as part of the text string length and that is incorrect.

Since the above message uses KMIP protocol version 1.0 we are going to reference the KMIP 1.0 specification document (http://docs.oasis-open.org/kmip/spec/v1.0/os/kmip-spec-1.0-os.html). From this specification, Section 9.1.1.3 Item Length,

     "...If the Item Type is Integer, Enumeration, Text String, Byte String, or Interval, then 
     the Item Length is the number of bytes excluding the padding bytes. Text Strings and Byte 
     Strings SHALL be padded with the minimal number of bytes following the Item Value to obtain 
     a multiple of eight bytes." (emphasis added)


[2] An Extension Credential Type with an Incorrect Byte String Encoding

While not an error this message does use an interesting encoding for the message credential.

420024 05 00000004 8000000100000000 
  420025 08 00000018 540001010000001054000407000000034442320000000000


The “420024″ Tag indicates “Credential Type”, the “05″ Type is enumeration, the “00000004″ is the length of the enumeration, and finally the
“8000000100000000″ is a Db2 defined KMIP extension type. Now KMIP does provide several ways to extend the protocol but now our customer has to find out the Db2 proprietary definition and implement that.

The next part is the Credential Value itself and is encoded as a Byte String. Interesting the length value of the Byte String value also looks wrong as the apparent padding is again included in the defined length.

Full featured KMIP clients are not easy to implement and that is why P6R has spent years developing and testing with every commercially available KMIP server it can find. P6R’s Secure KMIP Client (SKC) is a commercial product that has been shipping for over 5 years.

2018 OASIS KMIP Client Interop Results

By Mark Joseph - April 13, 2018 @ 2:40 pm

P6R had a pod in the OASIS booth at the 2018 RSA Conference Expo. This was our 4th year at this conference. We where showing off our KMIP and PKCS#11 products.
P6R at 2018 RSA Conference Expo

P6R participated in its 4th OASIS KMIP Interop. This interop tested KMIP 1.4 and the draft specification of KMIP 2.0. P6R tested its Secure KMIP Client (SKC) with the following list of KMIP Servers: Cryptsoft KMIP C and Java Servers, Fornetix Key Orchestration Server, IBM SKLM, Kryptus kNET HSM, Micro Focus ESKM, Q-Labs qCrypt, Thales DSM, and Unbound KMIP server. Below are the results of all clients participating in the Interop. Note that P6R’s SKC results is the full column on the right. P6R SKC passed all test cases conducted in this Interop.

KeyNexus and P6R Announce KMIP Partnership

By Mark Joseph - March 27, 2018 @ 8:57 am

KeyNexus and P6R Announce KMIP Partnership, Delivering a Complete End-to-End Client-Server KMIP Solution
http://www.prweb.com/releases/2018/03/prweb15365259.htm

Detailed differences between KMIP 1.4 and 2.0

By Mark Joseph - March 24, 2018 @ 12:51 pm

This document focuses on the technical content that has changed from KMIP protocol version 1.4 to 2.0. While there are significant changes in how the two documents are organized and the material presented this article will not address those differences. This article uses the published KMIP 1.4 standard document
KMIP 1.4, 22 November 2017 and a draft version of the KMIP 2.0 standard. Please note that since this comparison is based on a draft KMIP 2.0 standard the details presented here can still change in the future.

We started this task of comparing the two protocol versions as part of the process of adding KMIP 2.0 support to our suite of KMIP products: P6R’s KMIP Client Product Suite, Secure KMIP Client (SKC), and P6R’s KMIP Server Library (KSL). We have done a similar comparsion between KMIP 1.0 and 1.1.

At a high level what has changed?

The first significant thing to notice is that all the depreciated features have been removed from previous protocol versions. The main example of this are Templates. Templates are no longer a managed object and are nowhere to be found in the specification. Another big change has occurred to attributes both in how they are represented and encoded in the protocol. The text string name of each attribute, which was also passed in the binary TTLV protocol version, has finally been removed. Lastly, I would categorize the remaining changes to be mostly improvements of existing attributes. The motivations behind these changes have been to increase interoperability and efficiency of the protocol.

1. Managed Objects

  • a. PGP Certificates have been removed and are not part of KMIP 2.0
  • b. Template objects have been removed (depreciated in KMIP 1.3) and are not part of KMIP 2.0
  • c. A Certificate Request has been added as a new managed object

2. Base Objects

  • The following have been remove and are not part of KMIP 2.0: Transparent ECDSA Private Key, Transparent ECDSA Public Key, Transparent ECDH Private Key, Transparent ECDH Public Key, Transparent ECMQV Private Key, and Transparent ECMQV Public Key.

It was deemed that the remaining Transparent EC Private Key and Transparent EC Public Key attributes where sufficient, and all have identical structures anyway. For the second item, all have been replaced and simplified which will be mentioned below.

In the Key Value structure, the Attribute array has been replaced with the Attributes structure.

3. Attributes

  • a. The following attributes have been removed and are not part of KMIP 2.0: Certificate Identifier, Certificate Issuer, Certificate Subject, Custom Attribute, and Operation Policy Name.
  • b. The following attributes have been added to KMIP 2.0: NIST Key Type, Short Unique Identifier, and Vendor Attribute (replaces the Custom Attribute).

There has also been a major change in the way that attributes are encoded. Pre-KMIP 2.0 the string name of an attribute (e.g., “Cryptographic Usage Mask”) would be sent over the network. That practice is now limited to only vendor defined attributes. In doing this a more economical encoding of each standard defined attribute has been adopted. This is significant improvement over the previous versions of the protocol.

4. Attribute Structures

  • a. The following attribute structures have been removed and are not part of KMIP 2.0: Template-Attribute, Common Template-Attribute, Private Key Template-Attribute, and Public Key Template-Attribute.
  • b. The following attribute structures have been added to KMIP 2.0: Attributes, Common Attributes, Private Key Attributes, Public Key Attributes, Attribute Reference, Current Attribute, and New Attribute.

This change was motivated by the removal of Templates from the standard. The new attribute structures are meant as a “simplified” replacement of the previous structures.

5. Modified and New Structures

  • a. The Extension Information structure has been extended with the following optional fields: Extension Enumeration, Extension Attribute, Extension Parent Structure Tag, and Extension Description.
  • b. The Profile Information structure has been extended with the “Profile Version” field.
  • c. The Key Wrapping Specification structure has its “Attribute Name” field replaced with an Attribute Reference field.
  • d. The Server Information structure was an undefined structure in KMIP 1.4 and has been changed to a well defined, multi-field structure. This is a much overdue change and finally makes this base object useful.

  • e. The Log Message base object has been added new to KMIP 2.0

6. Operations

  • a. There has been a positive change in all operations that sent attributes to a KMIP server. In KMIP 1.4 and earlier, the responses to such operations would return a copy of all the attributes that where included in the request. This has changed in KMIP 2.0 in that responses no longer return a copy of the attributes that appeared in the request

    b. Operations where this change has been made include: Create, Create Key Pair, Add Attribute, Delete Attribute, Derive Key, Create Split Key, Join Split Key, Register, Certify, Re-Certify, Re-Key, and Re-Key Key Pair.

  • c. Add Attribute, Attribute replaced by Current Attribute structure
  • d. Certify, Template-Attribute replaced by Attributes structure
  • e. Create, Template-Attribute replaced by Attributes
  • f. Create Key Pair, Common Template-Attribute replaced by Common Attributes, Private Key Template-Attribute replaced by Private Key Attributes, Public Key Template-Attribute replaced by Public Key Attributes
  • g. Create Split Key, Template-Attribute replaced by Attributes
  • h. Delete Attribute, Attribute Name and Attribute Index replaced by Current Attribute. Note, that to delete an attribute the value of that attribute must be provided in the Current Attribute structure. This is different from KMIP 1.4
  • i. Derive Key, Template-Attribute replaced by Attributes
  • j. Export, in the response one or more Attribute structures are replaced by Attributes, Template is removed
  • k. Get, in the response Template is removed
  • l. Get Attributes, Attribute Name replaced by Attribute Reference, in response zero or more Attribute structures replaced by Attributes
  • m. Get Atribute List, in response Attribute Name replaced byAttribute Reference
  • n. Import, Object Type added, one or more Attribute structures replaced by Attributes, Template removed
  • o. Join Split Key, Template-Attribute replaced by Attributes
  • q. Locate, zero or more Attribute structures replaced by Attributes.
    The paragraph starting with “Wild-cards or regular expressions” has been removed since it has not been implemented and it is unclear how to implement it.
    The description of how the “Storage Status Mask field” is used has been expanded.
  • r. Log, a new operation
  • s. Modify Attribute, Attribute replaced by Current Attribute and New Attribute structures
  • t. Register, Template-Attribute replace by Attributes, Template removed
  • u. Re-Certify, Certificate Request Unique Identifier added, Template-Attribute replaced by Attributes
  • v. Re-Key, Template-Attribute replaced by Attributes
  • w. Re-Key Key Pair Common Template-Attribute replaced by Common Attributes, Key Private Template-Attribute replaced by Private Key Attributes, Public Key Template-Attributes replaced by Public Key Attributes
  • x. Notify, the list of Attribute structures has been replaced by the new Attributes structure for indicating attributes that have changed and a list of Attribute Reference structures indicating attributes that have been deleted.
  • y. Put, Template object has been removed from the list of objects that can be pushed to the client and the list of Attribute structures has been replaced by the new Attributes structure.

7. Enumerations and Masks

  • a. Certificate Request Type Enumeration: PGP has been removed
  • b. Certificate Type Enumeration: PGP has been removed
  • c. Item Type Enumeration: Data Time Extended is new
  • d. Link Type Enumeration: Wrapping Key Link is new
  • e. Object Type Enumeration: Certificate Request is new
  • f. NIST Key Type Enumeration has been added to KMIP 2.0
  • g. Profile Name Enumeration: all profiles before KMIP 2.0 have been removed
  • h. Storage Status Mask: Destroyed Storage is new
  • i. Tags have been moved into the enumerations section. Several old tag values have been removed by being marked as “reserved”. New tag values have been from 420125 (i.e., Attributes) to 42013D (i.e., New Attribute).

8. Miscellaneous

  • a. Under message encoding a new TTLV type has been added: Data Time Extended which is a 64 bit POSIX Time in micro-seconds.
  • b. The default value for Batch Order Option has been changed to True (i.e., batched operations shall be executed in the order in which they appear in a request).

P6R’s KMIP Verification Suite (KVS)

By Mark Joseph - March 13, 2018 @ 11:08 am

This document was updated on 10 June 2018.

P6R is introducing the new product KMIP Verification Suite (KVS). Due to customer interest we have taken our KMIP test harness, which we have used to develop our KMIP Client product (SKC) and have used during several OASIS KMIP Interop events, and are making it available to vendors to test their KMIP server products. KVS implements all defined OASIS KMIP test cases for protocol versions 1.0, 1.1, 1.2, 1.3, and 1.4. Test cases for KMIP 2.0 are currently in beta and will be released shortly. KVS is implemented with P6R’s Secure KMIP Client (SKC) to generate proper KMIP messages in TTLV, JSON, XML, and TTLV over HTTPS. SKC is also used to parse the server’s response while KVS matches the server’s response to what is expected as defined by the OASIS test cases.

KVS supports the following OASIS defined KMIP defined tests:
KMIP Test Cases Version 1.0, (defined in several of the documents below such as http://docs.oasis-open.org/kmip/testcases/v1.2/kmip-testcases-v1.2.html)

KMIP Test Cases Version 1.1, http://docs.oasis-open.org/kmip/testcases/v1.1/kmip-testcases-v1.1.html

KMIP Test Cases Version 1.2, http://docs.oasis-open.org/kmip/testcases/v1.2/kmip-testcases-v1.2.html

KMIP Test Cases Version 1.3, http://docs.oasis-open.org/kmip/testcases/v1.3/kmip-testcases-v1.3.html

KMIP Test Cases Version 1.4, http://docs.oasis-open.org/kmip/testcases/v1.4/cn01/kmip-testcases-v1.4-cn01.html

KMIP Test Cases Version 2.0 Draft

KVS has been used to test interoperability with the following KMIP servers:
1. Cryptsoft KMIP C Server SDK
2. Cryptsoft KMIP Java Server SDK
3. Dell KMIP Server
4. Fornetix Key Orchestration Server
5. Micro Focus ESKM Server (formerly HPE)
6. IBM SKLM Server
7. QuintessenceLabs qCrypt Server
8. SafeNet KeySecure Server
9. Thales KeyAuthority KMIP Server
10. Townsend Security Alliance Key Manager
11. Utimaco KeyServer
12. Vormetric Data Security Manager KMIP Server
13. Kryptus kNET HSM
14. Hancom Secure KeyManager
15. Unbound UKC Server
16. keyNexus KMIP Server

P6R is a member of the OASIS KMIP technical committee and one if its employees is a co-editor on several of the KMIP test case documents.

P6R has been in business for 14 years

By Mark Joseph - November 30, 2017 @ 10:44 am

P6R is a privately held, self-funded and self-sustaining software company found in 2004. Providing multi-platform solutions to a broad range of businesses, P6R’s security products and professional services enable businesses to easily solve their key management and encryption integration challenges with OASIS KMIP, PKCS#11 toolkits and custom clients.

P6R partners with our customers in an ongoing relationship to develop successful solutions that deliver the highest levels of quality and customer value. P6R has a wide range of expertise in areas including computer security, networking, mobile technologies, scalability, high-availability, email, and ad serving. We take personal pride in everything that we do and are committed to achieving exceptional business results.

P6R is a Sponsor level member of OASIS (https://www.oasis-open.org/member-roster).

P6R is a member of the OASIS KMIP Technical Committee.

P6R is a member of the OASIS PKCS#11 Technical Committee.

P6R provides KMIP client (https://www.p6r.com/articles/2016/08/08/p6rs-kmip-client-product-suite/) and server (https://www.p6r.com/articles/2017/11/14/p6rs-kmip-server-library-ksl/) products.

P6R also provides a PKCS#11 library that integrates with KMIP and all major HSMs (https://www.p6r.com/articles/2014/11/22/p6rs-pkcs-11-provider/)

P6R has customers in disk storage, health care, financial, and enterprise data management.

P6R is a technology partner with several major security companies:
Safenet (https://safenet.gemalto.com/partners/p6r/), Thales e-Security ASAP member, Microfocus (previously HPE).

P6R is a US company based in California. All development and testing are done in the US.

P6R’s KMIP Server Library (KSL)

By Mark Joseph - November 14, 2017 @ 12:32 pm

This document was updated on 21 Jan. 2018.

P6R is introducing the new product KMIP Server Library (KSL). Due to customer interest we have extended our powerful KMIP client parsing library (i.e., SKC) to be able to parse server side requests. This product includes a server side parser and all the functions needed to send a properly encoded response back to a KMIP client. The idea is that a vendor, who has a key server, can now use KSL to add a KMIP protocol front end. The server vendor will still have to implement all server side mechanisms, but will not have to deal with the complexity of parsing or generating TTLV, XML, and JSON KMIP messages.

KSL is available on Windows and Linux. It supports a C++, C, and Java Native Interface (JNI) language bindings. KSL supports all KMIP operations that are defined for KMIP 1.0, 1.1, 1.2, 1.3, and 1.4 except for: Export. Support for the KMIP 1.4 operation Export will be added in the near future. KMIP 2.0 support will also be added at a future date once the specification for that protocol version is published.

P6R’s KMIP Client Product Suite

By Mark Joseph - August 8, 2016 @ 10:09 pm

This document was updated on 11 April 2018.

P6R KMIP software can support a wide range of customer requirements with various programming language and integration support.

Supported Programming Languages


1. C/C++ — Secure KMIP Client (SKC) SDK
2. Java Security Provider
3. Java Native Interface (JNI)p6javakmip is a wrapper around the SKC library
4. python extension modulep6pythonkmip is a wrapper around the SKC library with a similar API as defined by p6javakmip

Supported Integrations


1. PKCS#11 KMIP Token
2. Oracle Transparent Data Encryption (TDE) support via P6R’s PKCS#11 KMIP Token
In this integration the Oracle database thinks it is connected to a Hardware Security Module (HSM) but it actually is using a KMIP server.
3. KMIP used in a SSH server
4. KMIP Command Line Tool allows customers to script their access to a KMIP server
5. PKCS#11 KMIP token as the PKCS#11 provider for PrimeKey’s SignServer

Supported Platforms


1. Linux x86 Kernel 2.6+ (32bit/64bit)
2. Windows 7/8+ (32bit/64bit), Windows Server 2008R2+ (32bit/64bit)
3. Unified Extensible Firmware Interface (UEFI) 64bit Tianocore Native PE Format
4. Intel and ARM processors

Supported KMIP Protocol Versions


Complete implementations of: 1.0, 1.1, 1.2, 1.3, 1.4

Supported KMIP Servers


P6R has performed inter-operation testing with the following KMIP servers either at an OASIS run event or via private testing arranged between the two companies.

1. Cryptsoft KMIP C Server SDK
2. Cryptsoft KMIP Java Server SDK
3. Dell KMIP Server
4. Fornetix Key Orchestration Server
5. Micro Focus ESKM Server (formerly HPE)
6. IBM SKLM Server
7. QuintessenceLabs qCrypt Server
8. SafeNet KeySecure Server
9. Thales KeyAuthority KMIP Server
10. Townsend Security Alliance Key Manager
11. Utimaco KeyServer
12. Vormetric KMIP Server
13. Kryptus kNET HSM
14. Hancom Secure KeyManager
15. Unbound UKC Server
16. KeyNexus Universal Key Manager

Need a Command Line KMIP Client?

By Mark Joseph - June 4, 2016 @ 9:47 am

What was the need?

P6R sells a KMIP client SDK and a Transparent Data Encryption (TDE) Connector. The TDE connector uses PKCS#11 with a KMIP token so that an Oracle database can use a KMIP server to manage its keys. In supporting these products we have seen the need for a full featured, scriptable, KMIP command line tool that can be used with any KMIP Server.

There are similar questions that occur during KMIP application development, deployment, and support some of which include: What KMIP protocol version does the server support?; What KMIP features does the server support (e.g., streaming encryption)?; Is the TLS connection to a server working?; Did we create the key we attempted to create, what is its state, what are the attributes associated with it? Logging into the KMIP server’s Web front end won’t answer all of these questions and each server’s UI is different. Most KMIP application developers we talk to want their applications to work with all KMIP servers, and would prefer the tools they use to also work with all KMIP servers rather then one per server vendor.

We have gotten customer requests for such a tool and in response we have built a full featured, scriptable command line tool that was implemented with our own KMIP client SDK. Since we have tested our SDK with just about every KMIP server commercially available our KMIP command line tool should work with every KMIP server. Our KMIP client SDK product page documents all the servers we have test with: SKC Secure KMIP Client

Our Solution

It is important to note that KMIP supports more than just keys. It also supports a collection of objects which include: Certificates, Opaque objects, and Secret data such as passwords. So instead of just talking about keys we will try to use the generic term Managed Object wherever possible.

From our experience we have added the most commonly used and useful KMIP features to our command line tool. Basically each command performs one KMIP operation which includes: creating objects, exporting/importing objects, adding/modifying/deleting/listing attributes associated with objects, deleting objects, activate/revoking a key, re-keying keys, encrypt/decrypt files, obtain server generated random numbers, query server features, and searching for objects based on various filters (e.g., object type, attribute values associated with a Managed object). The search command is an very useful one. For example, we can assign a set of Managed Objects with the same KMIP custom attributes such as
“x-group-name = customerZ”. Then we can do a search (actual a KMIP Locate operation) for all Managed Objects with the associated attribute “x-group-name = customerZ”. The result of that search will be all the objects we stamped with the “x-group-name = customerZ” attribute value.

Another nice feature is that our command line tool can be configured to work with one or more KMIP servers at the same time. Each command requires the user to provide either the IP address or fully qualified domain name of a KMIP server as part of the command (e.g., “p6kmiptool -list -server kmiptest01.p6r.com ….”). Here are some simple examples of using our command line tool.


.......>p6kmiptool -config

----- Server List  -----
1> Server: [192.168.72.1]
2> Server: [kmiptest01.p6r.com]

Config found 2 items.


....>p6kmiptool -list -server kmiptest01.p6r.com -type symmetrickey

----- Object List  -----
1> Type: Symmetric Key, Unique Id: [4c5db22f-3747-4d19-9593-7fa1b83816aa]
2> Type: Symmetric Key, Unique Id: [a6efe3ed-08c5-418b-b76a-c15e1652a5ac], Alias: [frank]
3> Type: Symmetric Key, Unique Id: [80116b3e-156e-4079-abd8-34ff337fffad]
4> Type: Symmetric Key, Unique Id: [96a97e73-3e6a-4b95-8c93-65c1bd2966c9], Alias: [henry11]

List found 4 managed objects.


.....>p6kmiptool -attributes -server kmiptest01.p6r.com -uid a6efe3ed-08c5-418b-b76a-c15e1652a5ac

List of attributes associated with object [a6efe3ed-08c5-418b-b76a-c15e1652a5ac].

x-P6R-CMD-LABEL = frank, index 0
x-P6R-CMD-SKCCLIENT = true, index 0
Object Type = Symmetric Key (2), index 0
Cryptographic Algorithm = AES (3), index 0
Cryptographic Length = 256, index 0
Alternative Name = frank, index 0
Cryptographic Usage Mask = Encrypt, Decrypt, index 0

Digest hash algorithm = SHA256 (6), index 0
Digest value: b251c1ad58587d294421696063aad76f655f7c47055f83bc53dcc5a1de3c

Fresh = true, index 0
Initial Date = 2016-05-16T03:32:55Z, index 0
Last Change Date = 2016-05-16T03:32:55Z, index 0
Lease Time = 3600, index 0
Original Creation Date = 2016-05-16T03:32:55Z, index 0
State = Pre-Active (1), index 0

List of object attributes succeeded (error: eOk).


The current shipping version of our KMIP command line tool can be used to script access to a KMIP server and it runs on Linux and Windows. P6R’s KMIP command line tool comes standard with our SKC KMIP client SDK and is also available as a standalone product.

Using KMIP via a Java Security Provider

By Mark Joseph - May 9, 2016 @ 5:23 pm

This document was updated on 12 May 2016.

Introduction

P6R sells a PKCS 11 Version 2.40 Provider with a KMIP token. The KMIP token translates each PKCS 11 API function into and out of the KMIP protocol. The user of the PKCS 11 KMIP token does not even know they are talking to a KMIP server. Java supports PKCS 11 as a possible security provider via the SunPKCS11 wrapper. Also JCE provider products also directly support PKCS 11 wrappers (e.g., IAIK).

The significant benefit of using KMIP via a Java security provider is that a Java programmer can use KMIP without having to learn anything about KMIP. No company specific KMIP APIs to learn. Its even possible that existing Java programs can be converted (with the occasional tweak) to use KMIP this way. All that is required to make this work is some straightforward configuration.

Testing Environment

We have tested out our PKCS 11 library as a Java security provider both on Centos 6 and Windows using the following:

To build our Java examples we used: 
jdk1.8.0_65, language level 8.0, IntelliJ IDEA 2016.1.1
JVM: Java HotSpot(TM) 64-Bit Server VM by Oracle Corporation

Systems tested on:
[1] Windows 7 Ultimate, 64 bit
C:\....>java -version
java version "1.8.0_91"
Java(TM) SE Runtime Environment (build 1.8.0_91-b14)
Java HotSpot(TM) 64-Bit Server VM (build 25.91-b14, mixed mode)
64 bit p6pkcs11.dll library 

[2] Centos6 Linux
[...... ~]$ cat /etc/redhat-release
CentOS release 6.7 (Final)
[....... ~]$ java -version
openjdk version "1.8.0_77"
OpenJDK Runtime Environment (build 1.8.0_77-b03)
OpenJDK 64-Bit Server VM (build 25.77-b03, mixed mode)
64 bit libp6pkcs11.so

Java Examples

Below are just a few code snippets that we have taken out of several of our Java test programs.

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.

Code example 4:

SecureRandom sr = SecureRandom.getInstance("PKCS11", "SunPKCS11-P6RPKCS11");
sr.setSeed("778373644".getBytes());

byte[] randomBytes = new byte[128];
sr.nextBytes(randomBytes);

Code example 4 shows how to use the random number generator on the KMIP server. The Java statement “sr.setSeed()” maps to the KMIP operation RNGSeed, and the statement “sr.nextBytes()” maps to the KMIP operation RNGRetrieve. Of course this mapping is done by the P6R PKCS#11 library. The trick in the above example is to make sure that the first parameter in the getInstance() call is “PKCS11″ and not the “SHA1PRNG” that appears in may Java examples of SecureRandom.

KMIP Server Capabilities

Well the above is all fine and good but how do I know what my KMIP server is capable of? Does my KMIP server support encryption, streaming encryption, what protocol version does it support? These are all basic questions and we provide the answer via our KMIP command line tool. Our command line tool, p6kmiptool, runs on Linux and Windows and provides scriptable access to many KMIP operations (e.g., one being KMIP Query).

>p6kmiptool -serverinfo -server {fully qualified host name}

KMIP server information:
server address: {fully qualified host name}:5696
using protocol version: 1.3

-------------------------
supported object: Certificate
supported object: SymmetricKey
supported object: SecretData
supported object: PublicKey
supported object: PrivateKey
supported object: Template
supported object: OpaqueObject
supported object: SplitKey
supported object: PGPKey

-------------------------
supported operation: Query
supported operation: Locate
supported operation: Destroy
supported operation: Get
supported operation: Create
supported operation: Register
supported operation: GetAttributes
supported operation: GetAttributeList
supported operation: AddAttribute
supported operation: ModifyAttribute
supported operation: DeleteAttribute
supported operation: Activate
supported operation: Revoke
supported operation: Poll
supported operation: Cancel
supported operation: Check
supported operation: GetUsageAllocation
supported operation: CreateKeyPair
supported operation: ReKey
supported operation: Archive
supported operation: Recover
supported operation: ObtainLease
supported operation: ReKeyKeyPair
supported operation: Certify
supported operation: ReCertify
supported operation: DiscoverVersions
supported operation: Notify
supported operation: Put
supported operation: RNGRetrieve
supported operation: RNGSeed
supported operation: Encrypt
supported operations: Decrypt
supported operations: Sign
supported operation: SignatureVerify
supported operation: MAC
supported operation: MACVerify
supported operation: Hash
supported operation: CreateSplitKey
supported operation: JoinSplitKey

-------------------------
vendor: {company name} KMIP Server {version}

-------------------------
capability: streaming is supported
capability: asynchronous command processing is supported
capability: attestation is supported
capability: unwrap mode is not processed
capability: destroy action is key material deleted
capability: shredding algorithm is unsupported
capability: RNG mode is unspecified


Given the information above, we can conclude that the above server can handle all the functions of our Java Security provider (e.g., streaming encryption: C_EncryptInit(), C_EncryptUpdate() … multiple calls, and finally C_EncryptFinal().

Our PKCS 11 library also comes with an equally powerful command line tool of its own that lets the user see what is stored on a token (also runs on Linux and Windows).

>p6pkcs11tool -list 0 -p 12345678


----- Object List  (slotId: 0) -----
1> Type: Certificate, Alias: [rsa_private_key] ID: [rsa_private_key],   Token
2> Type: Secret Key , Alias: [symmetric_aes_128_key] ID: [], AES  Token
3> Type: Private Key, Alias: [C6AC22B2-5330-48CE-A950-47CA883C03F6] ID: [rsa_private_key], RSA  Token


The above syntax is p6pkcs11tool {operation} {slotid} -p {User PIN}.

The PKCS 11 command line tool is also feature rich including functions to clean up after applications that do not call C_CloseSession(), create keys, delete keys, import and export keys and certificates, etc.