KMIP Server
Key Management Interoperability Protocol (KMIP) Server
The Akeyless Gateway built-in KMIP server handles the lifecycle of KMIP-managed objects.
Cryptographic objects managed by the Akeyless KMIP server are stored under the /kmip/default/
path, hence your Akeyless Gateway authentication method must have sufficient privileges, including create
, list
, delete
and read
rules, under the /kmip/default/*
path. This path can be changed during the KMIP server setup.
Note
Only users from your Gateway admins list can configure the KMIP server.
Enable a KMIP server from the Akeyless CLI
To start the Akeyless KMIP server using Akeyless CLI, run the following command:
akeyless kmip-server-setup \
--hostname <akeyless.gateway.hostname> \
--gateway-url 'https://<Your_Akeyless_GW_URL:8000>' \
--root /kmip/default
Where:
-
hostname
: Hostname of this KMIP server. -
root[=/kmip/default]
: Path to store all KMIP Objects. -
gateway-url[=http://localhost:8000]
: Akeyless Gateway URL.
You can find the complete list of settings for this command in the CLI Reference - Akeyless KMIP Server section.
Note
Make sure to replace the
hostname
field with your Akeyless Gateway hostname.
This returns the CA certificate:
A new KMIP environment was successfully created.
Please store the certificate someplace safe:
-----BEGIN CERTIFICATE-----
MIIDCTCC...jOVHG8Og==
-----END CERTIFICATE-----
Note that this will automatically create 2 items under the /kmip/default
path in Akeyless:
ca.key
(the CA certificate that was the output of the kmip-server-setup)- A PKI Cert Issuer named server
KMIP client configuration
- In this guide, we will use MongoDB Enterprise as a KMIP Client.
Note
Activate Keys - Akeyless supports an optional setting to enable keys upon creation automatically. To set this function by default for your client, provide the
--activate-keys-on-creation=true
setting as part of your client creation command.
Create a KMIP client from the Akeyless CLI
akeyless kmip-create-client \
--name mongodb \
--gateway-url 'https://<Your_Akeyless_GW_URL:8000>' \
--output-file-folder /current/working/dir
Where:
-
name
: A unique name of the KMIP client. The name can include the path to the virtual folder where you want to create the new client, using slash/
separators. If the folder does not exist, it will be created together with the client. -
gateway-url[=http://localhost:8000]
: Akeyless Gateway Configuration Manager URL (port8000
).
You can find the complete list of settings for this command in the CLI Reference - Akeyless KMIP Server section.
output-file-folder
: Folder path to save client certificate files locally (for example,.
for current working dir).
Two files are created:<client-name>.key
and<client-name>.cert
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-----
Note
Save the received certificate and key in a safe place. They will be used to set up the connection.
Key and certificate will not be shown anymore, but you will still be able to retrieve the ID of every KMIP client:
akeyless kmip-list-clients --gateway-url 'https://<Your-Akeyless-Gateway-URL:8000>'
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 'https://<Your-Akeyless-Gateway-URL:8000>' \
--client-id kc-5BL...7yVP \
--path "/*" \
--capability CREATE \
--capability GET
Where:
-
path
: The path in the Akeyless KMIP server folder, where your client objects will be stored. -
capability
: The capabilities of your KMIP client.(DENY, CREATE, REGISTER, REKEY, LOCATE, GET, GET_ATTRIBUTES, ACTIVATE, REVOKE, DESTROY
). -
name
: KMIP client name (either name or ID is required). -
client-id
: KMIP client ID (either name or ID is required). -
gateway-url[=http://localhost:8000]
: Akeyless Gateway Configuration Manager URL (port8000
).
This command grants our MongoDB KMIP client the ability to create and retrieve objects under the /kmip/default/
path.
You can find the complete list of settings for this command in the CLI Reference - Akeyless KMIP Server section.
Note
Please note that these roles and permissions are only valid for the selected KMIP Server, not for all Akeyless functions.
MongoDB Encryption configuration
MongoDB Enterprise supports integration with KMIP Servers. To set up MongoDB integration with the Akeyless KMIP server, the following settings need to be provided (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 the KMIP Server. -
kmipServerCAFile
is the file that contains the KMIP CA Certificate received earlier
(can be retrieved using theakeyless kmip-describe-server
command). -
kmipClientCertificateFile
is the file with both private key and certificate that were created during thekmip-create-client
step. Simplycat 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 it as a value of the kmipKeyIdentifier
parameter. 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.
Create a KMIP server using the Akeyless Console
-
Log in to the Akeyless Console and navigate to Data Protection > New.
-
Define KMIP server settings as follows:
-
Gateway: Select the Gateway where you will set up your KMIP server.
-
Custom hostname: Select this checkbox if you want to provide an alternative hostname for the KMIP server.
-
Hostname: Provide the hostname for the KMIP server. By default, use the hostname of the selected Gateway.
-
Location: Specify the path to the Akeyless folder where you want to create the new KMIP server objects, using the slash
/
separators. If the folder does not exist, it will be created together with the server. -
Certificate TTL: Specify the TTL of the KMIP Server certificate (in days).
- Click Setup to save the changes.
Create a KMIP client using the Akeyless Console
-
Click on your KMIP Server > Clients > New Client.
-
Define the KMIP client settings as follows:
-
Name: Define the name of the KMIP client.
-
Certificate TTL: Specify the TTL of the Client certificate (in days).
-
Restrict to the following path: Provide a path where this client will store all its objects. Default value is /KMIP/data.
-
Allow the following actions: Select all the actions that are allowed to this client on the relevant path.
-
Click Setup to save the changes.
-
Save the private key and certificate of the client to set up the connection with your KMIP Client system.
Updated 6 months ago