Chainguard Container for go-fips

Container image for building Go applications with FIPS

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/go-fips:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

1.25 changes

The 1.25 images have the following differences compared to 1.24:

• GOEXPERIMENT=systemcrypto is now on by default and doesn't need to (but still can) be explicitly provided
• The GOFIPS environment variable has been removed. The recommended way to enable FIPS now is to set GODEBUG=fips140=on or to use to requirefips build tag

1.24 changes

The 1.24 images have switched to use microsoft/go toolchain. There are a few difference compared to 1.23:

• Additional guard-rails preventing missbuilding binaries
• GOEXPERIMENT name changed from missnamed 'boringssl' to 'systemcrypto'
• It still uses the same go-openssl bindings, OpenSSL and the same/existing certified Chainguard FIPS provider for OpenSSL
• All FIPS approved algorithms are executed through the OpenSSL FIPS provider, which it supports
• Unsupported algorithms automatically fallback to a native go implementation
• In particular, MD5 is accessible for non-security purposes (as commonly used as a CRC, rather than a secure hash)
• GOTOOLCHAIN environment variable is set to local to prevent accidental upgrades to a non-systemcrypto capable toolchain

For a go toolchain without any access to any historical or unapproved algorithms please use go-msft-fips image instead.

There are further developments needed in 1.25 to consolidate the available go toolchains with OpenSSL support (with/without FIPS, with/without fallbacks).

Go FIPS with OpenSSL

This image provides a Go toolchain for producing FIPS compliant binaries. For this purpose, the image is compiled with golang-fips/go (FIPS enabled Go using OpenSSL) patches applied. They are further enhanced to always default to FIPS mode, without ability to opt out.

Binaries built with this edition of go on Linux:

• Require OpenSSL at runtime
• Require OpenSSL FIPS provider at runtime
• Will abort execution if the above conditions are not satisfied

While 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. Specifically the following modules are patched to redirect to the OpenSSL FIPS provider:

• crypto
• crypto/tls
• subset of golang.org/x/crypto that use stock crypto primitives only

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

Note that the crypto/md5 algorithm implementation is available for non-cryptographically secure use cases only. If your application uses crypto/md5 or any other third-party golang cryptographic modules, engage with a CST testing laboratory for additional audit and certification needs.

Where otherwise possible, the Go Chainguard Image is built for compatibility with the Docker official image for Golang. For a non-FIPS Go toolchain, see the go Chainguard Image.

Go Compatibility

The go-fips Chainguard Image uses the glibc implementation of the C standard library, while the Alpine version of thegolang official Docker Image uses musl. See our article on glibc vs. musl on Chainguard Academy for an overview of the differences between these implementations.

Consider executing Go binaries from one of our FIPS-enabled runtime Chainguard Images, such as the glibc-openssl-fips Chainguard Image.

In Go 1.20, we default to using the new GODEBUG settings of tarinsecurepath=0 and zipinsecurepath=0. These can be disabled by clearing the GODEBUG environment variable or by setting them to 1. Learn more about these settings in the Go release notes.

Getting Started

Working with the go-fips Chainguard Image has the following limitations:

• Use native architecture builds (no-cross compilation)
• Ensure default build settings are used
• Do not customize toolchain -tags, GOEXPERIMENT, CGO_ENABLED

For more information on working with this Image, check out our Getting Started with the Go Chainguard Image guide on Chainguard Academy.

Interactive FIPS Verification

In this example, we'll build a test application and verify that the approved external cryptographic library and OpenSSL symbols are in use.

Run a container based on the go-fips image interactively:

docker run --rm -it --entrypoint bash -w /root cgr.dev/ORGANIZATION/go-fips:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

At the interactive prompt, install helloserver, a Golang demo application :

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

You should see output like the following:

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

We can now check the toolchain flags used to build the binary we just created:

go version -m go/bin/helloserver

This produces an output similar to the following:

