adds documentation for entropy augmentation (#7721)

* adds documentation for entorpy augmentation

* adds a link to pkcs11 seal configuration from a mention of it

website/source/api/system/mounts.html.md

@@ -143,6 +143,9 @@ relevant functionality is only supported in Vault Enterprise:
 
 - `seal_wrap` `(bool: false)` - Enable seal wrapping for the mount, causing
   values stored by the mount to be wrapped by the seal's encryption capability.
+  
+- `external_entropy_access` `(bool: false)` - Enable the secrets engine to access
+  Vault's external entropy source.
 
 ### Sample Payload
 

website/source/docs/configuration/entropy-augmentation/index.html.md

@@ -0,0 +1,49 @@
+---
+layout: "docs"
+page_title: "Entropy Augmentation - Configuration"
+sidebar_title: "<code>Entropy Augmentation</code> <sup>ENT</sup>"
+sidebar_current: "docs-configuration-entropy-augmentation"
+description: |-
+  Entropy augmentation enables Vault to sample entropy from external cryptographic modules.
+---
+
+# `Entropy Augmentation` Seal
+
+  Entropy augmentation enables Vault to sample entropy from an external cryptographic modules.
+  Currently, sourcing external entropy is done through a configured [PKCS11 seal](/docs/configuration/seal/pkcs11.html).
+  Vault Enterprises's external entropy support is activated by the presence of an `entropy "seal"`
+  block in Vault's configuration file.
+
+## Requirements
+
+The following software packages are required for Vault Enterprise Entropy Augmentation:
+
+- PKCS#11 compatible HSM integration library. Vault targets version 2.2 or
+  higher of PKCS#11. Depending on any given HSM, some functions (such as key
+  generation) may have to be performed manually.
+- The [GNU libltdl library](https://www.gnu.org/software/libtool/manual/html_node/Using-libltdl.html)
+  — ensure that it is installed for the correct architecture of your servers
+- Governance and Policy module of a Vault Enterprise license
+
+## `entropy` Example
+
+This example shows configuring entropy augmentation through a PKCS11 HSM seal from Vault's configuration
+file:
+
+```hcl
+seal "pkcs11" {
+    ...
+}
+
+entropy "seal" {
+    mode = "augmentation"
+}
+```
+
+## `entropy augmentation` Parameters
+
+These parameters apply to the `entropy` stanza in the Vault configuration file:
+
+- `mode` `(string: <required>)`: The mode determines which Vault operations requiring
+entropy will sample entropy from the external source. Currently, the only mode supported
+is `augmentation` which sources entropy for [Critical Security Parameters (CSPs)](/docs/enterprise/entropy-augmentation/index.html#Critical-Security-Parameters-(CSPs)).

website/source/docs/enterprise/entropy-augmentation/index.html.md

@@ -0,0 +1,53 @@
+---
+layout: "docs"
+page_title: "Vault Enterprise Entropy Augmentation"
+sidebar_title: "Entropy Augmentation"
+sidebar_current: "docs-vault-enterprise-entropy-augmentation"
+description: |-
+  Vault Enterprise features a mechanism to sample entropy from external
+  cryptographic modules.
+---
+
+# Entropy Augmentation
+
+Vault Enterprise features a mechanism to sample entropy (or randomness for 
+cryptographic operations) from external cryptographic modules via the [seals](/docs/configuration/seal/index.html)
+interface. While the system entropy used by Vault is more than capable of
+operating in most threat models, there are some situations where additional
+entropy from hardware-based random number generators is desirable.
+
+To use this feature, you must have an active or trial license for Vault
+Enterprise. To start a trial, contact [HashiCorpsales](mailto:sales@hashicorp.com).
+
+# Critical Security Parameters (CSPs)
+
+Entropy augmentation allows Vault Enterprise to supplement its system entropy with
+entropy from an external cryptography module. Designed to operate in environments
+where alignment with cryptographic regulations like [NIST SP800-90B](https://csrc.nist.gov/publications/detail/sp/800-90b/final)
+is required or when augmented entropy from external sources such as hardware true
+random number generators (TRNGs) or [quantum computing TRNGs](https://www.hashicorp.com/blog/quantum-security-and-cryptography-in-hashicorp-vault/)
+are desirable, augmented entropy replaces system entropy when performing random
+number operations on critical security parameters (CSPs). 
+
+These CSPs have been selected from our previous work in [evaluating Vault for conformance with
+FIPS 140-2 guidelines for key storage and key transport](https://www.datocms-assets.com/2885/1510600487-vault_compliance_letter_fips_140-2.pdf)
+and include the following: 
+
+
+- Vault’s master key 
+- Keyring encryption keys
+- Auto Unseal recovery keys
+- TLS private keys for inter-node and inter cluster communication (HA leader, raft, and replication)
+- Enterprise MFA TOTP token keys
+- JWT token wrapping keys
+- Root tokens
+- DR operation tokens
+- [Transit](/docs/secrets/transit/index.html) backend key generation
+
+## Enabling/Disabling
+
+Entropy augmentation is disabled by default. To enable entropy augmentation Vault's
+[configuration file][configuration] must include a properly configured [PKCS#11 seal and
+entropy stanza](/docs/configuration/entropy-augmentation/index.html).
+
+[configuration]: /docs/configuration/index.html

website/source/layouts/docs.erb

@@ -79,7 +79,8 @@
                 ]
               },
               'telemetry',
-              { category: 'ui' }
+              { category: 'ui' },
+              { category: 'entropy-augmentation' }
             ]
           }, {
             category: 'commands',
@@ -384,6 +385,7 @@
                 category: 'hsm',
                 content: ['behavior', 'security']
               },
+              { category: 'entropy-augmentation' },
               { category: 'sealwrap' },
               { category: 'namespaces' },
               { category: 'performance-standby' },