project documentation, helper scripts

Author: sipasing

docs/build.md

@@ -0,0 +1,38 @@
+# How to build a fips compliant go binary that includes golang-fips patches
+
+The easiest way to do is to simply clone this repo and run make. see a more comprehensive script at `scripts/build1.sh`
+
+```
+git clone https://github.com/golang-fips/go.git golang-fips
+cd golang-fips
+./scripts/full-initialize-repo.sh go$GOLANG_VER
+cd go/src
+./make.bash --no-clean
+```
+
+## Env variables
+
+`GOEXPERIMENT=strictfipsruntime` helps ensure a fips compliant binary is build.  Note that this is functionally equivalent of
+
+```
+GO_BUILDTAGS+="goexperiment.strictfipsruntime"
+```
+
+You can export more Go flags like `GO_GCFLAGS="-N -l"` to add symbols in the final binary.
+
+# Other way to apply fips patches
+
+Another way is to directly apply fips patches by downloading binaries for go and golang-fips.  see full script at `scripts/build2.sh`
+
+```
+wget https://github.com/golang/go/archive/refs/tags/go1.22.2.tar.gz
+wget https://github.com/golang-fips/go/archive/refs/tags/go1.22.2-1-openssl-fips.tar.gz
+tar -xf go1.22.2.tar.gz
+tar -xf go1.22.2-1-openssl-fips.tar.gz
+cd go-go1.22.2
+for patch in ../go-go1.22.2-1-openssl-fips/patches/*.patch; do
+    patch -p1 < "${patch}"
+done
+cd src
+./make.bash --no-clean
+```

docs/deps.md

@@ -0,0 +1 @@
+# Dependencies

docs/openssl.md

@@ -0,0 +1 @@
+# OpenSSL considerations

docs/overview.md

@@ -0,0 +1 @@
+# Overview here

docs/test-conf.md

@@ -0,0 +1 @@
+# Test configuration

scripts/build1.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# this script builds a go binary after applying openssl fips patches.
+
+set -x
+export GOLANG_VER=1.22.2
+TOP_DIR=/tmp/golang-fips/build1
+[[ -d $TOP_DIR ]] || mkdir -p $TOP_DIR
+cd $TOP_DIR
+[[ -d golang-fips ]] || git clone https://github.com/golang-fips/go.git golang-fips
+cd golang-fips
+./scripts/full-initialize-repo.sh go$GOLANG_VER
+cd go/src
+export GO_BUILDTAGS+="goexperiment.strictfipsruntime,!no_openssl"
+export CGO_ENABLED=1
+./make.bash --no-clean
+{ set +x ; } 2>/dev/null

scripts/build2.sh

@@ -0,0 +1,49 @@
+#! /usr/bin/env bash
+# this script builds a go binary after applying openssl fips patches one by one.
+#
+export GOLANG_VER=1.22.2
+export GOLANG_REL=1
+
+# variables to store tar file names
+GO_TAR_NAME=go$GOLANG_VER
+PATCH_TAR_NAME=go$GOLANG_VER-$GOLANG_REL-openssl-fips
+GO_SRC_TAR=$GO_TAR_NAME.tar.gz
+PATCH_TAR=$PATCH_TAR_NAME.tar.gz
+
+# after untar, the dir names are stored in PATCH_DIR and SRC_DIR
+SRC_DIR=go-$GO_TAR_NAME
+PATCH_DIR=go-$PATCH_TAR_NAME
+TOP_DIR=/tmp/golang-fips/build2
+# If the go src dir ends up in a weird state where in patches are failing to apply, you might want to remove the $TOP_DIR (rm -rf /tmp/golang-fips/build2) to start with a clean slate.
+PATCH_PATH=$TOP_DIR/$PATCH_DIR/patches
+
+# this file stores state of last applied patch, that way patches are not reapplied
+PATCH_STATE=$TOP_DIR/state
+set -x
+[[ -d $TOP_DIR ]] || mkdir -p $TOP_DIR
+cd $TOP_DIR
+
+[[ -f $GO_SRC_TAR ]] || wget -q --show-progress https://github.com/golang/go/archive/refs/tags/$GO_SRC_TAR
+[[ -f $PATCH_TAR ]] || wget -q --show-progress https://github.com/golang-fips/go/archive/refs/tags/$PATCH_TAR
+[[ -d $SRC_DIR ]] || tar -xf $GO_SRC_TAR
+[[ -d $PATCH_DIR ]] || tar -xf $PATCH_TAR
+
+cd $SRC_DIR
+{ set +x; } 2>/dev/null
+if [[ -f $PATCH_STATE && "$(cat $PATCH_STATE)" == "complete" ]]; then
+    echo "patches already applied. skipping"
+else
+    for patch in $PATCH_PATH/*.patch; do
+        patch -p1 < "${patch}"
+        [[ $? -eq 0 ]] || { echo "incomplete" > $PATCH_STATE; break; exit 1; }
+    done
+fi
+
+echo "complete" > $PATCH_STATE
+# patches have been supplied successfully, simply build like above.
+set -x
+cd src
+export GO_BUILDTAGS+="goexperiment.strictfipsruntime,!no_openssl"
+export CGO_ENABLED=1
+./make.bash --no-clean
+{ set +x; } 2>/dev/null