Chainguard Image for go-fips

Container image for building Go applications with FIPS

Chainguard Images are regularly-updated, minimal container images with low-to-zero CVEs.

Download this Image

This 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

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)]](https://github.com/golang-fips/go) 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.

First, set your organization to an environment variable.

ORGANIZATION=my-organization

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

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

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 go/bin/helloserver

This produces the following output:

go/bin/helloserver: go1.22.9 X:boringcrypto

This indicates the binary was built with X:boringcrypto experiment enabled as an indicator that FIPS is in use.

While the toolchain experiment is called boringcrypto, the actual implementation uses OpenSSL. We can check this by outputting additional build settings:

go version -m go/bin/helloserver

This produces the following output:

go/bin/helloserver: go1.22.9 X:boringcrypto
	path	golang.org/x/example/helloserver
	mod	golang.org/x/example/helloserver	v0.0.0-20241014184706-d7b0ac127859	h1:sq8V/Wkg4iphNC8gwX8Cta3KfyVLQgx8/uOEGp+6lmU=
	build	-buildmode=exe
	build	-compiler=gc
	build	DefaultGODEBUG=httplaxcontentlength=1,httpmuxgo121=1,panicnil=1,tls10server=1,tlsrsakex=1,tlsunsafeekm=1
	build	CGO_ENABLED=1
	build	CGO_CFLAGS=
	build	CGO_CPPFLAGS=
	build	CGO_CXXFLAGS=
	build	CGO_LDFLAGS=
	build	GOARCH=amd64
	build	GOEXPERIMENT=boringcrypto
	build	GOOS=linux
	build	GOAMD64=v1

For FIPS verification, check that:

• The build CGO_ENABLED=1 setting is in place.
• The build GOEXPERIMENT=boringcrypto setting 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 the following output:

  652830 T _cgo_91985741879f_Cfunc_go_openssl_OpenSSL_version
  966840 D _g_OpenSSL_version
  4df6a0 t vendor/github.com/golang-fips/openssl/v2._Cfunc_go_openssl_OpenSSL_version.abi0
  8d27f8 d vendor/github.com/golang-fips/openssl/v2._cgo_91985741879f_Cfunc_go_openssl_OpenSSL_version

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, modify the FIPS provider:

cp /etc/ssl/fipsmodule.cnf fipsmodule.cnf.back
cat fipsmodule.cnf.back | tr 89 98 > /etc/ssl/fipsmodule.cnf

Now attempt to re-run the application server:

go/bin/helloserver

You should receive the following error:

panic: opensslcrypto: can't enable FIPS mode for OpenSSL 3.4.0 22 Oct 2024: OSSL_PROVIDER_try_load
openssl error(s):
error:1C8000D4:Provider routines::invalid state
	providers/fips/self_test.c:262
...

This shows that the helloserver binary panics when OpenSSL FIPS fails integrity tests.

You can restore the fipsmodule.cnf file to revert 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 our image build. First, set your organization as an environment variable:

ORGANIZATION=my-organization

Use the following command to create the Dockerfile:

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 boringcrypto:

go	go1.22.9 X:boringcrypto

build	GOEXPERIMENT=boringcrypto

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

Contact Support

If you have a Zendesk account (typically set up for you by your Customer Success Manager) you can reach out to Chainguard's Customer Success team through our Zendesk portal.

What are Chainguard Images?

Chainguard Images are a collection of container images designed for security and minimalism.

Many Chainguard Images are distroless; they contain only an open-source application and its runtime dependencies. These images do not even contain a shell or package manager. Chainguard Images are built with Wolfi, our Linux undistro designed to produce container images that meet the requirements of a secure software supply chain.

The main features of Chainguard Images include:

• Minimal design, with no unnecessary software bloat
• Automated nightly builds to ensure Images are completely up-to-date and contain all available security patches
• High quality build-time SBOMs (software bills of materials) attesting the provenance of all artifacts within the Image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

-dev Variants

As mentioned previously, Chainguard’s distroless Images have no shell or package manager by default. This is great for security, but sometimes you need these things, especially in builder images. For those cases, most (but not all) Chainguard Images come paired with a -dev variant which does include a shell and package manager.

Although the -dev image variants have similar security features as their distroless versions, such as complete SBOMs and signatures, they feature additional software that is typically not necessary in production environments. The general recommendation is to use the -dev variants only to build the application and then copy all application artifacts into a distroless image, which will result in a final container image that has a minimal attack surface and won’t allow package installations or logins.

That being said, it’s worth noting that -dev variants of Chainguard Images are completely fine to run in production environments. After all, the -dev variants are still more secure than many popular container images based on fully-featured operating systems such as Debian and Ubuntu since they carry less software, follow a more frequent patch cadence, and offer attestations for what they include.

Learn More

To better understand how to work with Chainguard Images, we encourage you to visit Chainguard Academy, our documentation and education platform.