fipsutil: report which module is linked, not just the mode

Enabled() and Only() answer whether the process is in FIPS 140-3 mode. They
cannot answer which cryptographic module it is running, and the two are
independent: a process built without GOFIPS140 but run with
GODEBUG=fips140=on performs the integrity self-check, the known-answer
tests and the TLS restriction, yet does all of it with the toolchain's
in-tree crypto packages rather than a CMVP-validated code set. Nothing
observable distinguishes that from the real thing except the version, so a
caller with a certificate to point at had no way to tell.

Adds Version() (the module version, "latest" when no frozen module is
linked), BuildVersion() (the resolved GOFIPS140 build setting) and
Validated() (whether a frozen snapshot is linked at all).

Also fixes Only() on Go 1.26+. It decided by parsing the GODEBUG environment
variable, which misses a default baked in at build time by GOFIPS140 or a
//go:debug directive. A binary with //go:debug fips140=only and no
GODEBUG set reported Only() == false while genuinely being in only-mode.
crypto/fips140.Enforced, added in Go 1.26, is the runtime's own answer;
older toolchains keep the environment scan since they have nothing better.

crypto/fips140.Version and .Enforced are both Go 1.26, so the version-gated
halves are split out and the pre-1.26 build falls back to the recorded build
setting. That fallback carries the snapshot suffix ("v1.0.0-c2097c7c") where
Go 1.26 reports the formal version ("v1.0.0"); the doc comment says so.

Author: joshdrake

fipsutil/fipsutil.go

@@ -1,19 +1,15 @@
 //go:build go1.24
 
+// Package fipsutil reports how the running process relates to the FIPS 140-3
+// Go Cryptographic Module.
 package fipsutil
 
 import (
 	"crypto/fips140"
-	"os"
-	"strings"
+	"runtime/debug"
 	"sync"
 )
 
-var (
-	only bool
-	once sync.Once
-)
-
 // Enabled reports whether the cryptography libraries are operating in FIPS
 // 140-3 mode.
 //
@@ -26,24 +22,45 @@ func Enabled() bool {
 	return fips140.Enabled()
 }
 
