crypto: mechanism to enable FIPS mode

[FiloSottile]

As tracked in #69536 we are pursuing a FIPS 140-3 validation for the Go cryptography packages. This proposal is about the mechanism to selectively enable and disable FIPS mode.

All Linux binaries will be FIPS-capable, so there will be no need for a compile-time on-switch. We believe we can make the build-time overhead low enough that we can remove this entire layer of complexity, so there will be no need for a "FIPS build". Note however that the module will not be FIPS validated on all architectures¹.

A run-time GODEBUG flag, fips140 defaults to off but can be set to on to operate the binary in FIPS mode. Primarily, this enables the slower and more complex RNG system, and the slow runtime self-tests. The GODEBUG can also be set to only to make any non-approved crypto return errors.²

A build tag, fips140, can be used to switch the GODEBUG default from off to on. It has no other effect. This allows building arbitrary programs so that they will run in FIPS mode by default. Note that //go:debug annotations can also be used to enable or disable the GODEBUG.

If fips140=on is set (in any way) and the binary can't operate in FIPS mode (because it was not built for Linux or it was built for an architecture that was not validated, for example), the binary will immediately panic at runtime.

A new package, crypto/fips140 will be added with a single function Enabled() bool which can be used to check at runtime if the binary is operating in FIPS mode.

Changing the GODEBUG after the binary started is not supported, it will not result in compliant FIPS operations, and may or may not cause the binary to panic. This is unlikely to change.

This proposal does not address how to select the FIPS module to compile against, which will require either a go build flag or a build tag. We are discussing this with @rsc. By default, binaries will build against the latest unvalidated version of the module³, but it will be possible to select both the latest In Process modules and the latest certified module. This will be transparent, although some newly introduced functionality may not be available when compiling against frozen versions of the module.

/cc @golang/security @cpu

Footnotes

1. The current tentative plan is to validate on some Linux OSes on some amd64, arm64, mips64, ppc64le, and s390x. If you need specific OEs validated, reach out to me ASAP. ↩

2. We're aware this is usually less granularity than required by production applications, which sometimes need to use non-approved crypto for non-security purposes, as allowed by FIPS 140-3. We'll share precise plans later, but in short this only mode will be implemented in terms of an internal API that can be used by downstream forks (without explicit backward compatibility guarantees) to enforce such a fine-grained policy. We don't plan to provide an exposed upstream mechanism at this time. ↩

3. Running the latest unvalidated version in FIPS mode still makes sense in some settings, hopefully more and more over time. ↩

[gabyhelp]

Related Issues and Documentation

• crypto: obtain a FIPS 140-3 validation #69536
• crypto: FIPS Mode and Validation of Crypto Provider? #11658 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[qmuntal]

If changing the FIPS mode is not possible at runtime, it's a property fixed when building the binary, then IMO it would make sense to define fips140.Enabled as a const instead of as a func. This way it is clearer for that caller that the value can't change at runtime and that the compiler will strip any branch conditioned by fips140.Enabled.

Also, will FIPS mode affect the Go runtime behavior (or even other packages outside crypto)? If that's the case, then I would consider moving the fips140.Enabled flag to the runtime package.

[FiloSottile]

If changing the FIPS mode is not possible at runtime, it's a property fixed when building the binary, then IMO it would make sense to define fips140.Enabled as a const instead of as a func. This way it is clearer for that caller that the value can't change at runtime and that the compiler will strip any branch conditioned by fips140.Enabled.

The idea is that FIPS mode will be selected only at runtime, by the GODEBUG env var. I think you might have been confused by my poorly worded "Changing the GODEBUG at runtime is not supported", edited to "Changing the GODEBUG after the binary started is not supported". I just meant that you can't do os.Setenv halfway through the run.

Also, will FIPS mode affect the Go runtime behavior (or even other packages outside crypto)? If that's the case, then I would consider moving the fips140.Enabled flag to the runtime package.

There is a bit of runtime support, but I think logically the package makes more sense under crypto/. It will be a package with no dependencies anyway.

[aclements]

By default, binaries will build against the latest unvalidated version of the module3, but it will be possible to select both the latest In Process modules and the latest certified module.

Isn't it going to cause confusion that, by default, when you set the fips140 build tag, what you get is not actually FIPS 140 certified?

[FiloSottile]

Isn't it going to cause confusion that, by default, when you set the fips140 build tag, what you get is not actually FIPS 140 certified?

In general, "FIPS 140 certified" is more of a spectrum than a binary state, and for example with the new FedRAMP rules a binary that's in FIPS mode would be acceptable even if it's an updated version of the one that underwent validation.

Still, I agree that the build tag is confusing, also because people will end up assuming it does more than just set the default GODEBUG. Let's just drop it. Instead, we discussed with @rsc making the module version selection mechanism (which is out of scope for this proposal) also flip the GODEBUG default to on any time it's used.

[rsc]

The module details are a separate proposal, #70200.

