What do GOFIPS140 at build time and GODEBUG=fips140 at run time each control in a Go binary?

## Two switches, deliberately separated FIPS 140-3 is a US federal standard for cryptographic modules. Since Go 1.24 the Go toolchain ships its own **Go Cryptographic Module** — the code under `crypto/internal/fips140`, written in Go, no C library involved — and gives you two independent controls over it: one at build time and one at process start. Confusing them is the most common mistake in this area, so take them one at a time. ### GOFIPS140 — a build setting `GOFIPS140` is read by the `go` command when it builds. Its default is `off`, which means the build behaves exactly as it always has. Any other value does **two** things at once: 1. **It picks which copy of the cryptographic source is compiled in.** With `GOFIPS140=latest` you get the toolchain's current tree. With a frozen version such as `GOFIPS140=v1.0.0` the `go` command unpacks a snapshot shipped in `GOROOT/lib/fips140` (module zips) into the module cache and compiles that instead. The reason snapshots exist is that external lab validation and certification apply to a specific, frozen copy of the code — not to whatever the tip of the Go tree happens to contain this month. So `latest` enables the mode without giving you a validated module, and a regulated build wants the pinned version. 2. **It stamps the default GODEBUG.** A binary built with any non-`off` `GOFIPS140` carries `fips140=on` as its default GODEBUG, so it starts in FIPS mode without anybody setting an environment variable at deploy time. Both facts are recorded in the binary. `go version -m ./svc` prints the build settings, and among them you will see `GOFIPS140=v1.0.0` and `DefaultGODEBUG=fips140=on`. The same data is available to the program itself through `runtime/debug.ReadBuildInfo`. That recorded metadata is what turns "we build this service in FIPS mode" from a claim into evidence. ### GODEBUG=fips140 — a run-time setting GODEBUG is Go's general mechanism for run-time behaviour toggles, read from the environment (layered over the binary's compiled-in default) once, at startup. The `fips140` setting takes three values: - **`off`** — normal behaviour. - **`on`** — cryptography runs through the Go Cryptographic Module, and the module verifies itself at load time. The linker lays the module's code and data out contiguously and records a hash of them; at startup the module re-hashes those sections and compares. If the check fails the program panics rather than proceeding with unverified cryptography. Non-approved algorithms still work in this mode. - **`only`** — everything `on` does, plus **strict enforcement**: calls into non-approved standard-library cryptography now fail. Where the API can return an error it returns one; where it cannot, it panics. The mode cannot be changed after the process starts — the self-check has to run before crypto package initialisation, so there is nothing to flip later. `crypto/fips140.Enabled()` (Go 1.24) reports whether the mode is on, and its documentation states the value cannot change during the run. Go 1.26 added `crypto/fips140.Enforced()`, which distinguishes strict `only` mode, `Version()`, which returns the module version in use, and `WithoutEnforcement(f func())`, which relaxes strict enforcement for the duration of one tightly scoped function. ### How they combine in practice The common recipe for a regulated service is to set `GOFIPS140` to a pinned snapshot in the release pipeline, so the shipped artefact defaults to FIPS mode, and to raise the environment to `GODEBUG=fips140=only` when the deployment must reject non-approved algorithms outright. Nothing stops you setting `GODEBUG=fips140=on` on a binary built with `GOFIPS140=off` — the run-time setting works on its own — but then you are running the toolchain's current cryptographic source rather than a validated snapshot, which is usually not what an auditor is asking about. One boundary worth being clear about: neither switch certifies your deployment. They select and enable a module that has been validated, and they constrain what the standard library will do. Whether your system as a whole satisfies a certification regime is a question about the regime and your security policy, not about these two environment variables. ### The short version to say out loud `GOFIPS140` is compile-time and does two jobs: choose the module snapshot, set the binary's default GODEBUG. `fips140` as a GODEBUG is run-time and does one: choose between off, on and strict `only`. Default is `off` on both. The state is readable at run time through `crypto/fips140` and inspectable on the artefact with `go version -m`.