Developer's Guide
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
KMIP Reference Guide

Introduction

The SKC toolkit provides C++ based component libraries that currently implement the KMIP 1.0/1.1/1.2 protocols. The toolkit provides full KMIP message parsing and message generation. The toolkit provides several different layers of abstraction, each building on the previous, enabling the developer to use whichever layer or layers best suit their needs. The toolkit comes with binaries for Linux, Solaris, and Windows platforms.

SKC implements the translation of binary KMIP protocol messages into a standard DOM tree. Since a KMIP message is essentially a tree of nested structures this translation is straight forward. The result is a powerful new tool that can be used with KMIP 1.0, 1.1, and 1.2. The DOM tree is capable of outputting its contents into XML, JSON, JsonML, and has been extended to support binary nodes so that it can very efficiently handle KMIP binary messages and other binary data such as keys. The library supports logging of incoming and outgoing KMIP messages in XML, JSON, and JsonML to simplify development and trouble shooting.

Implementing binary KMIP message support in our standard DOM tree makes available a wealth of other P6R technologies for use. For example, any part of a KMIP message can be searched for and/or extracted using XPath 2.0. Using XSLT 2.0, a portion of one KMIP message could be transformed into a new message, or the message could be transformed into XHTML for viewing or XML for input into another tool or database.

A description of the unique design of this client can be found at: https://www.p6r.com/articles/2012/01/30/p6r-kmip-toolkit-introduction/

Includes

Interfaces

Ease of Use

The same client API allows a client developer to send KMIP messages encoded in TTLV, XML, or JSON. The exact same client API allows the client developer to send KMIP messages using HTTPS POST or the default SSL connection. No significant code change is required to switch between any of these features. All that is required is to set a set of flags when initializing the KMIP client. In the p6IKMIPClient::initialize() method there is a "preferences" parameter of type P6KMIP_PREF. One of the fields of a P6KMIP_PREF is a bit mask field:

* compatibility1 - A bit mask to enable special features of the KMIP specification (e.g., XML or JSON message format, HTTPS).
* Bit mask values are defined at the end of the p6kmip.h file.
*

Just by setting the KMIP_CMP_MSGXML (KMIP XML Message format) flag the client will send XML encoded messages to the server over HTTPS POST. Or by setting the KMIP_CMP_HTTPSPOST (KMIP HTTPS POST) flag the client will send TTLV encoded messages to the server over HTTPS POST. Thus the exact same calls to the P6R client can be used to interact with a KMIP server(s) in different ways by just changing the values of a bit mask.

The default client preferences are as follows:

* message format: TTLV
* network protocol: SSL
* protocol version: 1.1
*

All of these defaults can be over ridden by the preferences parameter when initializing a P6R KMIP client object (e.g., protocol version can be defined by the P6KMIP_PREF pVersion field).

Some Configuration Parameters

Most of the the client's configuration parameters (e.g., host name and port to connect to) are passed as parameters to an API function. However, a few values appear in the p6kmip.conf file since they are mostly static.

* [p6kmip-gen]
* logDir = "/var/log/kmip"
* errorStream = "kmipclient-errors.txt"
* uri = "/kmip"
*
*

The "logDir" configuration parameter (string value), defines an existing, writable directory where the KMIP client can write log files. If this configuration parameter is missing then logging will be disabled. Note, that the KMIP client will create directories under this log directory. One directory will be created for each KMIP server it connects to. For example:

* /var/log/kmip
* /var/log/kmip/abc.example.com
* /var/log/kmip/abc.example.com/query_server_call
* /var/log/kmip/abc/example.com/query_server_call/kmip-1382493469125976.xml
* /var/log/kmip/abc/example.com/query_server_call/kmip-1382493469426757.xml
* /var/log/kmip/abc/example.com/query_server_call/http-1382376977461914.txt
* /var/log/kmip/abc.example.com/create_symmetric_key
* /var/log/kmip/q.onecompany.com
*

