mirror of
https://github.com/optim-enterprises-bv/vault.git
synced 2025-10-30 02:02:43 +00:00
f975259267
* Update the title & description for SEO improvement * Minor updates for style consistency * Revert back the change * Update website/content/docs/secrets/aws.mdx Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> --------- Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>
311 lines
15 KiB
Plaintext
311 lines
15 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: KMIP secrets engine
|
|
description: >-
|
|
The KMIP secrets engine allows Vault to act as a KMIP server provider and
|
|
handle the lifecycle of its KMIP managed objects.
|
|
---
|
|
|
|
# KMIP secrets engine
|
|
|
|
@include 'alerts/enterprise-and-hcp.mdx'
|
|
|
|
KMIP secrets engine requires [Vault Enterprise](https://www.hashicorp.com/products/vault/pricing)
|
|
with the Advanced Data Protection (ADP) module.
|
|
|
|
The KMIP secrets engine allows Vault to act as a [Key Management
|
|
Interoperability Protocol][kmip-spec] (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][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][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][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][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][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](/vault/docs/secrets/kmip-profiles) page for more details.
|
|
|
|
[baseline-server]: http://docs.oasis-open.org/kmip/profiles/v1.4/os/kmip-profiles-v1.4-os.html#_Toc491431430
|
|
[lifecycle-server]: http://docs.oasis-open.org/kmip/profiles/v1.4/os/kmip-profiles-v1.4-os.html#_Toc491431487
|
|
[basic-cryptographic-server]: http://docs.oasis-open.org/kmip/profiles/v1.4/os/kmip-profiles-v1.4-os.html#_Toc491431527
|
|
[asymmetric-key-lifecycle-server]: http://docs.oasis-open.org/kmip/profiles/v1.4/os/kmip-profiles-v1.4-os.html#_Toc491431516
|
|
[advanced-cryptographic-server]: http://docs.oasis-open.org/kmip/profiles/v1.4/os/kmip-profiles-v1.4-os.html#_Toc491431528
|
|
|
|
## Setup
|
|
|
|
The KMIP secrets engine must be configured before it can start accepting KMIP
|
|
requests.
|
|
|
|
1. Enable the KMIP secrets engine
|
|
|
|
```text
|
|
$ vault secrets enable kmip
|
|
Success! Enabled the kmip secrets engine at: kmip/
|
|
```
|
|
|
|
1. Configure the secrets engine with the desired listener addresses to use and
|
|
TLS parameters, or leave unwritten to use default values
|
|
|
|
```text
|
|
$ 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:
|
|
|
|
```text
|
|
$ vault write -f kmip/scope/my-service
|
|
Success! Data written to: kmip/scope/my-service
|
|
```
|
|
|
|
1. Create a role within the scope, specifying the set of operations to allow or
|
|
deny.
|
|
|
|
```text
|
|
$ 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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.
|
|
|
|
```text
|
|
$ 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.
|
|
|
|
```text
|
|
$ 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](/vault/tutorials/adp/kmip-engine)
|
|
guide for a step-by-step tutorial.
|
|
|
|
[kmip-spec]: http://docs.oasis-open.org/kmip/spec/v1.4/kmip-spec-v1.4.html
|
|
[kmip-ops]: http://docs.oasis-open.org/kmip/spec/v1.4/os/kmip-spec-v1.4-os.html#_Toc490660840
|