go/misc/boring

README.md

This directory holds build scripts for unofficial, unsupported distributions of Go+BoringCrypto.

Version strings

The distribution name for a Go+BoringCrypto release has the form <GoVersion>b<BoringCryptoVersion>, where <GoVersion> is the Go version the release is based on, and <BoringCryptoVersion> is an integer that increments each time there is a new release with different BoringCrypto bits. The <BoringCryptoVersion> is stored in the VERSION file in this directory.

For example, the first release is based on Go 1.8.3 is go1.8.3b1. If the BoringCrypto bits are updated, the next would be go1.8.3b2. If, after that, Go 1.9 is released and the same BoringCrypto code added to it, that would result in go1.9b2. There would likely not be a go1.9b1, since that would indicate Go 1.9 with the older BoringCrypto code.

Releases

The build.release script prepares a binary release and publishes it in Google Cloud Storage at gs://go-boringcrypto/, making it available for download at https://go-boringcrypto.storage.googleapis.com/<FILE>. The script records each published release in the RELEASES file in this directory.

The build.docker script, which must be run after build.release, prepares a Docker image and publishes it on hub.docker.com in the goboring organization. go1.8.3b1 is published as goboring/golang:1.8.3b1.

Release process

1. If the BoringCrypto bits have been updated, increment the number in VERSION, send that change out as a CL for review, get it committed, and run git sync.

2. Run build.release, which will determine the base Go version and the BoringCrypto version, build a release, and upload it.

3. Run build.docker, which will build and upload a Docker image from the latest release.

4. Send out a CL with the updated RELEASES file and get it committed.

Release process for dev.boringcrypto.go1.8.

In addition to the dev.boringcrypto branch, we have a dev.boringcrypto.go1.8 branch, which is BoringCrypto backported to the Go 1.8 release branch. To issue new BoringCrypto releases based on Go 1.8:

1. Do a regular release on the (not Go 1.8) dev.boringcrypto branch.

2. Change to the dev.boringcrypto.go1.8 branch and cherry-pick all BoringCrypto updates, including the update of the VERSION file. Mail them out and get them committed.

3. Back on the (not Go 1.8) dev.boringcrypto branch, run make.bash and then build.release <commit>, where <commit> is the latest commit on the dev.boringcrypto.go1.8 branch. The script will build a release and upload it.

4. Run build.docker.

5. Send out a CL with the updated RELEASES file and get it committed.

Building from Docker

A Dockerfile that starts with FROM golang:1.8.3 can switch to FROM goboring/golang:1.8.3b2 (see goboring/golang on Docker Hub) and should need no other modifications.

Building from Bazel

Starting from bazelbuild/rules_go tag 0.7.1, simply download the BoringCrypto-enabled Go SDK using go_download_sdk() before calling go_register_toolchains().

For example, to use Go 1.9.3 with BoringCrypto on Linux, use the following lines in WORKSPACE:

load("@io_bazel_rules_go//go:def.bzl", "go_rules_dependencies", "go_download_sdk", "go_register_toolchains")

go_rules_dependencies()

go_download_sdk(
    name = "go_sdk",
    sdks = {
       "linux_amd64": ("go1.9.3b4.linux-amd64.tar.gz", "db1997b2454a2f27669b849d2d2cafb247a55128d53da678f06cb409310d6660"),
    },
    urls = ["https://storage.googleapis.com/go-boringcrypto/{}"],
)

go_register_toolchains()

Note: you must not enable pure mode, since cgo must be enabled. To ensure that binaries are linked with BoringCrypto, you can set pure = "off" on all relevant go_binary rules.

Caveat

BoringCrypto is used for a given build only in limited circumstances:

• The build must be GOOS=linux, GOARCH=amd64.
• The build must have cgo enabled.
• The android build tag must not be specified.
• The cmd_go_bootstrap build tag must not be specified.

The version string reported by runtime.Version does not indicate that BoringCrypto was actually used for the build. For example, linux/386 and non-cgo linux/amd64 binaries will report a version of go1.8.3b2 but not be using BoringCrypto.

To check whether a given binary is using BoringCrypto, run go tool nm on it and check that it has symbols named *_Cfunc__goboringcrypto_*.

The program rsc.io/goversion will report the crypto implementation used by a given binary when invoked with the -crypto flag.