Introduction

This JNI implementation exposes a large subset of P6R's Secure KMIP Client SDK which is implemented in C++. This JNI implementation exposes the most commonly used and asked for KMIP features. The underlying SKC KMIP implementation is full featured supporting KMIP protocol versions: 1.0, 1.1, 1.2, 1.3, and 1.4. If there is something missing from the JNI KMIP API that you need please let us know and we will be happy to add it.

This KMIP JNI implementation is easy to use and follows standard Java practices (e.g., using Exceptions instead of return error codes). We have tested this JNI implementation with a set of JUNIT tests that we have included for your use and as examples of how to use this KMIP API. We got so used to this Java API we forgot that the underlying KMIP implementation was actually in C++.

Includes

Please refer to the included javadoc for each of these classes.

P6KMIPClient.java
KMIPConstants.java
KeyPairIds.java
CryptoParams.java
DeriveParams.java
DomainParams.java
GCMData.java
SignData.java
TransparentKey.java
TransparentECPrivateKey.java
TransparentECPublicKey.java
TransparentRSAPrivateKey.java
TransparentRSAPublicKey.java
TransparentSymmetricKey.java
WrappedKey.java
X509Key.java
TransparentCertificate.java
StreamHandle.java
StructAttribute.java
p6kmipclient.jar
p6javakmip.dll 32 and 64 bit JNI implementation for Windows
libp6javakmip.so 32 and 64 bit JNI implementation for Linux
An Intellij IDEA project
22 JUNIT test cases that demonstrate how to use the JNI KMIP API
p6kmiptool which is a KMIP command line tool

Set Up

First the normal SKC library setup is required. To run the SKC library you must first create an SKC example. This places all of the P6R KMIP code into one directory which you can use for all your testing. All P6R KMIP code runs out of one, writable, directory. Once that is created copy the file libp6javakmip.so (for linux) and p6javakmip.dll into this one "run" directory. This file is the bridge between the p6kmipclient.jar Java file and the SKC library. As defined in the Java Classpath section below the full path of this run directory must also appear in the Java Classpath so that Java can find this file. Meanwhile the p6kmipclient.jar file can be placed with the rest of your java application in any directory you choose.

KMIP requires the use of both server and client side TLS credentials. Instead of adding these details to the JNI KMIP API we have taken the standard Java approach to add these to a keystore via a command line tool. Our library uses the P6R keystore (which is based on a real databases either SQLite or Postgres) and our command line tool p6kmiptool to initialize that keystore. The p6kmiptool (separate documentation in this SDK) also provides a rich feature set to access a KMIP server, which can be done by hand or via scripts. So for each KMIP server to be accessed via the JNI API its TLS credentials must first be configured by the p6kmiptool. P6R's keystore and p6kmiptool can handle any number of KMIP servers there is no limit.

So for each KMIP server you wish to access via the JNI API first add its definition to the p6kmiptool.conf file and use the p6kmiptool to install those credentials into the generated keystore. At that point you can use the p6kmiptool to make sure your TLS connection is working properly by performing a "p6kmiptool -serverinfo -server <server IP address or domain name>" command.

In addition to the TLS credentials the p6kmiptool.conf file allows other KMIP client behavior to be adjusted. For example, you can turn on the KMIP message logging when needed to see the KMIP command / response messages that match your calls to JNI API functions and to help resolve support issues. There are many different KMIP settings that can be made such as whether to use KMIP TTLV, XML, or JSON message encoding for example. In addition, there is also a configuration setting to modify TLS session behavior. All of these parameters are documented in the standard SKC documentation for the C++ KMIP SDK.

Java Classpath

P6R's native KMIP client contains several ".dll" files on Windows and ".so" files on Linux that all run out of a single "run" directory. This directory includes the p6javakmip.dll (or libp6javakmip.so) JNI implementation. For the Java code in the p6kmipclient.jar file to find and load the JNI implementation the single P6R "run" directory must be specified on the command line with "-Djava.library.path=<full path to run directory>" (see below). This is set by the calling Java application and not by the JNI implementation.

Running JUNIT examples via the command line on Linux

All the JUNIT test cases can be run on Linux (we tested on Centos 6) via the command line as follows:

