diff --git a/eng/_util/cmd/updatecryptodocs/docs.go b/eng/_util/cmd/updatecryptodocs/docs.go index 35545d2e36a..7679c83d3f7 100644 --- a/eng/_util/cmd/updatecryptodocs/docs.go +++ b/eng/_util/cmd/updatecryptodocs/docs.go @@ -181,6 +181,13 @@ var doc = Document{ Notes: []string{ "Supports only hash algorithms that are supported as standalone hash functions.", }, + Platforms: Platforms{ + Windows: PlatformStatus{ + Notes: []string{ + "The CNG backend does not support sha224.", + }, + }, + }, }, }, }, @@ -232,6 +239,7 @@ var doc = Document{ Linux: PlatformStatus{ Supported: Warn, Notes: []string{ + "OpenSSL does not provide DES implementations in FIPS mode.", "When using OpenSSL 3, requires the legacy provider to be enabled.", }, }, @@ -243,6 +251,7 @@ var doc = Document{ Linux: PlatformStatus{ Supported: Warn, Notes: []string{ + "OpenSSL does not provide DES implementations in FIPS mode.", "When using OpenSSL 3, requires the legacy provider to be enabled.", }, }, @@ -256,6 +265,7 @@ var doc = Document{ Linux: PlatformStatus{ Supported: Warn, Notes: []string{ + "Some OpenSSL distributions don't implement RC4 (e.g., OpenSSL 1.x with -DOPENSSL_NO_RC4).", "When using OpenSSL 3, requires the legacy provider to be enabled.", }, }, @@ -304,6 +314,7 @@ var doc = Document{ Name: "OAEP (SHA-2)", Notes: []string{ "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms).", + "Requires OAEPOptions.Hash to match OAEPOptions.MGFHash.", }, Platforms: Platforms{ MacOS: PlatformStatus{ @@ -317,6 +328,7 @@ var doc = Document{ Name: "OAEP (SHA-3)", Notes: []string{ "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms).", + "Requires OAEPOptions.Hash to match OAEPOptions.MGFHash.", }, MinGoVersion: "1.26", Platforms: Platforms{ @@ -462,16 +474,28 @@ var doc = Document{ Title: "Ed25519", ColumnHeader: "Schemes", Packages: []string{"crypto/ed25519"}, - Description: "Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader).", + DescriptionParagraphs: []string{ + "Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader).", + "The CNG backend and some old OpenSSL distributions don't support Ed25519.", + }, Items: []Item{ { Name: "Ed25519", Platforms: Platforms{ Windows: PlatformStatus{Supported: NotSupported}, + Linux: PlatformStatus{ + MinVersion: "1.1.1b", + Notes: []string{ + "Verify requires OpenSSL 1.1.1b or higher.", + }, + }, }, }, { Name: "Ed25519ctx", + Notes: []string{ + "Only opts.Hash == nil && opts.Context == \"\" is implemented using the OpenSSL backend.", + }, Platforms: Platforms{ Windows: PlatformStatus{Supported: NotSupported}, Linux: PlatformStatus{Supported: NotSupported}, @@ -480,6 +504,9 @@ var doc = Document{ }, { Name: "Ed25519ph", + Notes: []string{ + "Only opts.Hash == nil && opts.Context == \"\" is implemented using the OpenSSL backend.", + }, Platforms: Platforms{ Windows: PlatformStatus{Supported: NotSupported}, Linux: PlatformStatus{Supported: NotSupported}, @@ -671,6 +698,10 @@ var doc = Document{ "TLS Signature Schemes", "crypto/tls", }, + DescriptionParagraphs: []string{ + "Package tls will automatically use FIPS compliant primitives implemented in other crypto packages.", + "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.", + }, Subsections: []Section{ { Title: "TLS Versions", diff --git a/eng/doc/CrossPlatformCryptography.md b/eng/doc/CrossPlatformCryptography.md index 17b727ccb1c..9d2a4b40196 100644 --- a/eng/doc/CrossPlatformCryptography.md +++ b/eng/doc/CrossPlatformCryptography.md @@ -75,7 +75,7 @@ This section includes the following packages: | SHAKE-256 | ✔️ | ✔️6 | ❌️ | | CSHAKE-128 | ✔️ | ❌️ | ❌️ | | CSHAKE-256 | ✔️ | ❌️ | ❌️ | -| HMAC7 | ✔️ | ✔️ | ✔️ | +| HMAC7 | ✔️8 | ✔️ | ✔️ | 1Available starting in the Microsoft build of Go 1.24. @@ -91,6 +91,8 @@ This section includes the following packages: 7Supports only hash algorithms that are supported as standalone hash functions. +8The CNG backend does not support sha224. + ## Symmetric encryption This section includes the following packages: @@ -100,23 +102,27 @@ This section includes the following packages: - [crypto/des](https://pkg.go.dev/crypto/des) - [crypto/rc4](https://pkg.go.dev/crypto/rc4) -| Cipher + Mode | Windows | Linux | macOS | -| ------------------- | ------- | -------------- | ----- | -| AES-ECB | ✔️ | ✔️ | ✔️ | -| AES-CBC | ✔️ | ✔️ | ✔️ | -| AES-CTR | ❌️ | ✔️ | ❌️ | -| AES-CFB | ❌️ | ❌️ | ❌️ | -| AES-OFB | ❌️ | ❌️ | ❌️ | -| AES-GCM1 | ✔️ | ✔️ | ✔️ | -| DES-CBC | ✔️ | ⚠️2 | ✔️ | -| DES-ECB | ✔️ | ⚠️2 | ✔️ | -| 3DES-ECB | ✔️ | ✔️ | ✔️ | -| 3DES-CBC | ✔️ | ✔️ | ✔️ | -| RC4 | ✔️ | ⚠️2 | ✔️ | +| Cipher + Mode | Windows | Linux | macOS | +| ------------------- | ------- | ---------------- | ----- | +| AES-ECB | ✔️ | ✔️ | ✔️ | +| AES-CBC | ✔️ | ✔️ | ✔️ | +| AES-CTR | ❌️ | ✔️ | ❌️ | +| AES-CFB | ❌️ | ❌️ | ❌️ | +| AES-OFB | ❌️ | ❌️ | ❌️ | +| AES-GCM1 | ✔️ | ✔️ | ✔️ | +| DES-CBC | ✔️ | ⚠️2,3 | ✔️ | +| DES-ECB | ✔️ | ⚠️2,3 | ✔️ | +| 3DES-ECB | ✔️ | ✔️ | ✔️ | +| 3DES-CBC | ✔️ | ✔️ | ✔️ | +| RC4 | ✔️ | ⚠️3,4 | ✔️ | 1AES-GCM supports specific keys, nonces, and tags: -2When using OpenSSL 3, requires the legacy provider to be enabled. +2OpenSSL does not provide DES implementations in FIPS mode. + +3When using OpenSSL 3, requires the legacy provider to be enabled. + +4Some OpenSSL distributions don't implement RC4 (e.g., OpenSSL 1.x with -DOPENSSL_NO_RC4). - Key Sizes @@ -158,35 +164,37 @@ Operations that require random numbers (rand io.Reader) only support [rand.Reade | -------------------------------------- | ---------------- | -------------- | -------------- | | OAEP (MD5) | ✔️ | ✔️ | ✔️1 | | OAEP (SHA-1) | ✔️ | ✔️ | ✔️1 | -| OAEP (SHA-2)2 | ✔️ | ✔️ | ✔️1 | -| OAEP (SHA-3)2,3 | ✔️ | ✔️ | ❌️ | -| PSS (MD5) | ✔️4 | ✔️ | ❌️ | -| PSS (SHA-1) | ✔️4 | ✔️ | ✔️5 | -| PSS (SHA-2)2 | ✔️4 | ✔️ | ✔️5 | -| PSS (SHA-3)2 | ✔️3 | ✔️ | ❌️ | +| OAEP (SHA-2)2,3 | ✔️ | ✔️ | ✔️1 | +| OAEP (SHA-3)2,3,4 | ✔️ | ✔️ | ❌️ | +| PSS (MD5) | ✔️5 | ✔️ | ❌️ | +| PSS (SHA-1) | ✔️5 | ✔️ | ✔️6 | +| PSS (SHA-2)2 | ✔️5 | ✔️ | ✔️6 | +| PSS (SHA-3)2 | ✔️4 | ✔️ | ❌️ | | PKCS1v15 Signature (Unhashed) | ✔️ | ✔️ | ✔️ | -| PKCS1v15 Signature (RIPMED160) | ❌️ | ✔️6 | ❌️ | +| PKCS1v15 Signature (RIPMED160) | ❌️ | ✔️7 | ❌️ | | PKCS1v15 Signature (MD5) | ✔️ | ✔️ | ❌️ | -| PKCS1v15 Signature (MD5-SHA1) | ✔️6 | ✔️6 | ❌️ | +| PKCS1v15 Signature (MD5-SHA1) | ✔️7 | ✔️7 | ❌️ | | PKCS1v15 Signature (SHA-1) | ✔️ | ✔️ | ✔️ | | PKCS1v15 Signature (SHA-2)2 | ✔️ | ✔️ | ✔️ | -| PKCS1v15 Signature (SHA-3) | ✔️3,7 | ✔️8 | ❌️ | +| PKCS1v15 Signature (SHA-3) | ✔️4,8 | ✔️9 | ❌️ | 1macOS doesn't support passing a custom label to OAEP functions. 2Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms). -3Available starting in the Microsoft build of Go 1.26. +3Requires OAEPOptions.Hash to match OAEPOptions.MGFHash. + +4Available starting in the Microsoft build of Go 1.26. -4Verifying PSS signatures with [rsa.PSSSaltLengthAuto](https://pkg.go.dev/crypto/rsa#pkg-constants) is not supported. +5Verifying PSS signatures with [rsa.PSSSaltLengthAuto](https://pkg.go.dev/crypto/rsa#pkg-constants) is not supported. -5Custom salt lengths are not supported. PSS always uses the [`rsa.PSSSaltLengthEqualsHash`](https://pkg.go.dev/crypto/rsa#pkg-constants). +6Custom salt lengths are not supported. PSS always uses the [`rsa.PSSSaltLengthEqualsHash`](https://pkg.go.dev/crypto/rsa#pkg-constants). -6Available starting in the Microsoft build of Go 1.24. +7Available starting in the Microsoft build of Go 1.24. -7Requires Windows 11 (24H2) or later. +8Requires Windows 11 (24H2) or later. -8Requires OpenSSL 1.1.1 or later. +9Requires OpenSSL 1.1.1 or later. ### ECDSA @@ -232,11 +240,19 @@ This section includes the following packages: Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). -| Schemes | Windows | Linux | macOS | -| ---------- | ------- | ----- | ----- | -| Ed25519 | ❌️ | ✔️ | ✔️ | -| Ed25519ctx | ❌️ | ❌️ | ❌️ | -| Ed25519ph | ❌️ | ❌️ | ❌️ | +The CNG backend and some old OpenSSL distributions don't support Ed25519. + +| Schemes | Windows | Linux | macOS | +| ---------------------- | ------- | ---------------- | ----- | +| Ed25519 | ❌️ | ✔️1,2 | ✔️ | +| Ed25519ctx3 | ❌️ | ❌️ | ❌️ | +| Ed25519ph3 | ❌️ | ❌️ | ❌️ | + +1Requires OpenSSL 1.1.1b or later. + +2Verify requires OpenSSL 1.1.1b or higher. + +3Only opts.Hash == nil && opts.Context == "" is implemented using the OpenSSL backend. ### DSA @@ -353,7 +369,9 @@ This section includes the following packages: - [crypto/tls](https://pkg.go.dev/crypto/tls) -This section includes the following subsections: +Package tls will automatically use FIPS compliant primitives implemented in other crypto packages. + +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. - [TLS Versions](#tls-versions) - [TLS Cipher Suites](#tls-cipher-suites)