Flip seal pages upside down to put examples first

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: <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"
-}
-```

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: <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"
-}
-```

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" {
-  ...
+  # ...
 }
 ```
 

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
+- PKCS#11 compatible HSM integration library
-* `libtldl` 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
+
+- `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