Updating seal docs (#5616)

* updating seal docs * fixing api docs
hashicorp · Oct 25, 2018 · 2192858 · 2192858
1 parent 250c1b9
commit 2192858
Show file tree

Hide file tree

Showing 12 changed files with 60 additions and 49 deletions.
diff --git 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
@@ -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
@@ -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
+```
diff --git 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 <sup>ENT</sup>"
+sidebar_title: "AliCloud KMS <sup>1.0 BETA</sup>"
 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
@@ -1,7 +1,7 @@
 ---
 layout: "docs"
 page_title: "AWS KMS - Seals - Configuration"
-sidebar_title: "AWS KMS <sup>ENT</sup>"
+sidebar_title: "AWS KMS <sup>1.0 BETA</sup>"
 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
@@ -1,7 +1,7 @@
 ---
 layout: "docs"
 page_title: "Azure Key Vault - Seals - Configuration"
-sidebar_title: "Azure Key Vault <sup>ENT</sup>"
+sidebar_title: "Azure Key Vault <sup>1.0 BETA</sup>"
 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
@@ -1,7 +1,7 @@
 ---
 layout: "docs"
 page_title: "GCP Cloud KMS - Seals - Configuration"
-sidebar_title: "GCP Cloud KMS <sup>ENT</sup>"
+sidebar_title: "GCP Cloud KMS <sup>1.0 BETA</sup>"
 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
@@ -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
diff --git 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
@@ -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
@@ -324,7 +324,6 @@
             category: 'enterprise',
             content: [
               { category: 'replication' },
-              { category: 'auto-unseal' },
               {
                 category: 'hsm',
                 content: ['behavior', 'security']