[FiloSottile]

We've been discussing with @rolandshoemaker how to let applications enforce the use of NIST-approved algorithms implemented within the module, and for now we want to offer a coarse binary choice, and then add more fine-grained mechanisms in the future based on feedback.

We propose adding a third documented GODEBUG=fips140 option, enforce which:

• behaves like on
• makes crypto/tls and golang.org/x/crypto/ssh silently consider only FIPS-compliant algorithms (like crypto/tls/fipsonly in Go+BoringCrypto)
• makes non-approved cryptographic functions return errors or panic

The last point includes wholly non-approved algorithms implemented by the standard library or (an updated version of) golang.org/x/crypto, as well as approved algorithms used with non-approved parameters (such as HMAC with too short a key). This is to be considered a best-effort mechanism, since we can't for example detect applications implementing non-approved crypto with math/big or third-party modules, of course.

Here is a list of functions that would fail entirely:

• crypto/cipher.NewGCM
• crypto/cipher.NewGCMWithNonceSize
• crypto/cipher.NewGCMWithTagSize
• crypto/cipher.NewCFBDecrypter [p]
• crypto/cipher.NewCFBEncrypter [p]
• crypto/cipher.NewOFB [p]
• crypto/des.NewCipher
• crypto/des.NewTripleDESCipher
• crypto/dsa.GenerateKey
• crypto/dsa.GenerateParameters
• crypto/dsa.Sign
• crypto/dsa.Verify [p]
• crypto/ecdh.X25519.ECDH
• crypto/md5.New [p]
• crypto/md5.Sum [p]
• crypto/rand.Prime
• crypto/rc4.NewCipher
• crypto/rsa.EncryptPKCS1v15
• crypto/rsa.DecryptPKCS1v15
• crypto/sha1.New [p]
• crypto/sha1.Sum [p]
• golang.org/x/crypto/argon2.IDKey [p]
• golang.org/x/crypto/argon2.Key [p]
• golang.org/x/crypto/bcrypt.CompareHashAndPassword
• golang.org/x/crypto/bcrypt.GenerateFromPassword
• golang.org/x/crypto/blake2b.New*
• golang.org/x/crypto/blake2b.Sum* [p]
• golang.org/x/crypto/blake2s.New*
• golang.org/x/crypto/blake2s.Sum* [p]
• golang.org/x/crypto/blowfish.NewCipher
• golang.org/x/crypto/blowfish.NewSaltedCipher
• golang.org/x/crypto/cast5.NewCipher
• golang.org/x/crypto/chacha20.NewUnauthenticatedCipher
• golang.org/x/crypto/chacha20poly1305.New
• golang.org/x/crypto/chacha20poly1305.NewX
• golang.org/x/crypto/curve25519.ScalarBaseMult [p]
• golang.org/x/crypto/curve25519.ScalarMult [p]
• golang.org/x/crypto/curve25519.X25519
• golang.org/x/crypto/md4.New [p]
• golang.org/x/crypto/poly1305.New
• golang.org/x/crypto/poly1305.Sum [p]
• golang.org/x/crypto/poly1305.Verify [p]
• golang.org/x/crypto/ripemd160.New [p]
• golang.org/x/crypto/salsa20.XORKeyStream [p]
• golang.org/x/crypto/sha3.NewLekacyKeccak256 [p]
• golang.org/x/crypto/sha3.NewLekacyKeccak512 [p]
• golang.org/x/crypto/tea.NewCipher
• golang.org/x/crypto/tea.NewCipherWithRounds
• golang.org/x/crypto/twofish.NewCipher
• golang.org/x/crypto/xtea.NewCipher
• golang.org/x/crypto/xts.NewCipher

Note that scrypt is missing because it has been successfully described as approved due to its use of PBKDF2.

(Internally, we'll still let forks apply more fine-grained policy with a mechanism akin to #65265, but that's not part of this proposal.)

[ericlagergren]

crypto/cipher.NewGCM
crypto/cipher.NewGCMWithNonceSize
crypto/cipher.NewGCMWithTagSize

Doesn't this preclude AES-GCM?

[FiloSottile]

Doesn't this preclude AES-GCM?

It will require #69981, yes, or a special internal TLS mode we will probably not expose. That's FIPS 140-3 IG C.H for you.

[aclements]

We propose adding a third documented GODEBUG=fips140 option, enforce which:

Why would someone chose enforce versus on?

[FiloSottile]

Why would someone chose enforce versus on?

Having a FIPS module laying around is not enough to comply with anything, you also have to use it for all cryptographic operations, and use only its approved "services" (a NIST-ism for algorithms and modes). It's ok to do that by just being very careful not to use anything that's not approved, but enforce mode offers better assurance of it. Go+BoringCrypto doesn't have that mode (aside from crypto/tls/fipsonly) but some of the forks do.

[derekparker]

Why would someone chose enforce versus on?

