Backport FIPS 140-2 Documentation (#15555)

* 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> * Update FIPS documentation to clarify mlock (#15502) This clarifies a limitation of the FIPS based container images, to note that due to OpenShift requirements, we need to suggest ways of disabling mlock or allowing Vault to set mlock. * Link FIPS binary sources from the FIPS docs Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>
hashicorp · May 20, 2022 · 05c3b5a · 05c3b5a
1 parent 2014881
commit 05c3b5a
Show file tree

Hide file tree

Showing 10 changed files with 329 additions and 38 deletions.
diff --git a/website/content/api-docs/secret/pki.mdx b/website/content/api-docs/secret/pki.mdx
@@ -517,6 +517,9 @@ can be set in a CSR are supported.
 - `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
@@ -961,6 +964,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
@@ -1257,6 +1263,9 @@ overwrite the existing cert/key with new values.
 - `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

diff --git a/website/content/api-docs/secret/ssh.mdx b/website/content/api-docs/secret/ssh.mdx
@@ -229,6 +229,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
@@ -681,6 +684,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`

diff --git a/website/content/api-docs/secret/transit.mdx b/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
 }
 ```
@@ -715,6 +718,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
@@ -781,6 +788,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.
 
@@ -908,6 +919,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:
@@ -1066,6 +1081,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

diff --git a/website/content/api-docs/system/tools.mdx b/website/content/api-docs/system/tools.mdx
@@ -75,6 +75,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

diff --git a/website/content/docs/enterprise/fips/fips1402.mdx b/website/content/docs/enterprise/fips/fips1402.mdx
@@ -0,0 +1,175 @@
+---
+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.
+
+The FIPS 140-2 variant of Vault uses separate binaries; these are available
+from the following sources:
+
+ - From the [Hashicorp Releases Page](https://releases.hashicorp.com/vault),
+   ending with the `+ent.fips1402` and `+ent.hsm.fips1402` suffixes.
+ - From the [Docker Hub `hashicorp/vault-enterprise-fips`](https://hub.docker.com/r/hashicorp/vault-enterprise-fips)
+   container repository.
+ - From the [AWS ECR `hashicorp/vault-enterprise-fips`](https://gallery.ecr.aws/hashicorp/vault-enterprise-fips)
+   container repository.
+
+~> **Note**: When pulling the FIPS UBI-based images, note that they are
+   ultimately designed for OpenShift certification; consider either adding
+   the `--user root --cap-add IPC_LOCK` options, to allow Vault to enable
+   mlock, or use the `--env SKIP_SETCAP=1` option, to disable mlock
+   completely, as appropriate for your environment.
+
+## 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.
diff --git a/website/content/docs/enterprise/fips/index.mdx b/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.
diff --git a/website/content/docs/enterprise/fips/sealwrap.mdx b/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