KMIP Server

The Akeyless Gateway built-in KMIP server provides and handles the lifecycle of KMIP managed objects.

Cryptographic objects managed by Akeyless KMIP server are stored under /kmip/default/ path, hence your Akeyless Gateway authentication method, must have sufficient access capabilities includes create, list, and read rules, under /kmip/default/* path. This path can be changed during the server setup.

👍

Note:

Only users who belong to your Gateway admins list can configure the KMIP server.

Enable the KMIP server

To start Akeyless KMIP server using Akeyless CLI:

akeyless kmip-server-setup --hostname <akeyless.gateway.hostname>  --gateway-url <Akeyless GW URL:8000> --root /kmip/default

👍

Note

Make sure to replace the hostname field with your Akeyless Gateway host name.

This returns the CA certificate:

A new KMIP environment was successfully created.
Please store the certificate someplace safe:
-----BEGIN CERTIFICATE-----
MIIDCTCC...jOVHG8Og==
-----END CERTIFICATE-----

KMIP client configuration

For the purpose of this guide, we will use MongoDB Enterprise as KMIP Client.

Create KMIP client in Akeyless

akeyless kmip-create-client --name mongodb --gateway-url <Akeyless GW URL>

This returns the client ID, key and certificate:

New client successfully created.
Client ID: Zvzw0...VM2u
Client Key:
-----BEGIN RSA PRIVATE KEY-----
MIIEpA...yRCF8UQ==
-----END RSA PRIVATE KEY-----

Client Certificate:
-----BEGIN CERTIFICATE-----
MIIDSz...0otOEQQ==
-----END CERTIFICATE-----

Save the received certificate and key in a safe place, they will be used to setup the connection.

Key and certificate will not be shown anymore, but you will still be able to retrieve the ID of every client:

akeyless kmip-list-clients --gateway-url <Akeyless GW URL>

Client access permissions

By default, KMIP clients have no permissions. To grant your KMIP client minimal access permissions, execute the following command:

akeyless kmip-client-set-rule --gateway-url <Akeyless GW URL> --client-id Zvzw0...VM2u \
  --path "/*" \
  --capability CREATE \
  --capability GET                                                                                          <<<

This command grants our mongodb KMIP client the ability to create and retrieve objects under /kmip/default/ .

MongoDB Encryption configuration

MongoDB Enterprise supports integration with KMIP Servers. To setup MongoDB integration with Akeyless KMIP Server, the following parameters need to be supplied to mongod (see the linked guide for details):

mongod --enableEncryption \
  --kmipServerName <akeyless.gateway.hostname> \
  --kmipServerCAFile /<path to>/ca.cert \
  --kmipClientCertificateFile /<path to>/mongodb.pem

Where:
--kmipServerName is the address you specified when setting up KMIP Server.
--kmipServerCAFile is the file that contains KMIP CA Certificate received earlier (can be retrieved using akeyless kmip-describe-server command).
--kmipClientCertificateFile is the file with both private key and certificate that were created during akeyless kmip-create-client step. Simply cat key-file cert-file > mongodb.pem and use the resulting file to connect.

To use an existing key for encryption, please upload the key to Akeyless as a new Classic Keys and pass this argument:

--kmipKeyIdentifier allows to use an existing encryption key, provide the Classic Key “display ID” in this argument. If not provided, MongoDB will create a new encryption key in Akeyless, and use it for encryption.

The command output shows the created KMIP key ID:

Encryption key manager initialized using KMIP key with id: feu...uoz.


What’s Next
Did this page help you?