KMIP Secrets Engine
Enterprise Only
Key Management Interoperability Protocol (KMIP) secrets engine requires Vault Enterprise Advanced Data Protection (ADP) license.
Challenge
The OASIS Key Management Interoperability Protocol (KMIP) standard is a widely adopted protocol for handling cryptographic workloads and secrets management for enterprise infrastructure such as databases, network storage, and virtual/physical servers.
When an organization has services and applications that need to perform cryptographic operations (e.g.: transparent database encryption, full disk encryption, etc.), it often delegates the key management task to an external provider via KMIP protocol. As a result, your organization may have existing services or applications that implement KMIP or use wrapper clients with libraries/drivers that implement KMIP. This makes it difficult for an organization to adopt the Vault API in place of KMIP.
Solution
Vault Enterprise v1.2 introduced KMIP secrets engine which allows Vault to act as a KMIP server for clients that retrieve cryptographic keys for encrypting data via KMIP protocol.
Vault's KMIP secrets engine manages its own listener to service KMIP requests which operate on KMIP managed objects. Vault policies do not come into play during these KMIP requests. The KMIP secrets engine determines the set of KMIP operations the clients are allowed to perform based on the roles that are applied to the TLS client certificate.
This enables the existing systems to continue using the KMIP APIs instead of Vault APIs.
Prerequisites
To perform the tasks described in this tutorial, you need to have a Vault Enterprise v1.2 or later.
A KMIP client system for testing such as:
Policy requirements
Note
For the purpose of this tutorial, you can use root token to work
with Vault. However, it is recommended that root tokens are only used for just
enough initial setup or in emergencies. As a best practice, use tokens with
appropriate set of policies based on your role in the organization.
To perform all tasks demonstrated in this tutorial, your policy must include the following permissions:
If you are not familiar with policies, complete the policies tutorial.
Step 1: Enable and configure the KMIP secrets engine
First step is to enable the kmip secrets engine at a desired path. In this
tutorial, you are going to enable the kmip secrets engine at /kmip.
Execute the following command to enable the
kmipsecrets engine atkmip/.Execute the following command to configure the
kmipserver to listen to port5696.Execute the following command to read back the
kmipsecrets engine configuration.When the KMIP engine is configured, it generates and stores a key-pair and uses it to sign a root CA which is used to sign an intermediate CA. The intermediate CA is used to sign the server TLS certificate used by the KMIP listener to identify itself during the TLS handshake.
By default, the certificate type (
default_tls_client_key_type) isec(Elliptic Curve). If you need RSA instead, specify the certificate type (tls_ca_key_type) and bits (tls_ca_key_bits) when you configure thekmipserver.Execute the following command to retrieve the generated CA certificate:
Copy and save the CA certificate as
ca.pem.
Step 2: Create scopes and roles
Scopes partition KMIP managed object storage into multiple named buckets. (NOTE: Scopes cannot be nested.)
Roles in the KMIP secrets engine determine the set of KMIP operations that KMIP clients are allowed to perform.
Execute the following command to create a new scope named, "finance".
Execute the following command to list the existing scopes.
Execute the following command to create a new role, "accounting" under the
financescope.By setting the
operation_allparameter totrue, the created role is granted to perform all KMIP client-server operations. Refer to Step 6 to learn how to modify the allowed operation list.Execute the following command to list existing roles under
financescope.Execute the following command to read the
accountingrole definition.
Step 3: Client certificate generation
Once the scope was created and a role was created under the scope, the next step is to get the certification for the KMIP client.
Note
Available certificate formats are: pem, pem_bundle, or der.
If pem_bundle was chosen, the certificate field will contain the private
key, certificate, and ca_chain, concatenated.
Execute the following command to generate a certificate in PEM format, and save it in a JSON file named,
credential.json.Extract the certificate from the
credential.jsonusingjqtool and save it in a file namedcert.pem.Extract the private key from the
credential.jsonusingjqtool and save it in a file namedkey.pem.The resulting
cert.pemandkey.pemis what your KMIP client will use to establish a connection with Vault KMIP server.Execute the following command to list the certification serial numbers associated with the
accountingrole.Copy the returned serial number (e.g.
693751915900546682090704263335075174345458639865).You can now lookup the client certificate by its serial number as shown in the example. (NOTE: Be sure to pass the
serial_numberyou discovered.)Example:
Step 4: KMIP client configuration
In Step 1, you saved the CA certificate in a file named, ca.pem.
You created a role named, "accounting" with all supported KMIP operations
allowed. Based on the role, a client certificate was generated and saved in a
file, cert.pem and its private key in key.pem in Step 3.
MongoDB Enterprise Advanced
This tutorial assumes that you already have an instance of MongoDB Enterprise Advanced running.
Use mongod daemon
process to configure the KMIP settings.
First, combine the cert.pem and key.pem and save it as client.pem.
Execute the mongod command to specify the cert & key file locations.
The command output shows the created KMIP key ID:
MySQL Enterprise Edition
This tutorial assumes that you already have an instance of MySQL Enterprise Edition running with your own license.
The keyring_okv keyring plugin uses the KMIP 1.1 protocol to communicate
securely as a client of a KMIP back end. Follow the MySQL online
documentation
to create okvclient.ora file, and an ssl directory to place the certificate
and key files for keyring_ova to work properly.
Also, install the keyring_udf plugin and the user-defined functions (UDFs) as
described in the MySQL
documentation.
Now, generate a new random key with a given ID, type, and length, and store it in the keyring.
Step 5: Revoke a client certificate
Vault make it easy to revoke the existing client certificates if necessary.
Execute the following command to revoke a client certificate by its serial
number. (NOTE: Be sure to pass the serial_number for your system.)
Example:
Verify that it no longer exists.
Step 6: Manage KMIP roles
In Step 2, the accounting role was permitted to perform all KMIP
operations (operation_all). However, you should practice the least privileged
and avoid granting more permissions than necessary.
When you grant KMIP operations, the argument convention is
operation_<KMIP_operation>. For example, to grant a Create operation, the
parameter becomes operation_create.
Note
Refer to the KMIP Secrets Engine doc for the list of supported KMIP operations.
Execute the following command to update the
accountingrole and grant onlyActivate,Create, andGetoperations.Verify the changes.
To delete the
accountingrole, execute the following command.
Step 7: Delete scopes
If you need to delete scopes, follow this step.
Execute the following command to delete scope, finance.
NOTE: Pass -f or -force flag to allow deleting a scope which has some
managed objects created with.
Additional Discussion
As it was discussed, Vault policies do not come into play during these KMIP
requests. The KMIP secrets engine determines the set of KMIP operations the
clients are allowed to perform based on the roles (accounting).
Let's take a look at the generated client certificate file.
Notice the Subject properties: Subject: OU=5J7Ck, CN=ImYFE
The OU corresponds to the scope (finance) and CN corresponds to the role
(accounting). If you have access to the Vault's storage backend, you would
find persisted data with those IDs.
For example:
You can read the allowed operations for the role using the
sys/raw endpoint if it's
enabled.
When a situation requires you to delete the client certificate, simply revoke the certificate as described in Step 5.