A new platform for documentation and tutorials is launching soon.

We are migrating Vault documentation into HashiCorp Developer, our new developer experience.

Join Now
Type '/' to Search

»FIPS 140-2 Inside

Note: This feature requires Vault Enterprise Plus.

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.

»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.
  • Using Entropy Augmentation: because BoringCrypto uses its internal, FIPS 140-2 approved RNG, it cannot mix entropy from other sources. Attempting to use EA with FIPS 140-2 HSM enabled binaries will result in failures such as panic: boringcrypto: invalid code execution.

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:

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.

»Usage Restrictions

»Migration Restrictions

Hashicorp does not support in-place migrations from non-FIPS Inside versions of Vault to FIPS Inside versions of Vault, regardless of version. A fresh cluster installation is required to receive support. We generally recommend avoiding direct upgrades and replicated-migrations for several reasons:

  • Old entries remain encrypted with the old barrier key until overwritten, this barrier key was likely not created by a FIPS library and thus is not compliant.
  • Many secrets engines internally create keys; things like Transit create and store keys, but don't store any data (inside of Vault) -- these would still need to be accessible and rotated to a new, FIPS-compliant key. Any PKI engines would have also created non-compliant keys, but rotation of say, a Root CA involves a concerted, non-Vault effort to accomplish and must be done thoughtfully.

Combined, we suggest leaving the existing cluster in place, and carefully consider migration of specific workloads to the FIPS-backed cluster.

»Entropy Augmentation Restrictions

Entropy Augmentation does not work with FIPS 140-2 Inside. The internal BoringCrypto RNG is FIPS 140-2 certified and does not accept entropy from other sources. On Vault 1.11.0 and later, attempting to use Entropy Augmentation will result in a warning ("Entropy Augmentation is not supported...") and Entropy Augmentation will be disabled.

»TLS Restrictions

Vault Enterprise's FIPS modifications include restrictions to supported TLS cipher suites and key information. Only the following cipher suites are allowed:

Additionally, only the following key types are allowed in TLS chains of trust:

  • RSA 2048, 3072, 4096, 7680, and 8192-bit;
  • ECDSA P-256, P-384, and P-521.

Finally, only TLSv1.2 or higher is supported in FIPS mode. These are in line with recent NIST guidance and recommendations.

»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

                    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...

$ 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 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 ?? ()

$ 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.

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.

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.

»BoringCrypto Certification

BoringCrypto Version 7 uses the following FIPS 140-2 Certificate and software version:

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.

»Leidos Compliance

See the updated Leidos Compliance Letter (V Entr v1.10.0+entrfips) for FIPS Inside using the Boring Crypto Libraries for more details. All past letters are also available for reference.

What is the difference between Seal Wrap FIPS 140 compliance and the new FIPS Inside compliance?

  • Only the storage of sensitive entries (seal wrapped entries) is covered by FIPS-validated crypto when using Seal Wrapping.
  • The TLS connection to Vault by clients is not covered by FIPS-validated crypto when using Seal Wrapping (it is when using FIPS 140-2 Inside, per items 1, 2, 7, and 13 in the updated letter).
  • The generation of key material wasn't using FIPS-validated crypto in the Seal Wrap version (for example, the PKI certificates: item 8 in the updated FIPS 140-2 Inside letter; or SSH module: item 10 in the updated FIPS 140-2 Inside letter).
  • With Seal Wrapping, some entries were protected with FIPS-validated crypto, but all crypto in Vault wasn't FIPS certified. With FIPS 140-2 Inside, by default (if the algorithm is certified), Vault will be using the certified crypto implementation.