Configure the KMIP client - Futurex Documentation

Configure the application’s KMIP client with the files from the endpoint download, then verify that CryptoHub accepts the client certificate and answers a KMIP request. Field names and import steps differ by application, so use this page with the application vendor’s KMIP or external key manager documentation.

Map the endpoint files to KMIP settings

Most KMIP applications ask for the same settings. Use these values from the endpoint download:

KMIP setting	Value
Server host	The KMIP address from `info.txt`, for example `cryptohub.example.com`
Server port	`5696`
Client certificate	`client-cert.pem`, or the certificate inside `pki.p12`
Client private key	The private key inside `pki.p12`, protected by the password in `pki-password.txt`
Server CA certificate	`ca-chain.pem`
TLS version	TLS 1.2 or TLS 1.3
Username and password	Leave empty. TLS-bundle authentication uses the client certificate.

Prepare the TLS files

Run these commands on a protected administrator host with OpenSSL 3. Replace <endpoint-zip> with the path of the downloaded ZIP.

Extract the endpoint download

Create a private working directory and extract the ZIP into it.

umask 077
mkdir kmip-endpoint
unzip <endpoint-zip> -d kmip-endpoint
cd kmip-endpoint

The directory contains pki.p12, pki-password.txt, client-cert.pem, and ca-chain.pem.

Extract the client private key

Write the unencrypted client private key to client-key.pem. The command reads the PKCS #12 password from pki-password.txt, so the password does not appear in your shell history, and openssl pkey removes the PKCS #12 bag attributes from the output.

openssl pkcs12 -in pki.p12 -passin file:pki-password.txt -nocerts -nodes | openssl pkey -out client-key.pem

OpenSSL 3 opens pki.p12 without the -legacy option.

client-key.pem begins with a -----BEGIN PRIVATE KEY----- line.

Confirm that the key matches the certificate

Compare the public-key hash of the certificate with the public-key hash of the private key.

openssl x509 -in client-cert.pem -noout -pubkey | openssl sha256
openssl pkey -in client-key.pem -pubout | openssl sha256
openssl x509 -in client-cert.pem -noout -subject -enddate

The two hashes are identical, and the certificate expiry date is in the future.

Convert to the format the application accepts

Use the files in the format that the application requires:

Separate PEM files: use client-cert.pem, client-key.pem, and ca-chain.pem.
Combined PEM file: run cat client-cert.pem client-key.pem > client-cert-and-key.pem.
PKCS #12 file: import pki.p12 directly and enter the password from pki-password.txt.

You have the client certificate, client private key, and server CA in the format that the application’s KMIP settings accept.

Transfer and protect the files

Copy only the files that the application needs to the application host over a protected channel. Make the private key readable only by the account that runs the application’s KMIP client, then delete the working directory from the administrator host.

The private key file on the application host is not readable by other accounts.

Configure the application

Open the KMIP settings

Open the application’s KMIP, external key manager, or key management server settings. Use the vendor’s documentation for the exact location.

Enter the server settings

Enter the CryptoHub KMIP host from info.txt and port 5696. Add the contents of ca-chain.pem as the trusted server CA.

Enter the client credential

Import the client certificate and private key in the format that the application accepts. Leave any KMIP username and password fields empty.

Save and test

Save the settings and run the application’s connection or key-server test, if it has one.

The application reports a successful connection to the key server.

Verify the connection

Run two checks before you rely on the integration: TLS 1.2 client authentication, then one authenticated KMIP operation. Run them from the application host or from a host with the same network path to CryptoHub.

Check TLS 1.2 client authentication

Open a TLS 1.2 connection to the KMIP port with the endpoint client certificate.

openssl s_client -connect cryptohub.example.com:5696 -tls1_2 \
  -cert client-cert.pem -key client-key.pem -CAfile ca-chain.pem \
  -verify_return_error </dev/null

