Doc updates for "FIPS 140-2 in Contour" (projectcontour#4813)

Fixes projectcontour#4794.

Signed-off-by: moeyui1 <894immyk@gmail.com>

Dockerfile

@@ -21,6 +21,7 @@ ARG BUILD_SHA
 ARG BUILD_VERSION
 ARG BUILD_CGO_ENABLED
 ARG BUILD_EXTRA_GO_LDFLAGS
+ARG BUILD_GOEXPERIMENT
 ARG TARGETOS
 ARG TARGETARCH
 
@@ -29,6 +30,7 @@ RUN --mount=type=cache,target=/root/.cache/go-build --mount=type=cache,target=/g
 		EXTRA_GO_LDFLAGS="${BUILD_EXTRA_GO_LDFLAGS}" \
 		GOOS=${TARGETOS} \
 		GOARCH=${TARGETARCH} \
+		GOEXPERIMENT=${BUILD_GOEXPERIMENT} \
 	    BUILD_VERSION=${BUILD_VERSION} \
 	    BUILD_SHA=${BUILD_SHA} \
 	    BUILD_BRANCH=${BUILD_BRANCH}

Makefile

@@ -49,6 +49,8 @@ BUILD_CGO_ENABLED ?= 0
 # Go module mirror to use.
 BUILD_GOPROXY ?= https://proxy.golang.org
 
+BUILD_GOEXPERIMENT ?= none
+
 # Sets GIT_REF to a tag if it's present, otherwise the short git sha will be used.
 GIT_REF = $(shell git describe --tags --exact-match 2>/dev/null || git rev-parse --short=8 --verify HEAD)
 # Used for Contour container image tag.
@@ -124,6 +126,7 @@ multiarch-build: ## Build and optionally push a multi-arch Contour container ima
 		--build-arg "BUILD_SHA=$(BUILD_SHA)" \
 		--build-arg "BUILD_CGO_ENABLED=$(BUILD_CGO_ENABLED)" \
 		--build-arg "BUILD_EXTRA_GO_LDFLAGS=$(BUILD_EXTRA_GO_LDFLAGS)" \
+		--build-arg "BUILD_GOEXPERIMENT=$(BUILD_GOEXPERIMENT)" \
 		$(DOCKER_BUILD_LABELS) \
 		$(IMAGE_TAGS) \
 		$(shell pwd)
@@ -137,6 +140,7 @@ container: ## Build the Contour container image
 		--build-arg "BUILD_SHA=$(BUILD_SHA)" \
 		--build-arg "BUILD_CGO_ENABLED=$(BUILD_CGO_ENABLED)" \
 		--build-arg "BUILD_EXTRA_GO_LDFLAGS=$(BUILD_EXTRA_GO_LDFLAGS)" \
+		--build-arg "BUILD_GOEXPERIMENT=$(BUILD_GOEXPERIMENT)" \
 		$(DOCKER_BUILD_LABELS) \
 		$(shell pwd) \
 		--tag $(IMAGE):$(VERSION)

changelogs/unreleased/4813-moeyui1-docs.md

@@ -0,0 +1 @@
+Update [FIPS 140-2 in Contour](https://projectcontour.io/guides/fips/) for Go 1.19+.

site/content/guides/fips.md

@@ -47,8 +47,23 @@ The Contour [Dockerfile][8] uses a multistage build that performs compilation in
 In order to minimize the `projectcontour/contour` image footprint, the final output image only consists of a single layer, containing a lone file: the statically compiled `contour` binary.
 The standard Contour build uses the upstream `golang` image as a build base, however we will have to swap that out to build Contour with BoringCrypto.
 
-We can use the Google-provided Go implementation that has patches on top of standard Go to enable integrating BoringCrypto.
-This is available to us in the [`goboring/golang`][9] container image we can use as a build base.
+### Go 1.19 and higher
+
+Starting with Go 1.19, you can simply add [`BUILD_GOEXPERIMENT=boringcrypto`][18] and some related arguments to enable integrating BoringCrypto for standard Go.
+
+```bash
+make container \
+  BUILD_GOEXPERIMENT=boringcrypto \
+  BUILD_CGO_ENABLED=1 \
+  BUILD_EXTRA_GO_LDFLAGS="-linkmode=external -extldflags=-static"
+```
+
+### Go 1.18 and lower
+
+For the Go version under 1.19, we can use the Google-provided Go implementation that has patches on top of standard Go to enable integrating BoringCrypto.
+This is available to us in the [`goboring/golang`][9] container image we can use as a build base. 
+Note that the latest version of  [`goboring/golang`][9] image on the Docker hub is `1.16.7b7`, find more versions [here][19] and pull the images on Google Artifact Registry following [this document][20].
+
 In addition, to ensure we can statically compile the `contour` binary when it is linked with the BoringCrypto C library, we must pass some additional arguments to the `make container` target.
 
 To perform the Contour image build with BoringCrypto, change directories to where you have the Contour source code checked out and run the following (replacing `<goboring-version-tag>` with the appropriate version of Go and BoringCrypto, see [here][10] for version specifics):
@@ -67,8 +82,11 @@ The command above can be broken down as follows:
 
 The container image build process should fail before export of the `contour` binary to the final image if the compiled binary is not statically linked.
 
+### Validation
+
 To be fully sure the produced `contour` binary has been compiled with BoringCrypto you must remove the `-s` flag from the base Contour `Makefile` to stop stripping symbols and run through the build process above.
-Then you will be able to inspect the `contour` binary with `go tool nm` to check for symbols containing the string `_Cfunc__goboringcrypto_`.
+Then you will be able to inspect the `contour` binary with `go tool nm` to check for symbols containing the string `_Cfunc__goboringcrypto_`. 
+Also, you can use the program [rsc.io/goversion][21]. It will report the crypto implementation used by a given binary when invoked with the `-crypto` flag.
 
 Once you have a `projectcontour/contour` image built, you can re-tag it if needed, push the image to a registry, and reference it in a Contour deployment to use it!
 
@@ -141,3 +159,7 @@ The critical communication paths and how they are set up to be FIPS compliant ar
 [15]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#envoy-v3-api-field-extensions-transport-sockets-tls-v3-tlsparameters-cipher-suites
 [16]: https://github.com/projectcontour/contour/releases/tag/v1.13.0
 [17]: https://pkg.go.dev/github.com/projectcontour/contour/pkg/config#pkg-variables
+[18]: https://pkg.go.dev/internal/goexperiment@go1.19
+[19]: https://go-boringcrypto.storage.googleapis.com/
+[20]: https://go.googlesource.com/go/+/dev.boringcrypto/misc/boring/README.md#releases
+[21]: https://godoc.org/rsc.io/goversion