289 lines
14 KiB
Plaintext
289 lines
14 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: KMIP - Secrets Engines
|
|
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
|
|
|
|
-> **Note**: This secret engine requires [Vault Enterprise](https://www.hashicorp.com/products/vault/)
|
|
with the Advanced Data Protection 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 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:
|
|
|
|
* [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 supoorted).
|
|
|
|
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
|
|
```
|
|
|
|
## 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
|