go/bin/helloserver: go1.25.0
        path    golang.org/x/example/helloserver
        mod     golang.org/x/example/helloserver        v0.0.0-20250605160450-8b405629c4a5      h1:0JvruIGF0CrrXuph0bOeqKYj2LBuyxi2VVkpNL321EE=
        build   microsoft_systemcrypto=1
        build   -buildmode=exe
        build   -compiler=gc
        build   DefaultGODEBUG=asynctimerchan=1,containermaxprocs=0,decoratemappings=0,fips140=on,gotestjsonbuildtext=1,gotypesalias=0,httplaxcontentlength=1,httpmuxgo121=1,httpservecontentkeepheaders=1,multipathtcp=0,panicnil=1,randseednop=0,rsa1024min=0,tls10server=1,tls3des=1,tlsmlkem=0,tlsrsakex=1,tlssha1=1,tlsunsafeekm=1,updatemaxprocs=0,winreadlinkvolume=0,winsymlink=0,x509keypairleaf=0,x509negativeserial=1,x509rsacrt=0,x509sha256skid=0,x509usepolicies=0
        build   CGO_ENABLED=1
        build   CGO_CFLAGS=
        build   CGO_CPPFLAGS=
        build   CGO_CXXFLAGS=
        build   CGO_LDFLAGS=
        build   GOARCH=amd64
        build   GOFIPS140=latest
        build   GOOS=linux
        build   GOAMD64=v1

For FIPS verification, check that:

• The build CGO_ENABLED=1 setting is in place.
• The build microsoft_systemcrypto=1 is in place.
• The GOFIPS140=latest is in place.

You can also verify that OpenSSL symbols are used by the binary:

go tool nm go/bin/helloserver | grep -e OpenSSL_version

This produces an output similar to:

  6a4300 T _cgo_ba70ff964674_Cfunc__mkcgo_OpenSSL_version
  6a4340 T _cgo_ba70ff964674_Cfunc__mkcgo_OpenSSL_version_num
  6a46a0 T _cgo_ba70ff964674_Cfunc__mkcgo_available_OpenSSL_version_num
  a0ecf0 D _g_OpenSSL_version
  a0ece8 D _g_OpenSSL_version_num
  6acb90 T _mkcgo_OpenSSL_version
  6acbc0 T _mkcgo_OpenSSL_version_num
  6acba0 T _mkcgo_available_OpenSSL_version_num
  4fbe60 t vendor/github.com/golang-fips/openssl/v2/internal/ossl._Cfunc__mkcgo_OpenSSL_version.abi0
  4fbf00 t vendor/github.com/golang-fips/openssl/v2/internal/ossl._Cfunc__mkcgo_OpenSSL_version_num.abi0
  4fc380 t vendor/github.com/golang-fips/openssl/v2/internal/ossl._Cfunc__mkcgo_available_OpenSSL_version_num.abi0
  9a3898 d vendor/github.com/golang-fips/openssl/v2/internal/ossl._cgo_ba70ff964674_Cfunc__mkcgo_OpenSSL_version
  9a38a0 d vendor/github.com/golang-fips/openssl/v2/internal/ossl._cgo_ba70ff964674_Cfunc__mkcgo_OpenSSL_version_num
  9a38e0 d vendor/github.com/golang-fips/openssl/v2/internal/ossl._cgo_ba70ff964674_Cfunc__mkcgo_available_OpenSSL_version_num

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

Finally, let's verify that failing to use the allowed OpenSSL FIPS provider will prevent operation.

First, check the operation of the helloserver binary:

go/bin/helloserver

You should see the following message:

2024/11/14 20:37:30 serving http://localhost:8080

Press Control-C to stop the server.

Next, link the fipsmodule.cnf configuration file to /dev/null, which effectively invalidates FIPS configuration:

cp /etc/ssl/fipsmodule.cnf fipsmodule.cnf.back
ln -sf /dev/null /etc/ssl/fipsmodule.cnf

Now attempt to re-run the application server:

go/bin/helloserver

You should receive an error like the following:

panic: opensslcrypto: FIPS mode requested (environment variable GODEBUG=fips140=on) but not available: OpenSSL 3.5.2 5 Aug 2025

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

This shows that the helloserver binary panics when OpenSSL FIPS is disabled. Additionally, other software that uses OpenSSL will panic e.g. apk update.

You can restore the fipsmodule.cnf file to return to an operational state:

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

Web Application with Multi-Stage Build

The following build demonstrates an application that's accessible by HTTP server. The application renders a simple message that changes based on the URI. The example uses a multi-stage build, compiling a binary using the go-fips Chainguard Image and copying it to the glibc-openssl-fips Chainguard Image for execution.

First, create a project folder and change the working directory to that folder:

mkdir -p ~/greet-server && cd $_

Next, run the following command to write a main.go file defining our web application:

cat << 'EOF' > main.go
package main