In the above example, "abc.example.com" and "q.onecompany.com" are KMIP servers that the P6R client has connected to. The KMIP client API allows the the definition of another level of directories to be created under each of these server directories (e.g., see abc.example.com/query_server_call above). Also note that each KMIP message sent and received get its own file with a file name of the form: "kmip-unix time stamp.xml/json", so the files are ordered by time. Logging can be in XML or JSON when TTLV message format is used, however, when using XML message format logging will be in XML and when using JSON message format logging will be in JSON (to capture the exact message content). When HTTPS POST is used it is possible to turn on logging to capture the HTTP headers sent to the server. This logging will result in additional files with the format "http-unix time stamp.txt"

The "errorStream" configuration parameter (string value), is the name of a file to be created in the log directory that includes any XML/JSON/JsonML parsing errors and warning.

The "uri" configuration parameter (string value), is the path to be used in an HTTPS POST to the KMIP server.

Reference Documents

P6R's KMIP client follows the standards defined in the following documents.

1) OASIS, "Key Management Interoperabilty Protocol Specification 1.0", OASIS Standard, 15 June 2010.

2) OASIS, "Key Management Interoperabilty Protocol Specification 1.1", OASIS Standard, 24 January 2013.

3) OASIS, "Key Management Interoperabilty Protocol Specification 1.2", Working Draft 08, 21 August 2013.

4) OASIS, "Key Management Interoperability Protocol Test Cases Version 1.1", Working Draft 10, 27 April 2012.

5) OASIS, "Key Management Interoperability Protocol Test Cases Version 1.2", Working Draft 02, 06 August 2013.

6) OASIS, "KMIP Additional Message Encodings Version 1.0", Working Draft 03, 10 August 2013.

7) OASIS, "KMIP Asymmetric Key Lifecycle Profile Version 1.0", Working Draft 03, 10 August 2013.

8) OASIS, "KMIP Cryptographic Services Profile Version 1.0", Working Draft 05, 10 August 2013.

9) OASIS, "KMIP Symmetric Key Foundry for FIPS 140-2 Profile Version 1.0", Working Draft 03, 10 August 2013.

10) OASIS, "KMIP Symmetric Key Lifecycle Profile Version 1.0", Working Draft 03, 10 August 2013.

11) OASIS, "KMIP Opaque Managed Object Store Profile Version 1.0", Working Draft 03, 10 August 2013.

12) OASIS, "KMIP Tape Library Profile Version 1.0", Working Draft 04a, 24 October 2013.

13) OASIS, "Key Management Interoperability Protocol Storage Array with Self-Encrypting Drives Profile Version 1.0", Working Draft 04a, 24 October 2013.

14) OASIS, "KMIP Suite B Profile Version 1.0", Working Draft 03a, 24 October 2013.

Conformance