* First we set up a directory to run all of this out of and created the following subdirectories
* ../javakmip/   - top level directory
*    com/p6r/kmip/ - contains all JUNIT class files, e.g., JniActivateKmip.class
*
*    lib/hamcrest-all-1.3.jar  
*       /hamcrest-core-1.3.jar  
*       /junit-4.12.jar
*
*     p6kmipclient.jar
*
* Next we set up our SKC release in the directory /home/mjoseph/skc-2017.1.XXXXX/examples/kmip/kmip-1/linux-DBG64 (or linux-OPT64 for release mode), the "XXXXX" is the build number you have of the 2017.1 release.
* Then to run any one of the JUNIT tests from the ../javakmip directory we used the following command line:
*
*    java -ea -Djava.library.path=/home/mjoseph/skc-2017.1.xxxxx/examples/kmip/kmip-1/Linux2.6_x86_DBG_64bit_gcc.OBJ -cp .:/..../javakmip/lib/hamcrest-all-1.3.jar:/.../javakmip/lib/hamcrest-core-1.3.jar:/.../javakmip/lib/junit-4.12.jar:
*          /.../javakmip/p6kmipclient.jar org.junit.runner.JUnitCore com.p6r.kmip.JniActivateKmip
*
* Notice the following about this command: (1) the current directory is in the classpath ".:/", (2) the "/.../" needs to be replaced with the full path of where the javakmip directory is installed (e.g., /home/youraccount),
* and (3) "com.p6r.kmip.JniActivateKmip" is the name of one of the JUNIT class files in the ../javakmip/com/p6r/kmip/ directory.   Of course, this also properly configuring the KMIP code in the 
* /home/mjoseph/skc-2017.1.XXXXX/examples/kmip/kmip-1/linux-DBG64 directory with the KMIP TLS, and log configuration settings (see the Section "Set Up" above).
* #endcode
*
* Here what the output when running the JniBasicKmip unit test:
* @code
*
* JUnit version 4.12
* @BeforeClass - oneTimeSetUp
* .@Before - setUp
* @Test - JNICall-basicKMIP
*
* UID of new AES key: acdea2ef-7205-43d2-940a-aa14a804b224
* Secret key, algorithm: AES, format: RAW, encoded: [B@7a4f0f29
*
* locateByTextAttribute using Name attribute found uid: acdea2ef-7205-43d2-940a-aa14a804b224
* locateByTextAttribute using Custom attribute found uid: acdea2ef-7205-43d2-940a-aa14a804b224
* Created a symmetric key with a vendor extension algorithm: a91e8386-b09d-4939-bdbd-3d314ddab941
*
* UID of new public key:  b599af68-cf66-4090-917b-32f1b2bd670e
* UID of new private key: 723f6c9d-76ee-47da-9bf6-1637df4ebff0
* RSA public key, modulus: -40171930999389216293688976723322222954385088414108370926185987032158113214798577472034610147305918472012707335432250526767343761656984088297993727730002051594499861502356662219056707033213919339604646108532452975144164495205791133322146624302161033389724577088886997196245506538345210518833892546097703123957
* public exponent: 65537
*
* RSA private key, modulus: -40171930999389216293688976723322222954385088414108370926185987032158113214798577472034610147305918472012707335432250526767343761656984088297993727730002051594499861502356662219056707033213919339604646108532452975144164495205791133322146624302161033389724577088886997196245506538345210518833892546097703123957
* private exponent: 21326105764045742912952474511559416315653982423897711688185419997638776884174012927577807317349243860745279068662354059888080892071047111286126543380527551696332210509481371145463023124252613869781437447600869733788311139400153170520844496007317021537915825370597763608393004576684246337769339091485908926977
*
* @After - tearDown
* @AfterClass - oneTimeTearDown
*
* Time: 15.41
*
* OK (1 test)
* 

JNI References

1) Rob Gordon, "Essential JNI: Java Native Interface", Prentice Hall PTR, 1998, ISBN 0-13-679895-0.

2) Java Programming Tutorial, Java Native Interface (JNI), http://www.ntu.edu.sg/home/ehchua/programming/java/JavaNativeInterface.html.

3) S.Stricker, Java programming with JNI, http://www.ibm.com/developerworks/java/tutorials/j-jni/j-jni.html.