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.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)]](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 module-mac portion of the FIPS provider which will invalidate it:

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. Additionally, other software that uses OpenSSL will segfault 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 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

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.