Merge pull request #3582 from hashicorp/sethvargo/ent-seal
Update docs on auto unseal
This commit is contained in:
Seth Vargo
GitHub
commit
d9c197b260
|
|
@ -19,11 +19,50 @@ Vault Enterprise's AWS KMS seal is activated by one of the following:
|
|||
other AWS-related environment variables that lends to successful
|
||||
authentication (i.e. `AWS_ACCESS_KEY_ID`, etc.).
|
||||
|
||||
## `awskms` Example
|
||||
|
||||
This example shows configuring AWS KMS seal through the Vault configuration file
|
||||
by providing all the required values:
|
||||
|
||||
```hcl
|
||||
seal "awskms" {
|
||||
aws_region = "us-east-1"
|
||||
access_key = "AKIAIOSFODNN7EXAMPLE"
|
||||
secret_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
|
||||
kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey"
|
||||
}
|
||||
```
|
||||
|
||||
## `awskms` Parameters
|
||||
|
||||
These parameters apply to the `seal` stanza in the Vault configuration file:
|
||||
|
||||
- `region` `(string: "us-east-1")`: The AWS region where the encryption key
|
||||
lives. May also be specified by the `AWS_REGION` or `AWS_DEFAULT_REGION`
|
||||
environment variable or as part of the AWS profile from the AWS CLI or
|
||||
instance profile.
|
||||
|
||||
- `access_key` `(string: <required>)`: The AWS access key ID to use. May also be
|
||||
specified by the `AWS_ACCESS_KEY_ID` environment variable or as part of the
|
||||
AWS profile from the AWS CLI or instance profile.
|
||||
|
||||
- `secret_key` `(string: <required>)`: The AWS secret access key to use. May
|
||||
also be specified by the `AWS_SECRET_ACCESS_KEY` environment variable or as
|
||||
part of the AWS profile from the AWS CLI or instance profile.
|
||||
|
||||
- `kms_key_id` `(string: <required>)`: The AWS KMS key ID to use for encryption
|
||||
and decryption. May also be specified by the `VAULT_AWSKMS_SEAL_KEY_ID`
|
||||
environment variable.
|
||||
|
||||
## Authentication
|
||||
|
||||
Authentication-related values must be provided, either as enviroment
|
||||
Authentication-related values must be provided, either as environment
|
||||
variables or as configuration parameters.
|
||||
|
||||
~> **Note:** Although the configuration file allows you to pass in
|
||||
`AWS_ACCESS_KEY_ID` and `AWS_ACCESS_KEY_ID` as part of the seal's parameters, it
|
||||
is *strongly* recommended to set these values via environment variables.
|
||||
|
||||
```text
|
||||
AWS authentication values:
|
||||
|
||||
|
|
@ -37,28 +76,6 @@ credentials, environment credentials, shared file credentials, or IAM role/ECS
|
|||
task credentials in that order, if the above AWS specific values are not
|
||||
provided.
|
||||
|
||||
## `awskms` Parameters
|
||||
|
||||
These parameters apply to the `seal` stanza in the Vault configuration file:
|
||||
|
||||
* `region` `(string: "us-east-1")`: The AWS region where the encryption key
|
||||
lives. May also be specified by the `AWS_REGION` or `AWS_DEFAULT_REGION`
|
||||
environment variable or as part of the AWS profile from the AWS CLI or
|
||||
instance profile.
|
||||
* `access_key` `(string: <required>)`: The AWS access key ID to use. May also be
|
||||
specified by the `AWS_ACCESS_KEY_ID` environment variable or as part of the
|
||||
AWS profile from the AWS CLI or instance profile.
|
||||
* `secret_key` `(string: <required>)`: The AWS secret access key to use. May
|
||||
also be specified by the `AWS_SECRET_ACCESS_KEY` environment variable or as
|
||||
part of the AWS profile from the AWS CLI or instance profile.
|
||||
* `kms_key_id` `(string: <required>)`: The AWS KMS key ID to use for encryption
|
||||
and decryption. May also be specified by the `VAULT_AWSKMS_SEAL_KEY_ID`
|
||||
environment variable.
|
||||
|
||||
~> **Note:** Although the configuration file allows you to pass in
|
||||
`AWS_ACCESS_KEY_ID` and `AWS_ACCESS_KEY_ID` as part of the seal's parameters, it
|
||||
is *strongly* reccommended to set these values via environment variables.
|
||||
|
||||
## `awskms` Environment Variables
|
||||
|
||||
Alternatively, the AWS KMS seal can be activated by providing the following
|
||||
|
|
@ -70,17 +87,3 @@ Vault Seal specific values:
|
|||
* `VAULT_SEAL_TYPE`
|
||||
* `VAULT_AWSKMS_SEAL_KEY_ID`
|
||||
```
|
||||
|
||||
## `awskms` Example
|
||||
|
||||
This example shows configuring AWS KMS seal through the Vault configuration file
|
||||
by providing all the required values:
|
||||
|
||||
```hcl
|
||||
seal "awskms" {
|
||||
aws_region = "us-east-1"
|
||||
access_key = "AKIAIOSFODNN7EXAMPLE"
|
||||
secret_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
|
||||
kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey"
|
||||
}
|
||||
```
|
||||
|
|
@ -20,6 +20,44 @@ the following:
|
|||
well as all other GCP-related environment variables that lends to successful
|
||||
authentication (i.e. `GOOGLE_PROJECT`, etc.).
|
||||
|
||||
## `gcpckms` Example
|
||||
|
||||
This example shows configuring GCP Cloud KMS seal through the Vault
|
||||
configuration file by providing all the required values:
|
||||
|
||||
```hcl
|
||||
seal "gcpckms" {
|
||||
credentials = "/usr/vault/vault-project-user-creds.json"
|
||||
project = "vault-project"
|
||||
region = "global"
|
||||
key_ring = "vault-keyring"
|
||||
crypto_key = "vault-key"
|
||||
}
|
||||
```
|
||||
|
||||
## `gcpckms` Parameters
|
||||
|
||||
These parameters apply to the `seal` stanza in the Vault configuration file:
|
||||
|
||||
- `credentials` `(string: <required>)`: The path to the credentials JSON file
|
||||
to use. May be also specified by the `GOOGLE_CREDENTIALS` or
|
||||
`GOOGLE_APPLICATION_CREDENTIALS` environment variable or set automatically if
|
||||
running under Google App Engine, Google Compute Engine or Google Container
|
||||
Engine.
|
||||
|
||||
- `project` `(string: <required>)`: The GCP project ID to use. May also be
|
||||
specified by the `GOOGLE_PROJECT` environment variable.
|
||||
|
||||
- `region` `(string: "us-east-1")`: The GCP region/location where the key ring
|
||||
lives. May also be specified by the `GOOGLE_REGION` environment variable.
|
||||
|
||||
- `key_ring` `(string: <required>)`: The GCP CKMS key ring to use. May also be
|
||||
specified by the `VAULT_GCPCKMS_SEAL_KEY_RING` environment variable.
|
||||
|
||||
- `crypto_key` `(string: <required>)`: The GCP CKMS crypto key to use for
|
||||
encryption and decryption. May also be specified by the
|
||||
`VAULT_GCPCKMS_SEAL_CRYPTO_KEY` environment variable.
|
||||
|
||||
## Authentication
|
||||
|
||||
Authentication-related values must be provided, either as enviroment
|
||||
|
|
@ -38,25 +76,6 @@ credentials, environment credentials, or [application default
|
|||
credentials](https://developers.google.com/identity/protocols/application-default-credentials)
|
||||
in that order, if the above GCP specific values are not provided.
|
||||
|
||||
## `gcpckms` Parameters
|
||||
|
||||
These parameters apply to the `seal` stanza in the Vault configuration file:
|
||||
|
||||
* `credentials` `(string: <required>)`: The path to the credentials JSON file
|
||||
to use. May be also specified by the `GOOGLE_CREDENTIALS` or
|
||||
`GOOGLE_APPLICATION_CREDENTIALS` environment variable or set automatically if
|
||||
running under Google App Engine, Google Compute Engine or Google Container
|
||||
Engine.
|
||||
* `project` `(string: <required>)`: The GCP project ID to use. May also be
|
||||
specified by the `GOOGLE_PROJECT` environment variable.
|
||||
* `region` `(string: "us-east-1")`: The GCP region/location where the key ring
|
||||
lives. May also be specified by the `GOOGLE_REGION` environment variable.
|
||||
* `key_ring` `(string: <required>)`: The GCP CKMS key ring to use. May also be
|
||||
specified by the `VAULT_GCPCKMS_SEAL_KEY_RING` environment variable.
|
||||
* `crypto_key` `(string: <required>)`: The GCP CKMS crypto key to use for
|
||||
encryption and decryption. May also be specified by the
|
||||
`VAULT_GCPCKMS_SEAL_CRYPTO_KEY` environment variable.
|
||||
|
||||
## `gcpckms` Environment Variables
|
||||
|
||||
Alternatively, the GCP Cloud KMS seal can be activated by providing the following
|
||||
|
|
@ -67,18 +86,3 @@ environment variables:
|
|||
* `VAULT_GCPCKMS_SEAL_KEY_RING`
|
||||
* `VAULT_GCPCKMS_SEAL_CRYPTO_KEY`
|
||||
```
|
||||
|
||||
## `gcpckms` Example
|
||||
|
||||
This example shows configuring GCP Cloud KMS seal through the Vault
|
||||
configuration file by providing all the required values:
|
||||
|
||||
```hcl
|
||||
seal "gcpckms" {
|
||||
credentials = "/usr/vault/vault-project-user-creds.json"
|
||||
project = "vault-project"
|
||||
region = "global"
|
||||
key_ring = "vault-keyring"
|
||||
crypto_key = "vault-key"
|
||||
}
|
||||
```
|
||||
|
|
@ -17,6 +17,9 @@ is not configured.
|
|||
As of Vault 0.9.0, the seal can also be used for [seal wrapping][sealwrap] to
|
||||
add an extra layer of protection and satisfy compliance and regulatory requirements.
|
||||
|
||||
For more examples, please choose a specific auto unsealing technology from the
|
||||
sidebar.
|
||||
|
||||
## Configuration
|
||||
|
||||
Seal configuration can be done through the Vault configuration file using the
|
||||
|
|
@ -24,7 +27,7 @@ Seal configuration can be done through the Vault configuration file using the
|
|||
|
||||
```hcl
|
||||
seal [NAME] {
|
||||
...
|
||||
# ...
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -32,7 +35,7 @@ For example:
|
|||
|
||||
```hcl
|
||||
seal "pkcs11" {
|
||||
...
|
||||
# ...
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -25,55 +25,79 @@ HSM key backup strategy requires the key to be exportable, you should generate
|
|||
the key yourself. The list of creation attributes that Vault uses to generate
|
||||
the key are listed at the end of this document.
|
||||
|
||||
|
||||
## Requirements
|
||||
|
||||
The following software packages are required for Vault Enterprise HSM:
|
||||
|
||||
* PKCS#11 compatible HSM intgration library
|
||||
* `libtldl` library
|
||||
- PKCS#11 compatible HSM integration library
|
||||
- `libtldl` library
|
||||
|
||||
## `pkcs11` Example
|
||||
|
||||
This example shows configuring HSM PKCS11 seal through the Vault configuration
|
||||
file by providing all the required values:
|
||||
|
||||
```hcl
|
||||
seal "pkcs11" {
|
||||
lib = "/usr/vault/lib/libCryptoki2_64.so"
|
||||
slot = "0"
|
||||
pin = "AAAA-BBBB-CCCC-DDDD"
|
||||
key_label = "vault-hsm-key"
|
||||
hmac_key_label = "vault-hsm-hmac-key"
|
||||
}
|
||||
```
|
||||
|
||||
## `pkcs11` Parameters
|
||||
|
||||
These parameters apply to the `seal` stanza in the Vault configuration file:
|
||||
|
||||
* `lib` `(string: <required>)`: The path to the PKCS#11 library shared object
|
||||
- `lib` `(string: <required>)`: The path to the PKCS#11 library shared object
|
||||
file. May also be specified by the `VAULT_HSM_LIB` environment variable.
|
||||
**Note:** Depending on your HSM, this may be either a binary or a dynamic
|
||||
library, and its use may require other libraries depending on which system the
|
||||
Vault binary is currently running on (e.g.: a Linux system may require other
|
||||
libraries to interpret Windows .dll files).
|
||||
* `slot` `(string: <required>)`: The slot number to use, specified as a string
|
||||
libraries to interpret Windows .dll files).
|
||||
|
||||
- `slot` `(string: <required>)`: The slot number to use, specified as a string
|
||||
(e.g. `"0"`). May also be specified by the `VAULT_HSM_SLOT` environment
|
||||
variable.
|
||||
* `pin` `(string: <required>)`: The PIN for login. May also be specified by the
|
||||
|
||||
- `pin` `(string: <required>)`: The PIN for login. May also be specified by the
|
||||
`VAULT_HSM_PIN` environment variable. _If set via the environment variable,
|
||||
Vault will obfuscate the environment variable after reading it, and it will
|
||||
need to be re-set if Vault is restarted._
|
||||
* `key_label` `(string: <required>)`: The label of the key to use. If the key
|
||||
|
||||
- `key_label` `(string: <required>)`: The label of the key to use. If the key
|
||||
does not exist and generation is enabled, this is the label that will be given
|
||||
to the generated key. May also be specified by the `VAULT_HSM_KEY_LABEL`
|
||||
environment variable.
|
||||
* `hmac_key_label` `(string: <required>)`: The label of the key to use for
|
||||
|
||||
- `hmac_key_label` `(string: <required>)`: The label of the key to use for
|
||||
HMACing. This needs to be a suitable type; a good choice is an AES key marked
|
||||
as valid for signing and verifying. If the key does not exist and generation
|
||||
is enabled, this is the label that will be given to the generated key. May
|
||||
also be specified by the `VAULT_HSM_HMAC_KEY_LABEL` environment variable.
|
||||
* `mechanism` `(string: "0x1082")`: The encryption/decryption mechanism to use,
|
||||
|
||||
- `mechanism` `(string: "0x1082")`: The encryption/decryption mechanism to use,
|
||||
specified as a decimal or hexadecimal (prefixed by `0x`) string. Currently
|
||||
only `0x1082` (corresponding to `CKM_AES_CBC` from the specification) is
|
||||
supported. May also be specified by the `VAULT_HSM_MECHANISM` environment
|
||||
variable.
|
||||
* `hmac_mechanism` `(string: "0x0251")`: The encryption/decryption mechanism to
|
||||
|
||||
- `hmac_mechanism` `(string: "0x0251")`: The encryption/decryption mechanism to
|
||||
use, specified as a decimal or hexadecimal (prefixed by `0x`) string.
|
||||
Currently only `0x0251` (corresponding to `CKM_SHA256_HMAC` from the
|
||||
specification) is supported. May also be specified by the
|
||||
`VAULT_HSM_HMAC_MECHANISM` environment variable.
|
||||
* `generate_key` `(string: "false")`: If no existing key with the label
|
||||
|
||||
- `generate_key` `(string: "false")`: If no existing key with the label
|
||||
specified by `key_label` can be found at Vault initialization time, instructs
|
||||
Vault to generate a key. This is a boolean expressed as a string (e.g.
|
||||
`"true"`). May also be specified by the `VAULT_HSM_GENERATE_KEY` environment
|
||||
variable.
|
||||
* `regenerate_key` `(string: "false")`: At Vault initialization time, force
|
||||
|
||||
- `regenerate_key` `(string: "false")`: At Vault initialization time, force
|
||||
generation of a new key even if one with the given `key_label` already exists.
|
||||
This is a boolean expressed as a string (e.g. `"true"`). May also be specified
|
||||
by the `VAULT_HSM_REGENERATE_KEY` environment variable.
|
||||
|
|
@ -101,21 +125,6 @@ environment variables:
|
|||
* `VAULT_HSM_REGENERATE_KEY`
|
||||
```
|
||||
|
||||
## `pkcs11` Example
|
||||
|
||||
This example shows configuring HSM PKCS11 seal through the Vault configuration
|
||||
file by providing all the required values:
|
||||
|
||||
```hcl
|
||||
seal "pkcs11" {
|
||||
lib = "/usr/vault/lib/libCryptoki2_64.so"
|
||||
slot = "0"
|
||||
pin = "AAAA-BBBB-CCCC-DDDD"
|
||||
key_label = "vault-hsm-key"
|
||||
hmac_key_label = "vault-hsm-hmac-key"
|
||||
}
|
||||
```
|
||||
|
||||
## Vault Key Generation Attributes
|
||||
|
||||
If Vault generates the HSM key for you, the following is the list of attributes
|
||||
|
|
|
|||
32
website/source/docs/enterprise/auto-unseal/index.html.md
Normal file
32
website/source/docs/enterprise/auto-unseal/index.html.md
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Vault Enterprise Auto Unseal"
|
||||
sidebar_current: "docs-vault-enterprise-auto-unseal"
|
||||
description: |-
|
||||
Vault Enterprise supports automatic unsealing via cloud technologies like KMS.
|
||||
---
|
||||
|
||||
# Vault Enterprise Auto Unseal
|
||||
|
||||
As of version 0.9, Vault Enterprise supports opt-in automatic unsealing via
|
||||
cloud technologies such Amazon KMS or Google Cloud KMS. This feature enables
|
||||
operators to delegate the unsealing process to trusted cloud providers to ease
|
||||
operations in the event of partial failure and to aid in the creation of new or
|
||||
ephemeral clusters.
|
||||
|
||||
## Enabling Auto Unseal
|
||||
|
||||
Automatic unsealing is not enabled by default. To enable automatic unsealing,
|
||||
specify the `seal` stanza in your Vault configuration file:
|
||||
|
||||
```hcl
|
||||
seal "awskms" {
|
||||
aws_region = "us-east-1"
|
||||
access_key = "..."
|
||||
secret_key = "..."
|
||||
kms_key_id = "..."
|
||||
}
|
||||
```
|
||||
|
||||
For a complete list of examples and supported technologies, please see the
|
||||
[seal documentation](/docs/configuration/seal/index.html).
|
||||
|
|
@ -98,13 +98,13 @@
|
|||
<a href="/docs/configuration/seal/index.html"><tt>seal</tt></a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-configuration-seal-awskms") %>>
|
||||
<a href="/docs/configuration/seal/awskms.html">AWS KMS (Enterprise)</a>
|
||||
<a href="/docs/configuration/seal/awskms.html">AWS KMS <sup>ENT</sup></a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-configuration-seal-gcpckms") %>>
|
||||
<a href="/docs/configuration/seal/gcpckms.html">GCP Cloud KMS (Enterprise)</a>
|
||||
<a href="/docs/configuration/seal/gcpckms.html">GCP Cloud KMS <sup>ENT</sup></a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-configuration-seal-pkcs11") %>>
|
||||
<a href="/docs/configuration/seal/pkcs11.html">HSM PKCS11 (Enterprise)</a>
|
||||
<a href="/docs/configuration/seal/pkcs11.html">HSM PKCS11 <sup>ENT</sup></a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
|
@ -307,7 +307,7 @@
|
|||
<li<%= sidebar_current("docs-auth-gcp") %>>
|
||||
<a href="/docs/auth/gcp.html">Google Cloud</a>
|
||||
</li>
|
||||
|
||||
|
||||
<li<%= sidebar_current("docs-auth-kubernetes") %>>
|
||||
<a href="/docs/auth/kubernetes.html">Kubernetes</a>
|
||||
</li>
|
||||
|
|
@ -379,10 +379,13 @@
|
|||
<li<%= sidebar_current("docs-vault-enterprise") %>>
|
||||
<a href="/docs/enterprise/index.html">Vault Enterprise</a>
|
||||
<ul class="nav">
|
||||
<li <%= sidebar_current("docs-vault-enterprise-replication")%> >
|
||||
<li <%= sidebar_current("docs-vault-enterprise-replication")%>>
|
||||
<a href="/docs/enterprise/replication/index.html">Replication</a>
|
||||
</li>
|
||||
<li <%= sidebar_current("docs-vault-enterprise-hsm")%> >
|
||||
<li<%= sidebar_current("docs-vault-enterprise-auto-unseal") %>>
|
||||
<a href="/docs/enterprise/auto-unseal/index.html">Auto Unseal</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-vault-enterprise-hsm")%>>
|
||||
<a href="/docs/enterprise/hsm/index.html">HSM Support</a>
|
||||
<ul class="nav">
|
||||
<li <%= sidebar_current("docs-vault-enterprise-hsm-behavior")%>>
|
||||
|
|
@ -393,7 +396,7 @@
|
|||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li <%= sidebar_current("docs-vault-enterprise-sealwrap")%> >
|
||||
<li<%= sidebar_current("docs-vault-enterprise-sealwrap")%>>
|
||||
<a href="/docs/enterprise/sealwrap/index.html">Seal Wrap / FIPS 140-2</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-vault-enterprise-ui") %>>
|
||||
|
|
@ -403,9 +406,9 @@
|
|||
<a href="/docs/enterprise/identity/index.html">Identity</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-vault-enterprise-control-groups") %>>
|
||||
<a href="/docs/enterprise/control-groups/index.html">Control Groups</a>
|
||||
</li>
|
||||
<li <%= sidebar_current("docs-vault-enterprise-mfa")%> >
|
||||
<a href="/docs/enterprise/control-groups/index.html">Control Groups</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-vault-enterprise-mfa")%>>
|
||||
<a href="/docs/enterprise/mfa/index.html">MFA</a>
|
||||
<ul class="nav">
|
||||
<li <%= sidebar_current("docs-vault-enterprise-mfa-duo")%>>
|
||||
|
|
|
|||
Loading…
Reference in a new issue