import (
	"flag"
	"fmt"
	"html"
	"log"
	"net/http"
	"os"
	"runtime/debug"
	"strings"
)

func usage() {
	fmt.Fprintf(os.Stderr, "usage: helloserver [options]\n")
	flag.PrintDefaults()
	os.Exit(2)
}

var (
	greeting = flag.String("g", "Hello", "Greet with `greeting`")
	addr     = flag.String("addr", "0.0.0.0:8080", "address to serve")
)

func main() {
	// Parse flags.
	flag.Usage = usage
	flag.Parse()

	// Parse and validate arguments (none).
	args := flag.Args()
	if len(args) != 0 {
		usage()
	}

	// Register handlers. for greeting and version
	http.HandleFunc("/", greet)
	http.HandleFunc("/version", version)

	log.Printf("serving http://%s\n", *addr)
	log.Fatal(http.ListenAndServe(*addr, nil))
}

func version(w http.ResponseWriter, r *http.Request) {
	info, ok := debug.ReadBuildInfo()
	if !ok {
		http.Error(w, "no build information available", 500)
		return
	}

	fmt.Fprintf(w, "<!DOCTYPE html>\n<pre>\n")
	fmt.Fprintf(w, "%s\n", html.EscapeString(info.String()))
}

func greet(w http.ResponseWriter, r *http.Request) {
	name := strings.Trim(r.URL.Path, "/")
	if name == "" {
		name = "Linky 🐙"
	}

	fmt.Fprintf(w, "<!DOCTYPE html>\n")
	fmt.Fprintf(w, "%s, %s!\n", *greeting, html.EscapeString(name))
}
EOF

Next, run the following command to write a go.mod file listing dependencies:

cat << 'EOF' > go.mod
module chainguard.dev/greet-server

go 1.19
EOF

Write a Dockerfile to define your image build:

cat << EOF > Dockerfile
FROM cgr.dev/ORGANIZATION/go-fips:latest AS builder

COPY . /app
RUN cd /app && go build

FROM cgr.dev/ORGANIZATION/glibc-openssl-fips:latest
COPY --from=builder /app/greet-server /usr/bin/

EXPOSE 8080

ENTRYPOINT ["/usr/bin/greet-server"]
EOF

This Dockerfile uses a multi-stage build approach, compiling the application using the go Chainguard Image, then copying the binary to the glibc-openssl-fips Chainguard Image to serve.

Build the image, tagging it greet-server:

docker build . -t greet-server

Run the container:

docker run -p 8080:8080 greet-server

Visit http://0.0.0.0:8080/ using a web browser on your host machine. You should see the following:

Hello, Linky 🐙!

Changes to the URI will be routed to the application. Try visiting http://0.0.0.0:8080/Chainguard%20Customer. You should see the following output:

Hello, Chainguard Customer!

The application will also share version information at http://0.0.0.0:8080/version. We can see on that page that the binary has been compiled with OpenSSL:

go      go1.25.0
path    chainguard.dev/greet-server
mod     chainguard.dev/greet-server     (devel)
build   microsoft_systemcrypto=1
...
build   GOFIPS140=latest
...

If you're building a web application with the go-fips Chainguard Image, consider the nginx-fips Chainguard Image for use as a reverse proxy.

Documentation and Resources

• Chainguard Academy: FIPS-enabled Chainguard Images
• Go FIPS with OpenSSL
• Chainguard Academy: Getting Started with the Go Chainguard Image
• Video: Migrating a Dockerfile for a Go application to use Chainguard Images
• Blog Post: Statically Linking Go in 2022
• Blog Post: Building minimal and low CVE images for compiled languages
• Chainguard Academy: glibc vs. musl

What are Chainguard Containers?

Chainguard Containers are minimal container images that are secure by default.

In many cases, the Chainguard Containers tagged as :latest contain only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager. Chainguard Containers are built with Wolfi, our Linux undistro designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a -dev variant.

Although the -dev container image variants have similar security features as their more minimal versions, they feature additional software that is typically not necessary in production environments. We recommend using multi-stage builds to leverage the -dev variants, copying application artifacts into a final minimal container that offers a reduced attack surface that won’t allow package installations or logins.

Learn More

To better understand how to work with Chainguard Containers, please visit Chainguard Academy and Chainguard Courses.

In addition to Containers, Chainguard offers VMs and Libraries. Contact Chainguard to access additional products.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.