HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Vault
Vault Home

KMIP secrets engine

Enterprise

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 the Vault active server, or any of the Vault performance standby 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:

  • Baseline Server

    • 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).

  • Basic Cryptographic Server

    • 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.

  • Advanced Cryptographic Server

    • 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 supported).

Refer to KMIP - Profiles Support page for more details.

Setup

The KMIP secrets engine must be configured before it can start accepting KMIP requests.

  1. Enable the KMIP secrets engine

    $ vault secrets enable kmip
Success! Enabled the kmip secrets engine at: kmip/

  2. Configure the secrets engine with the desired listener addresses to use and TLS parameters, or leave unwritten to use default values

    $ vault write kmip/config listen_addrs=0.0.0.0:5696

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.

  1. Create a scope:

    $ vault write -f kmip/scope/my-service
Success! Data written to: kmip/scope/my-service

  2. Create a role within the scope, specifying the set of operations to allow or deny.

    $ vault write kmip/scope/my-service/role/admin operation_all=true
  Success! Data written to: kmip/scope/my-service/role/admin

Supported KMIP operations

The KMIP secrets engine currently supports the following set of operations:

operation_activate
operation_add_attribute
operation_create
operation_create_keypair
operation_decrypt
operation_delete_attribute
operation_destroy
operation_discover_versions
operation_encrypt
operation_get
operation_get_attribute_list
operation_get_attributes
operation_import
operation_locate
operation_mac
operation_mac_verify
operation_modify_attribute
operation_query
operation_register
operation_rekey
operation_rekey_keypair
operation_revoke
operation_sign
operation_signature_verify
operation_rng_seed
operation_rng_retrieve

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:

