go-msft-fips

Container image for building Go applications with FIPS

Download this Image

The image is available on cgr.dev:

docker pull cgr.dev/chainguard-private/go-msft-fips:latest

Go FIPS with OpenSSL

This image provides go toolchain that produces FIPS compliant binaries. It is go toolchain compiled with microsoft/go patches applied. The image itself has the go binary itself compiled in FIPS compliant mode, and contains a CMVP certified OpenSSL FIPS provider.

The image has recommended environment variables set to compile binaries in enforcing mode.

• CGO_ENABLED=1
• GOFIPS=1
• GOEXPERIMENT=systemcrypto
• GOFLAGS=-tags=requirefips

Further documentation is available from upstream:

• README covering build and runtime options
• User Guide covering changes to individual golang standard library APIs

Whilst Chainguard's edition of OpenSSL FIPS is recommended, the resulting binaries are vendor-agnostic and can be used at runtime with OpenSSL FIPS providers on other OpenSSL FIPS hosts.

FIPS compliance is achieved by not using any native golang cryptographic functionality and redirecting all calls to OpenSSL at runtime.

If no other cryptographic algorithms are implemented or used, certification status will depend on the runtime OpenSSL FIPS certification. For Chainguard that is #4282 and the submitted rebrand of that.

Usage guidance

Default execution of the container has all of the recommended flags preset. The toolchain defaults to GOEXPERIMENT=systemcrypto, even when GOEXPERIMENT variable is unset.

• Use CGO_ENABLED=1
• Either compile applications with -tags=requirefips OR use GOFIPS=1 at runtime
• Ensure runtime environment has OpenSSL with FIPS provider (e.g. cgr.dev/chainguard-private/glibc-openssl-fips image)

Interactive build with FIPS operation validation

This section contains two examples of how you can use the Go FIPS Chainguard Image to build an example Go application. For more information on working with this Image, check out our Getting Started with the Go Chainguard Image guide.

Start interractive shell in the go-msft-fips image:

docker run --rm -ti --user root -w /root --entrypoint bash cgr.dev/chainguard-private/go-msft-fips:latest

User root is used here, to perform tampering with the FIPS module selfcheck after compiling and running the application.

Install a golang demo application helloserver:

# go install golang.org/x/example/helloserver@latest
go: downloading golang.org/x/example v0.0.0-20240205180059-32022caedd6a
go: downloading golang.org/x/example/helloserver v0.0.0-20240205180059-32022caedd6a

Observe toolchain flags used to build the binary:

# go version go/bin/helloserver
go/bin/helloserver: go1.23.1 X:systemcrypto

This indicates the binary was built with 1.23.1 version of go, with X:systemcrypto experiment enabled as an indicator that OpenSSL will be in use at runtime.

Observe further build settings used on the binary:

# go version -m go/bin/helloserver
go version -m go/bin/helloserver
go/bin/helloserver: go1.23.1 X:systemcrypto
	path	golang.org/x/example/helloserver
	mod	golang.org/x/example/helloserver	v0.0.0-20240906150555-4e46ff54a64b	h1:NeVassC3ZI5k1BFhmtaXxDQEE+yI1ULHg6E4bodS88s=
	build	-buildmode=exe
	build	-compiler=gc
	build	-tags=requirefips
	build	DefaultGODEBUG=asynctimerchan=1,gotypesalias=0,httplaxcontentlength=1,httpmuxgo121=1,httpservecontentkeepheaders=1,panicnil=1,tls10server=1,tls3des=1,tlskyber=0,tlsrsakex=1,tlsunsafeekm=1,winreadlinkvolume=0,winsymlink=0,x509keypairleaf=0,x509negativeserial=1
	build	CGO_ENABLED=1
	build	CGO_CFLAGS=
	build	CGO_CPPFLAGS=
	build	CGO_CXXFLAGS=
	build	CGO_LDFLAGS=
	build	GOARCH=amd64
	build	GOEXPERIMENT=systemcrypto
	build	GOOS=linux
	build	GOAMD64=v1

Observe the following settings are in place:

• build CGO_ENABLED=1 enables access to OpenSSL via CGO
• build GOEXPERIMENT=systemcrypto enables systemcrypto experiment
• build -tags=requirefips ensures FIPS mode is enforced at the binary startup

Verify that OpenSSL symbols are used by the binary:

# $ go tool nm go/bin/helloserver | grep -e OpenSSL_version
  404120 T _cgo_91985741879f_Cfunc_go_openssl_OpenSSL_version
  9520c8 D _g_OpenSSL_version
  4f0e00 T vendor/github.com/golang-fips/openssl/v2._Cfunc_go_openssl_OpenSSL_version.abi0
  921e60 D vendor/github.com/golang-fips/openssl/v2._cgo_91985741879f_Cfunc_go_openssl_OpenSSL_version

Note that golang-fips/openssl/v2 are the underlying bindings for all the available APIs, even if individual binary may not use all of them.

Verify binary execution with suitable OpenSSL FIPS provider (use Ctrl+C to terminate):

# go/bin/helloserver
2024/04/15 10:22:21 serving http://localhost:8080
^C

Now tamper with the fips provider to observe failure to start the application in FIPS mode

# cp /etc/ssl/fipsmodule.cnf /etc/ssl/fipsmodule.cnf.back
# sed -i 's|:*|:00|' /etc/ssl/fipsmodule.cnf
# go/bin/helloserver
go/bin/helloserver
panic: opensslcrypto: can't enable FIPS mode for OpenSSL 3.3.2 3 Sep 2024: OSSL_PROVIDER_try_load
	openssl error(s):
	error:1C8000D5:Provider routines::missing config data
		providers/fips/self_test.c:290
	error:1C8000E0:Provider routines::fips module entering error state
		providers/fips/self_test.c:388
	error:1C8000D8:Provider routines::self test post failure
		providers/fips/fipsprov.c:707
	error:078C0105:common libcrypto routines::init fail
		crypto/provider_core.c:969

goroutine 1 [running]:
crypto/internal/backend.init.1()
	/usr/lib/go/src/crypto/internal/backend/openssl_linux.go:85 +0x254

As you can see above helloserver panics when on startup OpenSSL FIPS fails self tests.

Now restore fipsmodule.cnf to get back into operational state:

cp /etc/ssl/fipsmodule.cnf.back /etc/ssl/fipsmodule.cnf

Dockerfile example

The following example Dockerfile builds a helloserver program in Go and copies it on top of the cgr.dev/chainguard-private/glibc-openssl-fips:latest base image:

FROM cgr.dev/chainguard-private/go-msft-fips:latest AS build

RUN go install golang.org/x/example/helloserver@latest

FROM cgr.dev/chainguard-private/glibc-openssl-fips:latest

COPY --from=build /home/nonroot/go/bin/helloserver /helloserver
CMD ["/helloserver"]

Run the following command to build the demo image and tag it as go-helloserver-fips:

docker build -t go-helloserver-fips .

Now you can run the image with:

docker run go-helloserver-fips