Having a FIPS module laying around is not enough to comply with anything, you also have to use it for all cryptographic operations, and use only its approved "services" (a NIST-ism for algorithms and modes). It's ok to do that by just being very careful not to use anything that's not approved, but enforce mode offers better assurance of it. Go+BoringCrypto doesn't have that mode (aside from crypto/tls/fipsonly) but some of the forks do.

This mode I think is very important. Within the golang-fips/go fork we have a strict FIPS mode we operate in by default which essentially matches the description of enforce. It takes the burden off the consumer of the toolchain to ensure they are using the crypto libraries in a FIPS compliant way by ensuring any violation is met with an error and ensuring that higher level packages such as tls are also operating in a FIPS compliant way.

[aclements]

Okay, in that case why would someone chose on over enforce?

[aclements]

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.

[FiloSottile]

Okay, in that case why would someone chose on over enforce?

There's the concept of non-security purposes. E.g. the AWS APIs use MD5 as a checksum. That's not a security purpose, so it's allowed, but it involves the use of non-approved cryptography, so requires operating in on rather than enforce mode.

Ultimately, we'll want some finer-grained mechanism to make that coexist with the safety of enforce, but I don't think we can design it for Go 1.24, and having the two modes matches what's being used in the field at the moment.

[FiloSottile]

We noticed I called enforce mode force in the proposal and enforce in #70123 (comment). Both are kind of confusing. Let's go with only since in that mode you can only use FIPS 140-3 cryptography.

[aclements]

A new package, crypto/fips140 will be added with a single function Enabled() bool which can be used to check at runtime if the binary is operating in FIPS mode.

Does this need to distinguish on and only?

[aclements]

It's worth noting that we believe this will have little effect on binary size, even though all binaries will be built with the ability to turn on FIPS mode. We're not going to be compiling in two different crypto trees. There will be a little extra code to support the dynamic selection between off and on, but not much.

Does this need to distinguish on and only?

To be clear, I think we would still want an Enabled() bool function since that's all people care about the vast majority of the time. That also means we can add functions to interrogate this more deeply in the future if we need to. @rolandshoemaker says people will let us know if they need this. :)

[aclements]

Based on the discussion above, this proposal seems like a likely accept.

The proposal is to add a fips140 GODEBUG setting that can take the following three values:

• fips140=off - The binary does not operate in FIPS mode.
• fips140=on - The binary operates in FIPS mode. Primarily, this enables the slower and more complex RNG system, and the slow runtime self-tests. If for any reason the binary can't operate in FIPS mode, it will immediately panic during startup.
• fips140=only - Like "on", but additionally any non-approved crypto will return errors.

The default value of fips140 will depend on the GOFIPS140 build-time environment variable (see #70200), but if no GOFIPS140 is set, it defaults to off.

The fips140 GODEBUG cannot be changed at runtime. Attempting to do so may or may not panic.

A new package, crypto/fips140 will be added with a single function Enabled() bool which can be used to check at runtime if the binary is operating in FIPS mode.

[gopherbot]

Change https://go.dev/cl/629816 mentions this issue: cmd/go: add GOFIPS140 to 'go help environment'

[gopherbot]

Change https://go.dev/cl/630115 mentions this issue: all: rename crypto/internal/fips to crypto/internal/fips140

[aclements]

No change in consensus, so accepted. 🎉
This issue now tracks the work of implementing the proposal.

The proposal is to add a fips140 GODEBUG setting that can take the following three values:

• fips140=off - The binary does not operate in FIPS mode.
• fips140=on - The binary operates in FIPS mode. Primarily, this enables the slower and more complex RNG system, and the slow runtime self-tests. If for any reason the binary can't operate in FIPS mode, it will immediately panic during startup.
• fips140=only - Like "on", but additionally any non-approved crypto will return errors.

The default value of fips140 will depend on the GOFIPS140 build-time environment variable (see #70200), but if no GOFIPS140 is set, it defaults to off.

The fips140 GODEBUG cannot be changed at runtime. Attempting to do so may or may not panic.

A new package, crypto/fips140 will be added with a single function Enabled() bool which can be used to check at runtime if the binary is operating in FIPS mode.

[gopherbot]

Change https://go.dev/cl/631017 mentions this issue: crypto/fips140: new package

[gopherbot]

Change https://go.dev/cl/631018 mentions this issue: crypto: implement fips140=only mode

[liggitt]

The description says:

A run-time GODEBUG flag, fips140 defaults to off but can be set to on to operate the binary in FIPS mode
...
Changing the GODEBUG after the binary started is not supported

The accepted summary says:

The fips140 GODEBUG cannot be changed at runtime. Attempting to do so may or may not panic.

For clarity, is the description still accurate, that the fips140 GODEBUG can be set at runtime but not changed after the binary started? Or did the proposal shift to make this a build-time decision only?

[FiloSottile]

the fips140 GODEBUG can be set at runtime but not changed after the binary started

Correct. The summary probably left "after the binary started" implied.