diff --git a/eng/doc/MigrationGuide.md b/eng/doc/MigrationGuide.md new file mode 100644 index 0000000000..b244de0ba2 --- /dev/null +++ b/eng/doc/MigrationGuide.md @@ -0,0 +1,56 @@ +# Migration Guide: Switching to the Microsoft build of Go Toolset + +This guide provides step-by-step instructions on migrating from Google's Go distribution to the Microsoft build of Go toolset. It also covers enabling FIPS compliance and common troubleshooting steps. + +## Prerequisites + +- Ensure your system meets the Microsoft build of Go toolset requirements. +- Backup your existing Go environment before making changes. +- Verify that all dependencies are available in the Microsoft build of Go toolset. + +## Installing the Microsoft build of Go Toolset + +See [Downloading a binary release of the Microsoft build of Go](./Downloads.md) for our up-to-date documentation on downloading the Microsoft build of Go Toolset. + +## Enabling FIPS Mode + +The Microsoft build of Go toolset provides FIPS-compliant cryptographic operations by leveraging system cryptography on Windows and macOS. On Linux, the toolset leverages OpenSSL's FIPS-compliant implementation. + +### FIPS configuration + +The toolchain accepts the FIPS-related settings which align with the upstream Go toolchain: + +- `GODEBUG=fips140=on` (runtime setting) enables the FIPS 140-3 compliant cryptographic module. Supersedes `GOFIPS=1`, which is now deprecated. +- `GODEBUG=fips140=only` (runtime setting) acts as `on`, but panics if a non-FIPS 140-3 compliant algorithm is used. This setting is partially supported in Go 1.24, and will be fully supported in Go 1.25. +- `GOFIPS140=latest` (build setting) sets `GODEBUG=fips140` to `on` by default. Replaces `-tags=requirefips`. + +To know more about these settings, please refer to [our FIPS documentation](./fips/README.md). + +Note that the Go runtime will automatically enter FIPS mode when running on a FIPS-compliant system, such as [Azure Linux](https://github.com/microsoft/azurelinux) or [Windows](https://learn.microsoft.com/en-us/windows/security/security-foundations/certification/fips-140-validation), so you don't need to set `GODEBUG=fips140=on` on those systems. + +## Checking Supported Cryptographic Algorithms + +For details on the cryptographic algorithms supported by the Microsoft build of Go toolset across different platforms, refer to [Cross-Platform Cryptography in the Microsoft Build of Go](./CrossPlatformCryptography.md). + +## FAQ + +1. Why is my FIPS mode not working? + Ensure that: + - Your system FIPS mode is enabled. + - You are using only system-approved cryptographic algorithms. + - You have set `GODEBUG=fips140=on`. + +1. Will my existing Go code work with Microsoft build of Go? + + Yes, most Go code will work without modification. However, if you rely on custom cryptographic implementations, you may need to adjust your code for FIPS compliance. + +1. I'm seeing `panic: opensslcrypto: can't enable FIPS mode for OpenSSL 3.3.2: OSSL_PROVIDER_try_load` + + You are likely building with a Microsoft Build of Go version older than Go `1.23.3-2`, which is the minimum required to support Azure Linux 3.0. + +## Support +For further assistance, please open a [new GitHub issue](https://github.com/microsoft/go/issues/new). + +--- + +By following this guide, you should be able to smoothly transition from Google's Go distribution to the Microsoft build of Go toolset and enable FIPS compliance where necessary.