KMIP secrets engine
Appropriate Vault Enterprise license or HCP Vault Dedicated cluster required.
KMIP secrets engine requires Vault Enterprise with the Advanced Data Protection (ADP) module.
The KMIP secrets engine allows Vault to act as a Key Management Interoperability Protocol (KMIP) server provider and handle the lifecycle of its KMIP managed objects. KMIP is a standardized protocol that allows services and applications to perform cryptographic operations without having to manage cryptographic material, otherwise known as managed objects, by delegating its storage and lifecycle to a key management server.
Vault's KMIP secrets engine listens on a separate port from the standard Vault listener. Each Vault server in a Vault cluster configured with a KMIP secrets engine uses the same listener configuration. The KMIP listener defaults to port 5696 and is configurable to alternative ports, for example, if there are multiple KMIP secrets engine mounts configured. KMIP clients connect and authenticate to this KMIP secrets engine listener port using generated TLS certificates. KMIP clients may connect directly to any of the Vault servers on the configured KMIP port. A layer 4 tcp load balancer may be used in front of the Vault server's KMIP ports. The load balancer should support long-lived connections and it may use a round robin routing algorithm as Vault servers will forward to the primary Vault server, if necessary.
KMIP conformance
Vault implements version 1.4 of the following Key Management Interoperability Protocol Profiles:
- Supports all profile attributes except for Key Value Location.
- Supports all profile operations except for Check.
- Operation Locate supports all profile attributes except for Key Value Location.
Symmetric Key Lifecycle Server
- Supports cryptographic algorithm AES (3DES is not supported).
- Only the Raw key format type is supported. (Transparent Symmetric Key is not supported).
- Supports block cipher modes CBC, CFB, CTR, ECB, GCM, and OFB.
- On multi-part (streaming) operations, block cipher mode GCM is not supported.
- The supported padding methods are None and PKCS5.
Asymmetric Key Lifecycle Server
- Supports Public Key and Private Key objects.
- Supports RSA cryptographic algorithm
- Supports PKCS#1, PKCS#8, X.509, Transparent RSA Public Key and Transparent RSA Private Key key format types.
- Supports Encrypt, Decrypt, Sign, Signature Verify, MAC, MAC Verify, RNG Retrieve, and RNG Seed client-to-server operations.
- The supported hashing algorithms for Sign and Signature Verify operations are SHA224, SHA256, SHA384, SHA512, RIPEMD160, SHA512_224, SHA512_256, SHA3_224, SHA3_256, SHA3_384, and SHA3_512 for PSS padding method, and algorithms SHA224, SHA256, SHA384, SHA512, and RIPEMD160 for PKCS1v15 padding method.
- The supported hashing algorithms for MAC and MAC Verify operations are SHA224, SHA256, SHA384, SHA512, RIPEMD160, SHA512_224, SHA512_256, SHA3_224, SHA3_256, SHA3_384, and SHA3_512 (MD4, MD5, and SHA1 are not supoorted).
Refer to KMIP - Profiles Support page for more details.
Setup
The KMIP secrets engine must be configured before it can start accepting KMIP requests.
Enable the KMIP secrets engine
Configure the secrets engine with the desired listener addresses to use and TLS parameters, or leave unwritten to use default values
KMIP Certificate Authority for Client Certificates
When the KMIP Secrets Engine is initially configured, Vault generates a KMIP Certificate Authority (CA) whose only purpose is to authenticate KMIP client certificates.
Vault uses the internal KMIP CA to generate certificates for clients authenticating to Vault with the KMIP protocol. You cannot import external KMIP authorities. All KMIP authentication must use the internally-generated KMIP CA.
Usage
Scopes and roles
The KMIP secrets engine uses the concept of scopes to partition KMIP managed object storage into multiple named buckets. Within a scope, roles can be created which dictate the set of allowed operations that the particular role can perform. TLS client certificates can be generated for a role, which services and applications can then use when sending KMIP requests against Vault's KMIP secret engine.
In order to generate client certificates for KMIP clients to interact with Vault's KMIP server, we must first create a scope and role and specify the desired set of allowed operations for it.
Create a scope:
Create a role within the scope, specifying the set of operations to allow or deny.
Supported KMIP operations
The KMIP secrets engine currently supports the following set of operations:
Additionally, there are two pseudo-operations that can be used to allow or deny all operation capabilities to a role. These operations are mutually exclusive to all other operations. That is, if it's provided during role creation or update, no other operations can be provided. Similarly, if an existing role contains a pseudo-operation, and it is then updated with a set supported operation, it will be overwritten with the newly set of provided operations.
Pseudo-operations:
Client certificate generation
Once a scope and role has been created, client certificates can be generated for that role. The client certificate can then be provided to applications and services that support KMIP to establish communication with Vault's KMIP server. Scope and role identifiers are embedded in the certificate, which will be used when evaluating permissions during a KMIP request.
Generate a client certificate. This returns the CA Chain, the certificate, and the private key.
Client certificate signing
As an alternative to the above section on generating client certificates, the KMIP secrets engine supports signing of Certificate Signing Requests (CSRs). Normally the above generation process is simpler, but some KMIP clients prefer (or only support) retaining the private key associated with their client certificate.
In this workflow the first step is KMIP-client dependent: use the KMIP client's UI or CLI to create a client certificate CSR in PEM format.
Sign the client certificate. This returns the CA Chain and the certificate, but not the private key, which never leaves the KMIP client.
Tutorial
Refer to the KMIP Secrets Engine guide for a step-by-step tutorial.