From b09d042173baa0fb017cbf427b8d79146eba2bcd Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Tue, 14 Nov 2017 13:11:55 -0500 Subject: [PATCH 1/3] Use super to show enterprise --- website/source/layouts/docs.erb | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index c24c8dd3d..a97ddef9c 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -98,13 +98,13 @@ seal From 4efcfe03d1129ef09e9966b8163059f10d5dab35 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Tue, 14 Nov 2017 13:12:20 -0500 Subject: [PATCH 2/3] Add an auto-unseal page to the docs This helps with SEO and also is where I'd expect auto unsealing to be referenced. --- .../docs/enterprise/auto-unseal/index.html.md | 32 +++++++++++++++++++ website/source/layouts/docs.erb | 17 ++++++---- 2 files changed, 42 insertions(+), 7 deletions(-) create mode 100644 website/source/docs/enterprise/auto-unseal/index.html.md diff --git a/website/source/docs/enterprise/auto-unseal/index.html.md b/website/source/docs/enterprise/auto-unseal/index.html.md new file mode 100644 index 000000000..3b2398c2f --- /dev/null +++ b/website/source/docs/enterprise/auto-unseal/index.html.md @@ -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). diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index a97ddef9c..584280a25 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -307,7 +307,7 @@ > Google Cloud - + > Kubernetes @@ -379,10 +379,13 @@ > Vault Enterprise
    -
  • > +
  • > Replication
    • -
  • > + > + Auto Unseal +
    • + > HSM Support
    • > @@ -393,7 +396,7 @@
    -
  • > + > Seal Wrap / FIPS 140-2
    • > @@ -403,9 +406,9 @@ Identity > - Control Groups - -
  • > + Control Groups +
    • + > MFA
    • > From 68052f18d015082a11641ddabf2457edd47af253 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Tue, 14 Nov 2017 13:12:35 -0500 Subject: [PATCH 3/3] Flip seal pages upside down to put examples first --- .../docs/configuration/seal/awskms.html.md | 77 ++++++++++--------- .../docs/configuration/seal/gcpckms.html.md | 72 +++++++++-------- .../docs/configuration/seal/index.html.md | 7 +- .../docs/configuration/seal/pkcs11.html.md | 63 ++++++++------- 4 files changed, 119 insertions(+), 100 deletions(-) diff --git a/website/source/docs/configuration/seal/awskms.html.md b/website/source/docs/configuration/seal/awskms.html.md index 2465bb2f0..f6ffb2dc1 100644 --- a/website/source/docs/configuration/seal/awskms.html.md +++ b/website/source/docs/configuration/seal/awskms.html.md @@ -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: )`: 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: )`: 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: )`: 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: )`: 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: )`: 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: )`: 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" -} -``` \ No newline at end of file diff --git a/website/source/docs/configuration/seal/gcpckms.html.md b/website/source/docs/configuration/seal/gcpckms.html.md index d0a183426..6b50c7ac1 100644 --- a/website/source/docs/configuration/seal/gcpckms.html.md +++ b/website/source/docs/configuration/seal/gcpckms.html.md @@ -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: )`: 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: )`: 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: )`: The GCP CKMS key ring to use. May also be + specified by the `VAULT_GCPCKMS_SEAL_KEY_RING` environment variable. + +- `crypto_key` `(string: )`: 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: )`: 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: )`: 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: )`: The GCP CKMS key ring to use. May also be - specified by the `VAULT_GCPCKMS_SEAL_KEY_RING` environment variable. -* `crypto_key` `(string: )`: 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" -} -``` \ No newline at end of file diff --git a/website/source/docs/configuration/seal/index.html.md b/website/source/docs/configuration/seal/index.html.md index ba8ab542d..5de7d8165 100644 --- a/website/source/docs/configuration/seal/index.html.md +++ b/website/source/docs/configuration/seal/index.html.md @@ -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" { - ... + # ... } ``` diff --git a/website/source/docs/configuration/seal/pkcs11.html.md b/website/source/docs/configuration/seal/pkcs11.html.md index 090ca025d..cc45b7985 100644 --- a/website/source/docs/configuration/seal/pkcs11.html.md +++ b/website/source/docs/configuration/seal/pkcs11.html.md @@ -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: )`: The path to the PKCS#11 library shared object +- `lib` `(string: )`: 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: )`: The slot number to use, specified as a string + libraries to interpret Windows .dll files). + +- `slot` `(string: )`: 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: )`: The PIN for login. May also be specified by the + +- `pin` `(string: )`: 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: )`: The label of the key to use. If the key + +- `key_label` `(string: )`: 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: )`: The label of the key to use for + +- `hmac_key_label` `(string: )`: 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