The command forces TLS 1.2 because a TLS 1.3 server can reject a client certificate after the handshake appears complete. With TLS 1.2, a rejected client certificate fails the handshake with an alert.

The output shows Verify return code: 0 (ok) and no alert line. The Acceptable client certificate CA names list includes CN=Client App TLS CA <number>, the CA whose certificate is in the endpoint download.

Run one authenticated KMIP operation

Run the application’s own key-server test, or use the PyKMIP client as a neutral KMIP client. To use PyKMIP, install it in a Python virtual environment:

python3 -m venv pykmip-venv
. pykmip-venv/bin/activate
pip install PyKMIP==0.11.0

Create pykmip.conf with the endpoint files:

[client]
host=cryptohub.example.com
port=5696
certfile=/path/to/client-cert.pem
keyfile=/path/to/client-key.pem
ca_certs=/path/to/ca-chain.pem
cert_reqs=CERT_REQUIRED
ssl_version=PROTOCOL_TLS
do_handshake_on_connect=True
suppress_ragged_eofs=True

Omit the username and password options. Without them, PyKMIP sends no KMIP credential and authenticates with the client certificate alone.Send a KMIP Locate request:

from kmip.pie.client import ProxyKmipClient

client = ProxyKmipClient(config="client", config_file="pykmip.conf")
with client:
    print(client.locate())

PyKMIP verifies the server certificate chain against ca-chain.pem. It does not compare the server certificate with the host name. With ssl_version=PROTOCOL_TLS, PyKMIP negotiates TLS 1.3 with CryptoHub.

The script prints a list of object identifiers. A new service can return an empty list, []. An error or a closed connection means the operation failed.

Check key retrieval (applications that retrieve keys)

If the application retrieves key material, confirm that it can create and retrieve a key. This PyKMIP example creates a test AES-256 key and retrieves it.

The example ends with a KMIP Destroy request for the test key only. Do not reuse its identifier for application keys.

from kmip.core import enums
from kmip.pie.client import ProxyKmipClient

client = ProxyKmipClient(config="client", config_file="pykmip.conf")
with client:
    uid = client.create(enums.CryptographicAlgorithm.AES, 256, name="kmip-connection-test")
    key = client.get(uid)
    print(uid, len(key.value) * 8)
    client.destroy(uid)

Skip this step if the application uses only server-side operations. KMIP object names must be unique: if an earlier run stopped before the Destroy request, change the name value before you run the example again.

The script prints an object identifier and 256, and completes without an error.

Find the key in CryptoHub

In the CryptoHub web interface, open Key Management and select Keys. Select the key by name and open its History tab to see which endpoint identity created or retrieved it.KMIP secret data objects appear under Classic Tools > Key Management > GO TO SECRETS.

The key’s History tab lists the endpoint identity name under Username(s).

Troubleshooting

Symptom	Cause and resolution
The TLS 1.2 check fails with `alert unknown ca`, `alert certificate unknown`, or `alert handshake failure`	CryptoHub did not accept the client certificate. Use `client-cert.pem` and the key from the same endpoint download, and confirm that the endpoint still exists in the service. If the files are lost or expired, create a new endpoint.
`Verify return code` is not `0 (ok)`, or the application reports an untrusted server certificate	The client does not trust the KMIP server certificate. Use `ca-chain.pem` from the endpoint download as the server CA.
The connection times out or is refused	A firewall, proxy, or TLS inspection device blocks TCP 5696. Allow TCP 5696 from the application host to CryptoHub and exempt it from TLS inspection.
An operation fails as unsupported	The CryptoHub KMIP server does not implement that operation or attribute. Record the operation name and contact Futurex support.

​Map the endpoint files to KMIP settings

​Prepare the TLS files

​Configure the application

​Verify the connection

​Troubleshooting

Map the endpoint files to KMIP settings

Prepare the TLS files

Configure the application

Verify the connection

Troubleshooting