From 4ee4caabe977bf0554878ec36bd05d03faf2d840 Mon Sep 17 00:00:00 2001 From: qmuntal Date: Mon, 10 Feb 2025 15:40:40 +0100 Subject: [PATCH] correct references to Microsoft build of Go --- README.md | 8 ++--- docs/go1.23.md | 2 +- eng/README.md | 8 ++--- eng/_util/cmd/sign/README.md | 2 +- eng/_util/cmd/sign/sign.go | 2 +- eng/_util/go-install.ps1 | 28 +++++++-------- eng/doc/CrossPlatformCryptography.md | 22 ++++++------ eng/doc/DeveloperGuide.md | 12 +++---- eng/doc/fips/README.md | 34 +++++++++---------- eng/doc/fips/UserGuide.md | 10 +++--- eng/pipeline/stages/run-stage.yml | 2 +- eng/run.ps1 | 4 +-- eng/signing/README.md | 2 +- patches/0002-Vendor-crypto-backends.patch | 2 +- patches/0004-Use-crypto-backends.patch | 6 ++-- .../0008-remove-long-path-support-hack.patch | 4 +-- patches/README.md | 4 +-- 17 files changed, 76 insertions(+), 76 deletions(-) diff --git a/README.md b/README.md index 7064b0dc31c..a3d1fd14b70 100644 --- a/README.md +++ b/README.md @@ -108,17 +108,17 @@ The first step is to clone this repository using Git and check out the desired tag or commit. The `zip` file that GitHub offers for download is incomplete: it doesn't include the `go` submodule. -If you want to contribute to the Microsoft Go project, read the [Developer +If you want to contribute to the Microsoft for Go developers project, read the [Developer Guide](eng/doc/DeveloperGuide.md). It lists the steps we recommend to set up a -Microsoft Go development environment, execute your first Microsoft Go build, run +Microsoft build of Go development environment, execute your first build, run the standard library test suite, and contribute a PR. -If you just want to build Microsoft Go on your own machine, you may find it more +If you just want to build on your own machine, you may find it more convenient to use the tools provided by the `eng/run.ps1` script. We use this script for CI builds. See [eng/README.md](eng/README.md) for more details about `eng/run.ps1` and other repository infrastructure. -Once built, the Microsoft Go binary is found at `go/bin/go`. +Once built, the Microsoft build of Go binary is found at `go/bin/go`. ## Contributing diff --git a/docs/go1.23.md b/docs/go1.23.md index d9b9f56fa98..c99b2796226 100644 --- a/docs/go1.23.md +++ b/docs/go1.23.md @@ -1,3 +1,3 @@ -# Microsoft Go 1.23 release notes +# Microsoft build of Go 1.23 release notes After the release of 1.23, 1.21 is no longer supported, per the [Go release policy](https://go.dev/doc/devel/release). diff --git a/eng/README.md b/eng/README.md index 5f43b5fabb3..9a8786749f2 100644 --- a/eng/README.md +++ b/eng/README.md @@ -64,12 +64,12 @@ complete, to match the content of the official binary releases of Go. ## Patch files -The Microsoft Go repository uses patch files to store changes to the `go` +The Microsoft build of Go repository uses patch files to store changes to the `go` submodule. The patch files are found in [`/patches`](/patches). We created [the `git-go-patch` tool][git-go-patch] to develop and maintain the -patch files. We wrote this tool specifically for the Microsoft Go project. It's -a Go program that can be invoked as `git go-patch` after it's installed. See +patch files. We wrote this tool specifically for the Microsoft for Go developers project. +It's a Go program that can be invoked as `git go-patch` after it's installed. See [the `git-go-patch` readme][git-go-patch] for more information. We also have some utilities in this repository to apply patches without @@ -79,7 +79,7 @@ installing `git-go-patch`: patches. * Pass `-commits` to apply each patch as a separate commit. * `pwsh eng/run.ps1 build -refresh` refreshes the submodule and applies patches - and then goes on to build Microsoft Go. + and then goes on to build the Microsoft build of Go. The patch files are ordinary Git patches and can also be applied manually without any custom tooling. Git commands like [`git diff --git a/eng/_util/cmd/sign/README.md b/eng/_util/cmd/sign/README.md index a74a2beffdd..56f2794154c 100644 --- a/eng/_util/cmd/sign/README.md +++ b/eng/_util/cmd/sign/README.md @@ -1,4 +1,4 @@ -# `sign` and the Microsoft Go signing infrastructure +# `sign` and the Microsoft build of Go signing infrastructure Most of the logic for signing (extracting files, repackaging, creating checksums) is implemented by this `sign` command. diff --git a/eng/_util/cmd/sign/sign.go b/eng/_util/cmd/sign/sign.go index b91959a2a8e..587758e8062 100644 --- a/eng/_util/cmd/sign/sign.go +++ b/eng/_util/cmd/sign/sign.go @@ -20,7 +20,7 @@ import ( ) const description = ` -This command signs build artifacts using MicroBuild. It is used in the Microsoft Go build pipeline. +This command signs build artifacts using MicroBuild. It is used in the Microsoft build of Go build pipeline. Use '-n' to test the command locally. Signs in multiple passes. Some steps only apply to certain types of archives: diff --git a/eng/_util/go-install.ps1 b/eng/_util/go-install.ps1 index 29cc7fc9a13..b3f1cf3b1e7 100644 --- a/eng/_util/go-install.ps1 +++ b/eng/_util/go-install.ps1 @@ -3,14 +3,14 @@ <# .SYNOPSIS - Installs Microsoft Go + Installs the Microsoft build of Go .DESCRIPTION - Installs the Microsoft Go toolset. + Installs the Microsoft build of Go. Note that the intended use of this script is for Continuous Integration (CI) scenarios, where: - The toolset needs to be installed without user interaction and without admin rights. - The toolset installation doesn't need to persist across multiple CI runs. - Visit https://github.com/microsoft/go for a list of other ways to install Microsoft Go. + Visit https://github.com/microsoft/go for a list of other ways to install the Microsoft build of Go. .PARAMETER Version Default: Latest @@ -21,11 +21,11 @@ examples: go1.18, go1.23 - 3-part version in format go1.A.B - latest revision of a specific release. examples: go1.18.0, go1.23.1 - - 4-part version in format go1.A.B-C - a specific revision of Microsoft Go, immutable. + - 4-part version in format go1.A.B-C - a specific revision of the Microsoft build of Go, immutable. examples: go1.18.0-1, go1.23.1-3 - Microsoft Go doesn't publish prereleases, so they are not available. + The Microsoft build of Go doesn't publish prereleases, so they are not available. .PARAMETER InstallDir - Path to where to install Microsoft Go. Note that if a directory is given, GOROOT is placed + Path to where to install the Microsoft build of Go. Note that if a directory is given, GOROOT is placed directly in that directory. Default: - a folder automatically selected inside LocalApplicationData as evaluated by PowerShell. Example auto on Windows: C:\Users\myself\AppData\Local\microsoft-go\ @@ -42,9 +42,9 @@ Possible values are: , amd64, x64, 386, x86, arm64, arm .PARAMETER DryRun If set, it will not perform installation. Instead, it displays what command line to use to - consistently install currently requested version of Microsoft Go. For example, if you specify - Version 'Latest', it will print a command with the specific 4-part version so this command can - be used deterministicly in a build script. + consistently install currently requested version of the Microsoft build of Go. For example, + if you specify Version 'Latest', it will print a command with the specific 4-part version + so this command can be used deterministicly in a build script. It also prints the location the binaries would have been installed to. .PARAMETER NoPath By default, this script will update the environment variable PATH for the current process to @@ -75,10 +75,10 @@ Displays diagnostics information. .EXAMPLE go-install.ps1 - Installs the latest released Microsoft Go version. + Installs the latest released Microsoft build of Go version. .EXAMPLE go-install.ps1 -Version Previous - Installs the latest version of the previous major (1.X) version of Microsoft Go. + Installs the latest version of the previous major (1.X) version of the Microsoft build of Go. #> [cmdletbinding()] param( @@ -802,12 +802,12 @@ if ($Help) { exit } -Say "Microsoft Go Install Script version $MicrosoftGoInstallScriptVersion" +Say "Microsoft build of Go Install Script version $MicrosoftGoInstallScriptVersion" Say-Verbose "Note that the intended use of this script is for Continuous Integration (CI) scenarios, where:" Say-Verbose "- The toolset needs to be installed without user interaction and without admin rights." Say-Verbose "- The toolset installation doesn't need to persist across multiple CI runs." -Say-Verbose "Visit https://github.com/microsoft/go for a list of other ways to install Microsoft Go.`r`n" +Say-Verbose "Visit https://github.com/microsoft/go for a list of other ways to install the Microsoft build of Go.`r`n" Measure-Action "Product discovery" { $script:CLIArchitecture = Get-CLIArchitecture-From-Architecture $Architecture @@ -835,7 +835,7 @@ Say-Verbose "Found download link $DownloadLink with version $SpecificVersion" if (-Not $DryRun) { Say-Verbose "Checking if the version $SpecificVersion is already installed" if (Is-ToolsetInstalled -InstallRoot $InstallRoot -SpecificVersion $SpecificVersion) { - Say "Microsoft Go version '$SpecificVersion' is already installed." + Say "The Microsoft build of Go version '$SpecificVersion' is already installed." Measure-Action "Setting up shell environment" { Prepend-ToolsetPathEnv -InstallRoot $InstallRoot -SpecificVersion $SpecificVersion } return } diff --git a/eng/doc/CrossPlatformCryptography.md b/eng/doc/CrossPlatformCryptography.md index dbdf1829362..83638ff681d 100644 --- a/eng/doc/CrossPlatformCryptography.md +++ b/eng/doc/CrossPlatformCryptography.md @@ -1,7 +1,7 @@ -# Cross-Platform Cryptography in Microsoft Go +# Cross-Platform Cryptography in the Microsoft build of Go -Cryptographic operations in Microsoft Go are delegated to the operating system (OS) libraries in some conditions. -The high level conditions and the benefits of delegating cryptographic operations are described in the [Microsoft Go FIPS README](./fips/README.md). +Cryptographic operations in the Microsoft build of Go are delegated to the operating system (OS) libraries in some conditions. +The high level conditions and the benefits of delegating cryptographic operations are described in the [Microsoft build of Go FIPS README](./fips/README.md). At a fine-grained level, Go apps will fall back to the native Go implementation of an algorithm if the OS libraries don't support it. This article identifies the features that are supported on each platform. @@ -9,26 +9,26 @@ This article assumes you have a working familiarity with cryptography in Go. ## Platform support -Microsoft Go supports the following platforms: +The Microsoft build of Go supports the following platforms: ### Windows -On Windows, Microsoft Go uses the [CNG library (Cryptography API: Next Generation)](https://learn.microsoft.com/en-us/windows/win32/seccng/cng-portal) for cryptographic operations. +On Windows, the Microsoft build of Go uses the [CNG library (Cryptography API: Next Generation)](https://learn.microsoft.com/en-us/windows/win32/seccng/cng-portal) for cryptographic operations. CNG is available since Windows Vista and Windows Server 2008 and it doesn't require any additional installation nor configuration. ### Linux -On Linux, Microsoft Go uses the [OpenSSL crypto library](https://docs.openssl.org/3.0/man7/crypto/) for cryptographic operations. +On Linux, the Microsoft build of Go uses the [OpenSSL crypto library](https://docs.openssl.org/3.0/man7/crypto/) for cryptographic operations. OpenSSL is normally available on Linux distributions, but it may not be installed by default. If it is not installed, you can install it using the package manager of your distribution. OpenSSL 3 implements all the cryptographic algorithms using [Providers](https://docs.openssl.org/3.0/man7/crypto/#providers). -Microsoft Go officially supports the built-in providers and [SCOSSL (SymCrypt provider for OpenSSL)](https://github.com/microsoft/SymCrypt-OpenSSL) v1.6.1 or later. +The Microsoft build of Go officially supports the built-in providers and [SCOSSL (SymCrypt provider for OpenSSL)](https://github.com/microsoft/SymCrypt-OpenSSL) v1.6.1 or later. SCOSSL is expected to be used with the default built-in provider enabled as a fallback (which is the case when using [Azure Linux 3](https://github.com/microsoft/AzureLinux)). ## macOS -On macOS, Microsoft Go uses [CommonCrypto](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/Common%20Crypto.3cc.html) and [CryptoKit](https://developer.apple.com/documentation/cryptokit) for cryptographic operations. +On macOS, th Microsoft build Go uses [CommonCrypto](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/Common%20Crypto.3cc.html) and [CryptoKit](https://developer.apple.com/documentation/cryptokit) for cryptographic operations. CommonCrypto and CryptoKit are shipped with macOS and don't require any additional installation nor configuration. Currently macOS 13 and above is supported. @@ -42,7 +42,7 @@ The following legend describes the symbols used in the tables to indicate the le | ⚠️ | Supported with limitations that require special configuration action | | ❌ | Not supported | -When an algorithm is not supported or the limitations are exceeded, Microsoft Go will fall back to the Go implementation. +When an algorithm is not supported or the limitations are exceeded, the Microsoft build of Go will fall back to the Go implementation. ## Hash and Message Authentication Algorithms @@ -75,7 +75,7 @@ This section includes the following packages: | CSHAKE-256 | ❌ | ❌ | ❌ | | HMAC3 | ✔️ | ✔️ | ✔️ | -1Available starting in Microsoft Go 1.24. +1Available starting in the Microsoft build of Go 1.24. 2Requires OpenSSL 1.1.1 or later. @@ -167,7 +167,7 @@ Operations that require random numbers (rand io.Reader) only support [rand.Reade 1Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms). -2Available starting in Microsoft Go 1.24. +2Available starting in the Microsoft build of Go 1.24. 3On Windows, when verifying a PSS signature, [rsa.PSSSaltLengthAuto](https://pkg.go.dev/crypto/rsa#pkg-constants) is not supported. diff --git a/eng/doc/DeveloperGuide.md b/eng/doc/DeveloperGuide.md index 7f95f61ff70..65cae50fa63 100644 --- a/eng/doc/DeveloperGuide.md +++ b/eng/doc/DeveloperGuide.md @@ -1,6 +1,6 @@ # Developer Guide -This document is a guide for developers who want to contribute to the Microsoft Go repository. +This document is a guide for developers who want to contribute to the Microsoft build of Go repository. It explains how to build the repository, how to work with the Go submodule, and how to use the different tools that help maintain the repository. This guide is primarily intended for developers working for the Go team at Microsoft, but it can also be useful for external contributors. @@ -15,7 +15,7 @@ For details, visit https://cla.opensource.microsoft.com. ### Install a Go toolchain A preexisting Go toolchain is required to bootstrap the build process. -You can use your system's package manager to install Go, download Go from the [official Go website](https://golang.org/dl/), or download a prebuilt version of Microsoft Go itself. +You can use your system's package manager to install Go, download Go from the [official Go website](https://golang.org/dl/), or download a prebuilt version of the Microsoft build Go itself. The only requirement is that the Go version is high enough for the bootstrap process. If you attempt to build Go while using a bootstrap Go with a version that is too low, the bootstrap process will fail and ask you to install a newer version. @@ -23,13 +23,13 @@ If you attempt to build Go while using a bootstrap Go with a version that is too > [!NOTE] > The in-support versions of Go found on the [official Go website](https://golang.org/dl/) are always high enough to bootstrap the development branch. > This is because: -> * The [last two major versions of Go are supported by the Go project](https://go.dev/s/release#release-maintenance). (Microsoft Go has the same policy.) +> * The [last two major versions of Go are supported by the Go project](https://go.dev/s/release#release-maintenance). (the Microsoft build of Go has the same policy.) > * Go N can always be bootstrapped by [both N-1 and N-2](https://tip.golang.org/doc/install/source#go14). > [!NOTE] -> This repository's `eng/run.ps1` PowerShell script is able to download a correct bootstrapping Go version automatically before building Microsoft Go from source. -> We recommend that Microsoft Go team members be familiar with this script because it is used by Microsoft Go CI. -> However, it isn't necessary to use the script for most work on the Microsoft Go patches. +> This repository's `eng/run.ps1` PowerShell script is able to download a correct bootstrapping Go version automatically before building the Microsoft build of Go from source. +> We recommend that Microsoft developers team members be familiar with this script because it is used by our CI. +> However, it isn't necessary to use the script for most work on the Microsoft build of Go patches. > See the [`eng` Readme](/eng/README.md) for more information about `eng/run.ps1`. ### Install git and the git-go-patch command diff --git a/eng/doc/fips/README.md b/eng/doc/fips/README.md index ac20296f092..827b376dc87 100644 --- a/eng/doc/fips/README.md +++ b/eng/doc/fips/README.md @@ -23,9 +23,9 @@ In addition to that, the boringcrypto flag also provides a mechanism to restrict import _ "crypto/tls/fipsonly" ``` -## Microsoft Go fork FIPS compliance +## Microsoft build of Go FIPS compliance -The Microsoft Go fork modifies the Go runtime to implement several crypto primitives using cgo to call into a platform-provided cryptographic library rather than use the standard Go crypto implementations. This allows Go programs to use a platform-provided FIPS 140-2 certified crypto library. +The Microsoft build of Go modifies the Go runtime to implement several crypto primitives using cgo to call into a platform-provided cryptographic library rather than use the standard Go crypto implementations. This allows Go programs to use a platform-provided FIPS 140-2 certified crypto library. On Linux, the fork uses [OpenSSL](https://www.openssl.org/) through the [golang-fips/openssl] module in Go 1.21+ and the [go-crypto-openssl] module in earlier versions. On Windows, [CNG](https://docs.microsoft.com/en-us/windows/win32/seccng/about-cng), using [go-crypto-winnative]. Since 1.24, on macOS, [CommonCrypto](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/Common%20Crypto.3cc.html) and [CryptoKit](https://developer.apple.com/documentation/cryptokit) using [go-crypto-darwin]. Similar to BoringSSL, certain OpenSSL, CNG and CommonCrypto/CryptoKit versions are FIPS 140-2 certified. @@ -33,7 +33,7 @@ It is important to note that an application built with Microsoft's Go toolchain ## Configuration overview -The Microsoft Go fork provides several ways to configure the crypto backend and its behavior. These are described in the following sections in detail. +The Microsoft build of Go fork provides several ways to configure the crypto backend and its behavior. These are described in the following sections in detail. - Build-time configuration (`go build`): - [`GOEXPERIMENT=crypto` environment variable](#usage-build) @@ -54,7 +54,7 @@ The Microsoft Go fork provides several ways to configure the crypto backend and There are typically two goals that lead to this document. Creating a FIPS compliant app is one. The other is to comply with internal Microsoft crypto policies that have been set for Go. This table summarizes common configurations and how suitable each one is for these goals. > [!NOTE] -> This section assumes the use of Microsoft Go 1.24 or later. +> This section assumes the use of the Microsoft build of Go 1.24 or later. > > 1.24 introduces `GODEBUG=fips140=on` as a preferred way to enable FIPS mode. See also [the Go 1.24 changelog](#go-124-feb-2025). > @@ -117,10 +117,10 @@ If a crypto backend is selected but isn't supported, the build fails. For exampl > [!NOTE] > Prior to Go 1.21, instead of failing, the build automatically uses the Go standard library crypto implementation. This behavior can cause accidental or unclear fallback to Go crypto, silently breaking compliance with the internal Microsoft crypto policy. > -> In 1.21, this behavior was changed. Fallback is now opt-in with the `GOEXPERIMENT` `allowcryptofallback`. This option is primarily intended for internal use during the Microsoft Go build and should be avoided in general use. See [`allowcryptofallback`](#build-option-to-allow-go-standard-library-crypto-fallback) for more information. +> In 1.21, this behavior was changed. Fallback is now opt-in with the `GOEXPERIMENT` `allowcryptofallback`. This option is primarily intended for internal use during the Microsoft build of Go build and should be avoided in general use. See [`allowcryptofallback`](#build-option-to-allow-go-standard-library-crypto-fallback) for more information. -The Microsoft Go fork must be used for these `GOEXPERIMENT` values to work. See setup instructions in [the distribution section of the microsoft/go readme][microsoft-go-download]. +The Microsoft build of Go must be used for these `GOEXPERIMENT` values to work. See setup instructions in [the distribution section of the microsoft/go readme][microsoft-go-download]. > [!NOTE] > "Experiment" doesn't indicate the FIPS features are experimental. The original intent of `GOEXPERIMENT` is to use it to enable experimental features in the Go runtime and toolchain, but we and Google are now using `GOEXPERIMENT` for this FIPS-related feature because the mechanism itself perfectly fits our needs. @@ -129,14 +129,14 @@ The next sections describe how to select a crypto backend in some common scenari ### Dockerfile base image -Since Go 1.21, you can swap your Dockerfile's base image to the special Microsoft Go images marked with `-fips-`. These images include `env GOEXPERIMENT=systemcrypto` and are otherwise the same as the non`-fips-` images. These exist for convenience. See [the microsoft/go-images documentation][microsoft-go-images] for more information about available images and how to use them. +Since Go 1.21, you can swap your Dockerfile's base image to the special Microsoft build of Go images marked with `-fips-`. These images include `env GOEXPERIMENT=systemcrypto` and are otherwise the same as the non`-fips-` images. These exist for convenience. See [the microsoft/go-images documentation][microsoft-go-images] for more information about available images and how to use them. > [!NOTE] > Prior to Go 1.21, `-fips-` images do exist, but they are only available for Linux and include `env GOEXPERIMENT=opensslcrypto`. For this reason, these images can't easily be used to build Windows binaries on a Linux host. ### Dockerfile env instruction -If you don't use the standard Go base images (e.g. your Dockerfile downloads Microsoft Go manually), use an `env` instruction before the build instruction in your Dockerfile: +If you don't use the standard Go base images (e.g. your Dockerfile downloads the Microsoft build of Go manually), use an `env` instruction before the build instruction in your Dockerfile: ```dockerfile env GOEXPERIMENT=systemcrypto @@ -251,7 +251,7 @@ Refer to the [About Apple security certifications](https://support.apple.com/gui This means that setting `GOFIPS=1` or `GODEBUG=fips140=on` will never cause a panic on macOS. They are still necessary to instruct Go to run in FIPS mode, as there is no system-provided parameter to do so. -Prior to 1.24, CommonCrypto/CryptoKit is not used by Microsoft Go. +Prior to 1.24, CommonCrypto/CryptoKit is not used by the Microsoft build of Go. ## Usage: Extra configuration options @@ -308,7 +308,7 @@ A scenario we expect is that a dev attempts to rebuild an open source Go app wit > [!NOTE] > In rare cases, it may be more practical to use `allowcryptofallback` than to remove the `GOEXPERIMENT`. For example, a generic build script that supports many platforms, some of which don't support crypto backends, may find it practical to use `GOEXPERIMENT=systemcrypto,allowcryptofallback` despite the risk of unclear or accidental fallback to Go crypto. > -> For example, `allowcryptofallback` plays an important role in the Microsoft Go build process. We have CI jobs that run the build and tests under the OpenSSL, CNG, and Boring crypto backends, but parts of the upstream build and tests disable cgo and run cross-builds. This would cause a failure because the backend can't be enabled, but by including `allowcryptofallback`, the build is allowed to continue and fall back to the Go standard library crypto implementation when necessary. +> For example, `allowcryptofallback` plays an important role in the Microsoft build of Go build process. We have CI jobs that run the build and tests under the OpenSSL, CNG, and Boring crypto backends, but parts of the upstream build and tests disable cgo and run cross-builds. This would cause a failure because the backend can't be enabled, but by including `allowcryptofallback`, the build is allowed to continue and fall back to the Go standard library crypto implementation when necessary. ### Runtime OpenSSL version override @@ -350,7 +350,7 @@ Since Go 1.21: > Prior to the introduction of the systemcrypto alias in Go 1.21, the constraint is: `//go:build goexperiment.opensslcrypto && goexperiment.cngcrypto && goexperiment.boringcrypto`. -The `goexperiment.systemcrypto` tag's behavior is implemented in a Microsoft Go patch to the build system. It is not available in builds of upstream Go. The constraint `//go:build !goexperiment.systemcrypto` won't cause a build to fail with upstream Go, but it is always satisfied even if the BoringCrypto backend is enabled. +The `goexperiment.systemcrypto` tag's behavior is implemented in a patch to the build system. It is not available in builds of upstream Go. The constraint `//go:build !goexperiment.systemcrypto` won't cause a build to fail with upstream Go, but it is always satisfied even if the BoringCrypto backend is enabled. ## Features @@ -372,7 +372,7 @@ Not all OpenSSL versions are supported. OpenSSL does not maintain ABI compatibil Versions not listed above are not supported at all. > [!NOTE] -> Any build of OpenSSL might have various [OpenSSL features] enabled or disabled, diverging from the default configuration. Microsoft Go does not support all possible OpenSSL configurations. Some may cause the Go runtime to panic during initialization or not work as expected. +> Any build of OpenSSL might have various [OpenSSL features] enabled or disabled, diverging from the default configuration. The Microsoft build of Go does not support all possible OpenSSL configurations. Some may cause the Go runtime to panic during initialization or not work as expected. > > The Go runtime is tested with the default configuration of each supported OpenSSL version and with the OpenSSL configurations in the [Azure Linux] 2 and [Azure Linux] 3 distributions. @@ -384,7 +384,7 @@ For OpenSSL, Go uses [dlopen] when initializing. Sometimes this is called *dynam For CNG, Go uses Windows syscalls to call the CNG APIs. This can also not be considered *dynamic linking*, but like *dynamic loading*, syscalls also mean the app is using OS-provided crypto functionality. -It's common in the Go ecosystem to statically link all dependencies to produce a single binary that can run standalone (e.g. in a minimal Docker container). Unfortunately, the requirements of FIPS and the way it's implemented in Microsoft mean this is not possible for a Go program that uses the Microsoft Go runtime and FIPS features. If you are responsible for a Go app in Microsoft and this is impossible, contact the crypto board for more details. We opened an issue to discuss support for static linking: [microsoft/go#744 *OpenSSL static linking proposal*](https://github.com/microsoft/go/issues/744). However, as we learned this would not be considered FIPS compliant for use in Microsoft, we don't have any plans to implement it. +It's common in the Go ecosystem to statically link all dependencies to produce a single binary that can run standalone (e.g. in a minimal Docker container). Unfortunately, the requirements of FIPS and the way it's implemented in Microsoft mean this is not possible for a Go program that uses the Microsoft build of Go runtime and FIPS features. If you are responsible for a Go app in Microsoft and this is impossible, contact the crypto board for more details. We opened an issue to discuss support for static linking: [microsoft/go#744 *OpenSSL static linking proposal*](https://github.com/microsoft/go/issues/744). However, as we learned this would not be considered FIPS compliant for use in Microsoft, we don't have any plans to implement it. ### Portable OpenSSL @@ -396,7 +396,7 @@ This feature does not require any additional configuration, but it only works wi The Go TLS stack will automatically use crypto primitives from the selected crypto backend. Yet, this isn't enough for FIPS compliance: the FIPS 140-2 standard places additional restrictions on TLS communications, mainly on which cyphers and signers are allowed. Note that this can reduce compatibility with old devices that do not support modern cryptography techniques such as TLS 1.2. -Since Go 1.22, the Microsoft Go runtime automatically enforces that `crypto/tls` and `crypto/x509` only use FIPS-compliant settings when running in FIPS mode. This differs from upstream's BoringCrypto backend, which requires you to import `crypto/tls/fipsonly` to apply the FIPS-mandated restrictions. The Microsoft Go crypto backends do this automatically to reduce the source code changes necessary to produce a FIPS-compliant Go application, and to make it easier to use the same binary in both FIPS and non-FIPS environments. +Since Go 1.22, the Microsoft build of Go runtime automatically enforces that `crypto/tls` and `crypto/x509` only use FIPS-compliant settings when running in FIPS mode. This differs from upstream's BoringCrypto backend, which requires you to import `crypto/tls/fipsonly` to apply the FIPS-mandated restrictions. The Microsoft build of Go crypto backends do this automatically to reduce the source code changes necessary to produce a FIPS-compliant Go application, and to make it easier to use the same binary in both FIPS and non-FIPS environments. Prior to Go 1.22, a program using the Go TLS stack must import the `crypto/tls/fipsonly` package to be compliant with these restrictions. The configuration is done by an `init()` function, so only importing it is necessary: @@ -456,13 +456,13 @@ This list of major changes is intended for quick reference and for access to his - Upstream Go made this change for BoringCrypto, and we adopted it for our OpenSSL and CNG backends. See [the `dev.boringcrypto` branch readme](https://github.com/golang/go/blob/dev.boringcrypto/README.boringcrypto.md). For more details about the merge, see [golang/go#51940](https://github.com/golang/go/issues/51940). `dev.boringcrypto*` branches are no longer maintained. - Downloading a different toolset build to build FIPS vs. non-FIPS programs is no longer necessary. - Backend selection is done at compile time. The backend is always used by the resulting program, and it can't be changed at runtime. -- Only one Microsoft Go toolset is provided per platform. It supports building both FIPS and non-FIPS programs. +- Only one Microsoft build of Go is provided per platform. It supports building both FIPS and non-FIPS programs. ### Go 1.16 (Feb 2022) - OpenSSL (Linux) backend introduced. -- Introduction of FIPS features in the Microsoft Go fork based on the upstream `dev.boringcrypto*` branches of Go. -- The backend is only used if FIPS mode is requested (e.g. `GOFIPS=1`), otherwise Microsoft Go falls back to the Go standard library at runtime. +- Introduction of FIPS features in the Microsoft build of Go based on the upstream `dev.boringcrypto*` branches of Go. +- The backend is only used if FIPS mode is requested (e.g. `GOFIPS=1`), otherwise the Microsoft build of Go falls back to the Go standard library at runtime. - To build a FIPS-compliant program, a FIPS-specific toolset build must be downloaded and used. - For historical information about Go 1.16-1.18, see [the FIPS documentation in the 1.20 release branch](https://github.com/microsoft/go/tree/microsoft/release-branch.go1.20/eng/doc/fips). It includes details about FIPS in 1.18 and the changes in 1.19. diff --git a/eng/doc/fips/UserGuide.md b/eng/doc/fips/UserGuide.md index 7053637c545..af6c9599579 100644 --- a/eng/doc/fips/UserGuide.md +++ b/eng/doc/fips/UserGuide.md @@ -1,13 +1,13 @@ # FIPS 140-2 User Guide -This document is a user guide for the Microsoft Go crypto package running on FIPS 140-2 compatibility mode (hereafter referred to as FIPS). It is intended as a technical reference for developers using, and system administrators installing, the Go toolset, and for use in risk assessment reviews by security auditors. This is not a replacement for the Go crypto documentation, rather it is a collection of notes and more detailed explanations in the context of FIPS compatibility. +This document is a user guide for the Microsoft build of Go crypto package running on FIPS 140-2 compatibility mode (hereafter referred to as FIPS). It is intended as a technical reference for developers using, and system administrators installing, the Go toolset, and for use in risk assessment reviews by security auditors. This is not a replacement for the Go crypto documentation, rather it is a collection of notes and more detailed explanations in the context of FIPS compatibility. The Go crypto documentation is available online at https://pkg.go.dev/crypto. - [FIPS 140-2 User Guide](#fips-140-2-user-guide) - - [The Microsoft Go crypto backends](#the-microsoft-go-crypto-backends) + - [The Microsoft build of Go crypto backends](#the-microsoft-build-of-go-crypto-backends) - [Using Go crypto APIs](#using-go-crypto-apis) - [crypto/aes](#cryptoaes) - [func NewCipher](#func-newcipher) @@ -95,11 +95,11 @@ The Go crypto documentation is available online at https://pkg.go.dev/crypto. - [crypto/subtle](#cryptosubtle) - [crypto/tls](#cryptotls) -## The Microsoft Go crypto backends +## The Microsoft build of Go crypto backends The OpenSSL backend uses [golang-fips/openssl]. The CNG backend uses [go-crypto-winnative]. -For more general information about the backends, such as how to enable them, see the [Microsoft Go FIPS README](./README.md). +For more general information about the backends, such as how to enable them, see the [Microsoft build of Go FIPS README](./README.md). [golang-fips/openssl]: https://github.com/golang-fips/openssl [go-crypto-winnative]: https://github.com/microsoft/go-crypto-winnative @@ -1697,7 +1697,7 @@ Package tls partially implements TLS 1.2, as specified in RFC 5246, and TLS 1.3, Package tls will automatically use FIPS compliant primitives implemented in other crypto packages. -Since Go 1.22, the Microsoft Go runtime automatically enforces that tls only uses FIPS-approved settings when running in FIPS mode. +Since Go 1.22, the Microsoft build of Go runtime automatically enforces that tls only uses FIPS-approved settings when running in FIPS mode. Prior to Go 1.22, a program using tls must import the `crypto/tls/fipsonly` package to be compliant with these restrictions. When using TLS in FIPS-only mode the TLS handshake has the following restrictions: diff --git a/eng/pipeline/stages/run-stage.yml b/eng/pipeline/stages/run-stage.yml index 328b724fc73..f9e8bc7f17f 100644 --- a/eng/pipeline/stages/run-stage.yml +++ b/eng/pipeline/stages/run-stage.yml @@ -94,7 +94,7 @@ stages: - name: MS_GO_UTIL_ALLOW_ONLY_MINIMAL_DEPS value: '1' - # On darwin (macOS) we haven't released a Microsoft Go toolchain. + # On darwin (macOS) we haven't released a Microsoft build Go toolchain. - ${{ if eq(parameters.builder.os, 'darwin') }}: - name: MS_USE_PATH_GO value: '1' diff --git a/eng/run.ps1 b/eng/run.ps1 index d3cebeafba8..8fa0dfe07f2 100644 --- a/eng/run.ps1 +++ b/eng/run.ps1 @@ -17,8 +17,8 @@ To list all possible tools: Builds 'eng/_util/cmd//.go' and runs it using the list of arguments. -This command automatically installs a known version of Microsoft Go that will be -used to build the tools. The known version of Go will also be used to build the +This command automatically installs a known version of the Microsoft build Go that +will be used to build the tools. The known version of Go will also be used to build the Go source code, if it's built. Set environment variable "MS_USE_PATH_GO" to 1 to your own Go from PATH instead. diff --git a/eng/signing/README.md b/eng/signing/README.md index 2ffc00ab368..5062fda3f25 100644 --- a/eng/signing/README.md +++ b/eng/signing/README.md @@ -1,6 +1,6 @@ # MSBuild signing infrastructure -This directory contains a component of the Microsoft Go signing infrastructure written using MSBuild. +This directory contains a component of the Microsoft build of Go signing infrastructure written using MSBuild. `Sign.csproj` is the interface between the Go signing command [`/eng/_util/cmd/sign`][sign] and MicroBuild, an internal Microsoft toolset written to primarily support .NET projects that use MSBuild. See [`/eng/_util/cmd/sign`][sign] for more information about the signing infrastructure. diff --git a/patches/0002-Vendor-crypto-backends.patch b/patches/0002-Vendor-crypto-backends.patch index d8083025015..45b684bd58e 100644 --- a/patches/0002-Vendor-crypto-backends.patch +++ b/patches/0002-Vendor-crypto-backends.patch @@ -427,7 +427,7 @@ index 00000000000000..1bfbaf60f4dd58 +All supported OpenSSL versions pass a small set of automatic tests that ensure they can be built and that there are no major regressions. +These tests do not validate the cryptographic correctness of the `openssl` package. + -+On top of that, the [golang-fips Go fork](https://github.com/golang-fips/go) -maintained by Red Hat- and the [Microsoft Go fork](https://github.com/microsoft/go), tests a subset of the supported OpenSSL versions when integrated with the Go `crypto` package. ++On top of that, the [golang-fips Go fork](https://github.com/golang-fips/go) -maintained by Red Hat- and the [Microsoft build of Go](https://github.com/microsoft/go), tests a subset of the supported OpenSSL versions when integrated with the Go `crypto` package. +These tests are much more exhaustive and validate a specific OpenSSL version can produce working applications. + +### Building without OpenSSL headers diff --git a/patches/0004-Use-crypto-backends.patch b/patches/0004-Use-crypto-backends.patch index 030657c00a9..db8298b6bd0 100644 --- a/patches/0004-Use-crypto-backends.patch +++ b/patches/0004-Use-crypto-backends.patch @@ -301,7 +301,7 @@ index 7614b6d194facf..f0f53ab2bab047 100644 if goexperiment := buildcfg.Experiment.String(); goexperiment != "" { - buildVersion += " X:" + goexperiment + // buildVersion is intended to contain non-default experiment flags. -+ // The Microsoft Go toolchain default behavior is to set the ++ // The Microsoft build of Go default behavior is to set the + // allowcryptofallback experiment, so we don't include it in the + // buildVersion string. + goexperiment = strings.Join(slices.DeleteFunc(strings.Split(goexperiment, ","), func(s string) bool { @@ -744,7 +744,7 @@ index 00000000000000..1dc05d09b2062d + +import _ "unsafe" + -+// The symbols below are pulled by some crypto backend in the Microsoft Go compiler. ++// The symbols below are pulled by some crypto backend in the Microsoft build of Go compiler. +// We provide a push linkname here, to keep them accessible with pull linknames. + +//go:linkname encodeSignature @@ -2304,7 +2304,7 @@ index 00000000000000..1adf3098356307 +// license that can be found in the LICENSE file. + +/* -+Microsoft Go only package. ++Microsoft build of Go only package. + +TLS 1.3 Key Schedule is normally not part of the FIPS boundary, but upstream Go +decided to include it in the FIPS boundary to facilitate the FIPS 140-3 certification diff --git a/patches/0008-remove-long-path-support-hack.patch b/patches/0008-remove-long-path-support-hack.patch index e8852986509..35bf86b183f 100644 --- a/patches/0008-remove-long-path-support-hack.patch +++ b/patches/0008-remove-long-path-support-hack.patch @@ -4,11 +4,11 @@ Date: Mon, 25 Mar 2024 12:14:00 +0100 Subject: [PATCH] remove long path support hack Upstream Go tricks Windows into enabling long path support by setting an -undocumented flag in the PEB. The Microsoft Go fork can't use undocumented +undocumented flag in the PEB. The Microsoft build of Go can't use undocumented APIs, so this commit removes the hack. There is no documented way to enable long path support from within the -process, so this this is a breaking change for the Microsoft Go fork. +process, so this this is a breaking change for the Microsoft build of Go. Note that the Go standard library makes a best effort to support long paths by using the `\\?\` prefix when possible, so this change should only affect long relative paths, which can't be used with the `\\?\`. diff --git a/patches/README.md b/patches/README.md index 51e6703679a..9bf2fe6ed98 100644 --- a/patches/README.md +++ b/patches/README.md @@ -1,6 +1,6 @@ -# Microsoft Go patches +# Microsoft build of Go patches -The patches in this directory are applied to the `/go` submodule before building Microsoft Go. +The patches in this directory are applied to the `/go` submodule before building th Microsoft build of Go. This is done automatically by the build tools provided in `/eng`. We use [`git-go-patch`](https://github.com/microsoft/go-infra/tree/main/cmd/git-go-patch) to maintain these patch files.