From ff24fa60b9d1bf96418bd49e3bb0201bd9dea001 Mon Sep 17 00:00:00 2001 From: "bot-for-go[bot]" <199222863+bot-for-go[bot]@users.noreply.github.com> Date: Wed, 28 Oct 2026 16:50:16 +0000 Subject: [PATCH] Sync docs from microsoft/main into microsoft/release-branch.go1.27 --- CODE_OF_CONDUCT.md | 6 + CONTRIBUTING.md | 43 ++++++ README.md | 21 +-- SECURITY.md | 6 + SUPPORT.md | 6 + eng/doc/AdditionalFeatures.md | 41 ++++-- eng/doc/CrossPlatformCryptography.md | 35 ++++- eng/doc/DeveloperGuide.md | 6 + eng/doc/Downloads.md | 28 ++-- eng/doc/Installation.md | 6 + eng/doc/MicrosoftToolsetIdentification.md | 6 + eng/doc/MigrationGuide.md | 76 +++++++--- eng/doc/NocgoOpenSSL.md | 18 ++- eng/doc/README.md | 6 + eng/doc/SupportedPlatforms.md | 7 + eng/doc/Telemetry.md | 10 ++ eng/doc/fips/README.md | 89 +++++------- eng/doc/fips/UserGuide.md | 91 ++++++++++++ eng/doc/release-branch-links.json | 169 ++++++++++++---------- 19 files changed, 475 insertions(+), 195 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index f9ba8cf65f3..74be02057b7 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,3 +1,9 @@ + + # Microsoft Open Source Code of Conduct This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..54aff816cab --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,43 @@ + + +# Contributing + +This project welcomes contributions and suggestions. + +## Reporting bugs and requesting features + +See [SUPPORT.md](SUPPORT.md) for how to report bugs, request features, and ask questions. +Please search existing issues before opening a new one. +Report security vulnerabilities privately by following [SECURITY.md](SECURITY.md), rather than opening a public issue. + +## Contributing changes + +We submit changes to the upstream Go project rather than patching it when possible. +If your change also applies to upstream Go, see the [Go contribution guide](https://go.dev/doc/contribute). + +For changes specific to the Microsoft build of Go: + +1. Read the [Developer Guide](eng/doc/DeveloperGuide.md) for repository setup, building, and testing instructions. + Changes to the Go source are maintained as patch files; the guide explains how to work with the `go` submodule and generate those patches. +2. Make your changes and run the relevant tests. +3. Submit a pull request with a short description of the change and links to any related issues. + See [Submitting changes](eng/doc/DeveloperGuide.md#submitting-changes) for details. + +## Contributor License Agreement + +Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us +the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. + +When you submit a pull request, a CLA bot will automatically determine whether you need to provide +a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions +provided by the bot. You will only need to do this once across all repos using our CLA. + +## Code of Conduct + +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). +For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or +contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. diff --git a/README.md b/README.md index d45cad04af9..c7f0107904f 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,9 @@ + + # The Microsoft build of Go Go is an open source programming language that makes it easy to build simple, reliable, and efficient software. @@ -84,19 +90,8 @@ The [Installation](eng/doc/Installation.md) documentation contains sections desc ## Contributing -This project welcomes contributions and suggestions. Most contributions require you to agree to a -Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us -the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. - -When you submit a pull request, a CLA bot will automatically determine whether you need to provide -a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions -provided by the bot. You will only need to do this once across all repos using our CLA. - -This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). -For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or -contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. - -Please read the [Developer Guide](eng/doc/DeveloperGuide.md) for more information about contributing to this project. +This project welcomes contributions and suggestions. +Please read [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines, including the Contributor License Agreement and Code of Conduct. ## Trademarks diff --git a/SECURITY.md b/SECURITY.md index f7b89984f0f..b81d4fac351 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,3 +1,9 @@ + + ## Security diff --git a/SUPPORT.md b/SUPPORT.md index a5c8aaa4b58..f264286a691 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -1,3 +1,9 @@ + + # Support For help and questions about the Go programming language and tools, visit the official website: . diff --git a/eng/doc/AdditionalFeatures.md b/eng/doc/AdditionalFeatures.md index 57af521fdfc..11f3e75d646 100644 --- a/eng/doc/AdditionalFeatures.md +++ b/eng/doc/AdditionalFeatures.md @@ -1,3 +1,9 @@ + + # Additional Features Provided by the Microsoft build of Go This document provides a comprehensive overview of all features currently implemented in the Microsoft build of Go that are not part of the official Go distribution. @@ -48,19 +54,28 @@ The possible values of `ms_tlsx25519` are: - `0` disables the X25519 and X25519MLKEM768 TLS groups. - `1` (default) enables these groups. -Setting the environment variable `MS_GOTLSMLKEM=0` when building a program changes -its `tlsmlkem` GODEBUG default to `0`. This disables the default use of the -X25519MLKEM768, SecP256r1MLKEM768, and SecP384r1MLKEM1024 TLS groups without -changing the default use of the classical groups, including X25519. -Other values leave the default unchanged. -Explicit `godebug` directives in `go.mod` or `go.work` and `//go:debug` directives -take precedence over this build-time default. Setting `GODEBUG=tlsmlkem=1` at -runtime re-enables these groups, subject to the other TLS settings. -Setting `MS_GOTLSMLKEM` only at runtime has no effect. -This setting applies independently of `ms_tlsprofile` and does not override -explicit `tls.Config.CurvePreferences`. -It can also be persisted with `go env -w MS_GOTLSMLKEM=0` and cleared with -`go env -u MS_GOTLSMLKEM`. +Microsoft build of Go 1.28 introduces the `MS_GOTLSMLKEM` environment variable, which controls the default use of ML-KEM TLS key exchange in built programs. +The build-time values are: + +- `0`: sets the program's `tlsmlkem` GODEBUG default to `0`. +- Unset or any other value: leaves the default unchanged. + +With `tlsmlkem=0`, programs disable the X25519MLKEM768, SecP256r1MLKEM768, and SecP384r1MLKEM1024 TLS groups by default. +The default use of classical groups, including X25519, is unchanged. +This setting applies independently of `ms_tlsprofile` and does not override explicit `tls.Config.CurvePreferences`. + +`MS_GOTLSMLKEM` takes effect when the program is built, not when it runs. +The following command persists the setting for subsequent builds: + +```sh +go env -w MS_GOTLSMLKEM=0 +``` + +`go env -u MS_GOTLSMLKEM` removes the persisted setting. +Neither command changes programs that have already been built. + +Explicit `godebug` directives in `go.mod` or `go.work` and `//go:debug` directives take precedence over this build-time default. +At runtime, `GODEBUG=tlsmlkem=1` overrides the built-in default and re-enables the ML-KEM groups, subject to the other TLS settings. Microsoft build of Go `v1.27.2-2` introduces `ms_tlsmldsacert`, which controls ML-DSA advertisement in the `signature_algorithms_cert` extension. The possible values are: diff --git a/eng/doc/CrossPlatformCryptography.md b/eng/doc/CrossPlatformCryptography.md index 68af72742d1..02dc7f8b00b 100644 --- a/eng/doc/CrossPlatformCryptography.md +++ b/eng/doc/CrossPlatformCryptography.md @@ -1,3 +1,9 @@ + + # Cross-Platform Cryptography in the Microsoft build of Go @@ -31,7 +37,6 @@ SCOSSL is expected to be used with the default built-in provider enabled as a fa ### FreeBSD Since Go 1.27, the Microsoft build of Go uses the [OpenSSL crypto library](https://docs.openssl.org/3.0/man7/crypto/) on FreeBSD, the same backend as on Linux. -All FreeBSD architectures are supported with cgo enabled; without cgo, only `amd64` and `arm64` are supported. The algorithm support listed in the Linux column of the tables below also applies to FreeBSD. ### macOS @@ -40,6 +45,34 @@ On macOS, the Microsoft build of Go uses [CommonCrypto](https://developer.apple. CommonCrypto and CryptoKit are shipped with macOS and don't require any additional installation nor configuration. Currently macOS 13 and above is supported. +## Cgo + +Sometimes, cgo is not available: + +* When performing a cross-platform build, a suitable C compiler for cgo is often not available or very difficult to set up correctly. +* Cgo may be intentionally disabled to simplify the build process, or for security or performance reasons. +* Cgo may be intentionally disabled to avoid producing a binary that depends on the build system's glibc version. The dependency may be too new, causing the program to fail to run on some target systems. See ["glibc resolution failure on Linux" in the Migration Guide](MigrationGuide.md#glibc-resolution-failure-on-linux). + +The Microsoft build of Go attempts to use a cgo-less `systemcrypto` backend when cgo is not enabled, but on some uncommon OS and architecture combinations, this is not supported: + +| Target platform | Cgo enabled | Cgo disabled | +| --- | --- | --- | +| Linux | ✔️ | ⚠️1 | +| FreeBSD (since Go 1.27) | ⚠️2,3 | ⚠️2 | +| Windows | ✔️ | ✔️ | +| macOS | ✔️ | ✔️ | + +1 Supported on **amd64**, **arm64**, and [many other architectures](NocgoOpenSSL.md#supported-architectures). + +2 Supported on **amd64** and **arm64** architectures. + +3 Support with cgo for all FreeBSD architectures is [expected in Go 1.27.1](https://github.com/microsoft/go/pull/2477). + +> [!IMPORTANT] +> When using Go 1.26 and targeting Linux or FreeBSD, the table only applies if `GOEXPERIMENT=ms_nocgo_opensslcrypto` is set. +> Otherwise, cgo is always required. +> See [No-cgo OpenSSL Backend](NocgoOpenSSL.md) for details. + ## Table legend The following legend describes the symbols used in the tables to indicate the level of support for each cryptographic algorithm: diff --git a/eng/doc/DeveloperGuide.md b/eng/doc/DeveloperGuide.md index 6968f6fa8f2..4e6bffc1352 100644 --- a/eng/doc/DeveloperGuide.md +++ b/eng/doc/DeveloperGuide.md @@ -1,3 +1,9 @@ + + # Developer Guide This document is a guide for developers who want to contribute to the Microsoft build of Go repository. diff --git a/eng/doc/Downloads.md b/eng/doc/Downloads.md index c3c2efbda94..30992972b6b 100644 --- a/eng/doc/Downloads.md +++ b/eng/doc/Downloads.md @@ -1,3 +1,9 @@ + + # Downloading a binary release of the Microsoft build of Go > [!IMPORTANT] @@ -13,17 +19,17 @@ For example, a 1.20 link will download 1.20.8-1 if that is the latest version of -| | 1.26 | 1.25 | +| | 1.27 | 1.26 | | --- | --- | --- | -| Source code | - [Source (tar.gz)](https://aka.ms/golang/release/latest/go1.26.src.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.26.src.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.26.src.tar.gz.sig)
| - [Source (tar.gz)](https://aka.ms/golang/release/latest/go1.25.src.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.25.src.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.25.src.tar.gz.sig)
| - Metadata | - [Asset manifest (json)](https://aka.ms/golang/release/latest/go1.26.assets.json)
| - [Asset manifest (json)](https://aka.ms/golang/release/latest/go1.25.assets.json)
| - darwin-amd64 | - [Binaries (tar.gz)](https://aka.ms/golang/release/latest/go1.26.darwin-amd64.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.26.darwin-amd64.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.26.darwin-amd64.tar.gz.sig)
| **Preview**2
- [Binaries (tar.gz)](https://aka.ms/golang/release/latest/go1.25.darwin-amd64.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.25.darwin-amd64.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.25.darwin-amd64.tar.gz.sig)
| - darwin-arm64 | - [Binaries (tar.gz)](https://aka.ms/golang/release/latest/go1.26.darwin-arm64.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.26.darwin-arm64.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.26.darwin-arm64.tar.gz.sig)
| **Preview**2
- [Binaries (tar.gz)](https://aka.ms/golang/release/latest/go1.25.darwin-arm64.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.25.darwin-arm64.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.25.darwin-arm64.tar.gz.sig)
| - linux-amd64 | - [Binaries (tar.gz)](https://aka.ms/golang/release/latest/go1.26.linux-amd64.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.26.linux-amd64.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.26.linux-amd64.tar.gz.sig)
| - [Binaries (tar.gz)](https://aka.ms/golang/release/latest/go1.25.linux-amd64.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.25.linux-amd64.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.25.linux-amd64.tar.gz.sig)
| - linux-arm64 | - [Binaries (tar.gz)](https://aka.ms/golang/release/latest/go1.26.linux-arm64.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.26.linux-arm64.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.26.linux-arm64.tar.gz.sig)
| - [Binaries (tar.gz)](https://aka.ms/golang/release/latest/go1.25.linux-arm64.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.25.linux-arm64.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.25.linux-arm64.tar.gz.sig)
| - linux-armv6l | - [Binaries (tar.gz)](https://aka.ms/golang/release/latest/go1.26.linux-armv6l.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.26.linux-armv6l.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.26.linux-armv6l.tar.gz.sig)
| - [Binaries (tar.gz)](https://aka.ms/golang/release/latest/go1.25.linux-armv6l.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.25.linux-armv6l.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.25.linux-armv6l.tar.gz.sig)
| - windows-amd64 | - [Binaries (zip)](https://aka.ms/golang/release/latest/go1.26.windows-amd64.zip)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.26.windows-amd64.zip.sha256)
| - [Binaries (zip)](https://aka.ms/golang/release/latest/go1.25.windows-amd64.zip)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.25.windows-amd64.zip.sha256)
| - windows-arm64 | - [Binaries (zip)](https://aka.ms/golang/release/latest/go1.26.windows-arm64.zip)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.26.windows-arm64.zip.sha256)
| N/A | +| Source code | - [Source (tar.gz)](https://aka.ms/golang/release/latest/go1.27.src.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.27.src.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.27.src.tar.gz.sig)
| - [Source (tar.gz)](https://aka.ms/golang/release/latest/go1.26.src.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.26.src.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.26.src.tar.gz.sig)
| + Metadata | - [Asset manifest (json)](https://aka.ms/golang/release/latest/go1.27.assets.json)
| - [Asset manifest (json)](https://aka.ms/golang/release/latest/go1.26.assets.json)
| + darwin-amd64 | - [Binaries (tar.gz)](https://aka.ms/golang/release/latest/go1.27.darwin-amd64.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.27.darwin-amd64.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.27.darwin-amd64.tar.gz.sig)
| - [Binaries (tar.gz)](https://aka.ms/golang/release/latest/go1.26.darwin-amd64.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.26.darwin-amd64.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.26.darwin-amd64.tar.gz.sig)
| + darwin-arm64 | - [Binaries (tar.gz)](https://aka.ms/golang/release/latest/go1.27.darwin-arm64.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.27.darwin-arm64.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.27.darwin-arm64.tar.gz.sig)
| - [Binaries (tar.gz)](https://aka.ms/golang/release/latest/go1.26.darwin-arm64.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.26.darwin-arm64.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.26.darwin-arm64.tar.gz.sig)
| + linux-amd64 | - [Binaries (tar.gz)](https://aka.ms/golang/release/latest/go1.27.linux-amd64.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.27.linux-amd64.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.27.linux-amd64.tar.gz.sig)
| - [Binaries (tar.gz)](https://aka.ms/golang/release/latest/go1.26.linux-amd64.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.26.linux-amd64.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.26.linux-amd64.tar.gz.sig)
| + linux-arm64 | - [Binaries (tar.gz)](https://aka.ms/golang/release/latest/go1.27.linux-arm64.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.27.linux-arm64.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.27.linux-arm64.tar.gz.sig)
| - [Binaries (tar.gz)](https://aka.ms/golang/release/latest/go1.26.linux-arm64.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.26.linux-arm64.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.26.linux-arm64.tar.gz.sig)
| + linux-armv6l | - [Binaries (tar.gz)](https://aka.ms/golang/release/latest/go1.27.linux-armv6l.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.27.linux-armv6l.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.27.linux-armv6l.tar.gz.sig)
| - [Binaries (tar.gz)](https://aka.ms/golang/release/latest/go1.26.linux-armv6l.tar.gz)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.26.linux-armv6l.tar.gz.sha256)
- [Signature1](https://aka.ms/golang/release/latest/go1.26.linux-armv6l.tar.gz.sig)
| + windows-amd64 | - [Binaries (zip)](https://aka.ms/golang/release/latest/go1.27.windows-amd64.zip)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.27.windows-amd64.zip.sha256)
| - [Binaries (zip)](https://aka.ms/golang/release/latest/go1.26.windows-amd64.zip)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.26.windows-amd64.zip.sha256)
| + windows-arm64 | - [Binaries (zip)](https://aka.ms/golang/release/latest/go1.27.windows-arm64.zip)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.27.windows-arm64.zip.sha256)
| - [Binaries (zip)](https://aka.ms/golang/release/latest/go1.26.windows-arm64.zip)
- [Checksum (SHA256)](https://aka.ms/golang/release/latest/go1.26.windows-arm64.zip.sha256)
| @@ -32,8 +38,6 @@ For example, a 1.20 link will download 1.20.8-1 if that is the latest version of > * https://download.microsoft.com/download/f/a/2/fa2420dd-3f08-4621-82cf-5a22abcbc8f9/microsoft-managed-lang-compiler.asc > * Shortened link for sharing: https://aka.ms/managed-lang-compiler-public-key -> 2 - In 1.25, the macOS builds and `systemcrypto` support are in preview and shouldn't be used in production. - ## Downloading a specific version The table only shows a small subset of the aka.ms links we generate. diff --git a/eng/doc/Installation.md b/eng/doc/Installation.md index e1be3595c18..0fc910a8fad 100644 --- a/eng/doc/Installation.md +++ b/eng/doc/Installation.md @@ -1,3 +1,9 @@ + + # Installation These are the installation methods available for the Microsoft build of Go. diff --git a/eng/doc/MicrosoftToolsetIdentification.md b/eng/doc/MicrosoftToolsetIdentification.md index 9cf06ceb37c..049595da568 100644 --- a/eng/doc/MicrosoftToolsetIdentification.md +++ b/eng/doc/MicrosoftToolsetIdentification.md @@ -1,3 +1,9 @@ + + # Microsoft Toolset Identification Identifying whether a Go binary or toolset is from the Microsoft build of Go or the official Go distribution can be important for diagnostics and verifying expectations. diff --git a/eng/doc/MigrationGuide.md b/eng/doc/MigrationGuide.md index c5e50e01eca..46853788447 100644 --- a/eng/doc/MigrationGuide.md +++ b/eng/doc/MigrationGuide.md @@ -1,3 +1,9 @@ + + # Migration Guide: Microsoft build of Go This guide provides high-level guidance to help migrate from the [official Go distribution](https://go.dev/) to the [Microsoft build of Go](https://github.com/microsoft/go), comply with Microsoft internal cryptography policy, and (in some cases) build a FIPS compliant Go program. @@ -17,6 +23,7 @@ To comply with Microsoft internal policy for the use of Go, most projects need t 1. [Use the Microsoft build of Go **for CI (Continuous Integration) and build environments.**](#ci-and-build-environment-migration-steps) - See [Microsoft Toolset Identification](./MicrosoftToolsetIdentification.md) if it's not clear which distribution of Go you're currently using. + - Not sure what version to use? See [What version should I use?](#what-version-should-i-use) 1. [**Test** your program.](#testing) - It's important to test on all target platforms. The changes to runtime behavior are platform-specific. 1. Consider **whether your project must be FIPS compliant** and if so, [**review your project**](#review-project-for-fips-compliance). @@ -30,15 +37,6 @@ Like the official Go distribution, the Microsoft build of Go has no Go runtime c Your Go application is still a single executable binary. However, in some cases, it may now have additional dependencies. -> [!TIP] -> Regardless of which method you use to install Go, we recommend picking a specific major version of Go and setting up your build system to use the latest update to that major version. -> (For example, `1.26.*`. This is also called "pinning" to major version `26`.) -> Both official Go and the Microsoft build of Go occasionally have breaking changes in new major versions, and pinning lets you migrate to the next major version at your own pace. -> -> However, pinning increases maintenance burden when there are no breaking changes, because you are responsible for making sure you aren't using a version of Go that is past End-of-Life (EOL) and insecure. -> Some projects may prefer to always use the latest version of Go to be sure they never miss maintenance, even though this puts the project at risk of unexpected breaks when a new major version is released. -> Ultimately, these risks must be evaluated in the context of each project. - ## What's different? The Microsoft build of Go includes [patches](/patches/) that: @@ -53,6 +51,55 @@ The Microsoft build of Go includes [patches](/patches/) that: For a detailed description of every feature, see the [Additional Features](./AdditionalFeatures.md) document. +## What version should I use? + +We support two major versions of the Microsoft build of Go. +They are called the *current* and *previous* major versions. +See the [Microsoft build of Go release cycle and policy](https://github.com/microsoft/go#release-cycle-and-policy) for details. + +> [!NOTE] +> "Current" and "previous" are also known as `N` and `N-1`, "stable" and "oldstable", and "latest" and "previous". +> These terms refer only to the major version. +> Do not use old patch versions. + +Check the [Microsoft build of Go binary archives table](https://github.com/microsoft/go/blob/microsoft/main/eng/doc/Downloads.md) to see the currently supported *current* and *previous* versions. + +If you don't already have a reason to pick *current* or *previous*, you can use these criteria to help decide: + +1. For an existing project using a supported major version of Go: use the same major version of the Microsoft build of Go. +1. For an existing project using an unsupported, old version of Go: use *previous*. + * It's very important that you migrate quickly to get security fixes. Using *previous* lets you avoid a few things that could delay your migration: + * A recently-released major version (for example, `1.26.0`) may have some initial bugs that will be fixed in the next handful of patch releases. + * If there have been breaking changes that affect your project, *current* may have more breaking changes than *previous*. You will need to resolve these changes eventually, but using *previous* as a stepping stone gives you security support in the meantime. +1. For a new project or a project in early development: use the *current* version to take advantage of new features. + * If you encounter issues with *current*, please investigate and report the issue in the correct location based on your findings. You can try using *previous* to unblock your development workflow while the problem is worked out. + +In all cases, after migration to the Microsoft build of Go is completed, we recommend that you upgrade from *previous* to *current* as soon as you can. +It's important to discover compatibility issues before *previous* reaches end of support, so the sooner you attempt to upgrade, the better. +Delaying the upgrade until *previous* is out of support allows compatibility issues to compound with security issues, delaying your ability to address Go security vulnerabilities. + +> [!NOTE] +> If you maintain a Go library, we recommend keeping it compatible with both the *previous* and *current* versions so the choice of version is left up to the library's users. +> Testing libraries against both *previous* and *current* is recommended. + +> [!TIP] +> If it seems like pointless effort to use *previous* and then quickly upgrade to *current*, simply use *current*. +> The suggested migration path is intended to help risk-averse or complex projects, but there may be cases where even in that context, this approach doesn't make sense. +> It's ok to use any supported version of the Microsoft build of Go. + +## Dependency pinning + +In ["What version should I use?"](#what-version-should-i-use), we described how to pick between *previous* and *current*. +Once you do, we recommend that you use the numeric version, so that when a new major version is released, you can upgrade your project at your own pace. +For example, if *current* is 1.26, we recommend that you configure your dependency upgrade tool to use the latest `1.26.*` version. + +Both official Go and the Microsoft build of Go occasionally have breaking changes in new major versions, and pinning lets you migrate to the next major version at your own pace while continuing to receive security updates. + +However, we recognize that in some situations, pinning may not be feasible. +The dependency update system may not provide all features necessary to pin a dependency in the desired way. +The maintenance cost of updating a major version pin may be too high compared to the risk and impact of encountering "live" compatibility breaks. +Ultimately, these risks and costs must be evaluated in the context of each project. + ## CI and build environment migration steps This section describes some migration scenarios we know about and the path we recommend following for each one. @@ -156,17 +203,6 @@ If you're using Go 1.26 or earlier, you may see this error message if cgo is not ` (untyped string constant "\n\tUsing GOEXPERIMENT=systemcrypto on Linux requires CGO_ENABLED=1....) is not used ``` -In Go 1.25, you may see this similar error: - -``` -# crypto -../../../sdk/msgo1.25.7-1/src/crypto/systemcrypto_nocgo.go:10:2: ` - Using a crypto backend requires CGO_ENABLED=1. - - For more information, visit https://github.com/microsoft/go/tree/microsoft/main/eng/doc/fips - ` (untyped string constant "\n\tUsing a crypto backend requires CGO_ENABLED=1.\n\t\n\tFor more i...) is not used -``` - > [!NOTE] > In Go 1.26, there is a cgo-less experiment available for Linux: `ms_nocgo_opensslcrypto`. > diff --git a/eng/doc/NocgoOpenSSL.md b/eng/doc/NocgoOpenSSL.md index d010446e7f1..8b36ca6811b 100644 --- a/eng/doc/NocgoOpenSSL.md +++ b/eng/doc/NocgoOpenSSL.md @@ -1,6 +1,18 @@ + + # No-cgo OpenSSL Backend -This document describes how the Microsoft build of Go uses the cgo-less OpenSSL backend on Linux and FreeBSD. +This document describes how the Microsoft build of Go uses the no-cgo OpenSSL backend on Linux and FreeBSD. + +> [!NOTE] +> The **no-cgo OpenSSL backend** is also known as the **cgo-less OpenSSL backend**. + +The no-cgo backend complements, rather than replaces, the cgo OpenSSL backend. +The cgo backend is still available and is used when cgo is enabled. ## Overview @@ -10,9 +22,7 @@ It is selected automatically when cgo is disabled and the target architecture is > [!NOTE] > In Go 1.26, this backend was available as the experimental `GOEXPERIMENT=ms_nocgo_opensslcrypto` feature on Linux only. > -> In Go 1.27, that experiment has been removed because the cgo-less backend is selected automatically when needed. -> -> FreeBSD support was added in Go 1.27. +> In Go 1.27, the cgo-less backend is no longer experimental. The experiment has been removed and the cgo-less backend is selected automatically when needed. This allows the use of OpenSSL without requiring cgo. diff --git a/eng/doc/README.md b/eng/doc/README.md index d974d1daa6c..05ad6a62ebb 100644 --- a/eng/doc/README.md +++ b/eng/doc/README.md @@ -1,3 +1,9 @@ + + # `/eng/doc` - Documentation for the Microsoft build of Go This directory, `/eng/doc`, contains detailed documents describing the Microsoft build of Go. diff --git a/eng/doc/SupportedPlatforms.md b/eng/doc/SupportedPlatforms.md index b7f635eb97a..bae22795f6e 100644 --- a/eng/doc/SupportedPlatforms.md +++ b/eng/doc/SupportedPlatforms.md @@ -1,3 +1,9 @@ + + # Supported Platforms This document describes the platforms supported by the Microsoft build of Go. @@ -19,6 +25,7 @@ Platforms outside this scope are supported on a best-effort basis with no guaran | linux/amd64 | Azure Linux 3.0, Ubuntu 22.04 | | linux/arm64 | Azure Linux 3.0, Ubuntu 22.04 | | linux/arm | Ubuntu 22.04 | +| windows/386 | Windows 10, Windows Server 2016 (since Go 1.28) | | windows/amd64 | Windows 10, Windows Server 2016 | | windows/arm64 | Windows 11, Windows Server 2025 | diff --git a/eng/doc/Telemetry.md b/eng/doc/Telemetry.md index 57b96d5dc48..7514c7049a8 100644 --- a/eng/doc/Telemetry.md +++ b/eng/doc/Telemetry.md @@ -1,3 +1,9 @@ + + # Telemetry in the Microsoft build of Go The Microsoft build of Go collects opt-out (enabled by default) toolset telemetry. @@ -80,6 +86,10 @@ go env -w MS_GOTOOLCHAIN_TELEMETRY_ENABLED=0 To override the setting for an individual process, set the `MS_GOTOOLCHAIN_TELEMETRY_ENABLED` environment variable to `0` when starting the process. +> [!NOTE] +> The ability to opt out using `go env -w` and `$GOROOT/go.env` was added in 1.27.2-2 and 1.26.10-1. +> Earlier versions support configuration only through the MS_GOTOOLCHAIN_TELEMETRY_ENABLED process environment variable. + Configuration is resolved in this order, from highest to lowest precedence: 1. The process environment. diff --git a/eng/doc/fips/README.md b/eng/doc/fips/README.md index 8ed1fc4afe5..01c20f001e5 100644 --- a/eng/doc/fips/README.md +++ b/eng/doc/fips/README.md @@ -1,3 +1,9 @@ + + This directory contains documentation about FIPS, details about the FIPS implementation in the Microsoft build of Go, and using system-provided cryptography via the Go standard library. * README.md (this file): an overview of the design and how to use it. @@ -68,16 +74,7 @@ The modified Go runtime is typically used to accomplish one of two goals: comply The following table summarizes common configurations and how suitable each one is for these goals. > [!NOTE] -> This document assumes the use of a supported version of the Microsoft build of Go: 1.25 or later. - -> [!NOTE] -> Since Go 1.25, `systemcrypto` is enabled by default on Linux and Windows. There is no need to manually enable using OpenSSL/CNG under the hood anymore. -> See also [the Go 1.25 changelog](#go-125-aug-2025). -> -> Since Go 1.26, `systemcrypto` is also enabled by default on macOS. -> -> Since Go 1.27, `systemcrypto` is no longer a `GOEXPERIMENT` setting. Supported platforms use it automatically unless it is disabled with `MS_GO_NOSYSTEMCRYPTO=1`. -> See also [the Go 1.27 changelog](#go-127-aug-2026). +> This document assumes the use of a supported version of the Microsoft build of Go: 1.26 or later. > [!TIP] > If an app uses no cryptography, FIPS compliance is not relevant and the internal Microsoft crypto policy doesn't apply. @@ -102,49 +99,35 @@ Some configurations are invalid and intentionally result in a build error or run ## Usage: Build -The default behavior of the Microsoft build of Go is to use a platform-provided cryptographic library using `systemcrypto`. -See the [Migration Guide](/eng/doc/MigrationGuide.md) for more information on incorporating the Microsoft build of Go into your build system. +The Microsoft build of Go uses `systemcrypto` by default. +`systemcrypto` modifies the Go runtime included in programs built by the Microsoft build of Go to use a platform-specific cryptographic library whenever it calls a Go standard library crypto API. + +The platform-specific library used by `systemcrypto` is selected by build constraints. +The target platform (`GOOS`, `GOARCH`, and cgo availability) is used to select the appropriate system-provided cryptography library. +See [Cross-Platform Cryptography in the Microsoft build of Go](../CrossPlatformCryptography.md) for more information about how each platform is implemented and the supported cryptographic algorithms. -`systemcrypto` modifies the Go runtime included in the program to use the specified platform-provided cryptographic library whenever it calls a Go standard library crypto API. If `systemcrypto` is disabled (see [build option to use Go crypto](#build-option-to-use-go-crypto)), Go standard library cryptography is used. +See the [Migration Guide](/eng/doc/MigrationGuide.md) for more information on incorporating the Microsoft build of Go into your build system. + > [!NOTE] -> Prior to Go 1.27, `systemcrypto` could be selected with `GOEXPERIMENT=systemcrypto`. In Go 1.27 and later, `systemcrypto` is no longer a `GOEXPERIMENT` setting. It is enabled automatically on supported platforms, `go env GOEXPERIMENT` doesn't report it, and `GOEXPERIMENT=systemcrypto` is rejected. +> Prior to Go 1.27, `systemcrypto` was a `GOEXPERIMENT` and could be selected with `GOEXPERIMENT=systemcrypto` and unselected with `GOEXPERIMENT=nosystemcrypto`. +> `systemcrypto` is no longer a `GOEXPERIMENT`. +> See [build option to use Go crypto](#build-option-to-use-go-crypto) for more information. > [!NOTE] > Prior to Go 1.27, per-platform experiments (`opensslcrypto`, `cngcrypto`, `darwincrypto`) were available. These experiments have been removed in Go 1.27, but the build tag associated with each experiment remains supported, ensuring source compatibility. -The `systemcrypto` experiment uses platform-specific code via build constraints. The platform is determined by the target platform (`GOOS`), and the appropriate system cryptography library is used: - -| Target platform | Library | -| --- | --- | -| Linux | OpenSSL | -| FreeBSD (amd64 and arm64, since Go 1.27) | OpenSSL | -| Windows | CNG | -| macOS | CommonCrypto & CryptoKit | - -In a cross-build scenario, such as using Linux to build an app that will run on Windows, `GOOS=windows` will correctly use CNG-based code for the `systemcrypto` backend. - -A cross-build to Windows or macOS will typically work, because these backends use approaches like syscalls to call the crypto library rather than cgo. - -A cross-build to Linux in Go 1.27 and later will work if the [cgo-less OpenSSL backend](../NocgoOpenSSL.md) is used. -The cgo-less backend may be unavailable for some processor architectures that aren't commonly used at Microsoft. -If cgo is enabled on Linux, the cgo-based OpenSSL backend is used. - -The Linux cgo-based backend introduces the glibc compatibility problem. -Building a cgo program on a distro that uses a new glibc version and running that program on a distro with an older glibc version may fail due to missing glibc symbols. -This is often mitigated by building on a distro with the oldest expected glibc version. -We have also successfully used a rootfs to build on an older glibc version (and cross-compile arm64 binaries on an amd64 machine), with rough notes available in [microsoft/go#1866](https://github.com/microsoft/go/issues/1866). +`systemcrypto` support may depend on whether cgo is enabled or disabled. +Specifically, some architectures do not support the cgo-less Linux backend. +See [No-cgo OpenSSL Backend](/eng/doc/NocgoOpenSSL.md) for more information about which platforms are supported. > [!TIP] > Go 1.27 uses the cgo-less OpenSSL backend automatically when Linux `systemcrypto` is enabled and cgo is disabled on a supported architecture. Go 1.26 provided this as the `GOEXPERIMENT=ms_nocgo_opensslcrypto` experiment. -> See [No-cgo OpenSSL Backend](/eng/doc/NocgoOpenSSL.md) for more information. If a crypto backend is selected but isn't supported, the build fails. For example, attempting to use the cgo-less OpenSSL backend on an unsupported Linux architecture results in a build error. -For more information about disabling the crypto backend, see [build option to use Go crypto](#build-option-to-use-go-crypto). - ## Usage: Runtime A program built with `systemcrypto` always uses the system-provided cryptography library for supported crypto APIs: OpenSSL on Linux, CNG on Windows, and CommonCrypto/CryptoKit on macOS. If the platform's crypto library can't be found or loaded, the Go program panics during initialization. @@ -313,19 +296,19 @@ It's possible to disable `systemcrypto` and use the Go standard library's implem > > For example, when computing a hash for non-cryptographic purposes, there are several alternatives in the Go standard library that don't require a crypto backend, such as `hash/fnv` or `hash/maphash`. -If it's acceptable to become noncompliant with the internal Microsoft crypto policy and FIPS, you can use the Go standard library cryptography implementation by disabling the `systemcrypto` backend: - -- With Go 1.25.2 or later, set the `MS_GO_NOSYSTEMCRYPTO` environment variable to `1`. -- With Go 1.25 through Go 1.26, set the `GOEXPERIMENT` environment variable to `nosystemcrypto`. +If it's acceptable to become noncompliant with the internal Microsoft crypto policy and FIPS, you can use the Go standard library cryptography implementation by disabling the `systemcrypto` backend. -Both of the above methods are supported in Go 1.25.2 through Go 1.26, but we encourage using `MS_GO_NOSYSTEMCRYPTO` instead of `GOEXPERIMENT`: +To disable `systemcrypto`, set the `MS_GO_NOSYSTEMCRYPTO` environment variable to `1`. -- `GOEXPERIMENT=nosystemcrypto` may make your *build command* incompatible with the official Go toolset. ([microsoft/go#1880](https://github.com/microsoft/go/issues/1880)) -- `MS_GO_NOSYSTEMCRYPTO=1` doesn't involve the `GOEXPERIMENT` mechanism. It's simple to use and to incorporate into any build process. -- Only the exact value `1` disables `systemcrypto`. Other values leave the default behavior in place. - -In Go 1.27 and later, `GOEXPERIMENT=nosystemcrypto` has been removed. -Remove `GOEXPERIMENT=systemcrypto` and `GOEXPERIMENT=nosystemcrypto` from build scripts when moving to Go 1.27 or later. +> [!NOTE] +> Prior to Go 1.27, setting the `GOEXPERIMENT` environment variable to `nosystemcrypto` is an alternative way to disable the `systemcrypto` backend. +> +> We recommend against using `GOEXPERIMENT=nosystemcrypto` even in projects that use Go 1.26: +> +> - `GOEXPERIMENT=nosystemcrypto` may make your *build command* incompatible with the official Go toolset. ([microsoft/go#1880](https://github.com/microsoft/go/issues/1880)) +> - The `GOEXPERIMENT` mechanism is not intuitive to every Go user and may be complicated to manipulate in a build script. `MS_GO_NOSYSTEMCRYPTO=1` doesn't involve this mechanism. It's simpler to use and to incorporate into any build process. +> +> Remove `GOEXPERIMENT=systemcrypto` and `GOEXPERIMENT=nosystemcrypto` from build scripts when moving to Go 1.27 or later. > [!WARNING] > In Go 1.25 and Go 1.26, `MS_GO_NOSYSTEMCRYPTO=1` has precedence over `GOEXPERIMENT` values. @@ -333,7 +316,9 @@ Remove `GOEXPERIMENT=systemcrypto` and `GOEXPERIMENT=nosystemcrypto` from build > > Specifically, `MS_GO_NOSYSTEMCRYPTO=1 GOEXPERIMENT=systemcrypto go build .` builds a program that uses Go standard library cryptography. > -> Go 1.27 and later reject `GOEXPERIMENT=systemcrypto` and `GOEXPERIMENT=nosystemcrypto` with an error. Use `MS_GO_NOSYSTEMCRYPTO=1` to disable the backend. +> The precedence is arbitrary, and may seem logical in some scenarios but not others. +> We recommend avoiding it by removing `GOEXPERIMENT=systemcrypto` and `GOEXPERIMENT=nosystemcrypto` from build scripts. +> This conflict is no longer possible as of Go 1.27 because `systemcrypto` is no longer a `GOEXPERIMENT` value. > [!NOTE] > Your program may use Go crypto even if `systemcrypto` is enabled. @@ -360,8 +345,8 @@ This algorithm can be overridden by setting the environment variable `GO_OPENSSL ### Multiple GOEXPERIMENTS -In Go 1.26 and earlier, when using `GOEXPERIMENT` to enable `systemcrypto`, you can enable other non-crypto experiments simultaneously using a comma separator, e.g. `GOEXPERIMENT=systemcrypto,loopvar`. -Combining other experiments with `systemcrypto` is supported. +In Go 1.26 and earlier, when using `GOEXPERIMENT` to enable or disable `systemcrypto`, you can enable other non-crypto experiments simultaneously using a comma separator. +For example, you can enable the [cgo-less OpenSSL backend for Linux](../NocgoOpenSSL.md) along with other experiments like `GOEXPERIMENT=ms_nocgo_opensslcrypto,goroutineleakprofile`. In Go 1.27 and later, `systemcrypto` isn't configured through `GOEXPERIMENT`. Do not include `systemcrypto` or `nosystemcrypto` in `GOEXPERIMENT`; the go command rejects both values. diff --git a/eng/doc/fips/UserGuide.md b/eng/doc/fips/UserGuide.md index 0e40a44aceb..4ff53c7aec6 100644 --- a/eng/doc/fips/UserGuide.md +++ b/eng/doc/fips/UserGuide.md @@ -1,3 +1,9 @@ + + # FIPS 140-2 User Guide @@ -121,6 +127,19 @@ The Go crypto documentation is available online at https://pkg.go.dev/crypto. - [func PrivateKey.Sign](#func-privatekeysign-3) - [crypto/subtle](#cryptosubtle) - [crypto/tls](#cryptotls) + - [crypto/x509](#cryptox509) + - [func CreateCertificate](#func-createcertificate) + - [func CreateCertificateRequest](#func-createcertificaterequest) + - [func CreateRevocationList](#func-createrevocationlist) + - [func Certificate.CreateCRL](#func-certificatecreatecrl) + - [func Certificate.CheckSignature](#func-certificatechecksignature) + - [func Certificate.CheckSignatureFrom](#func-certificatechecksignaturefrom) + - [func CertificateRequest.CheckSignature](#func-certificaterequestchecksignature) + - [func RevocationList.CheckSignatureFrom](#func-revocationlistchecksignaturefrom) + - [func Certificate.CheckCRLSignature](#func-certificatecheckcrlsignature) + - [func Certificate.Verify](#func-certificateverify) + - [func EncryptPEMBlock](#func-encryptpemblock) + - [func DecryptPEMBlock](#func-decryptpemblock) ## The Microsoft build of Go crypto backends @@ -2271,6 +2290,78 @@ When using TLS in FIPS-only mode the TLS handshake has the following restriction - `tls.PKCS1WithSHA512` - `tls.ECDSAWithP521AndSHA512` +### [crypto/x509](https://pkg.go.dev/crypto/x509) + +Package x509 parses and creates X.509 certificates, certificate signing requests (CSRs), certificate revocation lists (CRLs), and encoded public and private keys. + +Package x509 does not have a separate crypto backend. Its cryptographic operations use other crypto packages, so their backend support and FIPS requirements also apply here. Backend support alone does not imply that an algorithm or its parameters are FIPS-approved; see [Cross-Platform Cryptography](../CrossPlatformCryptography.md) for platform support. + +Parsing and marshaling certificates, CSRs, CRLs, and keys use the standard Go implementation. Parsing an object does not verify its signature or establish trust, and successfully parsing or marshaling a key does not mean that it is suitable for FIPS-approved operations. Certificate pools and name checks, such as `Certificate.VerifyHostname`, do not themselves perform cryptographic signature verification. + +The signing APIs below accept a `crypto.Signer`. With standard-library RSA, ECDSA, or Ed25519 private keys, signing uses the corresponding crypto package. A custom `crypto.Signer` can use a different implementation, such as an HSM; the application is responsible for ensuring that implementation meets its FIPS requirements. Use `crypto/rand.Reader` for APIs that accept a random source. + +#### func [CreateCertificate](https://pkg.go.dev/crypto/x509#CreateCertificate) + +CreateCertificate creates and signs a certificate using `priv`, which must implement `crypto.Signer`. The template's `SignatureAlgorithm` selects the signature algorithm; if it is zero, x509 chooses a default based on the signing key. + +The signature algorithm, hash, and signing key must meet the requirements of [crypto/rsa](#cryptorsa), [crypto/ecdsa](#cryptoecdsa), or [crypto/ed25519](#cryptoed25519), as applicable. RSA-PSS signatures use a salt length equal to the hash length. The subject public key (`pub`) is encoded in the certificate; it is not used to sign it. + +#### func [CreateCertificateRequest](https://pkg.go.dev/crypto/x509#CreateCertificateRequest) + +CreateCertificateRequest creates and signs a CSR using `priv`, which must implement `crypto.Signer`. The template's `SignatureAlgorithm` and the signing key select the signature scheme in the same way as [CreateCertificate](#func-createcertificate), with the same underlying crypto package requirements. + +#### func [CreateRevocationList](https://pkg.go.dev/crypto/x509#CreateRevocationList) + +CreateRevocationList creates and signs a CRL using the issuer's private key, `priv`. The template's `SignatureAlgorithm` and the signing key select the signature scheme in the same way as [CreateCertificate](#func-createcertificate), with the same underlying crypto package requirements. + +#### func [Certificate.CreateCRL](https://pkg.go.dev/crypto/x509#Certificate.CreateCRL) + +Certificate.CreateCRL is deprecated; use [CreateRevocationList](#func-createrevocationlist) instead. It signs a CRL using the supplied `crypto.Signer`, choosing a default signature algorithm based on the signing key. The same underlying crypto package requirements apply. + +#### func [Certificate.CheckSignature](https://pkg.go.dev/crypto/x509#Certificate.CheckSignature) + +Certificate.CheckSignature checks a signature using the certificate's public key. It does not validate the certificate or establish trust. + +RSA signatures use [rsa.VerifyPKCS1v15](#func-verifypkcs1v15) or [rsa.VerifyPSS](#func-verifypss), ECDSA signatures use [ecdsa.VerifyASN1](https://pkg.go.dev/crypto/ecdsa#VerifyASN1), and Ed25519 signatures use [ed25519.Verify](https://pkg.go.dev/crypto/ed25519#Verify). Hashing and signature verification inherit the backend support and FIPS restrictions of those packages. + +MD5 signatures are rejected. This low-level API permits SHA-1 signatures, but that does not make SHA-1 an approved choice for every FIPS use or override restrictions imposed by the crypto backend. + +#### func [Certificate.CheckSignatureFrom](https://pkg.go.dev/crypto/x509#Certificate.CheckSignatureFrom) + +Certificate.CheckSignatureFrom checks the certificate's signature using the parent's public key and checks the parent's certificate-signing constraints. It uses the same underlying signature verification primitives as [Certificate.CheckSignature](#func-certificatechecksignature), but rejects SHA-1 certificate signatures. It does not build a chain to a trusted root or perform all the checks of [Certificate.Verify](#func-certificateverify). + +#### func [CertificateRequest.CheckSignature](https://pkg.go.dev/crypto/x509#CertificateRequest.CheckSignature) + +CertificateRequest.CheckSignature checks a CSR's signature using its public key. It uses the same underlying signature verification primitives as [Certificate.CheckSignature](#func-certificatechecksignature), including its SHA-1 behavior. A valid CSR signature does not establish trust in the requested identity. + +#### func [RevocationList.CheckSignatureFrom](https://pkg.go.dev/crypto/x509#RevocationList.CheckSignatureFrom) + +RevocationList.CheckSignatureFrom checks a CRL's signature and the parent's CRL-signing constraints. It uses the same underlying signature verification primitives as [Certificate.CheckSignature](#func-certificatechecksignature), including its SHA-1 behavior. It does not establish trust in the issuer or check whether the CRL is current. + +#### func [Certificate.CheckCRLSignature](https://pkg.go.dev/crypto/x509#Certificate.CheckCRLSignature) + +Certificate.CheckCRLSignature is deprecated; use [RevocationList.CheckSignatureFrom](#func-revocationlistchecksignaturefrom) instead. It checks a CRL's signature using the certificate's public key, with the same underlying crypto package requirements as [Certificate.CheckSignature](#func-certificatechecksignature). + +#### func [Certificate.Verify](https://pkg.go.dev/crypto/x509#Certificate.Verify) + +Certificate.Verify builds and verifies certificate chains, checking signatures and certificate constraints such as validity periods and key usage. The Go verifier uses the signature verification primitives described above and rejects SHA-1 certificate signatures. It does not perform revocation checking. + +When using system roots on Windows and macOS, Verify can use the platform certificate verifier instead of the Go verifier. That verifier's trust and algorithm policies apply; it is not the same as delegating individual crypto primitives to CNG or OpenSSL. With a root pool created by `x509.NewCertPool`, the Go verifier is used. Enabling a crypto backend does not replace Go's chain verification with OpenSSL's X.509 verifier. + +The [crypto/tls](#cryptotls) FIPS restrictions apply when certificates are used by TLS. Do not assume that a direct call to Certificate.Verify applies all of TLS's additional FIPS restrictions. + +#### func [EncryptPEMBlock](https://pkg.go.dev/crypto/x509#EncryptPEMBlock) + +EncryptPEMBlock is deprecated and must not be used for new applications. It implements legacy RFC 1423 PEM encryption, which is unauthenticated and vulnerable to padding oracle attacks. + +It derives an encryption key from the password using MD5, then encrypts using DES, Triple DES, or AES in CBC mode according to `alg`. The IV is generated from the supplied random source. These operations use [crypto/md5](#cryptomd5), [crypto/des](#cryptodes), [crypto/aes](#cryptoaes), and [crypto/cipher](#cryptocipher), inheriting their backend restrictions. Selecting AES does not make the MD5-based password derivation FIPS-approved. Do not use this format for FIPS-approved protection of private keys. + +#### func [DecryptPEMBlock](https://pkg.go.dev/crypto/x509#DecryptPEMBlock) + +DecryptPEMBlock is deprecated. It decrypts legacy encrypted PEM blocks using the same MD5-based password derivation and CBC ciphers as [EncryptPEMBlock](#func-encryptpemblock), with the same FIPS limitations. It may fail when the crypto backend disallows the required algorithms. + +The format provides no authentication: a wrong password is not always detected, and successful decryption does not establish the integrity of the plaintext. `IsEncryptedPEMBlock` only detects this legacy format; it does not decrypt or authenticate the block. + [EVP_EncryptUpdate]: https://www.openssl.org/docs/man3.0/man3/EVP_EncryptUpdate.html [EVP_DecryptUpdate]: https://www.openssl.org/docs/man3.0/man3/EVP_DecryptUpdate.html [RAND_bytes]: https://www.openssl.org/docs/man3.0/man3/RAND_bytes.html diff --git a/eng/doc/release-branch-links.json b/eng/doc/release-branch-links.json index 0fb0cee7a2f..8b789bdbf08 100644 --- a/eng/doc/release-branch-links.json +++ b/eng/doc/release-branch-links.json @@ -1,178 +1,187 @@ [ { - "version": "go1.26", + "version": "go1.27", "stable": true, "latestStable": true, "files": [ { - "filename": "go1.26.src.tar.gz", + "filename": "go1.27.src.tar.gz", "os": "", "arch": "", - "version": "go1.26", + "version": "go1.27", "kind": "source", - "url": "https://aka.ms/golang/release/latest/go1.26.src.tar.gz", - "checksumURL": "https://aka.ms/golang/release/latest/go1.26.src.tar.gz.sha256", - "signatureURL": "https://aka.ms/golang/release/latest/go1.26.src.tar.gz.sig" + "url": "https://aka.ms/golang/release/latest/go1.27.src.tar.gz", + "checksumURL": "https://aka.ms/golang/release/latest/go1.27.src.tar.gz.sha256", + "signatureURL": "https://aka.ms/golang/release/latest/go1.27.src.tar.gz.sig" }, { - "filename": "go1.26.assets.json", + "filename": "go1.27.assets.json", "os": "", "arch": "", - "version": "go1.26", + "version": "go1.27", "kind": "manifest", - "url": "https://aka.ms/golang/release/latest/go1.26.assets.json" + "url": "https://aka.ms/golang/release/latest/go1.27.assets.json" }, { - "filename": "go1.26.darwin-amd64.tar.gz", + "filename": "go1.27.darwin-amd64.tar.gz", "os": "darwin", "arch": "amd64", - "version": "go1.26", + "version": "go1.27", "kind": "archive", - "url": "https://aka.ms/golang/release/latest/go1.26.darwin-amd64.tar.gz", - "checksumURL": "https://aka.ms/golang/release/latest/go1.26.darwin-amd64.tar.gz.sha256", - "signatureURL": "https://aka.ms/golang/release/latest/go1.26.darwin-amd64.tar.gz.sig" + "url": "https://aka.ms/golang/release/latest/go1.27.darwin-amd64.tar.gz", + "checksumURL": "https://aka.ms/golang/release/latest/go1.27.darwin-amd64.tar.gz.sha256", + "signatureURL": "https://aka.ms/golang/release/latest/go1.27.darwin-amd64.tar.gz.sig" }, { - "filename": "go1.26.darwin-arm64.tar.gz", + "filename": "go1.27.darwin-arm64.tar.gz", "os": "darwin", "arch": "arm64", - "version": "go1.26", + "version": "go1.27", "kind": "archive", - "url": "https://aka.ms/golang/release/latest/go1.26.darwin-arm64.tar.gz", - "checksumURL": "https://aka.ms/golang/release/latest/go1.26.darwin-arm64.tar.gz.sha256", - "signatureURL": "https://aka.ms/golang/release/latest/go1.26.darwin-arm64.tar.gz.sig" + "url": "https://aka.ms/golang/release/latest/go1.27.darwin-arm64.tar.gz", + "checksumURL": "https://aka.ms/golang/release/latest/go1.27.darwin-arm64.tar.gz.sha256", + "signatureURL": "https://aka.ms/golang/release/latest/go1.27.darwin-arm64.tar.gz.sig" }, { - "filename": "go1.26.linux-amd64.tar.gz", + "filename": "go1.27.linux-amd64.tar.gz", "os": "linux", "arch": "amd64", - "version": "go1.26", + "version": "go1.27", "kind": "archive", - "url": "https://aka.ms/golang/release/latest/go1.26.linux-amd64.tar.gz", - "checksumURL": "https://aka.ms/golang/release/latest/go1.26.linux-amd64.tar.gz.sha256", - "signatureURL": "https://aka.ms/golang/release/latest/go1.26.linux-amd64.tar.gz.sig" + "url": "https://aka.ms/golang/release/latest/go1.27.linux-amd64.tar.gz", + "checksumURL": "https://aka.ms/golang/release/latest/go1.27.linux-amd64.tar.gz.sha256", + "signatureURL": "https://aka.ms/golang/release/latest/go1.27.linux-amd64.tar.gz.sig" }, { - "filename": "go1.26.linux-arm64.tar.gz", + "filename": "go1.27.linux-arm64.tar.gz", "os": "linux", "arch": "arm64", - "version": "go1.26", + "version": "go1.27", "kind": "archive", - "url": "https://aka.ms/golang/release/latest/go1.26.linux-arm64.tar.gz", - "checksumURL": "https://aka.ms/golang/release/latest/go1.26.linux-arm64.tar.gz.sha256", - "signatureURL": "https://aka.ms/golang/release/latest/go1.26.linux-arm64.tar.gz.sig" + "url": "https://aka.ms/golang/release/latest/go1.27.linux-arm64.tar.gz", + "checksumURL": "https://aka.ms/golang/release/latest/go1.27.linux-arm64.tar.gz.sha256", + "signatureURL": "https://aka.ms/golang/release/latest/go1.27.linux-arm64.tar.gz.sig" }, { - "filename": "go1.26.linux-armv6l.tar.gz", + "filename": "go1.27.linux-armv6l.tar.gz", "os": "linux", "arch": "armv6l", - "version": "go1.26", + "version": "go1.27", "kind": "archive", - "url": "https://aka.ms/golang/release/latest/go1.26.linux-armv6l.tar.gz", - "checksumURL": "https://aka.ms/golang/release/latest/go1.26.linux-armv6l.tar.gz.sha256", - "signatureURL": "https://aka.ms/golang/release/latest/go1.26.linux-armv6l.tar.gz.sig" + "url": "https://aka.ms/golang/release/latest/go1.27.linux-armv6l.tar.gz", + "checksumURL": "https://aka.ms/golang/release/latest/go1.27.linux-armv6l.tar.gz.sha256", + "signatureURL": "https://aka.ms/golang/release/latest/go1.27.linux-armv6l.tar.gz.sig" }, { - "filename": "go1.26.windows-amd64.zip", + "filename": "go1.27.windows-amd64.zip", "os": "windows", "arch": "amd64", - "version": "go1.26", + "version": "go1.27", "kind": "archive", - "url": "https://aka.ms/golang/release/latest/go1.26.windows-amd64.zip", - "checksumURL": "https://aka.ms/golang/release/latest/go1.26.windows-amd64.zip.sha256" + "url": "https://aka.ms/golang/release/latest/go1.27.windows-amd64.zip", + "checksumURL": "https://aka.ms/golang/release/latest/go1.27.windows-amd64.zip.sha256" }, { - "filename": "go1.26.windows-arm64.zip", + "filename": "go1.27.windows-arm64.zip", "os": "windows", "arch": "arm64", - "version": "go1.26", + "version": "go1.27", "kind": "archive", - "url": "https://aka.ms/golang/release/latest/go1.26.windows-arm64.zip", - "checksumURL": "https://aka.ms/golang/release/latest/go1.26.windows-arm64.zip.sha256" + "url": "https://aka.ms/golang/release/latest/go1.27.windows-arm64.zip", + "checksumURL": "https://aka.ms/golang/release/latest/go1.27.windows-arm64.zip.sha256" } ] }, { - "version": "go1.25", + "version": "go1.26", "stable": true, "previousStable": true, "files": [ { - "filename": "go1.25.src.tar.gz", + "filename": "go1.26.src.tar.gz", "os": "", "arch": "", - "version": "go1.25", + "version": "go1.26", "kind": "source", - "url": "https://aka.ms/golang/release/latest/go1.25.src.tar.gz", - "checksumURL": "https://aka.ms/golang/release/latest/go1.25.src.tar.gz.sha256", - "signatureURL": "https://aka.ms/golang/release/latest/go1.25.src.tar.gz.sig" + "url": "https://aka.ms/golang/release/latest/go1.26.src.tar.gz", + "checksumURL": "https://aka.ms/golang/release/latest/go1.26.src.tar.gz.sha256", + "signatureURL": "https://aka.ms/golang/release/latest/go1.26.src.tar.gz.sig" }, { - "filename": "go1.25.assets.json", + "filename": "go1.26.assets.json", "os": "", "arch": "", - "version": "go1.25", + "version": "go1.26", "kind": "manifest", - "url": "https://aka.ms/golang/release/latest/go1.25.assets.json" + "url": "https://aka.ms/golang/release/latest/go1.26.assets.json" }, { - "filename": "go1.25.darwin-amd64.tar.gz", + "filename": "go1.26.darwin-amd64.tar.gz", "os": "darwin", "arch": "amd64", - "version": "go1.25", + "version": "go1.26", "kind": "archive", - "url": "https://aka.ms/golang/release/latest/go1.25.darwin-amd64.tar.gz", - "checksumURL": "https://aka.ms/golang/release/latest/go1.25.darwin-amd64.tar.gz.sha256", - "signatureURL": "https://aka.ms/golang/release/latest/go1.25.darwin-amd64.tar.gz.sig" + "url": "https://aka.ms/golang/release/latest/go1.26.darwin-amd64.tar.gz", + "checksumURL": "https://aka.ms/golang/release/latest/go1.26.darwin-amd64.tar.gz.sha256", + "signatureURL": "https://aka.ms/golang/release/latest/go1.26.darwin-amd64.tar.gz.sig" }, { - "filename": "go1.25.darwin-arm64.tar.gz", + "filename": "go1.26.darwin-arm64.tar.gz", "os": "darwin", "arch": "arm64", - "version": "go1.25", + "version": "go1.26", "kind": "archive", - "url": "https://aka.ms/golang/release/latest/go1.25.darwin-arm64.tar.gz", - "checksumURL": "https://aka.ms/golang/release/latest/go1.25.darwin-arm64.tar.gz.sha256", - "signatureURL": "https://aka.ms/golang/release/latest/go1.25.darwin-arm64.tar.gz.sig" + "url": "https://aka.ms/golang/release/latest/go1.26.darwin-arm64.tar.gz", + "checksumURL": "https://aka.ms/golang/release/latest/go1.26.darwin-arm64.tar.gz.sha256", + "signatureURL": "https://aka.ms/golang/release/latest/go1.26.darwin-arm64.tar.gz.sig" }, { - "filename": "go1.25.linux-amd64.tar.gz", + "filename": "go1.26.linux-amd64.tar.gz", "os": "linux", "arch": "amd64", - "version": "go1.25", + "version": "go1.26", "kind": "archive", - "url": "https://aka.ms/golang/release/latest/go1.25.linux-amd64.tar.gz", - "checksumURL": "https://aka.ms/golang/release/latest/go1.25.linux-amd64.tar.gz.sha256", - "signatureURL": "https://aka.ms/golang/release/latest/go1.25.linux-amd64.tar.gz.sig" + "url": "https://aka.ms/golang/release/latest/go1.26.linux-amd64.tar.gz", + "checksumURL": "https://aka.ms/golang/release/latest/go1.26.linux-amd64.tar.gz.sha256", + "signatureURL": "https://aka.ms/golang/release/latest/go1.26.linux-amd64.tar.gz.sig" }, { - "filename": "go1.25.linux-arm64.tar.gz", + "filename": "go1.26.linux-arm64.tar.gz", "os": "linux", "arch": "arm64", - "version": "go1.25", + "version": "go1.26", "kind": "archive", - "url": "https://aka.ms/golang/release/latest/go1.25.linux-arm64.tar.gz", - "checksumURL": "https://aka.ms/golang/release/latest/go1.25.linux-arm64.tar.gz.sha256", - "signatureURL": "https://aka.ms/golang/release/latest/go1.25.linux-arm64.tar.gz.sig" + "url": "https://aka.ms/golang/release/latest/go1.26.linux-arm64.tar.gz", + "checksumURL": "https://aka.ms/golang/release/latest/go1.26.linux-arm64.tar.gz.sha256", + "signatureURL": "https://aka.ms/golang/release/latest/go1.26.linux-arm64.tar.gz.sig" }, { - "filename": "go1.25.linux-armv6l.tar.gz", + "filename": "go1.26.linux-armv6l.tar.gz", "os": "linux", "arch": "armv6l", - "version": "go1.25", + "version": "go1.26", "kind": "archive", - "url": "https://aka.ms/golang/release/latest/go1.25.linux-armv6l.tar.gz", - "checksumURL": "https://aka.ms/golang/release/latest/go1.25.linux-armv6l.tar.gz.sha256", - "signatureURL": "https://aka.ms/golang/release/latest/go1.25.linux-armv6l.tar.gz.sig" + "url": "https://aka.ms/golang/release/latest/go1.26.linux-armv6l.tar.gz", + "checksumURL": "https://aka.ms/golang/release/latest/go1.26.linux-armv6l.tar.gz.sha256", + "signatureURL": "https://aka.ms/golang/release/latest/go1.26.linux-armv6l.tar.gz.sig" }, { - "filename": "go1.25.windows-amd64.zip", + "filename": "go1.26.windows-amd64.zip", "os": "windows", "arch": "amd64", - "version": "go1.25", + "version": "go1.26", "kind": "archive", - "url": "https://aka.ms/golang/release/latest/go1.25.windows-amd64.zip", - "checksumURL": "https://aka.ms/golang/release/latest/go1.25.windows-amd64.zip.sha256" + "url": "https://aka.ms/golang/release/latest/go1.26.windows-amd64.zip", + "checksumURL": "https://aka.ms/golang/release/latest/go1.26.windows-amd64.zip.sha256" + }, + { + "filename": "go1.26.windows-arm64.zip", + "os": "windows", + "arch": "arm64", + "version": "go1.26", + "kind": "archive", + "url": "https://aka.ms/golang/release/latest/go1.26.windows-arm64.zip", + "checksumURL": "https://aka.ms/golang/release/latest/go1.26.windows-arm64.zip.sha256" } ] }