Start documentation for FIPS variants of Vault Enterprise (#15475)

* Begin restructuring FIPS documentation

This creates a new FIPS category under Enterprise and copies the
FIPS-specific seal wrap documentation into it.

We leave the existing Seal Wrap page at the old path, but document that
the FIPS-specific portions of it have moved.

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Add initial FIPS 140-2 inside documentation

This documents the new FIPS 140-2 Inside binary and how to use and
validate it. This also documents which algorithms are certified for
use in the BoringCrypto distribution.

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Add notes about FIPS algorithm restrictions

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

website/content/api-docs/secret/pki.mdx

@@ -1228,6 +1228,9 @@ use the values set via `config/urls`.
 - `key_type` `(string: "rsa")` - Specifies the desired key type; must be `rsa`, `ed25519`
   or `ec`.
 
+~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified
+   and thus should not be used: `ed25519`.
+
 - `key_bits` `(int: 0)` - Specifies the number of bits to use for the
   generated keys. Allowed values are 0 (universal default); with
   `key_type=rsa`, allowed values are: 2048 (default), 3072, or
@@ -1407,6 +1410,9 @@ generated depending on the `type` request parameter.
 - `key_type` `(string: "rsa")` - Specifies the desired key type; must be `rsa`, `ed25519`
   or `ec`. Not suitable for `type=existing` requests.
 
+~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified
+   and thus should not be used: `ed25519`.
+
 ~> **Note**: Keys of type `rsa` currently only support PKCS#1 v1.5 signatures.
    This includes any managed keys.
 
@@ -2110,6 +2116,9 @@ request is denied.
   existing CSRs, `any` can be specified to allow keys of either type
   and with any bit size (subject to >1024 bits for RSA keys).
 
+~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified
+   and thus should not be used: `ed25519`.
+
 - `key_bits` `(int: 0)` - Specifies the number of bits to use for the
   generated keys. Allowed values are 0 (universal default); with
   `key_type=rsa`, allowed values are: 2048 (default), 3072, or

website/content/api-docs/secret/ssh.mdx

@@ -231,6 +231,9 @@ This endpoint creates or updates a named role.
   with `ecdsa-sha2-nistp256` or `ed25519`), the value of the length is ignored (and
   can be zero).
 
+  ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified
+     and thus should not be used: `ed25519`.
+
 - `algorithm_signer` `(string: "default")` - Algorithm to sign keys with. Valid
   values are `ssh-rsa`, `rsa-sha2-256`, `rsa-sha2-512`, or `default`. This
   value may also be left blank to use the signer's default algorithm, and must
@@ -683,6 +686,9 @@ overridden._
   `ecdsa-sha2-nistp384`, `ecdsa-sha2-nistp521`, or `ssh-ed25519`) or an
   algorithm (`rsa`, `ec`, or `ed25519`).
 