operation_all
operation_none

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.

  1. Generate a client certificate. This returns the CA Chain, the certificate, and the private key.

    $ vault write -f kmip/scope/my-service/role/admin/credential/generate
  Key              Value
  ---              -----
  ca_chain         [-----BEGIN CERTIFICATE-----
  MIICNTCCAZigAwIBAgIUKqNFb3Zy+8ypIhTDs/2/8f/xEI8wCgYIKoZIzj0EAwIw
  HTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE4MjQyN1oX
  DTI5MDYyMTE4MjQ1N1owKjEoMCYGA1UEAxMfdmF1bHQta21pcC1kZWZhdWx0LWlu
  dGVybWVkaWF0ZTCBmzAQBgcqhkjOPQIBBgUrgQQAIwOBhgAEAbniGNXHOiPvSb0I
  fbc1B9QkOmdT2Ecx2WaQPLISplmO0Jm0u0z11CGuf3Igby7unnCNvCuCXrKJFCsQ
  8JGhwknNAG3eesSZxG4tklA6FMZjE9ETUtYfjH7Z4vuJSw/fxOeey7fhrqAzhV3P
  GRkvA9EQUHJOeV4rEpiINP/fneHNfsn1o2YwZDAOBgNVHQ8BAf8EBAMCAQYwEgYD
  VR0TAQH/BAgwBgEB/wIBCTAdBgNVHQ4EFgQUR0o0v4rPiBU9RwQfEUucx3JwbPAw
  HwYDVR0jBBgwFoAUMhORultSN+ABogxQdkt7KChD0wQwCgYIKoZIzj0EAwIDgYoA
  MIGGAkF1IvkIaXNkVfe+q0V78CnX0XIJuvmPpgjN8AQzqLci8txikd9gF1zt8fFQ
  gIKERm2QPrshSV9srHDB0YnThRKuiQJBNcDjCfYOzqKlBHifT4WT4OX1U6nP/Y2b
  imGaLJK9VIwfcJOpVCFGp7Xi8QGV6rJIFiQAqzqCy69vcU6nVMsvens=
  -----END CERTIFICATE----- -----BEGIN CERTIFICATE-----
  MIICKjCCAYugAwIBAgIUerDfApmkq0VYychkhlxEnBlIDUcwCgYIKoZIzj0EAwIw
  HTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE4MjQyNloX
  DTI5MDYyMTE4MjQ1NlowHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MIGb
  MBAGByqGSM49AgEGBSuBBAAjA4GGAAQBA466Axrrz+HWanNe35gPVvB7OE7TWZcc
  QZw1QSMQ+QIQMu5NcdfvZfh68exhe1FiJezKB+zeoJWp1Q/kqhyh7fsAFUuIcJDO
  okZYPTmjPh3h5IZLPg5r7Pw1j99rLHhc/EXF9wYVy2UeH/2IqGJ+cncmVgqczlG8
  m36g9OXd6hkofhCjZjBkMA4GA1UdDwEB/wQEAwIBBjASBgNVHRMBAf8ECDAGAQH/
  AgEKMB0GA1UdDgQWBBQyE5G6W1I34AGiDFB2S3soKEPTBDAfBgNVHSMEGDAWgBQy
  E5G6W1I34AGiDFB2S3soKEPTBDAKBggqhkjOPQQDAgOBjAAwgYgCQgGtPVCtgDc1
  0SrTsVpEtUMYQKbOWnTKNHZ9h5jSna8n9aY+70Ai3U57q3FL95iIhZRW79PRpp65
  d6tWqY51o2hHpwJCAK+eE7xpdnqh5H8TqAXKVuSoC0WEsovYCD03c8Ih3jWcZn6N
  kbz2kXPcAk+dE6ncnwhwqNQgsJQGgQzJroH+Zzvb
  -----END CERTIFICATE-----]
  certificate      -----BEGIN CERTIFICATE-----
  MIICOzCCAZygAwIBAgIUN5V7bLAGu8QIUFxlIugg8fBb+eYwCgYIKoZIzj0EAwIw
  KjEoMCYGA1UEAxMfdmF1bHQta21pcC1kZWZhdWx0LWludGVybWVkaWF0ZTAeFw0x
  OTA2MjQxODQ3MTdaFw0xOTA2MjUxODQ3NDdaMCAxDjAMBgNVBAsTBWNqVVNJMQ4w
  DAYDVQQDEwVkdjRZbTCBmzAQBgcqhkjOPQIBBgUrgQQAIwOBhgAEANVsHV8CHYpW
  CBKbYVEx/sLphk67SdWxbII4Sc9Rj1KymApD4gPmS+rw0FDMZGFbn1sAfpqMBqMj
  ylv72o9izbYSALHnYT+AaE0NFn4eGWZ2G0p56cVmfXm3ZI959E+3gvZK6X5Jnzm4
  FKXTDKGA4pocYec/rnYJ5X8sbAJKHvk1OeO+o2cwZTAOBgNVHQ8BAf8EBAMCA6gw
  EwYDVR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0OBBYEFBEIsBo3HiBIg2l2psaQoYkT
  D1RNMB8GA1UdIwQYMBaAFEdKNL+Kz4gVPUcEHxFLnMdycGzwMAoGCCqGSM49BAMC
  A4GMADCBiAJCAc8DV23DJsHV4fdmbmssu0eDIgNH+PrRKdYgqiHptbuVjF2qbILp
  Z34dJRVN+R9B+RprZXkYiv7gJ/47KSUKzRZpAkIByMjZqLtcypamJM/t+/O1BSst
  CWcblb45FIxAmO4hE00Q5wnwXNxNnDHXWiuGdSNmIBjpb9nM5wehQlbkx7HzvPk=
  -----END CERTIFICATE-----
  private_key      -----BEGIN EC PRIVATE KEY-----
  MIHcAgEBBEIB9Nn7M28VUVW6g5IlOTS3bHIZYM/zqVy+PvYQxn2lFbg1YrQzfd7h
  sdtCjet0lc7pvtoOwd1dFiATOGg98OVN7MegBwYFK4EEACOhgYkDgYYABADVbB1f
  Ah2KVggSm2FRMf7C6YZOu0nVsWyCOEnPUY9SspgKQ+ID5kvq8NBQzGRhW59bAH6a
  jAajI8pb+9qPYs22EgCx52E/gGhNDRZ+HhlmdhtKeenFZn15t2SPefRPt4L2Sul+
  SZ85uBSl0wyhgOKaHGHnP652CeV/LGwCSh75NTnjvg==
  -----END EC PRIVATE KEY-----
  serial_number    317328055225536560033788492808123425026102524390

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.

  1. 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.

  2. Sign the client certificate. This returns the CA Chain and the certificate, but not the private key, which never leaves the KMIP client.

    $ vault write kmip/scope/my-service/role/admin/credential/sign csr="$(cat my-csr.pem)"
  Key              Value
  ---              -----
  ca_chain         [-----BEGIN CERTIFICATE-----
  MIICNTCCAZigAwIBAgIUKqNFb3Zy+8ypIhTDs/2/8f/xEI8wCgYIKoZIzj0EAwIw
  HTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE4MjQyN1oX
  DTI5MDYyMTE4MjQ1N1owKjEoMCYGA1UEAxMfdmF1bHQta21pcC1kZWZhdWx0LWlu
  dGVybWVkaWF0ZTCBmzAQBgcqhkjOPQIBBgUrgQQAIwOBhgAEAbniGNXHOiPvSb0I
  fbc1B9QkOmdT2Ecx2WaQPLISplmO0Jm0u0z11CGuf3Igby7unnCNvCuCXrKJFCsQ
  8JGhwknNAG3eesSZxG4tklA6FMZjE9ETUtYfjH7Z4vuJSw/fxOeey7fhrqAzhV3P
  GRkvA9EQUHJOeV4rEpiINP/fneHNfsn1o2YwZDAOBgNVHQ8BAf8EBAMCAQYwEgYD
  VR0TAQH/BAgwBgEB/wIBCTAdBgNVHQ4EFgQUR0o0v4rPiBU9RwQfEUucx3JwbPAw
  HwYDVR0jBBgwFoAUMhORultSN+ABogxQdkt7KChD0wQwCgYIKoZIzj0EAwIDgYoA
  MIGGAkF1IvkIaXNkVfe+q0V78CnX0XIJuvmPpgjN8AQzqLci8txikd9gF1zt8fFQ
  gIKERm2QPrshSV9srHDB0YnThRKuiQJBNcDjCfYOzqKlBHifT4WT4OX1U6nP/Y2b
  imGaLJK9VIwfcJOpVCFGp7Xi8QGV6rJIFiQAqzqCy69vcU6nVMsvens=
  -----END CERTIFICATE----- -----BEGIN CERTIFICATE-----
  MIICKjCCAYugAwIBAgIUerDfApmkq0VYychkhlxEnBlIDUcwCgYIKoZIzj0EAwIw
  HTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE4MjQyNloX
  DTI5MDYyMTE4MjQ1NlowHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MIGb
  MBAGByqGSM49AgEGBSuBBAAjA4GGAAQBA466Axrrz+HWanNe35gPVvB7OE7TWZcc
  QZw1QSMQ+QIQMu5NcdfvZfh68exhe1FiJezKB+zeoJWp1Q/kqhyh7fsAFUuIcJDO
  okZYPTmjPh3h5IZLPg5r7Pw1j99rLHhc/EXF9wYVy2UeH/2IqGJ+cncmVgqczlG8
  m36g9OXd6hkofhCjZjBkMA4GA1UdDwEB/wQEAwIBBjASBgNVHRMBAf8ECDAGAQH/
  AgEKMB0GA1UdDgQWBBQyE5G6W1I34AGiDFB2S3soKEPTBDAfBgNVHSMEGDAWgBQy
  E5G6W1I34AGiDFB2S3soKEPTBDAKBggqhkjOPQQDAgOBjAAwgYgCQgGtPVCtgDc1
  0SrTsVpEtUMYQKbOWnTKNHZ9h5jSna8n9aY+70Ai3U57q3FL95iIhZRW79PRpp65
  d6tWqY51o2hHpwJCAK+eE7xpdnqh5H8TqAXKVuSoC0WEsovYCD03c8Ih3jWcZn6N
  kbz2kXPcAk+dE6ncnwhwqNQgsJQGgQzJroH+Zzvb
  -----END CERTIFICATE-----]
  certificate      -----BEGIN CERTIFICATE-----
  MIICOzCCAZygAwIBAgIUN5V7bLAGu8QIUFxlIugg8fBb+eYwCgYIKoZIzj0EAwIw
  KjEoMCYGA1UEAxMfdmF1bHQta21pcC1kZWZhdWx0LWludGVybWVkaWF0ZTAeFw0x
  OTA2MjQxODQ3MTdaFw0xOTA2MjUxODQ3NDdaMCAxDjAMBgNVBAsTBWNqVVNJMQ4w
  DAYDVQQDEwVkdjRZbTCBmzAQBgcqhkjOPQIBBgUrgQQAIwOBhgAEANVsHV8CHYpW
  CBKbYVEx/sLphk67SdWxbII4Sc9Rj1KymApD4gPmS+rw0FDMZGFbn1sAfpqMBqMj
  ylv72o9izbYSALHnYT+AaE0NFn4eGWZ2G0p56cVmfXm3ZI959E+3gvZK6X5Jnzm4
  FKXTDKGA4pocYec/rnYJ5X8sbAJKHvk1OeO+o2cwZTAOBgNVHQ8BAf8EBAMCA6gw
  EwYDVR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0OBBYEFBEIsBo3HiBIg2l2psaQoYkT
  D1RNMB8GA1UdIwQYMBaAFEdKNL+Kz4gVPUcEHxFLnMdycGzwMAoGCCqGSM49BAMC
  A4GMADCBiAJCAc8DV23DJsHV4fdmbmssu0eDIgNH+PrRKdYgqiHptbuVjF2qbILp
  Z34dJRVN+R9B+RprZXkYiv7gJ/47KSUKzRZpAkIByMjZqLtcypamJM/t+/O1BSst
  CWcblb45FIxAmO4hE00Q5wnwXNxNnDHXWiuGdSNmIBjpb9nM5wehQlbkx7HzvPk=
  -----END CERTIFICATE-----
  serial_number    317328055225536560033788492808123425026102524390

Tutorial

Refer to the KMIP Secrets Engine guide for a step-by-step tutorial.

Edit this page on GitHub