* KMIP 1.1 Operations
* Client provides both synchronous and asynchronous versions of the following operations:
*
* Create, Create Key Pair, Register, Re-key, Derive Key, Certify, Re-certify, Locate, Check, Get, Get Attributes
* Get Attribute List, Add Attribute, Modify Attribute, Delete Attribute, Obtain Lease, Get Usage Allocation,
* Activate, Revoke, Destroy, Archive, Recover, Validate, Query (synch only), Cancel, Poll, Re-key Key Pair,
* Discover Versions (synch only)
*
*
* KMIP 1.2 Operations
* Client provides both synchronous and asynchronous versions of the following operations:
*
* Create, Create Key Pair, Register, Re-key, Derive Key, Certify, Re-certify, Locate, Check, Get, Get Attributes
* Get Attribute List, Add Attribute, Modify Attribute, Delete Attribute, Obtain Lease, Get Usage Allocation,
* Activate, Revoke, Destroy, Archive, Recover, Validate, Query (synch only), Cancel, Poll, Re-key Key Pair,
* Discover Versions (synch only), Encrypt, Decrypt, Sign, Signature Verify, MAC, MAC Verify, RNG Retrieve,
* RNG Seed, Hash, Create Split Key, Join Split Key
*
*
* KMIP Version 1.1 Test Cases Supported
* TC-311-11 Create / Destroy
* TC-312-11 Register / Create / Get attributes / Destroy
* TC-313-11 Create / Locate / Get / Destroy
* TC-314-11 Dual Client Test Case, ID Placeholder-linked Locate & Get Batch
* TC-315-11 Register / Destroy Secret Data
* TC-32-11 Asynchronous Locate
* TC-41-11 Revoke Scenario
* TC-51-11 Get Usage Allocation Scenario
* TC-61-11 Import of a Third-party Key
* TC-71-11 Unrecognized Message Extension with Criticality Indicator False
* TC-72-11 Unrecognized Message Extension with Criticality Indicator True
* TC-81-11 Create a Key Pair
* TC-82-11 Register Both Halves of a Key Pair
* TC-91-11 Create a Key, Re-key
* TC-92-11 Existing Key Expired, Re-key with Same Life-cycle
* TC-93-11 Existing Key Compromised, Re-key with Same Life-cycle
* TC-94-11 Create Key, Re-key with New Life-cycle
* TC-95-11 Obtain Lease for Expired Key
* TC-101-11 Create a Key, Archive and Recover it
* TC-111-11 Credential, Operation Policy, Destroy Date
* TC-112-11 Device Credential, Operation Policy, Destroy Date
* TC-121-11 Query, Maximum Response Size
* TC-122-11 Query Vendor Extensions
* TC-131-11 Register an Asymmetric Key Pair in PKCS1 Format
* TC-132-11 Register an Asymmetric Key Pair and a Corresponding X509 Certificate
* TC-133-11 Create, Re-key Key Pair
* TC-134-11 Register Key Pair, Certify and Re-certify Public Key
* TC-141-11 Key Wrapping using AES Key Wrap and No Encoding
* TC-142-11 Key Wrapping using AES Key Wrap with Attributes
* TC-151-11 Locate a Fresh Object from the Default Group
* TC-152-11 Client-side Group Management
* TC-153-11 Default Object Group Member
* TC-161-11 Discover Versions
* TC-171-11 Handling of Attributes and Attribute Index Values
* TC-181-11 Digests of Symmetric Keys
* TC-182-11 Digests of RSA Private Keys
*
*
* Symmetric Key Lifecycle Profile Version 1.0
* SKLC-M-1-11 Create, GetAttributes, Destroy
* SKLC-M-2-11 Create, GetAttributes, Activate, GetAttributes, Destroy, Revoke, GetAttributes, Destroy
* SKLC-M-3-11 Create, GetAttributes, Activate, GetAttributes, ModifyAttribute, Revoke, GetAttributes, Destroy
* SKLC-O-1-11 Create, GetAttributes, Destroy, GetAttributes
*
*
* Symmetric Key Foundry for FIPS 140-2 Profile Version 1.0
* SKFF-M-1-11 Create, Destroy AES-128
* SKFF-M-2-11 Create, Destroy AES-192
* SKFF-M-3-11 Create, Destroy AES-256
* SKFF-M-4-11 Create, Destroy DES3-168
* SKFF-M-5-11 Create, Locate, Get, Destroy, Locate AES-128
* SKFF-M-6-11 Create, Locate, Get, Destroy, Locate AES-192
* SKFF-M-7-11 Create, Locate, Get, Destroy, Locate AES-256
* SKFF-M-8-11 Create, Locate, Get, Destroy, Locate DES3-168
* SKFF-M-9-11 Create, Get, Activate, Revoke, Locate, Add/Mod/Del Attributes, Destroy AES-128
* SKFF-M-10-11 Create, Get, Activate, Revoke, Locate, Add/Mod/Del Attributes, Destroy AES-192
* SKFF-M-11-11 Create, Get, Activate, Revoke, Locate, Add/Mod/Del Attributes, Destroy AES-256
* SKFF-M-12-11 Create, Get, Activate, Revoke, Locate, Add/Mod/Del Attributes, Destroy DES3-168
* SKFF-O-1-11 Create, Destroy SKIPJACK-80
* SKFF-O-2-11 Create, Locate, Get, Destroy, Locate SKIPJACK-80
* SKFF-O-3-11 Create, Get, Activate, Revoke, Locate, Add/Mod/Del Attributes, Destroy SKIPJACK-80
* SKFF-O-4-11 Create, Destroy DES3-112
* SKFF-O-5-11 Create, Locate, Get, Destroy, Locate DES3-112
* SKFF-O-6-11 Create, Get, Activate, Revoke, Locate, Add/Mod/Del Attributes, Destroy DES3-112
*
*
* Asymmetric Key Lifecycle Profile Version 1.0 Supported
* AKLC-M-1-11 CreateKeyPair, GetAttributes, GetAttributes, Destroy
* AKLC-M-2-11 CreateKeyPair, GetAttributes, Activate, GetAttributes, Destroy, Revoke, GetAttributes, Destroy
* AKLC-M-3-11 CreateKeyPair, GetAttributes, Activate, GetAttributes, Destroy, Revoke, GetAttributes, Destroy
* AKLC-O-1-11 CreateKeyPair, GetAttributes, Destroy, GetAttributes
*
*
* KMIP Opaque Managed Object Store Profile Version 1.0
* OMOS-M-1-11 Register small opaque object
* OMOS-O-1-11 Register large (>10k) opaque object
*
*
* KMIP Tape Library Profile Version 1.0
* TL-M-1-11 Configuration
* TL-M-2-11 Write with new (created) key
* TL-M-3-11 Read an encrypted tape
*
*
* Key Management Interoperability Protocol Storage Array with Self-Encrypting Drives Profile Version 1.0
* SASED-M-1-11 Configuration
* SASED-M-2-11 Register the authentication key
* SASED-M-3-11 Retrieve Authentication Key
*
*
*
* KMIP Version 1.2 Test Cases Supported
* TC-311-12 Create / Destroy
* TC-312-12 Register / Create / Get attributes / Destroy
* TC-313-12 Create / Locate / Get / Destroy
* TC-314-12 Dual Client Test Case, ID Placeholder-linked Locate & Get Batch
* TC-315-12 Register / Destroy Secret Data
* TC-32-12 Asynchronous Locate
* TC-41-12 Revoke Scenario
* TC-51-12 Get Usage Allocation Scenario
* TC-61-12 Import of a Third-party Key
* TC-71-12 Unrecognized Message Extension with Criticality Indicator False
* TC-72-12 Unrecognized Message Extension with Criticality Indicator True
* TC-81-12 Create a Key Pair
* TC-82-12 Register Both Halves of a Key Pair
* TC-91-12 Create a Key, Re-key
* TC-92-12 Existing Key Expired, Re-key with Same Life-cycle
* TC-93-12 Existing Key Compromised, Re-key with Same Life-cycle
* TC-94-12 Create Key, Re-key with New Life-cycle
* TC-95-12 Obtain Lease for Expired Key
* TC-101-12 Create a Key, Archive and Recover it
* TC-111-12 Credential, Operation Policy, Destroy Date
* TC-112-12 Device Credential, Operation Policy, Destroy Date
* TC-121-12 Query, Maximum Response Size
* TC-122-12 Query Vendor Extensions
* TC-131-12 Register an Asymmetric Key Pair in PKCS1 Format
* TC-132-12 Register an Asymmetric Key Pair and a Corresponding X509 Certificate
* TC-133-12 Create, Re-key Key Pair
* TC-134-12 Register Key Pair, Certify and Re-certify Public Key
* TC-141-12 Key Wrapping using AES Key Wrap and No Encoding
* TC-142-12 Key Wrapping using AES Key Wrap with Attributes
* TC-151-12 Locate a Fresh Object from the Default Group
* TC-152-12 Client-side Group Management
* TC-153-12 Default Object Group Member
* TC-161-12 Discover Versions
* TC-171-12 Handling of Attributes and Attribute Index Values
* TC-181-12 Digests of Symmetric Keys
* TC-182-12 Digests of RSA Private Keys
* TC-PGP-1-12 Register PGP Key - RSA
* TC-MDO-1-12 Register MDO Key
* TC-MDO-2-12 Locate MDO keys by Key Value Present
* TC-MDO-3-12 Register MDO Key using PKCS11 URI
* TC-SJ-1-12 Create and Split/Join
* TC-SJ-2-12 Register and Split / Join
* TC-SJ-3-12 Join Split Keys
* TC-SJ-4-12 Register and Split / Join with XOR
*
*
* Symmetric Key Lifecycle Profile Version 1.0
* SKLC-M-1-12 Create, GetAttributes, Destroy
* SKLC-M-2-12 Create, GetAttributes, Activate, GetAttributes, Destroy, Revoke, GetAttributes, Destroy
* SKLC-M-3-12 Create, GetAttributes, Activate, GetAttributes, ModifyAttribute, Revoke, GetAttributes, Destroy
* SKLC-O-1-12 Create, GetAttributes, Destroy, GetAttributes
*
*
* Symmetric Key Foundry for FIPS 140-2 Profile Version 1.0
* SKFF-M-1-12 Create, Destroy AES-128
* SKFF-M-2-12 Create, Destroy AES-192
* SKFF-M-3-12 Create, Destroy AES-256
* SKFF-M-4-12 Create, Destroy DES3-168
* SKFF-M-5-12 Create, Locate, Get, Destroy, Locate AES-128
* SKFF-M-6-12 Create, Locate, Get, Destroy, Locate AES-192
* SKFF-M-7-12 Create, Locate, Get, Destroy, Locate AES-256
* SKFF-M-8-12 Create, Locate, Get, Destroy, Locate DES3-168
* SKFF-M-9-12 Create, Get, Activate, Revoke, Locate, Add/Mod/Del Attributes, Destroy AES-128
* SKFF-M-10-12 Create, Get, Activate, Revoke, Locate, Add/Mod/Del Attributes, Destroy AES-192
* SKFF-M-11-12 Create, Get, Activate, Revoke, Locate, Add/Mod/Del Attributes, Destroy AES-256
* SKFF-M-12-12 Create, Get, Activate, Revoke, Locate, Add/Mod/Del Attributes, Destroy DES3-168
* SKFF-O-1-12 Create, Destroy SKIPJACK-80
* SKFF-O-2-12 Create, Locate, Get, Destroy, Locate SKIPJACK-80
* SKFF-O-3-12 Create, Get, Activate, Revoke, Locate, Add/Mod/Del Attributes, Destroy SKIPJACK-80
* SKFF-O-4-12 Create, Destroy DES3-112
* SKFF-O-5-12 Create, Locate, Get, Destroy, Locate DES3-112
* SKFF-O-6-12 Create, Get, Activate, Revoke, Locate, Add/Mod/Del Attributes, Destroy DES3-112
*
*
* Asymmetric Key Lifecycle Profile Version 1.0 Supported
* AKLC-M-1-12 CreateKeyPair, GetAttributes, GetAttributes, Destroy
* AKLC-M-2-12 CreateKeyPair, GetAttributes, Activate, GetAttributes, Destroy, Revoke, GetAttributes, Destroy
* AKLC-M-3-12 CreateKeyPair, GetAttributes, Activate, GetAttributes, Destroy, Revoke, GetAttributes, Destroy
* AKLC-O-1-12 CreateKeyPair, GetAttributes, Destroy, GetAttributes
*
*
* KMIP Opaque Managed Object Store Profile Version 1.0
* OMOS-M-1-12 Register small opaque object
* OMOS-O-1-12 Register large (>10k) opaque object
*
*
* KMIP Tape Library Profile Version 1.0
* TL-M-1-12 Configuration
* TL-M-2-12 Write with new (created) key
* TL-M-3-12 Read an encrypted tape
*
*
* Key Management Interoperability Protocol Storage Array with Self-Encrypting Drives Profile Version 1.0
* SASED-M-1-12 Configuration
* SASED-M-2-12 Register the authentication key
* SASED-M-3-12 Retrieve Authentication Key
*
*
* KMIP Cryptographic Services Profile Version 1.0 (KMIP 1.2) Supported
* CS-BC-M-1-12 Encrypt with New Symmetric Key
* CS-BC-M-2-12 Decrypt with New Symmetric Key
* CS-BC-M-3-12 Encrypt and Decrypt with New Symmetric Key
* CS-BC-M-4-12 Encrypt with Known Symmetric Key
* CS-BC-M-5-12 Decrypt with Known Symmetric Key
* CS-BC-M-6-12 Encrypt and Decrypt with Known Symmetric Key
* CS-BC-M-7-12 Encrypt with Known Symmetric Key with Usage Limits
* CS-BC-M-8-12 Encrypt and Decrypt with Known Symmetric Key and PKCS5 Padding
* CS-BC-M-9-12 Encrypt and Decrypt with Known Symmetric Key and PKCS5 Padding
* CS-BC-M-10-12 Encrypt and Decrypt with Known Symmetric Key and PKCS5 Padding and CBC
* CS-BC-M-11-12 Encrypt and Decrypt with Known Symmetric Key and PKCS5 Padding and CBC and IV
* CS-BC-M-12-12 Encrypt and Decrypt with Known Symmetric Key and PKCS5 Padding and CBC and IV
* CS-BC-M-13-12 Encrypt and Decrypt with Known Symmetric Key and PKCS5 Padding and CBC and Random IV
* CS-BC-M-14-12 Encrypt and Decrypt with Known Symmetric Key Date Checks
* CS-RNG-M-1-12 RNG Retrieve
* CS-RNG-O-1-12 Seed RNG with Server Accept
* CS-RNG-O-2-12 Seed RNG with Server Partial Accept
* CS-RNG-O-3-12 Seed RNG with Server Ignore
* CS-RNG-O-4-12 Seed RNG with Server Deny
* CS-AC-M-1-12 Sign with Known Asymmetric Key
* CS_AC_M_2_12 Signature Verify with Known Asymmetric Key
* CS-AC-M-3-12 Sign and Signature Verify with Known Asymmetric Key
* CS-AC-M-4-12 MAC with Known Key
* CS_AC_M_5_12 MAC Verify with Known Key
* CS-AC-M-6-12 MAC and MAC Verify with Known Key
* CS-AC-M-7-12 Hash
* CS-AC-M-8-12 Sign and Signature Verify with Known Asymmetric Key Date Checks
*
*
* KMIP Additional Message Encodings Version 1.0 Supported (for both KMIP 1.1 & 1.2)
* MSGENC-HTTPS-1-10 - HTTPS POST: Query, Maximum Response Size
* MSGENC-XML-1-10 - Message Encoding XML: Query, Maximum Response Size
* In addition, we have run all above test cases in XML mode.
* MSGENC-JSON-1-10 - Message Encoding JSON: Query, Maximum Response Size
* In addition, we have run all above test cases in JSON mode.
*
*
* Managed Objects Supported
* Certificate, Symmetric Key, Public Key, Private Key, Split Key, Template,
* Secret Data, Opaque Object, PGP Key
*
*
* Product SKU #1, includes P6R's version of openSSL
*
* Cryptographic Algorithms
* DES, 3DES, DES-X, AES (including counter mode), RSA, DSA, DH, HMAC-SHA1, HMAC-SHA224
* HMAC-SHA256, HMAC-SHA384, HMAC-SHA512, HMAC-MD2, HMAC-MD4, HMAC-MD5, Blowfish, CAST5, RC2
*
* Key Format Types
* Raw, Opaque, PKCS#1, PKCS#8, X.509, Transparent Symmetric Key, Transparent DSA Private Key
* Transparent DSA Public Key, Transparent RSA Private Key, Transparent RSA Public Key
*
* Certificate Types
* X.509
*
*
* Product SKU #2, customer provides openSSL
* TBD
*

Support for the Suite B Profile

This profile is defined by the document: OASIS, "KMIP Suite B Profile Version 1.0", Working Draft 03a, 24 October 2013.

P6R's KMIP client uses the OpenSSL library for its SSL/TLS support (see http://www.openssl.org/). Our client allows the user to select the ciphers to use for SSL/TLS via the API call:

* setSSLOptions( const P6WCHAR* pCiphers, P6SECURESOCKETFLAGS fSecureFlags )
*
* where the "pCiphers" paramter is a pointer to a NULL terminated wide character string containing the OpenSSL
* cipher command (see http://www.openssl.org/docs/apps/ciphers.html). If pCiphers parameter is NULL, then the
* secure default will be automatically be used: "TLSv1+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 first.
*

The only constraint, is that the specified ciphers in the setSSLOptions API call are supported by the OpenSSL library in use, whether supplied by the customer or P6R.