Get started with KMIP4J

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

The Key Management Interoperability Protocol (KMIP) defines the communication between a Key Lifecycle Management System (KLMS) and its clients. Some companies have been working with proprietary implementations of KMIP in different programming languages for a while, but until now, no open source solution existed. Hence, the creation of KMIP4J, an open source implementation of KMIP in Java™ code now available on www.sourceforge.net. This articles gives an overview of this open source implementation.

Michael Guster (michael.guster@gmail.com), Software Engineer, BSc FHO Systems Engineering

Photo of Michael GusterMichael Guster is a software engineer from Arnegg, Switzerland. He studied systems engineering at the University of Applied Sciences NTB. After beginning with basic engineering subjects, he then focused on computational engineering. He and his colleague Stefanie Meile have written and published KMIP4J, an open source implementation of KMIP.



Stefanie Meile (stefaniemeile@gmail.com), Software Engineer, BSc FHO Systems Engineering

Photo of Stefanie MeileStefanie Meile is a software engineer from St. Gallen (Switzerland). She studied systems engineering at the University of Applied Sciences NTB. After beginning with basic engineering subjects, she then focused on computational engineering. She and Michael Guster have written and published KMIP4J, an open source implementation of KMIP.



12 November 2013

eBook on managing data security and compliance

Organizations struggle to prioritize the multitude of compliance mandates and create data security policies to satisfy these requirements and protect their most sensitive data. You can download the eBook, Manage compliance and protect enterprise data, to read about the six essential steps to effectively manage compliance requirements and safeguard data within an enterprise data protection strategy.

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

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

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

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

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)

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

Downloading KMIP4J

You can download the open source implementation of the 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);
                System.out.println(response.toString());
            }
        
            private static KMIPContainer createKMIPRequest() {
                // Create Container with one Batch
                KMIPContainer container = new KMIPContainer();
                KMIPBatch batch = new KMIPBatch();
                container.addBatch(batch);
                container.calculateBatchCount();
        
                // Set Operation and Attribute
                batch.setOperation(EnumOperation.Create);
                batch.addAttribute(new ObjectType(EnumObjectType.SymmetricKey));
        
                // Set TemplateAttribute with Attributes 
                ArrayList<Attribute> templateAttributes = new ArrayList<Attribute>();
                templateAttributes.add(new 
CryptographicAlgorithm(EnumCryptographicAlgorithm.AES));
                templateAttributes.add(new CryptographicLength(128));
                templateAttributes.add(new CryptographicUsageMask(0x0C));
                TemplateAttributeStructure tas = new TemplateAttribute();
                tas.setAttributes(templateAttributes);
                batch.addTemplateAttributeStructure(tas);
            
                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

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

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.


Conclusion

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


Download

DescriptionNameSize
Sample implementation of KMIP4J clientkmip4j-client-example.zip652KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Security on developerWorks


  • Bluemix Developers Community

    Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.

  • Security

    Pragmatic, intelligent, risk-based IT Security practices.

  • DevOps Services

    Software development in the cloud. Register today to create a project.

  • IBM evaluation software

    Evaluate IBM software and solutions, and transform challenges into opportunities.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Security
ArticleID=952783
ArticleTitle=Get started with KMIP4J
publish-date=11122013