-// Only reports whether the cryptography libraries are operating in FIPS 140-3
-// "only" mode. When in this mode, using non-approved cryptography functions
-// will return errors or panic.
-func Only() bool {
-	once.Do(func() {
-		if !fips140.Enabled() {
+var (
+	buildVersion     string
+	buildVersionOnce sync.Once
+)
+
+// BuildVersion returns the GOFIPS140 setting recorded in the binary, such as
+// "v1.0.0-c2097c7c", or the empty string if it was built without one.
+//
+// This is the resolved version rather than the value passed to the go command:
+// GOFIPS140=v1.0.0 is read through $GOROOT/lib/fips140/v1.0.0.txt and records
+// as the exact snapshot whose checksum is fixed in the module's security
+// policy.
+func BuildVersion() string {
+	buildVersionOnce.Do(func() {
+		info, ok := debug.ReadBuildInfo()
+		if !ok {
 			return
 		}
-
-		// Parse GODEBUG backwards as the last value is the correct one.
-		settings := strings.Split(os.Getenv("GODEBUG"), ",")
-		for i := len(settings) - 1; i >= 0; i-- {
-			if settings[i] == "fips140=only" {
-				only = true
+		for _, s := range info.Settings {
+			if s.Key == "GOFIPS140" {
+				buildVersion = s.Value
 				return
 			}
 		}
 	})
 
-	return only
+	return buildVersion
+}
+
+// Validated reports whether the binary links a frozen module snapshot rather
+// than the toolchain's in-tree crypto packages.
+//
+// It says nothing about whether FIPS 140-3 mode is currently on; use [Enabled]
+// for that.
+func Validated() bool {
+	switch BuildVersion() {
+	case "", "off", "latest":
+		return false
+	default:
+		return true
+	}
 }

fipsutil/fipsutil_go126.go

@@ -0,0 +1,25 @@
+//go:build go1.26
+
+package fipsutil
+
+import "crypto/fips140"
+
+// Only reports whether the cryptography libraries are operating in FIPS 140-3
+// "only" mode. When in this mode, using non-approved cryptography functions
+// will return errors or panic.
+//
+// Note that the Go project documents "only" mode as a best-effort mode for
+// testing, assessment and debugging that is not intended for production use.
+func Only() bool {
+	return fips140.Enforced()
+}
+
+// Version returns the FIPS 140-3 Go Cryptographic Module version, such as
+// "v1.0.0", when the program was built against a frozen module with GOFIPS140,
+// and "latest" otherwise.
+//
+// Only a concrete version ties a running process to a CMVP certificate;
+// "latest" ties it to nothing.
+func Version() string {
+	return fips140.Version()
+}

fipsutil/fipsutil_internal_test.go

@@ -0,0 +1,37 @@
+//go:build go1.24
+
+package fipsutil
+
+import "testing"
+
+// TestValidated exercises the classification Validated() applies. The build
+// setting it reads cannot be changed by a test, so the cached value is swapped
+// directly rather than the reading of it being mocked.
+func TestValidated(t *testing.T) {
+	tests := []struct {
+		buildVersion string
+		want         bool
+	}{
+		{"", false},
+		{"off", false},
+		{"latest", false},
+		{"v1.0.0-c2097c7c", true},
+		{"v1.26.0", true},
+	}
+
+	// Run the sync.Once now so the assignments below are not overwritten by a
+	// later first call.
+	BuildVersion()
+
+	saved := buildVersion
+	t.Cleanup(func() { buildVersion = saved })
+
+	for _, tt := range tests {
+		t.Run(tt.buildVersion, func(t *testing.T) {
+			buildVersion = tt.buildVersion
+			if got := Validated(); got != tt.want {
+				t.Errorf("Validated() with BuildVersion() = %q is %v, want %v", tt.buildVersion, got, tt.want)
+			}
+		})
+	}
+}

fipsutil/fipsutil_other.go

@@ -17,3 +17,25 @@ func Enabled() bool {
 func Only() bool {
 	return false
 }
+
+// Version returns the FIPS 140-3 Go Cryptographic Module version.
+//
+// On Go < 1.24 there is no such module, so it will always return "latest".
+func Version() string {
+	return "latest"
+}
+
+// BuildVersion returns the GOFIPS140 setting recorded in the binary.
+//
+// On Go < 1.24 GOFIPS140 does not exist, so it will always return "".
+func BuildVersion() string {
+	return ""
+}
+
+// Validated reports whether the binary links a frozen, validated module
+// snapshot.
+//
+// On Go < 1.24 it will always return false.
+func Validated() bool {
+	return false
+}

fipsutil/fipsutil_pre126.go

@@ -0,0 +1,59 @@
+//go:build go1.24 && !go1.26
+
+package fipsutil
+
+import (
+	"crypto/fips140"
+	"os"
+	"strings"
+	"sync"
+)
+
+var (
+	only bool
+	once sync.Once
+)
+
+// Only reports whether the cryptography libraries are operating in FIPS 140-3
+// "only" mode. When in this mode, using non-approved cryptography functions
+// will return errors or panic.
+//
+// Before Go 1.26 the runtime does not expose this, so it is inferred from the
+// GODEBUG environment variable. That misses a default baked in at build time
+// by GOFIPS140 or a //go:debug directive; Go 1.26 and later ask the runtime
+// directly and do not have that gap.
+func Only() bool {
+	once.Do(func() {
+		if !fips140.Enabled() {
+			return
+		}
+
+		// Parse GODEBUG backwards as the last value is the correct one.
+		settings := strings.Split(os.Getenv("GODEBUG"), ",")
+		for i := len(settings) - 1; i >= 0; i-- {
+			if settings[i] == "fips140=only" {
+				only = true
+				return
+			}
+		}
+	})
+
+	return only
+}
+
+// Version returns the FIPS 140-3 Go Cryptographic Module version when the
+// program was built against a frozen module with GOFIPS140, and "latest"
+// otherwise.
+//
+// crypto/fips140.Version was added in Go 1.26. Before that this reports the
+// resolved GOFIPS140 build setting instead, so it carries the snapshot suffix
+// ("v1.0.0-c2097c7c") where Go 1.26 and later report the formal version
+// ("v1.0.0"). Use [BuildVersion] when you want the resolved value on every
+// Go version.
+func Version() string {
+	if v := BuildVersion(); v != "" && v != "off" {
+		return v
+	}
+
+	return "latest"
+}

fipsutil/fipsutil_test.go

@@ -1,8 +1,41 @@
 package fipsutil
 
-import "testing"
+import (
+	"strings"
+	"testing"
+)
 
 func TestFipsUtil(t *testing.T) {
 	t.Log("fipsutil.Enabled() is", Enabled())
 	t.Log("fipsutil.Only() is", Only())
+	t.Log("fipsutil.Version() is", Version())
+	t.Log("fipsutil.BuildVersion() is", BuildVersion())
+	t.Log("fipsutil.Validated() is", Validated())
+}
+
+// TestInvariants asserts the relationships that must hold however the test
+// binary was built and run, so it passes under `go test`,
+// `GOFIPS140=v1.0.0 go test`, and any GODEBUG=fips140 override of either.
+func TestInvariants(t *testing.T) {
+	if Only() && !Enabled() {
+		t.Error("Only() implies Enabled()")
+	}
+
+	if Validated() {
+		// A frozen module was selected, so the version must be a concrete one
+		// and must agree with the recorded build setting. Go 1.26 and later
+		// report the formal version ("v1.0.0") while the build setting carries
+		// the snapshot suffix ("v1.0.0-c2097c7c"), so this is a prefix match.
+		if got := Version(); got == "latest" {
+			t.Error(`Validated() is true but Version() is "latest"`)
+		} else if !strings.HasPrefix(BuildVersion(), got) {
+			t.Errorf("BuildVersion() = %q, want it to start with Version() = %q", BuildVersion(), got)
+		}
+
+		return
+	}
+
+	if got := Version(); got != "latest" {
+		t.Errorf("Version() = %q, want %q when no frozen module is linked", got, "latest")
+	}
 }