+  ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified
+      and thus should not be used: `ed25519`.
+
 - `key_bits` `(int: 0)` - Specifies the desired key bits for the generated SSH
   CA key when `generate_signing_key` is set to `true`. This is only used for
   variable length keys (such as `ssh-rsa`, where the value of `key_bits`

website/content/api-docs/secret/transit.mdx

@@ -64,6 +64,9 @@ values set here cannot be changed after key creation.
   - `rsa-3072` - RSA with bit size of 3072 (asymmetric)
   - `rsa-4096` - RSA with bit size of 4096 (asymmetric)
 
+  ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified
+     and thus should not be used: `chacha20-poly1305` and `ed25519`.
+
 - `auto_rotate_period` `(duration: "0", optional)` – The period at which
   this key should be rotated automatically. Setting this to "0" (the default)
   will disable automatic key rotation. This value cannot be shorter than one
@@ -73,7 +76,7 @@ values set here cannot be changed after key creation.
 
 ```json
 {
-  "type": "ed25519",
+  "type": "ecdsa-p256",
   "derived": true
 }
 ```
@@ -720,6 +723,10 @@ algorithm.
   - `sha3-384`
   - `sha3-512`
 
+  ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified
+     and thus should not be used: `sha3-224`, `sha3-256`, `sha3-384`, and
+     `sha3-512`.
+
 - `input` `(string: <required>)` – Specifies the **base64 encoded** input data.
 
 - `format` `(string: "hex")` – Specifies the output encoding. This can be either
@@ -786,6 +793,10 @@ be used.
   - `sha3-384`
   - `sha3-512`
 
+  ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified
+     and thus should not be used: `sha3-224`, `sha3-256`, `sha3-384`, and
+     `sha3-512`.
+
 - `input` `(string: "")` – Specifies the **base64 encoded** input data. One of
   `input` or `batch_input` must be supplied.
 
@@ -913,6 +924,10 @@ supports signing.
   - `sha3-384`
   - `sha3-512`
 
+  ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified
+     and thus should not be used: `sha3-224`, `sha3-256`, `sha3-384`, and
+     `sha3-512`.
+
   ~> ** Warning:** `sha1` should be considered a compromised algorithm and used
   only for legacy applications. Signing using SHA-1 can be blocked by operators by
   assigning the following policy corresponding to a named key:
@@ -1071,6 +1086,10 @@ data.
   - `sha3-384`
   - `sha3-512`
 
+  ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified
+     and thus should not be used: `sha3-224`, `sha3-256`, `sha3-384`, and
+     `sha3-512`.
+
   ~> ** Warning:** `sha1` should be considered a compromised algorithm. Signatures
   verified using the algorithm could be forgeries. Verification using SHA-1 can
   be blocked by operators by assigning the following policy corresponding to a

website/content/api-docs/system/tools.mdx

@@ -80,6 +80,10 @@ algorithm.
   - `sha3-384`
   - `sha3-512`
 
+  ~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified
+     and thus should not be used: `sha3-224`, `sha3-256`, `sha3-384`, and
+     `sha3-512`.
+
 - `input` `(string: <required>)` – Specifies the **base64 encoded** input data.
 
 - `format` `(string: "hex")` – Specifies the output encoding. This can be either

website/content/docs/enterprise/fips/fips1402.mdx

@@ -0,0 +1,159 @@
+---
+layout: docs
+page_title: Vault Enterprise FIPS 140-2 Inside
+description: |-
+  Vault Enterprise features a special build with FIPS 140-2 support built into
+  the Vault binary. This can directly be used for FIPS compliance.
+---
+
+# FIPS 140-2 Inside
+
+-> **Note**: This feature requires [Vault Enterprise Plus](https://www.hashicorp.com/products/vault/).
+
+Special builds of Vault Enterprise (marked with a `fips1402` feature name)
+include built-in support for FIPS 140-2 compliance. Unlike using Seal Wrap
+for FIPS compliance, this binary has no external dependencies on a HSM.
+
+To use this feature, you must have an active or trial license for Vault
+Enterprise Plus (HSMs). To start a trial, contact [HashiCorp
+sales](mailto:sales@hashicorp.com).
+
+## Using FIPS 140-2 Vault Enterprise
+
+FIPS 140-2 Inside versions of Vault Enterprise behave like non-FIPS versions
+of Vault. No restrictions are placed on algorithms; it is up to the operator
+to ensure Vault remains in a FIPS-compliant mode of operation. This means
+configuring some Secrets Engines to permit a limited set of algorithms (e.g.,
+forbidding ed25519-based CAs with PKI Secrets Engines).
+
+Because Vault Enterprise may return secrets in plain text, it is important to
+ensure the Vault server's `listener` configuration section utilizes TLS. This
+ensures secrets are transmitted securely from Server to Client. Additionally,
+note that TLSv1.3 will not work with FIPS 140-2 Inside, as HKDF is not a
+certified primitive. If TLSv1.3 is desired, it is suggested to front Vault
+Server with a FIPS-certified load balancer.
+
+A non-exhaustive list of potential compliance issues include:
+
+ - Using Ed25519 or ChaCha20+Poly1305 keys with the Transit Secrets Engine,
+ - Using Ed25519 keys as CAs in the PKI or SSH Secrets Engines,
+ - Using FF3-1/FPE in Transform Secrets Engine, or
+ - Using a Derived Key (using HKDF) for Agent auto-authing or the Transit
+   Secrets Engine.
+
+Hashicorp can only provide general guidance regarding using Vault Enterprise
+in a FIPS-compliant manner. We are not a NIST-certified testing laboratory
+and thus organizations may need to consult an approved auditor for final
+information.
+
+## Technical Details
+
+Vault Enterprise's FIPS 140-2 Inside binaries rely on a special version of the
+Go toolchain which include a FIPS-validated BoringCrypto version. To ensure
+your version of Vault Enterprise includes FIPS support, after starting the
+server, make sure you see a line with `Fips: Enabled`, such as:
+
+```
+                    Fips: FIPS 140-2 Enabled, BoringCrypto version 7
+```
+
+~> **Note**: FIPS 140-2 Inside binaries depend on cgo, which require that a
+   GNU C Library (glibc) Linux distribution be used to run Vault. We've
+   additionally opted to certify only on the AMD64 architecture at this time.
+   This means these binaries will not work on Alpine Linux based containers.
+
+### FIPS 140-2 Inside and External Plugins
+
+Vault Enterprise's built-in plugins are compiled into the Vault binary using
+the same Go toolchain version that compiled the core Vault; this results in
+these plugins having FIPS 140-2 compliance status as well. This same guarantee
+does not apply to external plugins.
+
+### Validating FIPS 140-2 Inside
+
+To validate that the FIPS 140-2 Inside binary correctly includes BoringCrypto,
+run `go tool nm` on the binary to get a symbol dump. On non-FIPS builds,
+searching for `goboringcrypto` in the output will yield no results, but on
+FIPS-enabled builds, you'll see many results with this:
+
+```
+$ go tool nm vault | grep -i goboringcrypto
+  4014d0 T _cgo_6880f0fbb71e_Cfunc__goboringcrypto_AES_cbc_encrypt
+  4014f0 T _cgo_6880f0fbb71e_Cfunc__goboringcrypto_AES_ctr128_encrypt
+  401520 T _cgo_6880f0fbb71e_Cfunc__goboringcrypto_AES_decrypt
+  401540 T _cgo_6880f0fbb71e_Cfunc__goboringcrypto_AES_encrypt
+  401560 T _cgo_6880f0fbb71e_Cfunc__goboringcrypto_AES_set_decrypt_key
+...additional lines elided...
+```
+
+All FIPS cryptographic modules must execute startup tests. BoringCrypto uses
+the `_goboringcrypto_BORINGSSL_bcm_power_on_self_test` symbol for this. To
+ensure the Vault Enterprise binary is correctly executing startup tests, use
+[GDB](https://www.sourceware.org/gdb/) to stop execution on this function to
+ensure it gets hit.
+
+```
+$ gdb --args vault server -dev
+...GDB startup messages elided...
+(gdb) break _goboringcrypto_BORINGSSL_bcm_power_on_self_test
+...breakpoint location elided...
+(gdb) run
+...additional GDB output elided...
+Thread 1 "vault" hit Breakpoint 1, 0x0000000000454950 in _goboringcrypto_BORINGSSL_bcm_power_on_self_test ()
+(gdb) backtrace
+#0  0x0000000000454950 in _goboringcrypto_BORINGSSL_bcm_power_on_self_test ()
+#1  0x00000000005da8f0 in runtime.asmcgocall () at /usr/local/hashicorp-fips-go-devel/src/runtime/asm_amd64.s:765
+#2  0x00007fffd07a5a18 in ?? ()
+#3  0x00007fffffffdf28 in ?? ()
+#4  0x000000000057ebce in runtime.persistentalloc.func1 () at /usr/local/hashicorp-fips-go-devel/src/runtime/malloc.go:1371
+#5  0x00000000005d8a49 in runtime.systemstack () at /usr/local/hashicorp-fips-go-devel/src/runtime/asm_amd64.s:383
+#6  0x00000000005dd189 in runtime.newproc (siz=6129989, fn=0x5d88fb <runtime.rt0_go+315>) at <autogenerated>:1
+#7  0x0000000000000000 in ?? ()
+```
+
+Exact output may vary.
+
+<div {...{"className":"alert alert-warning g-type-body"}}>
+
+**Note**: When executing Vault Enterprise within GDB, GDB must rewrite
+parts of the binary to permit stopping on the specified breakpoint. This
+results in the HMAC of the contained BoringCrypto library changing,
+breaking the FIPS integrity check. If execution were to be continued
+in the example above via the `continue` command, a message like the
+following would be emitted:
+
+```
+Continuing.
+FIPS integrity test failed.
+Expected: 18d35ae031f649825a4269d68d2e62583d060a31d359690f97b9c8bf8120cdf75b405f74be7018094da7eb5261f2f86d0f481cc3b5a9c7c432268d94bf91aad9
+Calculated: 111502a3201de3b23f54b29d79ca6a1a754f94ecfc57a379444aac0d3ada68bf3c06834e6d84e68599bdf763e28e2c994fcdaeac84adabd180b59cad5fc980bb
+
+Thread 1 "vault" received signal SIGABRT, Aborted.
+```
+
+This is expected. Rerunning Vault without GDB (or with no breakpoints
+set -- e.g., `delete 1`) will still result in this function executing, but
+with the FIPS integrity check succeeding.
+
+</div>
+
+### BoringCrypto Certification
+
+BoringCrypto Version 7 uses the following FIPS 140-2 Certificate and software
+version:
+
+ - NIST CMVP [Certificate #3678](https://csrc.nist.gov/Projects/Cryptographic-Module-Validation-Program/Certificate/3678).
+ - BoringSSL Release [`ae223d6138807a13006342edfeef32e813246b39`](https://github.com/google/boringssl/commit/ae223d6138807a13006342edfeef32e813246b39).
+
+The following algorithms were certified as part of this release:
+
+ - RSA in all key sizes greater than or equal to 2048 bits (tested at 2048
+   and 3072 bits),
+ - ECDSA and ECDH with P-224 (not accessible from Vault), P-256, P-384, and
+   P-521,
+ - AES symmetric encryption with 128/192/256-bit CBC, ECB, and CRT modes and
+   128/256-bit GCM modes,
+ - SHA-1 and SHA-2 (224, 256,384, and 512-bit variants),
+ - HMAC+SHA-2 with 224, 256, 384, and 512-bit variants of SHA-2,
+ - TLSv1.0/TLSv1.1 and TLSv1.2 KDFs,
+ - AES-256 based CRT_DRBG CS-PRNG.

website/content/docs/enterprise/fips/index.mdx

@@ -0,0 +1,24 @@
+---
+layout: docs
+page_title: Vault Enterprise FIPS
+description: An overview of FIPS compliance in Vault.
+---
+
+# FIPS
+
+The [Federal Information Processing Standard](https://www.nist.gov/federal-information-standards-fips)
+is a cryptography-focused certification standard for U.S. Government usage.
+
+Hashicorp's Vault Enterprise supports the modes of FIPS compliance documented below.
+
+## FIPS 140-2 Inside
+
+Vault Enterprise now includes release flavors with FIPS 140-2 compliant
+cryptography built into the Vault binary. More information on these releases
+can be found on the [FIPS 140-2 Inside](/docs/enterprise/fips/fips1402) page.
+
+## Seal Wrap
+
+Before our FIPS Inside effort, Vault [depended on](https://www.hashicorp.com/vault-compliance)
+an external HSM for FIPS 140-2 compliance. This uses the [Seal Wrap](/docs/enterprise/fips/sealwrap)
+functionality to wrap security relevant keys in an extra layer of encryption.

website/content/docs/enterprise/fips/sealwrap.mdx

@@ -0,0 +1,63 @@
+---
+layout: docs
+page_title: Vault Enterprise FIPS Seal Wrap
+description: |-
+  Vault Enterprise features a mechanism to wrap values with an extra layer of
+  encryption for supporting seals. This can be used for FIPS Compliance with
+  a certified HSM.
+---
+
+# Seal Wrap for FIPS Compliance
+
+-> **Note**: This feature requires [Vault Enterprise Plus](https://www.hashicorp.com/products/vault/).
+
+Vault Enterprise features a mechanism to wrap values with an extra layer of
+encryption for supporting [seals](/docs/configuration/seal). This adds an
+extra layer of protection and is useful in some compliance and regulatory
+environments, including FIPS 140-2 environments.
+
+To use this feature, you must have an active or trial license for Vault
+Enterprise Plus (HSMs). To start a trial, contact [HashiCorp
+sales](mailto:sales@hashicorp.com).
+
+## Using Seal Wrap
+
+See [the Enterprise documentation](/docs/enterprise/sealwrap) for instructions
+on how to use and enable Seal Wrap.
+
+## FIPS 140-2 Compliance
+
+Vault's Seal Wrap feature has been evaluated by Leidos for compliance with
+FIPS 140-2 requirements. When used with a FIPS 140-2-compliant HSM, Vault will
+store Critical Security Parameters (CSPs) in a manner that is compliant with
+KeyStorage and KeyTransit requirements. This is on by default for many parts of
+Vault and opt-in for each individual mount; see the Activating Seal Wrapping
+section below for details.
+
+[Download the current compliance letter](/docs/enterprise/sealwrap/Vault_Compliance_Letter_signed.pdf)
+
+### Updates Since The Latest FIPS Compliance Audit
+
+The following are values that take advantage of seal wrapping in the current
+release of Vault that have not yet been asserted as compliant by Leidos. The
+mechanism for seal wrapping is the same, they simply were not specifically
+evaluated by the auditors.
+
+- Root tokens
+- Replication secondary activation tokens
+- Client authentication information for the GCP Auth Backend
+- Client authentication information for the Kubernetes Auth Backend
+
+## Seal Wrap and Replication
+
+Because of the level of flexibility targeted for replication, values sent over
+replication connections do not currently meet KeyTransit requirements for FIPS
+140-2. Vault's clustering implementation does support best practices guidance
+given in FIPS 140-2, but the cryptographic implementation of TLS is not FIPS
+140-2 certified. We may look into providing certified TLS in the future for
+replication traffic; in the meantime, a transparent TCP proxy that supports
+certified FIPS 140-2 TLS (such as
+[stunnel](https://www.stunnel.org/index.html)) can be used for replication
+traffic if meeting KeyTransit requirements for replication is necessary.
+
+[configuration]: /docs/configuration

website/content/docs/enterprise/sealwrap.mdx

@@ -3,7 +3,7 @@ layout: docs
 page_title: Vault Enterprise Seal Wrap
 description: |-
   Vault Enterprise features a mechanism to wrap values with an extra layer of
-  encryption for supporting seals
+  encryption for supporting seals.
 ---
 
 # Seal Wrap
@@ -37,29 +37,6 @@ wrapping status will change. Similarly, if the flag is removed, it will be a
 lazy upgrade (which is the case when initially upgrading to a seal
 wrap-supporting version of Vault).
 
-## FIPS 140-2 Compliance
-
-Vault's Seal Wrap feature has been evaluated by Leidos for compliance with
-FIPS 140-2 requirements. When used with a FIPS 140-2-compliant HSM, Vault will
-store Critical Security Parameters (CSPs) in a manner that is compliant with
-KeyStorage and KeyTransit requirements. This is on by default for many parts of
-Vault and opt-in for each individual mount; see the Activating Seal Wrapping
-section below for details.
-
-[Download the current compliance letter](/docs/enterprise/sealwrap/Vault_Compliance_Letter_signed.pdf)
-
-### Updates Since The Latest FIPS Compliance Audit
-
-The following are values that take advantage of seal wrapping in the current
-release of Vault that have not yet been asserted as compliant by Leidos. The
-mechanism for seal wrapping is the same, they simply were not specifically
-evaluated by the auditors.
-
-- Root tokens
-- Replication secondary activation tokens
-- Client authentication information for the GCP Auth Backend
-- Client authentication information for the Kubernetes Auth Backend
-
 ## Activating Seal Wrapping
 
 For some values, seal wrapping is always enabled with a supporting seal. This
@@ -77,9 +54,6 @@ A given backend's author can specify which values should be seal-wrapped by
 identifying where CSPs are stored.  They may also choose to seal wrap all or none
 of their values.
 
-To see the current list of seal-wrapped data per backend type, see the latest
-audit letter and updates in the FIPS 140-2 Compliance section above.
-
 Note that it is often an order of magnitude or two slower to write to and read
 from HSMs or remote seals. However, values will be cached in memory
 un-seal-wrapped (but still encrypted by Vault's built-in cryptographic barrier)
@@ -98,14 +72,11 @@ In addition, it is possible to replicate from a Shamir-protected primary
 cluster to clusters that use HSMs when seal wrapping is required in downstream
 datacenters but not in the primary.
 
-Because of the level of flexibility targeted for replication, values sent over
+## FIPS Status
-replication connections do not currently meet KeyTransit requirements for FIPS
+
-140-2. Vault's clustering implementation does support best practices guidance
+See the [FIPS-specific Seal Wrap documentation](/docs/enterprise/fips/sealwrap)
-given in FIPS 140-2, but the cryptographic implementation of TLS is not FIPS
+for more information about using Seal Wrapping to achieve FIPS 140-2 compliance.
-140-2 certified. We may look into providing certified TLS in the future for
+Note that there are additional [FIPS considerations](/docs/enterprise/sealwrap#seal-wrap-and-replication)
-replication traffic; in the meantime, a transparent TCP proxy that supports
+regarding Seal Wrap usage and Vault Replication.
-certified FIPS 140-2 TLS (such as
-[stunnel](https://www.stunnel.org/index.html)) can be used for replication
-traffic if meeting KeyTransit requirements for replication is necessary.
 
 [configuration]: /docs/configuration

website/content/docs/secrets/transit.mdx

@@ -86,6 +86,9 @@ types also generate separate HMAC keys):
 - `rsa-4096`: 4096-bit RSA key; supports encryption, decryption, signing, and
   signature verification
 
+~> **Note**: In FIPS 140-2 mode, the following algorithms are not certified
+   and thus should not be used: `chacha20-poly1305` and `ed25519`.
+
 ## Convergent Encryption
 
 Convergent encryption is a mode where the same set of plaintext+context always

website/data/docs-nav-data.json

@@ -1933,7 +1933,24 @@
         "path": "enterprise/entropy-augmentation"
       },
       {
-        "title": "Seal Wrap / FIPS 140-2",
+        "title": "FIPS",
+        "routes": [
+          {
+            "title": "Overview",
+            "path": "enterprise/fips"
+          },
+          {
+            "title": "FIPS 140-2 Inside Vault",
+            "path": "enterprise/fips/fips1402"
+          },
+          {
+            "title": "Seal Wrap for FIPS 140-2",
+            "path": "enterprise/fips/sealwrap"
+          }
+        ]
+      },
+      {
+        "title": "Seal Wrap",
         "path": "enterprise/sealwrap"
       },
       {