Introduction

We recommend building and running the KMIP examples as the first step to get familiar with the SKC Toolkit. The examples are easy to build and makefiles (solution files on windows) are provided. A little bit of preparation and configuration will be required to successfully run them.

Verifying Your Environment

The SKC Toolkit has a couple of prerequisites that must be satisfied in order to run.

• OpenSSL version 1.0.x or 1.1.x must be installed on your system. SKC will not work pre-1.x.x versions (eg. 0.9.8).
• Your system must have enough available entropy. Especially a problem on Linux VMs.
• Dependent packages must be installed (openssl, postgresql).

For Linux systems, we have provided a script that will check you system for the prerequisites and let you know if something is not there. On Windows you will need to get/install openssl, however entropy is usually not an issue on windows system.The scripts can be found in:

/scripts/install

Choose the script appropriate for your operating system and run it to determine if any issues are found.

Installing Dependencies

As of the 2022 release, SKC no longer ships with dependencies included and instead uses the native OS packages on non-Windows platforms. This makes it easier for customer to stay up to date with security patches for their OS.  The required dependencies are:

• OpenSSL (should already be installed. See "Common Issues" ensure proper links exist.)
• Postgresql Client
• zlib

On RHEL/Centos you would install these packages like this:

yum install -y postgresql zlib

On Debian/Ubuntu systems:

apt-get install -y postgresql-client zlib1g

Common Issues

OpenSSL is installed but the appropriate link is missing.

In this case, the fix is simple. Just create the link manually. 

For OpenSSL 1.0.x versions you need to create links to:

libssl.so.1.0.0
libcrypto.so.1.0.0


For OpenSSL 1.1.x versions you need to create links to:

libssl.so.1.1
libcrypto.so.1.1

For example, on a Centos box using OpenSSL 1.0.x:

[root /usr/lib64 ] $ ln -s libssl.so.1.0.1e libssl.so.1.0.0
[root /usr/lib64 ] $ ln -s libcrypto.so.1.0.1e libcrypto.so.1.0.0

The wrong version of OpenSSL is installed or OpenSSL is not installed.

Linux
You will need to either install a 1.x.x version of OpenSSL using your operating system's package manager (apt, yum etc.), or download and build a compatible version from source yourself.

Windows
Download either pre-built OpenSSL binaries, or build from source. The standard set of OpenSSL files need to be copied into the directory that the example is running out of. For example:

examples/kmip/kmip-1/x64/Debug

or the location of the OpenSSL DLLs need to be added to the path so the Windows loader can find them.

On any platform, always make sure that the bitness of OpenSSL you are using matches the bitness of your project. Based on how the examples are compiled 64bit or 32bit, you will need the matching OpenSSL DLLs available.

There is not enough entropy available.

Entropy is required to create cryptographic keys. We have noticed that many Linux based systems have insufficient entropy to generate keys without significantly effecting system performance. We strongly recommend that our customers add either hardware random number generator or software that gathers entropy (e.g., egd -- entropy gathering daemon, or haveged -- A simple entropy daemon ) to their machines that will be required to create crypto keys. The haveged daemon is available as an installable package on RHEL/Centos/Ubuntu distributions.

Along with the SDK we have included several source code projects that help demonstrate how to use P6R's KMIP API. Each of these examples is designed to stand on its own. Each example creates its own keystore to securely place keys and certificates required to communicate to a KMIP server. And each keystore requires keys to encrypt and sign the data stored in it.

However, your application would normally create the keystore and its required keys only once. In addition, the keys for the keystore could be created on a special, high-entropy machine and then copied onto a separate deployed hardware. However, SSL connections also require entropy and perfoemance issues when making SSL connections will result when there is not enough entropy.

Building the examples

Several modifications are required to make this example run on your machine:

1. In the file ex-kmip-X.cpp (where 'X' is replace with a number like 1, 2, 3), in the function CKmipExample1::initialize(), replace the host name of "fqdn.com" to the fully qualified domain name of the KMIP server you wish to connect to.
   
   
2. (Optional) In the file ex-kmip-X.cpp, the function CKmipExample1::createKeystore(), replace the first parameter of the call to openSigned(). The first parameter of openSigned() is the file path where to create and access keystore databases. If NULL, then the keystore location will default to the P6R database directory. If SKC is installed in a read-only directory then the first parameter will need to be set to an existing read/write directory. Note that the keystore is used to hold the KMIP server certificates so that an SSL connection can be made.
   
   
3. Replace the contents of the files: ClientCert.pem, ClientPrivate.pem, and RootCert.pem. These files are required to make an SSL connection to a KMIP server.
   • RootCert.pem is the certificate for the server you wish to connect to.
   • ClientCert.pem is the client's certificate generated by the KMIP server.
   • ClientPrivate.pem is the client's private key generated by the KMIP server.
   Replace each file with certificate/private key given to you by the KMIP server administrator.
   
   
4. In the file:
   
   //confs/p6kmip.conf
   under the section "[p6kmip-gen]" change the "logDir" configuration parameter to an existing, writeable directory path. Use the proper path for the system you are on (Linux or Windows). For eample:
   
   logDir = "E:\work\current\WINNT6.1_x86_DBG_32bit.OBJ\logs" Or
   
   logDir = "/var/logs/kmip" Note, that this top level log directory must already exist. The SDK will create all needed directories under it.

Build an example

Makefiles for Linux and solution files for Windows are provided in each example directory. You should spend a little time and become familiar with the contents of these. Understanding what they do will help you create your own SKC projects. Below is an example of building the KMIP-1 example on Linux in 64bit debug mode. You can use the command "gmake -f Makefile.linux help" to see options.

[user@host kmip-1]$ gmake -f Makefile.linux BUILD_MODE=DBG64
ex-kmip-1.cpp
@g++ -c -Wall -Wno-non-virtual-dtor -g -DP6_LINUX=1 -m64 -DBITNESS=64 -I ../../../linux/Linux2.6_x86_DBG_64bit_gcc.OBJ/include -I../../common -o linux-DBG64/ex-kmip-1.o ex-kmip-1.cpp
../../common/p6api.cpp
../../common/cconsolestream.cpp
Linking linux-DBG64/ex-kmip-1 ...
Copying SKC components to output directory ...
[user@host kmip-1]$

Next you will need to copy your SSL credentials (as discussed above) and license file into the output directory. "linux-DBG64" in the above example. You should then be able to run the example.