Get started with KMIP4J

An open source implementation of the Key Management Interoperability Protocol (KMIP)


"Encryption provides security!" This statement is probably one of the biggest fundamental misunderstandings in the modern world of IT security. Those who have a basic knowledge of cryptography know that in addition to encryption, message integrity and authenticity of the communication partners are crucial for secure communication. But even if these concepts are combined, they are worthless if the keys used for encryption are handled carelessly. This goes from data protection to key management—the task of creating, storing, renewing, and distributing keys.

Problems KMIP solves

Some of the biggest and best-known IT companies have formed an OASIS working group to create a new protocol, the Key Management Interoperability Protocol (KMIP). A protocol can be seen as a language—it defines the order of events, the content of a message, and its coding. KMIP complies with today's requirements of communication between a key management system and its clients. For further information about KMIP, see the link to the official OASIS KMIP page in Related topics.

Today, large companies usually have various Key Lifecycle Management Systems (KLMS), each with its own communication protocol (see Figure 1, left side). KMIP takes a different approach and merges all objects and operations into a single protocol, making possible a centralized KLMS (see Figure 1, right side). Centralizing the KLMS with one protocol reduces the operating and infrastructure costs and provides a consistent enforcement of security policies. Additionally, all cryptographic objects are managed equally in the same application.

Figure 1. KLMS with and without KMIP
A chart showing two KLMS installations, both with and without KMIP
A chart showing two KLMS installations, both with and without KMIP

Some companies have been working with proprietary implementations of KMIP in different programming languages for a while, but up until now, no open source solution existed. Therefore, we decided to write and publish an open source implementation of KMIP, which should allow the protocol to proliferate in the near future.

How the implementation works

The structure of our system is based on a client-server architecture (see Figure 2). The horizontal dashed line shows the border between the KMIP library and the surrounding test environment. The implemented test environment consists of a GUI on the client side and a simplified KLMS together with the inherent adapter on the server side. The adapter enables KMIP to be adapted to any existing or new KLMS.

Figure 2. Architecture
A chart showing the KMIP architecture
A chart showing the KMIP architecture

The client GUI (see Figure 3) lets you choose and run requests of the specified use cases individually or in sequence. With an XML file, you can create any other request, such as a Create request for a symmetric key 128-bits long to be used for AES encryption. This information is forwarded to the stub as a KMIP container, filled with specified KMIP objects, attributes, and options.

Figure 3. KMIP4J Client GUI
A screenshot showing the KMIP4J Client GUI
A screenshot showing the KMIP4J Client GUI

The encoder's task is to process the information of the container and generate the Tag-Type-Length-Value–coded representation according to the KMIP specification (see Figure 4). The decoder is the encoder's counterpart; it transforms TTLV-coded responses into containers.

Figure 4. Container to Tag-Type-Length-Value (TTLV)
An image showing the Tag-Type-Length-Value (TTLV)
An image showing the Tag-Type-Length-Value (TTLV)

Several key classes implement an interface and can be replaced with other classes by changing the class path in a configuration file (StubConfig.xml or web.xml). At the next start-up, the requested class is loaded dynamically. This approach results in a very flexible software that is easy to configure. The communication layer is one example of such an exchangeable class. By default, an SSL/TLS connection is established between the client and server. For test cases, a simpler HTTP connection can be used by changing the communication layer.

On the server side, a web application server paired with a servlet is responsible for the communication and the forwarding of the message. After decoding the message, the adapter's task is to translate KMIP into a format that the KLMS understands. This function must be implemented by every user who wants to use the KMIP library with an existing KLMS. The KLMS of the implemented test environment has a four-layer architecture with an interface layer, service layer, manager layer, and data layer. However, only the operations of the use cases specified in KMIP 1.0 are supported.

The KMIP4J open source implementation

KMIP4J was implemented for the KMIP 1.0 specification. KMIP Version 1.1 was released by OASIS during the implementation and was not integrated into the work in progress. Due to the flexibility and easy expandability of the software, however, Version 1.1 could be realized with manageable effort.

