crypto/fips140: add Version

[FiloSottile]

package fips140

// Version returns the FIPS 140-3 Go Cryptographic Module version (such as
// "v1.0.0") if building against a frozen module with GOFIPS140. Otherwise, it
// returns "latest". If an alias is in use (such as "inprogress") the actual
// resolved version is returned.
func Version() string

/cc @golang/security

[gabyhelp]

Related Issues

• crypto/internal/fips140: Version should return an empty string on latest #71820 (closed)
• cmd/go: add fips140 module selection mechanism #70200 (closed)

Related Code Changes

• crypto/internal/fips140: add Name and Version

Related Documentation

• FIPS 140-3 Compliance > The GOFIPS140 environment variable
• Go 1.24 Release Notes > Standard library > FIPS 140-3 compliance

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

[rolandshoemaker]

Given we recently resealed the zip file, and the current zip has a hash suffix, would Version return the version with, or without, the hash suffix? It seems not ideal if two programs, using two different versions of the zip file, would think they were using the same version based on the result of Version.

[FiloSottile]

The behavior of v1.0.0 and v1.0.0-c2097c7c is indistinguishable by the application, and the official version of the module according to the Security Policy is still v1.0.0, so I think it's best if this API returns "v1.0.0". It would also be annoying to have to catch both values everywhere v1.0.0 is special-cased (for example to avoid using a feature it doesn't support).

If the application really wants to tell them apart they can check the Go version, as if the change was in the standard library outside the module.

[neild]

I do not understand a version that doesn't change when the code changes, but perhaps this makes sense in the context of the FIPS process.

If this doesn't change when the code changes, then the documentation should be clear on that fact.

What's the use case for this function? You mention feature detection, but we can already do that with build tags.

[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.
— aclements for the proposal review group

[aclements]

Proposal discussion:

• Why didn't those non-user-visible changes bump it to "v1.0.1"? Because the version number is really a name that's known by the FIPS certification process. Due to rules, we can make certain types of changes without re-certifying, but changing the name as known by FIPS is not one of them.

• The full, unique version in the more traditional sense is available to the binary via runtime/debug.BuildInfo.

• Version could return two strings, but it's probably better to just explain that the version does not uniquely identify the compiled code, and to see runtime/debug.BuildInfo if they need that.

So, Version() string as an API makes sense, but let's expand the documentation to explain what the version means and how to get a version that uniquely identifies the compiled code if that's what you're looking for.

[rolandshoemaker]

// Version returns the FIPS 140-3 Go Cryptographic Module version (such as
// "v1.0.0"), as referenced in the Security Policy for the module, if building
// against a frozen module with GOFIPS140. Otherwise, it returns "latest". If an
// alias is in use (such as "inprogress") the actual resolved version is
// returned.
//
// The returned version may not uniquely identify the frozen module which was
// used to build the program, if there are multiple copies of the frozen module
// at the same version. The uniquely identifying version suffix can be found by
// checking the value of the GOFIPS140 setting in
// runtime/debug.BuildInfo.Settings.
func Version() string

[aclements]

Based on the discussion above, this proposal seems like a likely accept.
— aclements for the proposal review group

The proposal is given in #75301 (comment)