1---
2layout: "docs"
3page_title: "KMIP - Secrets Engines"
4sidebar_title: "KMIP <sup>ENTERPRISE</sup>"
5sidebar_current: "docs-secrets-kmip"
6description: |-
7  The KMIP secrets engine allows Vault to act as a KMIP server provider and
8  handle the lifecycle of it KMIP managed objects.
9---
10
11# KMIP Secrets Engine
12
13The KMIP secrets engine allows Vault to act as a KMIP server provider and handle
14the lifecycle of it KMIP managed objects. KMIP, which stands for [Key Management
15Interoperability Protocol](#kmip-spec), is a standardized protocol that allows
16services and applications to perform cryptographic operations without having to
17manage cryptographic material, otherwise known as manage objects, by delegating
18its storage and lifecycle to a key management server.
19
20## Setup
21
22The KMIP secrets engine must be configured before it can start accepting KMIP
23requests.
24
251. Enable the KMIP secrets engine
26
27    ```text
28    $ vault secrets enable kmip
29    Success! Enabled the kmip secrets engine at: kmip/
30    ```
31
321. Configure the secrets engine with the desired listener addresses to use and
33TLS parameters, or leave unwritten to use default values
34
35    ```text
36    $ vault write kmip/config listen_addrs=0.0.0.0:5696
37    ```
38
39## Usage
40
41### Scopes and Roles
42
43The KMIP secrets engine uses the concept of scopes to partition KMIP managed
44object storage into multiple named buckets. Within a scope, roles can be created
45which dictates the set of allowed operations that the particular role can perform.
46TLS client certificates can be generated for a role, which services and applications
47can then use when sending KMIP requests against Vault's KMIP secret engine.
48
49In order to generate client certificates for KMIP clients to interact with Vault's
50KMIP server, we must first create a scope and role and specify the desired set of
51allowed operations for it.
52
531. Create a scope:
54
55    ```text
56    $ vault write -f kmip/scope/my-service
57    Success! Data written to: kmip/scope/my-service
58    ```
59
601. Create a role within the scope, specifying the set of operations to allow or
61deny.
62
63    ```text
64    $ vault write kmip/scope/my-service/role/admin operation_all=true
65      Success! Data written to: kmip/scope/my-service/role/admin
66    ```
67
68### Client Certificate Generation
69
70Once a scope and role has been created, client certificates can be generated for
71that role. The client certificate then can be provided to applications and
72services that supports KMIP to establish communication with Vault's KMIP server.
73The certificate contains scope and role identifiers embedded in the certificate,
74which will be used when evaluating permissions during a KMIP request.
75
761. Generate a client certificate. This returns the CA Chain, the certificate,
77and the private key.
78
79    ```text
80    $ vault write -f kmip/scope/my-service/role/admin/credential/generate
81      Key              Value
82      ---              -----
83      ca_chain         [-----BEGIN CERTIFICATE-----
84      MIICNTCCAZigAwIBAgIUKqNFb3Zy+8ypIhTDs/2/8f/xEI8wCgYIKoZIzj0EAwIw
85      HTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE4MjQyN1oX
86      DTI5MDYyMTE4MjQ1N1owKjEoMCYGA1UEAxMfdmF1bHQta21pcC1kZWZhdWx0LWlu
87      dGVybWVkaWF0ZTCBmzAQBgcqhkjOPQIBBgUrgQQAIwOBhgAEAbniGNXHOiPvSb0I
88      fbc1B9QkOmdT2Ecx2WaQPLISplmO0Jm0u0z11CGuf3Igby7unnCNvCuCXrKJFCsQ
89      8JGhwknNAG3eesSZxG4tklA6FMZjE9ETUtYfjH7Z4vuJSw/fxOeey7fhrqAzhV3P
90      GRkvA9EQUHJOeV4rEpiINP/fneHNfsn1o2YwZDAOBgNVHQ8BAf8EBAMCAQYwEgYD
91      VR0TAQH/BAgwBgEB/wIBCTAdBgNVHQ4EFgQUR0o0v4rPiBU9RwQfEUucx3JwbPAw
92      HwYDVR0jBBgwFoAUMhORultSN+ABogxQdkt7KChD0wQwCgYIKoZIzj0EAwIDgYoA
93      MIGGAkF1IvkIaXNkVfe+q0V78CnX0XIJuvmPpgjN8AQzqLci8txikd9gF1zt8fFQ
94      gIKERm2QPrshSV9srHDB0YnThRKuiQJBNcDjCfYOzqKlBHifT4WT4OX1U6nP/Y2b
95      imGaLJK9VIwfcJOpVCFGp7Xi8QGV6rJIFiQAqzqCy69vcU6nVMsvens=
96      -----END CERTIFICATE----- -----BEGIN CERTIFICATE-----
97      MIICKjCCAYugAwIBAgIUerDfApmkq0VYychkhlxEnBlIDUcwCgYIKoZIzj0EAwIw
98      HTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE4MjQyNloX
99      DTI5MDYyMTE4MjQ1NlowHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MIGb
100      MBAGByqGSM49AgEGBSuBBAAjA4GGAAQBA466Axrrz+HWanNe35gPVvB7OE7TWZcc
101      QZw1QSMQ+QIQMu5NcdfvZfh68exhe1FiJezKB+zeoJWp1Q/kqhyh7fsAFUuIcJDO
102      okZYPTmjPh3h5IZLPg5r7Pw1j99rLHhc/EXF9wYVy2UeH/2IqGJ+cncmVgqczlG8
103      m36g9OXd6hkofhCjZjBkMA4GA1UdDwEB/wQEAwIBBjASBgNVHRMBAf8ECDAGAQH/
104      AgEKMB0GA1UdDgQWBBQyE5G6W1I34AGiDFB2S3soKEPTBDAfBgNVHSMEGDAWgBQy
105      E5G6W1I34AGiDFB2S3soKEPTBDAKBggqhkjOPQQDAgOBjAAwgYgCQgGtPVCtgDc1
106      0SrTsVpEtUMYQKbOWnTKNHZ9h5jSna8n9aY+70Ai3U57q3FL95iIhZRW79PRpp65
107      d6tWqY51o2hHpwJCAK+eE7xpdnqh5H8TqAXKVuSoC0WEsovYCD03c8Ih3jWcZn6N
108      kbz2kXPcAk+dE6ncnwhwqNQgsJQGgQzJroH+Zzvb
109      -----END CERTIFICATE-----]
110      certificate      -----BEGIN CERTIFICATE-----
111      MIICOzCCAZygAwIBAgIUN5V7bLAGu8QIUFxlIugg8fBb+eYwCgYIKoZIzj0EAwIw
112      KjEoMCYGA1UEAxMfdmF1bHQta21pcC1kZWZhdWx0LWludGVybWVkaWF0ZTAeFw0x
113      OTA2MjQxODQ3MTdaFw0xOTA2MjUxODQ3NDdaMCAxDjAMBgNVBAsTBWNqVVNJMQ4w
114      DAYDVQQDEwVkdjRZbTCBmzAQBgcqhkjOPQIBBgUrgQQAIwOBhgAEANVsHV8CHYpW
115      CBKbYVEx/sLphk67SdWxbII4Sc9Rj1KymApD4gPmS+rw0FDMZGFbn1sAfpqMBqMj
116      ylv72o9izbYSALHnYT+AaE0NFn4eGWZ2G0p56cVmfXm3ZI959E+3gvZK6X5Jnzm4
117      FKXTDKGA4pocYec/rnYJ5X8sbAJKHvk1OeO+o2cwZTAOBgNVHQ8BAf8EBAMCA6gw
118      EwYDVR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0OBBYEFBEIsBo3HiBIg2l2psaQoYkT
119      D1RNMB8GA1UdIwQYMBaAFEdKNL+Kz4gVPUcEHxFLnMdycGzwMAoGCCqGSM49BAMC
120      A4GMADCBiAJCAc8DV23DJsHV4fdmbmssu0eDIgNH+PrRKdYgqiHptbuVjF2qbILp
121      Z34dJRVN+R9B+RprZXkYiv7gJ/47KSUKzRZpAkIByMjZqLtcypamJM/t+/O1BSst
122      CWcblb45FIxAmO4hE00Q5wnwXNxNnDHXWiuGdSNmIBjpb9nM5wehQlbkx7HzvPk=
123      -----END CERTIFICATE-----
124      private_key      -----BEGIN EC PRIVATE KEY-----
125      MIHcAgEBBEIB9Nn7M28VUVW6g5IlOTS3bHIZYM/zqVy+PvYQxn2lFbg1YrQzfd7h
126      sdtCjet0lc7pvtoOwd1dFiATOGg98OVN7MegBwYFK4EEACOhgYkDgYYABADVbB1f
127      Ah2KVggSm2FRMf7C6YZOu0nVsWyCOEnPUY9SspgKQ+ID5kvq8NBQzGRhW59bAH6a
128      jAajI8pb+9qPYs22EgCx52E/gGhNDRZ+HhlmdhtKeenFZn15t2SPefRPt4L2Sul+
129      SZ85uBSl0wyhgOKaHGHnP652CeV/LGwCSh75NTnjvg==
130      -----END EC PRIVATE KEY-----
131      serial_number    317328055225536560033788492808123425026102524390
132    ```
133
134### Supported KMIP Operations
135
136The KMIP protocol supports a wide [variety of operations](#kmip-ops) that can be
137issued by clients to perform certain actions, such as key management,
138encryption, signing, etc. The KMIP secrets engine currently supports a subset of
139KMIP operations.
140
141Supported KMIP operations:
142
143```text
144operation_create
145operation_rekey
146operation_locate
147operation_get
148operation_activate
149operation_revoke
150operation_destroy
151operation_discover_versions
152```
153
154Additionally, there are two pseudo-operations that can be used to allow or deny
155all operation capabilities to a role. These operations are mutually exclusive to
156all other operations. That is, if it's provided during role creation or update,
157no other operations can be provided. Similarly, if an existing role contains a
158pseudo-operation, and it is then updated with a set supported operation, it will
159be overwritten with the newly set of provided operations.
160
161Pseudo-operations:
162
163```text
164operation_all
165operation_none
166```
167
168[kmip-spec]: http://docs.oasis-open.org/kmip/spec/v1.4/kmip-spec-v1.4.html
169[kmip-ops]: http://docs.oasis-open.org/kmip/spec/v1.4/os/kmip-spec-v1.4-os.html#_Toc490660840