The official KMIP page from OASIS (see Related topics) presents more than the specification of the protocol. Another important document found there is "KMIP V1.0 Use Cases." These use cases include request-response scenarios for typical KMIP communications. The document includes the parameters and the resulting TTLV coding for every message. All use cases have been successfully tested with a test environment. Furthermore, an interoperability test against two major KMIP implementation providers—one of them Cryptsoft—has proven the compatibility with established implementations.

The following section explains how to implement a simple KMIP client using KMIP4J.

Implementing a KMIP client

This example shows a very simple KMIP client. It uses the KMIP4J library to create a request for its KLMS. The SimpleKMIPClient's main function is to configure a Logger, create a KMIPStub, and call createKMIPRequest (see Listing 1). This function creates the KMIP objects and attributes for a "Create Key" operation and puts them into a KMIPcontainer. With this request, the KLMS is asked to create a symmetric key of 128 bits to be used for encryption and decryption (0x0C of Usage Mask) with the AES algorithm. The function call stub.processRequest(request) results in a container with the KMIP objects and attributes of the server response.

Listing 1. Simple KMIP Client
        import java.util.ArrayList;
        import org.apache.log4j.Logger;
        import org.apache.log4j.xml.DOMConfigurator;
        import ch.ntb.inf.kmip.attributes.*;
        import ch.ntb.inf.kmip.container.*;
        import ch.ntb.inf.kmip.kmipenum.*;
        import ch.ntb.inf.kmip.objects.base.*;
        import ch.ntb.inf.kmip.stub.KMIPStub;
        public class SimpleKMIPClient {
            // initialize Logger
            private static final Logger logger = Logger.getLogger(SimpleKMIPClient.class);
            public static void main(String[] args) {
                // configure Logger
                DOMConfigurator.configureAndWatch( "config/log4j-1.2.17.xml", 60*1000 );
                KMIPStub stub = new KMIPStub();
                KMIPContainer request = createKMIPRequest();
                KMIPContainer response = stub.processRequest(request);
            private static KMIPContainer createKMIPRequest() {
                // Create Container with one Batch
                KMIPContainer container = new KMIPContainer();
                KMIPBatch batch = new KMIPBatch();
                // Set Operation and Attribute
                batch.addAttribute(new ObjectType(EnumObjectType.SymmetricKey));
                // Set TemplateAttribute with Attributes 
                ArrayList<Attribute> templateAttributes = new ArrayList<Attribute>();
                templateAttributes.add(new CryptographicLength(128));
                templateAttributes.add(new CryptographicUsageMask(0x0C));
                TemplateAttributeStructure tas = new TemplateAttribute();
                return container;

When run against our own server, the SimpleKMIPClient produces the following output (see Figure 5).

Figure 5. Output
Output from the SimpleKMIPClient program
Output from the SimpleKMIPClient program

To configure the project, the kmip4j.jar library needs to be added to the build path. Additionally, the configuration files StubConfig.xml and log4j-1.2.17.xml must be appended, as shown in Figure 6. An Eclipse Project with all the necessary files can be found in Related topics.

Figure 6. Project structure
An image showing the file structure of the Eclipse Project

Furthermore, if you want to communicate with HTTPS, you need a Java keystore with a certificate. The path of the keystore must be defined in the StubConfig.xml file.

This example shows how a client can create a basic KMIP request to a KLMS, using our open source KMIP4J implementation. It will be a good starting point for most clients.


The Key Management Interoperability Protocol defines the communication between a Key Lifecycle Management System and its clients. In comparison with older systems with many incompatible protocols, a centralized KLMS paired with KMIP reduces the operating and infrastructure costs and provides a consistent enforcement of the security policies. Using KMIP is an important step toward a better organized and more consistent management of cryptographic objects.

With an open source solution on the market, vendors with limited financial resources can also join the "KMIP club."

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

ArticleTitle=Get started with KMIP4J