From 219285850bcef4dc92f61e4ce552df59e877b1f4 Mon Sep 17 00:00:00 2001 From: Chris Hoffman Date: Thu, 25 Oct 2018 16:44:53 -0700 Subject: [PATCH] Updating seal docs (#5616) * updating seal docs * fixing api docs --- website/data/docs_detailed_categories.yml | 1 - website/source/api/system/unseal.html.md | 4 ++ website/source/docs/concepts/seal.html.md | 44 +++++++++++++++++++ .../configuration/seal/alicloudkms.html.md | 4 +- .../docs/configuration/seal/awskms.html.md | 4 +- .../configuration/seal/azurekeyvault.html.md | 5 +-- .../docs/configuration/seal/gcpckms.html.md | 5 +-- .../docs/configuration/seal/index.html.md | 3 +- .../docs/enterprise/auto-unseal/index.html.md | 33 -------------- .../operations/autounseal-aws-kms.html.md | 2 +- .../operations/reference-architecture.html.md | 3 +- website/source/layouts/docs.erb | 1 - 12 files changed, 60 insertions(+), 49 deletions(-) delete mode 100644 website/source/docs/enterprise/auto-unseal/index.html.md diff --git a/website/data/docs_detailed_categories.yml b/website/data/docs_detailed_categories.yml index 5c82b643e4..47bef06455 100644 --- a/website/data/docs_detailed_categories.yml +++ b/website/data/docs_detailed_categories.yml @@ -127,7 +127,6 @@ title: "Vault Enterprise" docs: - docs/enterprise/replication/index.html - - docs/enterprise/auto-unseal/index.html - docs/enterprise/hsm/index.html - docs/enterprise/sealwrap/index.html - docs/enterprise/namespaces/index.html diff --git a/website/source/api/system/unseal.html.md b/website/source/api/system/unseal.html.md index 9655d49d1e..6a5b4c8dff 100644 --- a/website/source/api/system/unseal.html.md +++ b/website/source/api/system/unseal.html.md @@ -33,6 +33,10 @@ Either the `key` or `reset` parameter must be provided; if both are provided, - `reset` `(bool: false)` – Specifies if previously-provided unseal keys are discarded and the unseal process is reset. +- `migrate` `(string: "")` - Available in 1.0 Beta - Used to migrate the seal + from shamir to autoseal or autoseal to shamir. Must be provided on all unseal + key calls. Valid values are "shamir" and "autoseal". + ### Sample Payload ```json diff --git a/website/source/docs/concepts/seal.html.md b/website/source/docs/concepts/seal.html.md index e27c62666f..b026da5e8b 100644 --- a/website/source/docs/concepts/seal.html.md +++ b/website/source/docs/concepts/seal.html.md @@ -71,3 +71,47 @@ a single operator with root privileges. This way, if there is a detected intrusion, the Vault data can be locked quickly to try to minimize damages. It can't be accessed again without access to the master key shards. + +## Auto Unseal + +Auto Unseal was developed to aid in reducing the operational complexity of +keeping the master key secure. This feature delegates the responsibility of +securing the master key from users to a trusted device or service. Instead of +only constructing the key in memory, the master key is encrypted with one of +these services or devices and then stored in the storage backend allowing Vault +to decrypt the master key at startup and unseal automatically. + +When using a Auto Unseal, there are certain operations in Vault that still +require a quorum of users to perform an operation such as generating a root token. +During the initialization process, a set of Shamir keys are generated that are called +Recovery Keys and are used for these operations. + +For a list of examples and supported providers, please see the +[seal documentation](/docs/configuration/seal/index.html). + +## Seal Migration + +The seal can be migrated between Shamir keys and automatic migration and vice versa. + +To migrate from Shamir keys to Auto Unseal, take your server cluster offline and update +the [seal configuration](/docs/configuration/seal/index.html) with the appropriate seal +configuration. When you bring up your server back up, run the unseal process with the +`-migrate` flag. All unseal commands must specify the `-migrate` flag. Once the +required threshold of unseal keys are entered, the unseal keys will be migrated to +recovery keys. + +``` +$ vault unseal -migrate autoseal +``` + +To migrate from Auto Unseal to Shamir keys, take your server cluster offline and update +the [seal configuration](/docs/configuration/seal/index.html) and add `disabled = "true"` +to the seal block. This allows the migration to use this information to decrypt the key +but will not unseal Vault. When you bring up your server back up, run the unseal process +with the `-migrate` flag and use the Recovery Keys to perform the migration. All unseal +commands must specify the `-migrate` flag. Once the required threshold of recovery keys +are entered, the recovery keys will be migrated to be used as unseal keys. + +``` +$ vault unseal -migrate shamir +``` \ No newline at end of file diff --git a/website/source/docs/configuration/seal/alicloudkms.html.md b/website/source/docs/configuration/seal/alicloudkms.html.md index 3bb14e265a..28eff5ceb3 100644 --- a/website/source/docs/configuration/seal/alicloudkms.html.md +++ b/website/source/docs/configuration/seal/alicloudkms.html.md @@ -1,7 +1,7 @@ --- layout: "docs" page_title: "AliCloud KMS - Seals - Configuration" -sidebar_title: "AliCloud KMS ENT" +sidebar_title: "AliCloud KMS 1.0 BETA" sidebar_current: "docs-configuration-seal-alicloudkms" description: |- The AliCloud KMS seal configures Vault to use AliCloud KMS as the seal wrapping @@ -11,7 +11,7 @@ description: |- # `alicloudkms` Seal The AliCloud KMS seal configures Vault to use AliCloud KMS as the seal wrapping mechanism. -Vault Enterprise's AliCloud KMS seal is activated by one of the following: +The AliCloud KMS seal is activated by one of the following: * The presence of a `seal "alicloudkms"` block in Vault's configuration file. * The presence of the environment variable `VAULT_SEAL_TYPE` set to `alicloudkms`. If diff --git a/website/source/docs/configuration/seal/awskms.html.md b/website/source/docs/configuration/seal/awskms.html.md index c2fc6d3dca..d22b087ed7 100644 --- a/website/source/docs/configuration/seal/awskms.html.md +++ b/website/source/docs/configuration/seal/awskms.html.md @@ -1,7 +1,7 @@ --- layout: "docs" page_title: "AWS KMS - Seals - Configuration" -sidebar_title: "AWS KMS ENT" +sidebar_title: "AWS KMS 1.0 BETA" sidebar_current: "docs-configuration-seal-awskms" description: |- The AWS KMS seal configures Vault to use AWS KMS as the seal wrapping @@ -11,7 +11,7 @@ description: |- # `awskms` Seal The AWS KMS seal configures Vault to use AWS KMS as the seal wrapping mechanism. -Vault Enterprise's AWS KMS seal is activated by one of the following: +The AWS KMS seal is activated by one of the following: * The presence of a `seal "awskms"` block in Vault's configuration file * The presence of the environment variable `VAULT_SEAL_TYPE` set to `awskms`. If diff --git a/website/source/docs/configuration/seal/azurekeyvault.html.md b/website/source/docs/configuration/seal/azurekeyvault.html.md index c19f0c961a..4191a3cffc 100644 --- a/website/source/docs/configuration/seal/azurekeyvault.html.md +++ b/website/source/docs/configuration/seal/azurekeyvault.html.md @@ -1,7 +1,7 @@ --- layout: "docs" page_title: "Azure Key Vault - Seals - Configuration" -sidebar_title: "Azure Key Vault ENT" +sidebar_title: "Azure Key Vault 1.0 BETA" sidebar_current: "docs-configuration-seal-azurekeyvault" description: |- The Azure Key Vault seal configures Vault to use Azure Key Vault as the seal wrapping @@ -11,8 +11,7 @@ description: |- # `azurekeyvault` Seal The Azure Key Vault seal configures Vault to use Azure Key Vault as the seal -wrapping mechanism. Vault Enterprise's Azure Key Vault seal is activated by one of -the following: +wrapping mechanism. The Azure Key Vault seal is activated by one of the following: * The presence of a `seal "azurekeyvault"` block in Vault's configuration file. * The presence of the environment variable `VAULT_SEAL_TYPE` set to `azurekeyvault`. diff --git a/website/source/docs/configuration/seal/gcpckms.html.md b/website/source/docs/configuration/seal/gcpckms.html.md index 60a2519029..1516c3774d 100644 --- a/website/source/docs/configuration/seal/gcpckms.html.md +++ b/website/source/docs/configuration/seal/gcpckms.html.md @@ -1,7 +1,7 @@ --- layout: "docs" page_title: "GCP Cloud KMS - Seals - Configuration" -sidebar_title: "GCP Cloud KMS ENT" +sidebar_title: "GCP Cloud KMS 1.0 BETA" sidebar_current: "docs-configuration-seal-gcpckms" description: |- The GCP Cloud KMS seal configures Vault to use GCP Cloud KMS as the seal wrapping @@ -11,8 +11,7 @@ description: |- # `gcpckms` Seal The GCP Cloud KMS seal configures Vault to use GCP Cloud KMS as the seal -wrapping mechanism. Vault Enterprise's GCP Cloud KMS seal is activated by one of -the following: +wrapping mechanism. The GCP Cloud KMS seal is activated by one of the following: * The presence of a `seal "gcpckms"` block in Vault's configuration file. * The presence of the environment variable `VAULT_SEAL_TYPE` set to `gcpckms`. diff --git a/website/source/docs/configuration/seal/index.html.md b/website/source/docs/configuration/seal/index.html.md index fba25a1cb1..356a67fad0 100644 --- a/website/source/docs/configuration/seal/index.html.md +++ b/website/source/docs/configuration/seal/index.html.md @@ -16,7 +16,8 @@ will use the Shamir algorithm to cryptographically split the master key if this 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. +add an extra layer of protection and satisfy compliance and regulatory requirements. +This feature is only available in Vault Enterprise. For more examples, please choose a specific auto unsealing technology from the sidebar. diff --git a/website/source/docs/enterprise/auto-unseal/index.html.md b/website/source/docs/enterprise/auto-unseal/index.html.md deleted file mode 100644 index 248f1efbdd..0000000000 --- a/website/source/docs/enterprise/auto-unseal/index.html.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -layout: "docs" -page_title: "Vault Enterprise Auto Unseal" -sidebar_title: "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" { - 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/guides/operations/autounseal-aws-kms.html.md b/website/source/guides/operations/autounseal-aws-kms.html.md index 5ba73d06b7..ac4162b7c7 100644 --- a/website/source/guides/operations/autounseal-aws-kms.html.md +++ b/website/source/guides/operations/autounseal-aws-kms.html.md @@ -28,7 +28,7 @@ instance that can utilize an encryption key from [AWS Key Management Services ## Reference Material -- [Vault Enterprise Auto Unseal](/docs/enterprise/auto-unseal/index.html) +- [Vault Auto Unseal](/docs/configuration/seal/index.html) - [Configuration: `awskms` Seal](/docs/configuration/seal/awskms.html) diff --git a/website/source/guides/operations/reference-architecture.html.md b/website/source/guides/operations/reference-architecture.html.md index 277bc5adbc..ff47b47583 100644 --- a/website/source/guides/operations/reference-architecture.html.md +++ b/website/source/guides/operations/reference-architecture.html.md @@ -318,8 +318,7 @@ within that replication set must use an HSM as well. secret sharing method), the clusters within that replication set can be mixed, such that some may use an HSM, others may use Shamir. -For sake of this discussion, the [cloud -auto-unseal](/docs/enterprise/auto-unseal/index.html) feature is treated as an +For sake of this discussion, the cloud auto-unseal feature is treated as an HSM. ## Additional References diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 14a47199df..35f9ccf0b5 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -324,7 +324,6 @@ category: 'enterprise', content: [ { category: 'replication' }, - { category: 'auto-unseal' }, { category: 'hsm', content: ['behavior', 'security']