From 6ded68fa70465f111b2196a5e92110265f07957b Mon Sep 17 00:00:00 2001 From: George Adams Date: Wed, 10 Dec 2025 15:39:58 +0000 Subject: [PATCH 1/7] auto generate crypto platform doc and programatically store status --- .gitignore | 1 + eng/_util/cmd/gencryptodoc/crypto.json | 2199 ++++++++++++++++++++++++ eng/_util/cmd/gencryptodoc/header.md | 45 + eng/_util/cmd/gencryptodoc/main.go | 317 ++++ eng/_util/cmd/gencryptodoc/schema.json | 51 + eng/doc/CrossPlatformCryptography.md | 195 +-- 6 files changed, 2708 insertions(+), 100 deletions(-) create mode 100644 .gitignore create mode 100644 eng/_util/cmd/gencryptodoc/crypto.json create mode 100644 eng/_util/cmd/gencryptodoc/header.md create mode 100644 eng/_util/cmd/gencryptodoc/main.go create mode 100644 eng/_util/cmd/gencryptodoc/schema.json diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000000..505c905fa0a --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +microsoft-go.sln diff --git a/eng/_util/cmd/gencryptodoc/crypto.json b/eng/_util/cmd/gencryptodoc/crypto.json new file mode 100644 index 00000000000..21176b4406e --- /dev/null +++ b/eng/_util/cmd/gencryptodoc/crypto.json @@ -0,0 +1,2199 @@ +{ + "$schema": "./schema.json", + "sections": [ + { + "title": "Hash and Message Authentication Algorithms", + "packages": [ + "crypto/md5", + "crypto/sha1", + "crypto/sha256", + "crypto/sha512", + "crypto/sha3", + "crypto/hmac" + ], + "description": "", + "subsections": [], + "items": [ + { + "name": "MD5", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "SHA-1", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "SHA-2-224", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "SHA-2-256", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "SHA-2-384", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "SHA-2-512", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "SHA-2-512_224", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "true", + "notes": [ + "Available starting in the Microsoft build of Go 1.24.", + "Requires OpenSSL 1.1.1 or later." + ] + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "SHA-2-512_256", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "true", + "notes": [ + "Available starting in the Microsoft build of Go 1.24.", + "Requires OpenSSL 1.1.1 or later." + ] + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "SHA-3-224", + "notes": ["Available starting in the Microsoft build of Go 1.26."], + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "true", + "notes": ["Requires OpenSSL 1.1.1 or later."] + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "SHA-3-256", + "notes": ["Available starting in the Microsoft build of Go 1.26."], + "platforms": { + "windows": { + "supported": "true", + "notes": ["Available in Windows 11, version 24H2 or later."] + }, + "linux": { + "supported": "true", + "notes": ["Requires OpenSSL 1.1.1 or later."] + }, + "macos": { + "supported": "true", + "notes": ["Available starting in macOS 26 (Tahoe)."] + } + } + }, + { + "name": "SHA-3-384", + "notes": ["Available starting in the Microsoft build of Go 1.26."], + "platforms": { + "windows": { + "supported": "true", + "notes": ["Available in Windows 11, version 24H2 or later."] + }, + "linux": { + "supported": "true", + "notes": ["Requires OpenSSL 1.1.1 or later."] + }, + "macos": { + "supported": "true", + "notes": ["Available starting in macOS 26 (Tahoe)."] + } + } + }, + { + "name": "SHA-3-512", + "notes": ["Available starting in the Microsoft build of Go 1.26."], + "platforms": { + "windows": { + "supported": "true", + "notes": ["Available in Windows 11, version 24H2 or later."] + }, + "linux": { + "supported": "true", + "notes": ["Requires OpenSSL 1.1.1 or later."] + }, + "macos": { + "supported": "true", + "notes": ["Available starting in macOS 26 (Tahoe)."] + } + } + }, + { + "name": "SHAKE-128", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true", + "notes": ["Requires OpenSSL 3.3 or later."] + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "SHAKE-256", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true", + "notes": ["Requires OpenSSL 3.3 or later."] + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "CSHAKE-128", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "false" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "CSHAKE-256", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "false" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "HMAC", + "notes": [ + "Supports only hash algorithms that are supported as standalone hash functions." + ], + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + } + ] + }, + { + "title": "Symmetric encryption", + "packages": ["crypto/aes", "crypto/cipher", "crypto/des", "crypto/rc4"], + "description": "", + "footer": "- Key Sizes\n\n AES-GCM works with 128, 192, and 256-bit keys.\n\n- Nonce Sizes\n\n AES-GCM works with 12-byte nonces.\n\n- Tag Sizes\n\n AES-GCM works with 16-byte tags.", + "subsections": [], + "items": [ + { + "name": "AES-ECB", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "AES-CBC", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "AES-CTR", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "AES-CFB", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "false" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "AES-OFB", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "false" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "AES-GCM", + "notes": ["AES-GCM supports specific keys, nonces, and tags:"], + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "DES-CBC", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "warn", + "notes": [ + "When using OpenSSL 3, requires the legacy provider to be enabled." + ] + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "DES-ECB", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "warn", + "notes": [ + "When using OpenSSL 3, requires the legacy provider to be enabled." + ] + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "3DES-ECB", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "3DES-CBC", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "RC4", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "warn", + "notes": [ + "When using OpenSSL 3, requires the legacy provider to be enabled." + ] + }, + "macos": { + "supported": "true" + } + } + } + ] + }, + { + "title": "Asymmetric encryption", + "packages": ["RSA", "ECDSA", "ECDH", "Ed25519", "DSA"], + "description": "", + "table": null, + "subsections": [ + { + "title": "RSA", + "packages": ["crypto/rsa"], + "description": "[rsa.GenerateKey](https://pkg.go.dev/crypto/rsa#GenerateKey) only supports the following key sizes (in bits): 2048, 3072, 4096.\nMulti-prime RSA keys are not supported.\nThe RSA key size is subject to the limitations of the underlying cryptographic library.\nFor example, on some Windows and SCOSSL configurations, the key size should be multiple of 8.\nPlease refer to the documentation of the underlying cryptographic library for the specific limitations.\nOperations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader).", + "subsections": [], + "items": [ + { + "name": "OAEP (MD5)", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true", + "notes": [ + "macOS doesn't support passing a custom label to OAEP functions." + ] + } + } + }, + { + "name": "OAEP (SHA-1)", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true", + "notes": [ + "macOS doesn't support passing a custom label to OAEP functions." + ] + } + } + }, + { + "name": "OAEP (SHA-2)", + "notes": [ + "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." + ], + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true", + "notes": [ + "macOS doesn't support passing a custom label to OAEP functions." + ] + } + } + }, + { + "name": "OAEP (SHA-3)", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "false" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "PSS (MD5)", + "platforms": { + "windows": { + "supported": "true", + "notes": [ + "On Windows, when verifying a PSS signature, [rsa.PSSSaltLengthAuto](https://pkg.go.dev/crypto/rsa#pkg-constants) is not supported." + ] + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "PSS (SHA-1)", + "platforms": { + "windows": { + "supported": "true", + "notes": [ + "On Windows, when verifying a PSS signature, [rsa.PSSSaltLengthAuto](https://pkg.go.dev/crypto/rsa#pkg-constants) is not supported." + ] + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true", + "notes": [ + "On macOS, custom salt lengths are not supported. PSS always uses the [`rsa.PSSSaltLengthEqualsHash`](https://pkg.go.dev/crypto/rsa#pkg-constants)." + ] + } + } + }, + { + "name": "PSS (SHA-2)", + "notes": [ + "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." + ], + "platforms": { + "windows": { + "supported": "true", + "notes": [ + "On Windows, when verifying a PSS signature, [rsa.PSSSaltLengthAuto](https://pkg.go.dev/crypto/rsa#pkg-constants) is not supported." + ] + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true", + "notes": [ + "On macOS, custom salt lengths are not supported. PSS always uses the [`rsa.PSSSaltLengthEqualsHash`](https://pkg.go.dev/crypto/rsa#pkg-constants)." + ] + } + } + }, + { + "name": "PSS (SHA-3)", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "false" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "PKCS1v15 Signature (Unhashed)", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "PKCS1v15 Signature (RIPMED160)", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "true", + "notes": [ + "Available starting in the Microsoft build of Go 1.24." + ] + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "PKCS1v15 Signature (MD4)", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "true", + "notes": [ + "Available starting in the Microsoft build of Go 1.24." + ] + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "PKCS1v15 Signature (MD5)", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "PKCS1v15 Signature (MD5-SHA1)", + "platforms": { + "windows": { + "supported": "true", + "notes": [ + "Available starting in the Microsoft build of Go 1.24." + ] + }, + "linux": { + "supported": "true", + "notes": [ + "Available starting in the Microsoft build of Go 1.24." + ] + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "PKCS1v15 Signature (SHA-1)", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "PKCS1v15 Signature (SHA-2)", + "notes": [ + "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." + ], + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "PKCS1v15 Signature (SHA-3)", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "false" + }, + "macos": { + "supported": "false" + } + } + } + ] + }, + { + "title": "ECDSA", + "packages": ["crypto/ecdsa", "crypto/elliptic"], + "description": "Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader).", + "subsections": [], + "items": [ + { + "name": "NIST P-224 (secp224r1)", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "NIST P-256 (secp256r1)", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "NIST P-384 (secp384r1)", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "NIST P-521 (secp521r1)", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + } + ] + }, + { + "title": "ECDH", + "packages": ["crypto/ecdh"], + "description": "Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader).\nX25519 is available starting from the Microsoft build of Go 1.26.", + "subsections": [], + "items": [ + { + "name": "NIST P-224 (secp224r1)", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "NIST P-256 (secp256r1)", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "NIST P-384 (secp384r1)", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "NIST P-521 (secp521r1)", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "X25519 (curve25519)", + "notes": [ + "Available starting in the Microsoft build of Go 1.26." + ], + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true", + "notes": ["Requires OpenSSL 1.1.1 or later."] + }, + "macos": { + "supported": "true" + } + } + } + ] + }, + { + "title": "Ed25519", + "packages": ["crypto/ed25519"], + "description": "Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader).", + "subsections": [], + "items": [ + { + "name": "Ed25519", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "Ed25519ctx", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "false" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "Ed25519ph", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "false" + }, + "macos": { + "supported": "false" + } + } + } + ] + }, + { + "title": "DSA", + "packages": [], + "description": "", + "subsections": [], + "items": [ + { + "name": "L1024N160", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "L2048N224", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "L2048N256", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "L3072N256", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "false" + } + } + } + ] + } + ] + }, + { + "title": "Key derivation functions (KDFs)", + "packages": ["crypto/hkdf", "crypto/pbkdf2"], + "description": "", + "subsections": [], + "items": [ + { + "name": "PBKDF2", + "platforms": { + "windows": { + "supported": "true", + "notes": [ + "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." + ] + }, + "linux": { + "supported": "true", + "notes": [ + "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." + ] + }, + "macos": { + "supported": "true", + "notes": [ + "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." + ] + } + } + }, + { + "name": "HKDF", + "platforms": { + "windows": { + "supported": "true", + "notes": [ + "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." + ] + }, + "linux": { + "supported": "true", + "notes": [ + "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." + ] + }, + "macos": { + "supported": "true", + "notes": [ + "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." + ] + } + } + } + ] + }, + { + "title": "Key Encapsulation Mechanisms (KEMs)", + "packages": ["ML-KEM"], + "description": "", + "table": null, + "subsections": [ + { + "title": "ML-KEM", + "packages": ["crypto/mlkem"], + "description": "ML-KEM is available starting from the Microsoft build of Go 1.26.", + "subsections": [], + "items": [ + { + "name": "768", + "platforms": { + "windows": { + "supported": "true", + "notes": [ + "Requires Windows Server 2025 or Windows 11 (24H2, 25H2) or later." + ] + }, + "linux": { + "supported": "true", + "notes": ["Requires OpenSSL 3.5.0 or later."] + }, + "macos": { + "supported": "true", + "notes": ["Requires macOS 26 (Tahoe) or later."] + } + } + }, + { + "name": "1024", + "platforms": { + "windows": { + "supported": "true", + "notes": [ + "Requires Windows Server 2025 or Windows 11 (24H2, 25H2) or later." + ] + }, + "linux": { + "supported": "true", + "notes": ["Requires OpenSSL 3.5.0 or later."] + }, + "macos": { + "supported": "true", + "notes": ["Requires macOS 26 (Tahoe) or later."] + } + } + } + ] + } + ] + }, + { + "title": "Higher-level protocols", + "packages": ["HPKE", "TLS"], + "description": "High-level protocols are algorithms that combine multiple cryptographic primitives to provide a specific functionality,\nsuch as TLS or Hybrid Public Key Encryption (HPKE).\nThese protocols are implemented using native Go code, but they rely on the underlying OS cryptographic libraries for the cryptographic operations.", + "table": null, + "subsections": [ + { + "title": "Hybrid Public Key Encryption (HPKE)", + "packages": ["AEAD Functions", "KDFs", "KEMs", "crypto/hpke"], + "description": "", + "table": null, + "subsections": [ + { + "title": "HPKE Authenticated Encryption with Associated Data (AEAD) Functions", + "shortTitle": "AEAD Functions", + "packages": [], + "description": "", + "subsections": [], + "items": [ + { + "name": "AES-128-GCM", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "AES-256-GCM", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "ChaCha20Poly1305", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "false" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "Export-only", + "platforms": { + "windows": { + "supported": "N/A" + }, + "linux": { + "supported": "N/A" + }, + "macos": { + "supported": "N/A" + } + } + } + ] + }, + { + "title": "HPKE Key Derivation Functions (KDFs)", + "shortTitle": "KDFs", + "packages": [], + "description": "", + "subsections": [], + "items": [ + { + "name": "HKDF-SHA256", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "HKDF-SHA384", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "HKDF-SHA512", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + } + ] + }, + { + "title": "HPKE Key Encapsulation Mechanisms (KEMs)", + "shortTitle": "KEMs", + "packages": [], + "description": "", + "subsections": [], + "items": [ + { + "name": "DHKEM(P-256, HKDF-SHA256)", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "DHKEM(P-384, HKDF-SHA384)", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "DHKEM(P-521, HKDF-SHA512)", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "DHKEM(X25519, HKDF-SHA256)", + "notes": [ + "See the [X25519](#ecdh) section for requirements." + ], + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "ML-KEM-768", + "notes": [ + "See the [ML-KEM](#ml-kem) section for requirements." + ], + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "ML-KEM-1024", + "notes": [ + "See the [ML-KEM](#ml-kem) section for requirements." + ], + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "MLKEM768-P256", + "notes": [ + "See the [ML-KEM](#ml-kem) section for requirements." + ], + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "MLKEM1024-P384", + "notes": [ + "See the [ML-KEM](#ml-kem) section for requirements." + ], + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "MLKEM768-X25519", + "notes": [ + "See the [X25519](#ecdh) section for requirements.", + "See the [ML-KEM](#ml-kem) section for requirements." + ], + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + } + ] + } + ] + }, + { + "title": "TLS", + "packages": [ + "TLS Versions", + "TLS Cipher Suites", + "TLS Curves and Groups", + "TLS Signature Schemes", + "crypto/tls" + ], + "description": "", + "table": null, + "subsections": [ + { + "title": "TLS Versions", + "packages": [], + "description": "The TLS stack is implemented using native Go code but the crypto primitives are provided by the system cryptographic libraries.", + "subsections": [], + "items": [ + { + "name": "SSL 3.0", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "false" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "TLS 1.0", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "TLS 1.1", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "TLS 1.2", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS 1.3", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + } + ] + }, + { + "title": "TLS Cipher Suites", + "packages": [], + "footer": "On Windows, it is possible to restrict and reorder the cipher suites following the [Schannel preferences](https://learn.microsoft.com/en-us/windows/win32/secauthn/cipher-suites-in-schannel) by building with the `ms_tls_config_schannel` goexperiment enabled.", + "subsections": [], + "items": [ + { + "name": "TLS_RSA_WITH_RC4_128_SHA", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "warn", + "notes": [ + "When using OpenSSL 3, requires the legacy provider to be enabled." + ] + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_RSA_WITH_3DES_EDE_CBC_SHA", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "warn", + "notes": [ + "When using OpenSSL 3, requires the legacy provider to be enabled." + ] + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_RSA_WITH_AES_128_CBC_SHA", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_RSA_WITH_AES_256_CBC_SHA", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_RSA_WITH_AES_128_CBC_SHA256", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_RSA_WITH_AES_128_GCM_SHA256", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_RSA_WITH_AES_256_GCM_SHA384", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_ECDHE_ECDSA_WITH_RC4_128_SHA", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "warn", + "notes": [ + "When using OpenSSL 3, requires the legacy provider to be enabled." + ] + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_ECDHE_RSA_WITH_RC4_128_SHA", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "warn", + "notes": [ + "When using OpenSSL 3, requires the legacy provider to be enabled." + ] + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "warn", + "notes": [ + "When using OpenSSL 3, requires the legacy provider to be enabled." + ] + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "false" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "false" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "TLS_AES_128_GCM_SHA256", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_AES_256_GCM_SHA384", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "TLS_CHACHA20_POLY1305_SHA256", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "false" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "false" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "false" + }, + "macos": { + "supported": "false" + } + } + }, + { + "name": "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "false" + }, + "macos": { + "supported": "false" + } + } + } + ] + }, + { + "title": "TLS Curves and Groups", + "packages": [], + "description": "Below are the supported [`tls.CurveIDs`](https://pkg.go.dev/crypto/tls#CurveID).", + "subsections": [], + "items": [ + { + "name": "CurveP256", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "CurveP384", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "CurveP521", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "X25519", + "notes": [ + "See the [X25519](#ecdh) section for requirements." + ], + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "X25519MLKEM768", + "notes": [ + "See the [X25519](#ecdh) section for requirements.", + "See the [ML-KEM](#ml-kem) section for requirements." + ], + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "SecP256r1MLKEM768", + "notes": [ + "See the [ML-KEM](#ml-kem) section for requirements." + ], + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "SecP384r1MLKEM1024", + "notes": [ + "See the [ML-KEM](#ml-kem) section for requirements." + ], + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + } + ] + }, + { + "title": "TLS Signature Schemes", + "packages": [], + "description": "Below are the supported [`tls.SignatureSchemes`](https://pkg.go.dev/crypto/tls#SignatureScheme).", + "subsections": [], + "items": [ + { + "name": "PKCS1WithSHA1", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "PKCS1WithSHA256", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "PKCS1WithSHA384", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "PKCS1WithSHA512", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "PSSWithSHA256", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "PSSWithSHA384", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "PSSWithSHA512", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "ECDSAWithSHA1", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "ECDSAWithP256AndSHA256", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "ECDSAWithP384AndSHA384", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "ECDSAWithP521AndSHA512", + "platforms": { + "windows": { + "supported": "true" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + }, + { + "name": "Ed25519", + "platforms": { + "windows": { + "supported": "false" + }, + "linux": { + "supported": "true" + }, + "macos": { + "supported": "true" + } + } + } + ] + } + ] + } + ] + } + ] +} diff --git a/eng/_util/cmd/gencryptodoc/header.md b/eng/_util/cmd/gencryptodoc/header.md new file mode 100644 index 00000000000..7c2690cc914 --- /dev/null +++ b/eng/_util/cmd/gencryptodoc/header.md @@ -0,0 +1,45 @@ +# Cross-Platform Cryptography in the Microsoft build of Go + +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. + +This article assumes you have a working familiarity with cryptography in Go. + +## Platform support + +The Microsoft build of Go supports the following platforms: + +### Windows + +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, 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). +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, the Microsoft build of 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. + +## Table legend + +The following legend describes the symbols used in the tables to indicate the level of support for each cryptographic algorithm: + +| Symbol | Meaning | +| ------ | ---------------------------------------------------------------------------------------------------------------------------- | +| ✔️ | Supported, possibly with minor limitations that don't require special configuration when using the latest Go and OS versions | +| ⚠️ | Supported with limitations that require special configuration action | +| ❌ | Not supported | + +When an algorithm is not supported or the limitations are exceeded, the Microsoft build of Go will fall back to the Go implementation. diff --git a/eng/_util/cmd/gencryptodoc/main.go b/eng/_util/cmd/gencryptodoc/main.go new file mode 100644 index 00000000000..bf8c617482f --- /dev/null +++ b/eng/_util/cmd/gencryptodoc/main.go @@ -0,0 +1,317 @@ +// Copyright (c) Microsoft Corporation. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + +//go:generate go run . -o ../../../doc/CrossPlatformCryptography.md crypto.json +//go:generate go run github.com/wasilibs/go-prettier/cmd/prettier@latest --write ../../../doc/CrossPlatformCryptography.md + +package main + +import ( + _ "embed" + "encoding/json" + "flag" + "fmt" + "os" + "sort" + "strings" +) + +//go:embed header.md +var header string + +type PlatformStatus struct { + Supported string `json:"supported"` + Notes []string `json:"notes,omitempty"` +} + +type Item struct { + Name string `json:"name"` + Notes []string `json:"notes,omitempty"` + Platforms map[string]PlatformStatus `json:"platforms"` +} + +type Section struct { + Title string `json:"title"` + ShortTitle string `json:"shortTitle,omitempty"` + Packages []string `json:"packages,omitempty"` + Description string `json:"description,omitempty"` + Items []Item `json:"items,omitempty"` + Subsections []Section `json:"subsections,omitempty"` + Footnotes []string `json:"footnotes,omitempty"` + Footer string `json:"footer,omitempty"` +} + +type Document struct { + Sections []Section `json:"sections"` +} + +var columnHeaders = map[string]string{ + "Hash and Message Authentication Algorithms": "Algorithm", + "Symmetric encryption": "Cipher + Mode", + "RSA": "Padding Mode", + "ECDSA": "Elliptic Curve", + "ECDH": "Elliptic Curve", + "Ed25519": "Schemes", + "DSA": "Parameters", + "Key derivation functions (KDFs)": "Functions", + "ML-KEM": "Parameters", + "HPKE Authenticated Encryption with Associated Data (AEAD) Functions": "Functions", + "HPKE Key Derivation Functions (KDFs)": "Functions", + "HPKE Key Encapsulation Mechanisms (KEMs)": "Functions", + "TLS Versions": "Version", + "TLS Cipher Suites": "Name", + "TLS Curves and Groups": "Name", + "TLS Signature Schemes": "Scheme", +} + +func main() { + output := flag.String("o", "", "output file path") + flag.Parse() + + args := flag.Args() + if len(args) != 1 { + fmt.Fprintf(os.Stderr, "Usage: %s [options] \n", os.Args[0]) + os.Exit(1) + } + + if *output != "" { + f, err := os.Create(*output) + if err != nil { + panic(err) + } + defer f.Close() + os.Stdout = f + } + + data, err := os.ReadFile(args[0]) + if err != nil { + panic(err) + } + + var doc Document + if err := json.Unmarshal(data, &doc); err != nil { + panic(err) + } + + if err := validate(doc); err != nil { + fmt.Fprintf(os.Stderr, "Validation error: %v\n", err) + os.Exit(1) + } + + fmt.Println("") + fmt.Println() + fmt.Println(header) + + for _, section := range doc.Sections { + printSection(section, 2) + } +} + +func printSection(section Section, level int) { + fmt.Printf("\n%s %s\n\n", strings.Repeat("#", level), section.Title) + + if section.Description != "" { + fmt.Println(section.Description) + fmt.Println() + } + + // Subsections list + if len(section.Subsections) > 0 { + if section.Description == "" { + fmt.Println("This section includes the following subsections:") + fmt.Println() + } + for _, sub := range section.Subsections { + // Generate anchor link + anchor := strings.ToLower(sub.Title) + anchor = strings.ReplaceAll(anchor, " ", "-") + anchor = strings.ReplaceAll(anchor, "(", "") + anchor = strings.ReplaceAll(anchor, ")", "") + + title := sub.Title + if sub.ShortTitle != "" { + title = sub.ShortTitle + } + fmt.Printf("- [%s](#%s)\n", title, anchor) + + } + fmt.Println() + } + + // Filter packages + var validPackages []string + for _, pkg := range section.Packages { + if strings.Contains(pkg, "/") || strings.Contains(pkg, ".") { + validPackages = append(validPackages, pkg) + } + } + + if len(validPackages) > 0 { + fmt.Println("This section includes the following packages:") + fmt.Println() + for _, pkg := range validPackages { + if strings.HasPrefix(pkg, "crypto/") { + fmt.Printf("- [%s](https://pkg.go.dev/%s)\n", pkg, pkg) + } else if strings.HasPrefix(pkg, "golang.org/") { + fmt.Printf("- [%s](https://pkg.go.dev/%s)\n", pkg, pkg) + } else { + // Fallback + fmt.Printf("- %s\n", pkg) + } + } + fmt.Println() + } + + if len(section.Items) > 0 { + printTable(section) + } + + if section.Footer != "" { + fmt.Println(section.Footer) + fmt.Println() + } + + for _, sub := range section.Subsections { + printSection(sub, level+1) + } +} + +func printTable(section Section) { + colHeader, ok := columnHeaders[section.Title] + if !ok { + colHeader = "Algorithm" // Default + } + + fmt.Printf("| %s | Windows | Linux | macOS |\n", colHeader) + + // Separator line + // I need to match the length of dashes if I want exact diff, but markdown doesn't strictly require it. + // The original file had varying lengths. + // I'll just use standard lengths. + fmt.Println("| --- | --- | --- | --- |") + + // Collect footnotes + footnotes := make(map[string]int) + nextFootnote := 1 + + // Pre-populate from section.Footnotes + for _, note := range section.Footnotes { + if _, exists := footnotes[note]; !exists { + footnotes[note] = nextFootnote + nextFootnote++ + } + } + + // Helper to get footnote indices + getFootnotes := func(notes []string) string { + if len(notes) == 0 { + return "" + } + var indices []int + for _, note := range notes { + idx, exists := footnotes[note] + if !exists { + idx = nextFootnote + footnotes[note] = idx + nextFootnote++ + } + indices = append(indices, idx) + } + sort.Ints(indices) + strs := make([]string, len(indices)) + for i, idx := range indices { + strs[i] = fmt.Sprintf("%d", idx) + } + return fmt.Sprintf("%s", strings.Join(strs, ",")) + } + + for _, item := range section.Items { + name := item.Name + nameNotes := getFootnotes(item.Notes) + + row := []string{name + nameNotes} + + for _, platform := range []string{"windows", "linux", "macos"} { + status := item.Platforms[platform] + symbol := "" + switch status.Supported { + case "N/A": + symbol = "N/A" + case "true": + symbol = "✔️" + case "warn": + symbol = "⚠️" + default: + symbol = "❌" + } + + notes := getFootnotes(status.Notes) + // Space before notes? Original: ✔️1 or ✔️ 1 + // Looking at original: ✔️1 (no space usually, but sometimes yes) + // "✔️ 4" in SHA-3-256 + // "✔️1" in PBKDF2 + // I'll use no space for now, or maybe check if I can detect it. + // The JSON doesn't store formatting. + // I'll use no space as it's cleaner. + row = append(row, symbol+notes) + } + + fmt.Printf("| %s | %s | %s | %s |\n", row[0], row[1], row[2], row[3]) + } + fmt.Println() + + // Print footnotes + // Sort by index + sortedNotes := make([]string, len(footnotes)) + for note, idx := range footnotes { + sortedNotes[idx-1] = note + } + + for i, note := range sortedNotes { + fmt.Printf("%d%s\n\n", i+1, note) + } +} + +func validate(doc Document) error { + for _, section := range doc.Sections { + if err := validateSection(section); err != nil { + return err + } + } + return nil +} + +func validateSection(section Section) error { + if section.Title == "" { + return fmt.Errorf("section missing title") + } + + for _, item := range section.Items { + if item.Name == "" { + return fmt.Errorf("item missing name in section %q", section.Title) + } + if item.Platforms == nil { + return fmt.Errorf("item %q missing platforms in section %q", item.Name, section.Title) + } + + for _, p := range []string{"windows", "linux", "macos"} { + status, ok := item.Platforms[p] + if !ok { + return fmt.Errorf("item %q missing platform %q in section %q", item.Name, p, section.Title) + } + switch status.Supported { + case "true", "false", "warn", "N/A": + // ok + default: + return fmt.Errorf("invalid supported status %q for item %q on platform %q", status.Supported, item.Name, p) + } + } + } + for _, sub := range section.Subsections { + if err := validateSection(sub); err != nil { + return err + } + } + return nil +} diff --git a/eng/_util/cmd/gencryptodoc/schema.json b/eng/_util/cmd/gencryptodoc/schema.json new file mode 100644 index 00000000000..e53236c7605 --- /dev/null +++ b/eng/_util/cmd/gencryptodoc/schema.json @@ -0,0 +1,51 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "properties": { + "sections": { + "type": "array", + "items": { "$ref": "#/definitions/section" } + } + }, + "definitions": { + "section": { + "type": "object", + "properties": { + "title": { "type": "string" }, + "shortTitle": { "type": "string" }, + "packages": { "type": "array", "items": { "type": "string" } }, + "description": { "type": "string" }, + "items": { "type": "array", "items": { "$ref": "#/definitions/item" } }, + "subsections": { "type": "array", "items": { "$ref": "#/definitions/section" } }, + "footnotes": { "type": "array", "items": { "type": "string" } }, + "footer": { "type": "string" } + }, + "required": ["title"] + }, + "item": { + "type": "object", + "properties": { + "name": { "type": "string" }, + "notes": { "type": "array", "items": { "type": "string" } }, + "platforms": { + "type": "object", + "properties": { + "windows": { "$ref": "#/definitions/platformStatus" }, + "linux": { "$ref": "#/definitions/platformStatus" }, + "macos": { "$ref": "#/definitions/platformStatus" } + }, + "required": ["windows", "linux", "macos"] + } + }, + "required": ["name", "platforms"] + }, + "platformStatus": { + "type": "object", + "properties": { + "supported": { "type": "string", "enum": ["true", "false", "warn", "N/A"] }, + "notes": { "type": "array", "items": { "type": "string" } } + }, + "required": ["supported"] + } + } +} diff --git a/eng/doc/CrossPlatformCryptography.md b/eng/doc/CrossPlatformCryptography.md index 1492ecfaea2..6f5f2c36f5f 100644 --- a/eng/doc/CrossPlatformCryptography.md +++ b/eng/doc/CrossPlatformCryptography.md @@ -1,3 +1,5 @@ + + # Cross-Platform Cryptography in the Microsoft build of Go Cryptographic operations in the Microsoft build of Go are delegated to the operating system (OS) libraries in some conditions. @@ -28,7 +30,7 @@ SCOSSL is expected to be used with the default built-in provider enabled as a fa ## macOS -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. +On macOS, the Microsoft build of 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. @@ -52,28 +54,28 @@ This section includes the following packages: - [crypto/sha1](https://pkg.go.dev/crypto/sha1) - [crypto/sha256](https://pkg.go.dev/crypto/sha256) - [crypto/sha512](https://pkg.go.dev/crypto/sha512) -- [crypto/sha3](https://pkg.go.dev/golang.org/x/crypto/sha3) +- [crypto/sha3](https://pkg.go.dev/crypto/sha3) - [crypto/hmac](https://pkg.go.dev/crypto/hmac) -| Algorithm | Windows | Linux | macOS | -| ---------------------- | --------------- | ----------------- | --------------- | -| MD5 | ✔️ | ✔️ | ✔️ | -| SHA-1 | ✔️ | ✔️ | ✔️ | -| SHA-2-224 | ❌ | ✔️ | ✔️ | -| SHA-2-256 | ✔️ | ✔️ | ✔️ | -| SHA-2-384 | ✔️ | ✔️ | ✔️ | -| SHA-2-512 | ✔️ | ✔️ | ✔️ | -| SHA-2-512_224 | ❌ | ✔️1, 2 | ❌ | -| SHA-2-512_256 | ❌ | ✔️1, 2 | ❌ | -| SHA-3-224 3 | ❌ | ✔️ 2 | ❌ | -| SHA-3-256 3 | ✔️ 4 | ✔️ 2 | ✔️ 5 | -| SHA-3-384 3 | ✔️ 4 | ✔️ 2 | ✔️ 5 | -| SHA-3-512 3 | ✔️ 4 | ✔️ 2 | ✔️ 5 | -| SHAKE-128 | ✔️ | ✔️ 7 | ❌ | -| SHAKE-256 | ✔️ | ✔️ 7 | ❌ | -| CSHAKE-128 | ✔️ | ❌ | ❌ | -| CSHAKE-256 | ✔️ | ❌ | ❌ | -| HMAC6 | ✔️ | ✔️ | ✔️ | +| Algorithm | Windows | Linux | macOS | +| --------------------- | -------------- | ---------------- | -------------- | +| MD5 | ✔️ | ✔️ | ✔️ | +| SHA-1 | ✔️ | ✔️ | ✔️ | +| SHA-2-224 | ❌ | ✔️ | ✔️ | +| SHA-2-256 | ✔️ | ✔️ | ✔️ | +| SHA-2-384 | ✔️ | ✔️ | ✔️ | +| SHA-2-512 | ✔️ | ✔️ | ✔️ | +| SHA-2-512_224 | ❌ | ✔️1,2 | ❌ | +| SHA-2-512_256 | ❌ | ✔️1,2 | ❌ | +| SHA-3-2243 | ❌ | ✔️2 | ❌ | +| SHA-3-2563 | ✔️4 | ✔️2 | ✔️5 | +| SHA-3-3843 | ✔️4 | ✔️2 | ✔️5 | +| SHA-3-5123 | ✔️4 | ✔️2 | ✔️5 | +| SHAKE-128 | ✔️ | ✔️6 | ❌ | +| SHAKE-256 | ✔️ | ✔️6 | ❌ | +| CSHAKE-128 | ✔️ | ❌ | ❌ | +| CSHAKE-256 | ✔️ | ❌ | ❌ | +| HMAC7 | ✔️ | ✔️ | ✔️ | 1Available starting in the Microsoft build of Go 1.24. @@ -85,9 +87,9 @@ This section includes the following packages: 5Available starting in macOS 26 (Tahoe). -6Supports only hash algorithms that are supported as standalone hash functions. +6Requires OpenSSL 3.3 or later. -7Requires OpenSSL 3.3 or later. +7Supports only hash algorithms that are supported as standalone hash functions. ## Symmetric encryption @@ -105,16 +107,16 @@ This section includes the following packages: | AES-CTR | ❌ | ✔️ | ❌ | | AES-CFB | ❌ | ❌ | ❌ | | AES-OFB | ❌ | ❌ | ❌ | -| AES-GCM2 | ✔️ | ✔️ | ✔️ | -| DES-CBC | ✔️ | ⚠️1 | ✔️ | -| DES-ECB | ✔️ | ⚠️1 | ✔️ | +| AES-GCM1 | ✔️ | ✔️ | ✔️ | +| DES-CBC | ✔️ | ⚠️2 | ✔️ | +| DES-ECB | ✔️ | ⚠️2 | ✔️ | | 3DES-ECB | ✔️ | ✔️ | ✔️ | | 3DES-CBC | ✔️ | ✔️ | ✔️ | -| RC4 | ✔️ | ⚠️1 | ✔️ | +| RC4 | ✔️ | ⚠️2 | ✔️ | -1When using OpenSSL 3, requires the legacy provider to be enabled. +1AES-GCM supports specific keys, nonces, and tags: -2AES-GCM supports specific keys, nonces, and tags: +2When using OpenSSL 3, requires the legacy provider to be enabled. - Key Sizes @@ -140,58 +142,55 @@ This section includes the following subsections: ### RSA -This section includes the following packages: - -- [crypto/rsa](https://pkg.go.dev/crypto/rsa) - [rsa.GenerateKey](https://pkg.go.dev/crypto/rsa#GenerateKey) only supports the following key sizes (in bits): 2048, 3072, 4096. - Multi-prime RSA keys are not supported. - The RSA key size is subject to the limitations of the underlying cryptographic library. For example, on some Windows and SCOSSL configurations, the key size should be multiple of 8. Please refer to the documentation of the underlying cryptographic library for the specific limitations. - Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). +This section includes the following packages: + +- [crypto/rsa](https://pkg.go.dev/crypto/rsa) + | Padding Mode | Windows | Linux | macOS | | -------------------------------------- | -------------- | -------------- | -------------- | -| OAEP (MD5) | ✔️ | ✔️ | ✔️5 | -| OAEP (SHA-1) | ✔️ | ✔️ | ✔️5 | -| OAEP (SHA-2)1 | ✔️ | ✔️ | ✔️5 | +| OAEP (MD5) | ✔️ | ✔️ | ✔️1 | +| OAEP (SHA-1) | ✔️ | ✔️ | ✔️1 | +| OAEP (SHA-2)2 | ✔️ | ✔️ | ✔️1 | | OAEP (SHA-3) | ❌ | ❌ | ❌ | | PSS (MD5) | ✔️3 | ✔️ | ❌ | | PSS (SHA-1) | ✔️3 | ✔️ | ✔️4 | -| PSS (SHA-2)1 | ✔️3 | ✔️ | ✔️4 | +| PSS (SHA-2)2 | ✔️3 | ✔️ | ✔️4 | | PSS (SHA-3) | ❌ | ❌ | ❌ | | PKCS1v15 Signature (Unhashed) | ✔️ | ✔️ | ✔️ | -| PKCS1v15 Signature (RIPMED160) | ❌ | ✔️2 | ❌ | -| PKCS1v15 Signature (MD4) | ❌ | ✔️2 | ❌ | +| PKCS1v15 Signature (RIPMED160) | ❌ | ✔️5 | ❌ | +| PKCS1v15 Signature (MD4) | ❌ | ✔️5 | ❌ | | PKCS1v15 Signature (MD5) | ✔️ | ✔️ | ❌ | -| PKCS1v15 Signature (MD5-SHA1) | ✔️2 | ✔️2 | ❌ | +| PKCS1v15 Signature (MD5-SHA1) | ✔️5 | ✔️5 | ❌ | | PKCS1v15 Signature (SHA-1) | ✔️ | ✔️ | ✔️ | -| PKCS1v15 Signature (SHA-2)1 | ✔️ | ✔️ | ✔️ | +| PKCS1v15 Signature (SHA-2)2 | ✔️ | ✔️ | ✔️ | | PKCS1v15 Signature (SHA-3) | ❌ | ❌ | ❌ | -1Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms). +1macOS doesn't support passing a custom label to OAEP functions. -2Available starting in the Microsoft build of Go 1.24. +2Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms). 3On Windows, when verifying a PSS signature, [rsa.PSSSaltLengthAuto](https://pkg.go.dev/crypto/rsa#pkg-constants) is not supported. 4On macOS, custom salt lengths are not supported. PSS always uses the [`rsa.PSSSaltLengthEqualsHash`](https://pkg.go.dev/crypto/rsa#pkg-constants). -5macOS doesn't support passing a custom label to OAEP functions. +5Available starting in the Microsoft build of Go 1.24. ### ECDSA +Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). + This section includes the following packages: - [crypto/ecdsa](https://pkg.go.dev/crypto/ecdsa) - [crypto/elliptic](https://pkg.go.dev/crypto/elliptic) -Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). - | Elliptic Curve | Windows | Linux | macOS | | ---------------------- | ------- | ----- | ----- | | NIST P-224 (secp224r1) | ✔️ | ✔️ | ❌ | @@ -201,16 +200,15 @@ Operations that require random numbers (rand io.Reader) only support [rand.Reade ### ECDH -This section includes the following packages: - -- [crypto/ecdh](https://pkg.go.dev/crypto/ecdsa) - Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). - X25519 is available starting from the Microsoft build of Go 1.26. -| Elliptic Curve | Windows | Linux | macOS | -| ------------------------------- | ------- | --------------- | ----- | +This section includes the following packages: + +- [crypto/ecdh](https://pkg.go.dev/crypto/ecdh) + +| Elliptic Curve | Windows | Linux | macOS | +| ------------------------------- | ------- | -------------- | ----- | | NIST P-224 (secp224r1) | ✔️ | ✔️ | ❌ | | NIST P-256 (secp256r1) | ✔️ | ✔️ | ✔️ | | NIST P-384 (secp384r1) | ✔️ | ✔️ | ✔️ | @@ -223,12 +221,12 @@ X25519 is available starting from the Microsoft build of Go 1.26. ### Ed25519 +Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). + This section includes the following packages: - [crypto/ed25519](https://pkg.go.dev/crypto/ed25519) -Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). - | Schemes | Windows | Linux | macOS | | ---------- | ------- | ----- | ----- | | Ed25519 | ❌ | ✔️ | ✔️ | @@ -251,10 +249,10 @@ This section includes the following packages: - [crypto/hkdf](https://pkg.go.dev/crypto/hkdf) - [crypto/pbkdf2](https://pkg.go.dev/crypto/pbkdf2) -| Functions | Windows | Linux | macOS | -| --------- | --------------- | ---------------- | --------------- | -| PBKDF2 | ✔️ 1 | ✔️ 1 | ✔️ 1 | -| HKDF | ✔️ 1 | ✔️ 1 | ✔️ 1 | +| Functions | Windows | Linux | macOS | +| --------- | -------------- | -------------- | -------------- | +| PBKDF2 | ✔️1 | ✔️1 | ✔️1 | +| HKDF | ✔️1 | ✔️1 | ✔️1 | 1Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms). @@ -266,16 +264,16 @@ This section includes the following subsections: ### ML-KEM +ML-KEM is available starting from the Microsoft build of Go 1.26. + This section includes the following packages: - [crypto/mlkem](https://pkg.go.dev/crypto/mlkem) -ML-KEM is available starting from the Microsoft build of Go 1.26. - -| Parameters | Windows | Linux | macOS | -| ---------- | --------------- | ---------------- | --------------- | -| 768 | ✔️ 1 | ✔️ 2 | ✔️ 3 | -| 1024 | ✔️ 1 | ✔️ 2 | ✔️ 3 | +| Parameters | Windows | Linux | macOS | +| ---------- | -------------- | -------------- | -------------- | +| 768 | ✔️1 | ✔️2 | ✔️3 | +| 1024 | ✔️1 | ✔️2 | ✔️3 | 1Requires Windows Server 2025 or Windows 11 (24H2, 25H2) or later. @@ -287,12 +285,9 @@ ML-KEM is available starting from the Microsoft build of Go 1.26. High-level protocols are algorithms that combine multiple cryptographic primitives to provide a specific functionality, such as TLS or Hybrid Public Key Encryption (HPKE). - These protocols are implemented using native Go code, but they rely on the underlying OS cryptographic libraries for the cryptographic operations. -This section includes the following subsections: - -- [HPKE](#hybrid-public-key-encryption-hpke) +- [Hybrid Public Key Encryption (HPKE)](#hybrid-public-key-encryption-hpke) - [TLS](#tls) ### Hybrid Public Key Encryption (HPKE) @@ -310,33 +305,33 @@ This section includes the following packages: #### HPKE Authenticated Encryption with Associated Data (AEAD) Functions | Functions | Windows | Linux | macOS | -| ---------------- | ------- | ----- | ------| -| AES-128-GCM | ✔️ | ✔️ | ✔️ | -| AES-256-GCM | ✔️ | ✔️ | ✔️ | -| ChaCha20Poly1305 | ❌ | ❌ | ❌ | -| Export-only | N/A | N/A | N/A | +| ---------------- | ------- | ----- | ----- | +| AES-128-GCM | ✔️ | ✔️ | ✔️ | +| AES-256-GCM | ✔️ | ✔️ | ✔️ | +| ChaCha20Poly1305 | ❌ | ❌ | ❌ | +| Export-only | N/A | N/A | N/A | #### HPKE Key Derivation Functions (KDFs) | Functions | Windows | Linux | macOS | -| ------------| ------- | ----- | ------| -| HKDF-SHA256 | ✔️ | ✔️ | ✔️ | -| HKDF-SHA384 | ✔️ | ✔️ | ✔️ | -| HKDF-SHA512 | ✔️ | ✔️ | ✔️ | +| ----------- | ------- | ----- | ----- | +| HKDF-SHA256 | ✔️ | ✔️ | ✔️ | +| HKDF-SHA384 | ✔️ | ✔️ | ✔️ | +| HKDF-SHA512 | ✔️ | ✔️ | ✔️ | #### HPKE Key Encapsulation Mechanisms (KEMs) | Functions | Windows | Linux | macOS | -| ---------------------------------------| ------- | ----- | ------| -| DHKEM(P-256, HKDF-SHA256) | ✔️ | ✔️ | ✔️ | -| DHKEM(P-384, HKDF-SHA384) | ✔️ | ✔️ | ✔️ | -| DHKEM(P-521, HKDF-SHA512) | ✔️ | ✔️ | ✔️ | -| DHKEM(X25519, HKDF-SHA256)1 | ✔️ | ✔️ | ✔️ | -| ML-KEM-7682 | ✔️ | ✔️ | ✔️ | -| ML-KEM-10242 | ✔️ | ✔️ | ✔️ | -| MLKEM768-P2562 | ✔️ | ✔️ | ✔️ | -| MLKEM1024-P3842 | ✔️ | ✔️ | ✔️ | -| MLKEM768-X255191,2 | ✔️ | ✔️ | ✔️ | +| -------------------------------------- | ------- | ----- | ----- | +| DHKEM(P-256, HKDF-SHA256) | ✔️ | ✔️ | ✔️ | +| DHKEM(P-384, HKDF-SHA384) | ✔️ | ✔️ | ✔️ | +| DHKEM(P-521, HKDF-SHA512) | ✔️ | ✔️ | ✔️ | +| DHKEM(X25519, HKDF-SHA256)1 | ✔️ | ✔️ | ✔️ | +| ML-KEM-7682 | ✔️ | ✔️ | ✔️ | +| ML-KEM-10242 | ✔️ | ✔️ | ✔️ | +| MLKEM768-P2562 | ✔️ | ✔️ | ✔️ | +| MLKEM1024-P3842 | ✔️ | ✔️ | ✔️ | +| MLKEM768-X255191,2 | ✔️ | ✔️ | ✔️ | 1See the [X25519](#ecdh) section for requirements. @@ -409,14 +404,14 @@ On Windows, it is possible to restrict and reorder the cipher suites following t Below are the supported [`tls.CurveIDs`](https://pkg.go.dev/crypto/tls#CurveID). | Name | Windows | Linux | macOS | -| ------------------------------ | ------- | ------| ----- | -| CurveP256 | ✔️ | ✔️ | ✔️ | -| CurveP384 | ✔️ | ✔️ | ✔️ | -| CurveP521 | ✔️ | ✔️ | ✔️ | -| X255191 | ✔️ | ✔️ | ✔️ | -| X25519MLKEM7681,2 | ✔️ | ✔️ | ✔️ | -| SecP256r1MLKEM7682 | ✔️ | ✔️ | ✔️ | -| SecP384r1MLKEM10242 | ✔️ | ✔️ | ✔️ | +| ------------------------------ | ------- | ----- | ----- | +| CurveP256 | ✔️ | ✔️ | ✔️ | +| CurveP384 | ✔️ | ✔️ | ✔️ | +| CurveP521 | ✔️ | ✔️ | ✔️ | +| X255191 | ✔️ | ✔️ | ✔️ | +| X25519MLKEM7681,2 | ✔️ | ✔️ | ✔️ | +| SecP256r1MLKEM7682 | ✔️ | ✔️ | ✔️ | +| SecP384r1MLKEM10242 | ✔️ | ✔️ | ✔️ | 1See the [X25519](#ecdh) section for requirements. @@ -426,7 +421,7 @@ Below are the supported [`tls.CurveIDs`](https://pkg.go.dev/crypto/tls#CurveID). Below are the supported [`tls.SignatureSchemes`](https://pkg.go.dev/crypto/tls#SignatureScheme). -| Name | Windows | Linux | macOS | +| Scheme | Windows | Linux | macOS | | ---------------------- | ------- | ----- | ----- | | PKCS1WithSHA1 | ✔️ | ✔️ | ✔️ | | PKCS1WithSHA256 | ✔️ | ✔️ | ✔️ | From d999b8f0ee2bc794bc2cdaa66d70d7591a0d25fd Mon Sep 17 00:00:00 2001 From: George Adams Date: Wed, 10 Dec 2025 16:02:30 +0000 Subject: [PATCH 2/7] quim feedback --- eng/_util/cmd/gencryptodoc/crypto.json | 17 ++++- eng/_util/cmd/gencryptodoc/main.go | 88 ++++++++++---------------- eng/_util/cmd/gencryptodoc/schema.json | 1 + eng/doc/CrossPlatformCryptography.md | 43 ++++++------- 4 files changed, 73 insertions(+), 76 deletions(-) diff --git a/eng/_util/cmd/gencryptodoc/crypto.json b/eng/_util/cmd/gencryptodoc/crypto.json index 21176b4406e..f954492882b 100644 --- a/eng/_util/cmd/gencryptodoc/crypto.json +++ b/eng/_util/cmd/gencryptodoc/crypto.json @@ -283,6 +283,7 @@ }, { "title": "Symmetric encryption", + "columnHeader": "Cipher + Mode", "packages": ["crypto/aes", "crypto/cipher", "crypto/des", "crypto/rc4"], "description": "", "footer": "- Key Sizes\n\n AES-GCM works with 128, 192, and 256-bit keys.\n\n- Nonce Sizes\n\n AES-GCM works with 12-byte nonces.\n\n- Tag Sizes\n\n AES-GCM works with 16-byte tags.", @@ -462,6 +463,7 @@ "subsections": [ { "title": "RSA", + "columnHeader": "Padding Mode", "packages": ["crypto/rsa"], "description": "[rsa.GenerateKey](https://pkg.go.dev/crypto/rsa#GenerateKey) only supports the following key sizes (in bits): 2048, 3072, 4096.\nMulti-prime RSA keys are not supported.\nThe RSA key size is subject to the limitations of the underlying cryptographic library.\nFor example, on some Windows and SCOSSL configurations, the key size should be multiple of 8.\nPlease refer to the documentation of the underlying cryptographic library for the specific limitations.\nOperations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader).", "subsections": [], @@ -739,6 +741,7 @@ }, { "title": "ECDSA", + "columnHeader": "Elliptic Curve", "packages": ["crypto/ecdsa", "crypto/elliptic"], "description": "Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader).", "subsections": [], @@ -803,8 +806,9 @@ }, { "title": "ECDH", + "columnHeader": "Elliptic Curve", "packages": ["crypto/ecdh"], - "description": "Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader).\nX25519 is available starting from the Microsoft build of Go 1.26.", + "description": "Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader).", "subsections": [], "items": [ { @@ -885,6 +889,7 @@ }, { "title": "Ed25519", + "columnHeader": "Schemes", "packages": ["crypto/ed25519"], "description": "Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader).", "subsections": [], @@ -935,6 +940,7 @@ }, { "title": "DSA", + "columnHeader": "Parameters", "packages": [], "description": "", "subsections": [], @@ -1001,6 +1007,7 @@ }, { "title": "Key derivation functions (KDFs)", + "columnHeader": "Functions", "packages": ["crypto/hkdf", "crypto/pbkdf2"], "description": "", "subsections": [], @@ -1061,6 +1068,7 @@ "subsections": [ { "title": "ML-KEM", + "columnHeader": "Parameters", "packages": ["crypto/mlkem"], "description": "ML-KEM is available starting from the Microsoft build of Go 1.26.", "subsections": [], @@ -1121,6 +1129,7 @@ "subsections": [ { "title": "HPKE Authenticated Encryption with Associated Data (AEAD) Functions", + "columnHeader": "Functions", "shortTitle": "AEAD Functions", "packages": [], "description": "", @@ -1186,6 +1195,7 @@ }, { "title": "HPKE Key Derivation Functions (KDFs)", + "columnHeader": "Functions", "shortTitle": "KDFs", "packages": [], "description": "", @@ -1237,6 +1247,7 @@ }, { "title": "HPKE Key Encapsulation Mechanisms (KEMs)", + "columnHeader": "Functions", "shortTitle": "KEMs", "packages": [], "description": "", @@ -1405,6 +1416,7 @@ "subsections": [ { "title": "TLS Versions", + "columnHeader": "Version", "packages": [], "description": "The TLS stack is implemented using native Go code but the crypto primitives are provided by the system cryptographic libraries.", "subsections": [], @@ -1483,6 +1495,7 @@ }, { "title": "TLS Cipher Suites", + "columnHeader": "Name", "packages": [], "footer": "On Windows, it is possible to restrict and reorder the cipher suites following the [Schannel preferences](https://learn.microsoft.com/en-us/windows/win32/secauthn/cipher-suites-in-schannel) by building with the `ms_tls_config_schannel` goexperiment enabled.", "subsections": [], @@ -1898,6 +1911,7 @@ }, { "title": "TLS Curves and Groups", + "columnHeader": "Name", "packages": [], "description": "Below are the supported [`tls.CurveIDs`](https://pkg.go.dev/crypto/tls#CurveID).", "subsections": [], @@ -2017,6 +2031,7 @@ }, { "title": "TLS Signature Schemes", + "columnHeader": "Name", "packages": [], "description": "Below are the supported [`tls.SignatureSchemes`](https://pkg.go.dev/crypto/tls#SignatureScheme).", "subsections": [], diff --git a/eng/_util/cmd/gencryptodoc/main.go b/eng/_util/cmd/gencryptodoc/main.go index bf8c617482f..823c121517e 100644 --- a/eng/_util/cmd/gencryptodoc/main.go +++ b/eng/_util/cmd/gencryptodoc/main.go @@ -32,39 +32,21 @@ type Item struct { } type Section struct { - Title string `json:"title"` - ShortTitle string `json:"shortTitle,omitempty"` - Packages []string `json:"packages,omitempty"` - Description string `json:"description,omitempty"` - Items []Item `json:"items,omitempty"` - Subsections []Section `json:"subsections,omitempty"` - Footnotes []string `json:"footnotes,omitempty"` - Footer string `json:"footer,omitempty"` + Title string `json:"title"` + ShortTitle string `json:"shortTitle,omitempty"` + ColumnHeader string `json:"columnHeader,omitempty"` + Packages []string `json:"packages,omitempty"` + Description string `json:"description,omitempty"` + Items []Item `json:"items,omitempty"` + Subsections []Section `json:"subsections,omitempty"` + Footnotes []string `json:"footnotes,omitempty"` + Footer string `json:"footer,omitempty"` } type Document struct { Sections []Section `json:"sections"` } -var columnHeaders = map[string]string{ - "Hash and Message Authentication Algorithms": "Algorithm", - "Symmetric encryption": "Cipher + Mode", - "RSA": "Padding Mode", - "ECDSA": "Elliptic Curve", - "ECDH": "Elliptic Curve", - "Ed25519": "Schemes", - "DSA": "Parameters", - "Key derivation functions (KDFs)": "Functions", - "ML-KEM": "Parameters", - "HPKE Authenticated Encryption with Associated Data (AEAD) Functions": "Functions", - "HPKE Key Derivation Functions (KDFs)": "Functions", - "HPKE Key Encapsulation Mechanisms (KEMs)": "Functions", - "TLS Versions": "Version", - "TLS Cipher Suites": "Name", - "TLS Curves and Groups": "Name", - "TLS Signature Schemes": "Scheme", -} - func main() { output := flag.String("o", "", "output file path") flag.Parse() @@ -111,6 +93,30 @@ func main() { func printSection(section Section, level int) { fmt.Printf("\n%s %s\n\n", strings.Repeat("#", level), section.Title) + // Filter packages + var validPackages []string + for _, pkg := range section.Packages { + if strings.Contains(pkg, "/") || strings.Contains(pkg, ".") { + validPackages = append(validPackages, pkg) + } + } + + if len(validPackages) > 0 { + fmt.Println("This section includes the following packages:") + fmt.Println() + for _, pkg := range validPackages { + if strings.HasPrefix(pkg, "crypto/") { + fmt.Printf("- [%s](https://pkg.go.dev/%s)\n", pkg, pkg) + } else if strings.HasPrefix(pkg, "golang.org/") { + fmt.Printf("- [%s](https://pkg.go.dev/%s)\n", pkg, pkg) + } else { + // Fallback + fmt.Printf("- %s\n", pkg) + } + } + fmt.Println() + } + if section.Description != "" { fmt.Println(section.Description) fmt.Println() @@ -139,30 +145,6 @@ func printSection(section Section, level int) { fmt.Println() } - // Filter packages - var validPackages []string - for _, pkg := range section.Packages { - if strings.Contains(pkg, "/") || strings.Contains(pkg, ".") { - validPackages = append(validPackages, pkg) - } - } - - if len(validPackages) > 0 { - fmt.Println("This section includes the following packages:") - fmt.Println() - for _, pkg := range validPackages { - if strings.HasPrefix(pkg, "crypto/") { - fmt.Printf("- [%s](https://pkg.go.dev/%s)\n", pkg, pkg) - } else if strings.HasPrefix(pkg, "golang.org/") { - fmt.Printf("- [%s](https://pkg.go.dev/%s)\n", pkg, pkg) - } else { - // Fallback - fmt.Printf("- %s\n", pkg) - } - } - fmt.Println() - } - if len(section.Items) > 0 { printTable(section) } @@ -178,8 +160,8 @@ func printSection(section Section, level int) { } func printTable(section Section) { - colHeader, ok := columnHeaders[section.Title] - if !ok { + colHeader := section.ColumnHeader + if colHeader == "" { colHeader = "Algorithm" // Default } diff --git a/eng/_util/cmd/gencryptodoc/schema.json b/eng/_util/cmd/gencryptodoc/schema.json index e53236c7605..a4ebef9516b 100644 --- a/eng/_util/cmd/gencryptodoc/schema.json +++ b/eng/_util/cmd/gencryptodoc/schema.json @@ -13,6 +13,7 @@ "properties": { "title": { "type": "string" }, "shortTitle": { "type": "string" }, + "columnHeader": { "type": "string" }, "packages": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/definitions/item" } }, diff --git a/eng/doc/CrossPlatformCryptography.md b/eng/doc/CrossPlatformCryptography.md index 6f5f2c36f5f..ab7150b4dc7 100644 --- a/eng/doc/CrossPlatformCryptography.md +++ b/eng/doc/CrossPlatformCryptography.md @@ -142,6 +142,10 @@ This section includes the following subsections: ### RSA +This section includes the following packages: + +- [crypto/rsa](https://pkg.go.dev/crypto/rsa) + [rsa.GenerateKey](https://pkg.go.dev/crypto/rsa#GenerateKey) only supports the following key sizes (in bits): 2048, 3072, 4096. Multi-prime RSA keys are not supported. The RSA key size is subject to the limitations of the underlying cryptographic library. @@ -149,10 +153,6 @@ For example, on some Windows and SCOSSL configurations, the key size should be m Please refer to the documentation of the underlying cryptographic library for the specific limitations. Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). -This section includes the following packages: - -- [crypto/rsa](https://pkg.go.dev/crypto/rsa) - | Padding Mode | Windows | Linux | macOS | | -------------------------------------- | -------------- | -------------- | -------------- | | OAEP (MD5) | ✔️ | ✔️ | ✔️1 | @@ -184,13 +184,13 @@ This section includes the following packages: ### ECDSA -Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). - This section includes the following packages: - [crypto/ecdsa](https://pkg.go.dev/crypto/ecdsa) - [crypto/elliptic](https://pkg.go.dev/crypto/elliptic) +Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). + | Elliptic Curve | Windows | Linux | macOS | | ---------------------- | ------- | ----- | ----- | | NIST P-224 (secp224r1) | ✔️ | ✔️ | ❌ | @@ -200,13 +200,12 @@ This section includes the following packages: ### ECDH -Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). -X25519 is available starting from the Microsoft build of Go 1.26. - This section includes the following packages: - [crypto/ecdh](https://pkg.go.dev/crypto/ecdh) +Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). + | Elliptic Curve | Windows | Linux | macOS | | ------------------------------- | ------- | -------------- | ----- | | NIST P-224 (secp224r1) | ✔️ | ✔️ | ❌ | @@ -221,12 +220,12 @@ This section includes the following packages: ### Ed25519 -Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). - This section includes the following packages: - [crypto/ed25519](https://pkg.go.dev/crypto/ed25519) +Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). + | Schemes | Windows | Linux | macOS | | ---------- | ------- | ----- | ----- | | Ed25519 | ❌ | ✔️ | ✔️ | @@ -264,12 +263,12 @@ This section includes the following subsections: ### ML-KEM -ML-KEM is available starting from the Microsoft build of Go 1.26. - This section includes the following packages: - [crypto/mlkem](https://pkg.go.dev/crypto/mlkem) +ML-KEM is available starting from the Microsoft build of Go 1.26. + | Parameters | Windows | Linux | macOS | | ---------- | -------------- | -------------- | -------------- | | 768 | ✔️1 | ✔️2 | ✔️3 | @@ -292,16 +291,16 @@ These protocols are implemented using native Go code, but they rely on the under ### Hybrid Public Key Encryption (HPKE) +This section includes the following packages: + +- [crypto/hpke](https://pkg.go.dev/crypto/hpke) + This section includes the following subsections: - [AEAD Functions](#hpke-authenticated-encryption-with-associated-data-aead-functions) - [KDFs](#hpke-key-derivation-functions-kdfs) - [KEMs](#hpke-key-encapsulation-mechanisms-kems) -This section includes the following packages: - -- [crypto/hpke](https://pkg.go.dev/crypto/hpke) - #### HPKE Authenticated Encryption with Associated Data (AEAD) Functions | Functions | Windows | Linux | macOS | @@ -339,6 +338,10 @@ This section includes the following packages: ### TLS +This section includes the following packages: + +- [crypto/tls](https://pkg.go.dev/crypto/tls) + This section includes the following subsections: - [TLS Versions](#tls-versions) @@ -346,10 +349,6 @@ This section includes the following subsections: - [TLS Curves and Groups](#tls-curves-and-groups) - [TLS Signature Schemes](#tls-signature-schemes) -This section includes the following packages: - -- [crypto/tls](https://pkg.go.dev/crypto/tls) - #### TLS Versions The TLS stack is implemented using native Go code but the crypto primitives are provided by the system cryptographic libraries. @@ -421,7 +420,7 @@ Below are the supported [`tls.CurveIDs`](https://pkg.go.dev/crypto/tls#CurveID). Below are the supported [`tls.SignatureSchemes`](https://pkg.go.dev/crypto/tls#SignatureScheme). -| Scheme | Windows | Linux | macOS | +| Name | Windows | Linux | macOS | | ---------------------- | ------- | ----- | ----- | | PKCS1WithSHA1 | ✔️ | ✔️ | ✔️ | | PKCS1WithSHA256 | ✔️ | ✔️ | ✔️ | From 339d6af11bcda88adbc4aea394c59863e9171c9f Mon Sep 17 00:00:00 2001 From: George Adams Date: Wed, 10 Dec 2025 16:23:22 +0000 Subject: [PATCH 3/7] fix formatting --- eng/_util/cmd/gencryptodoc/crypto.json | 4 ++-- eng/doc/CrossPlatformCryptography.md | 6 ++++++ 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/eng/_util/cmd/gencryptodoc/crypto.json b/eng/_util/cmd/gencryptodoc/crypto.json index f954492882b..52945027b1f 100644 --- a/eng/_util/cmd/gencryptodoc/crypto.json +++ b/eng/_util/cmd/gencryptodoc/crypto.json @@ -465,7 +465,7 @@ "title": "RSA", "columnHeader": "Padding Mode", "packages": ["crypto/rsa"], - "description": "[rsa.GenerateKey](https://pkg.go.dev/crypto/rsa#GenerateKey) only supports the following key sizes (in bits): 2048, 3072, 4096.\nMulti-prime RSA keys are not supported.\nThe RSA key size is subject to the limitations of the underlying cryptographic library.\nFor example, on some Windows and SCOSSL configurations, the key size should be multiple of 8.\nPlease refer to the documentation of the underlying cryptographic library for the specific limitations.\nOperations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader).", + "description": "[rsa.GenerateKey](https://pkg.go.dev/crypto/rsa#GenerateKey) only supports the following key sizes (in bits): 2048, 3072, 4096.\n\nMulti-prime RSA keys are not supported.\n\nThe RSA key size is subject to the limitations of the underlying cryptographic library.\nFor example, on some Windows and SCOSSL configurations, the key size should be multiple of 8.\nPlease refer to the documentation of the underlying cryptographic library for the specific limitations.\n\nOperations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader).", "subsections": [], "items": [ { @@ -1118,7 +1118,7 @@ { "title": "Higher-level protocols", "packages": ["HPKE", "TLS"], - "description": "High-level protocols are algorithms that combine multiple cryptographic primitives to provide a specific functionality,\nsuch as TLS or Hybrid Public Key Encryption (HPKE).\nThese protocols are implemented using native Go code, but they rely on the underlying OS cryptographic libraries for the cryptographic operations.", + "description": "High-level protocols are algorithms that combine multiple cryptographic primitives to provide a specific functionality,\nsuch as TLS or Hybrid Public Key Encryption (HPKE).\n\nThese protocols are implemented using native Go code, but they rely on the underlying OS cryptographic libraries for the cryptographic operations.\n\nThis section includes the following subsections:", "table": null, "subsections": [ { diff --git a/eng/doc/CrossPlatformCryptography.md b/eng/doc/CrossPlatformCryptography.md index ab7150b4dc7..bb5a318cd41 100644 --- a/eng/doc/CrossPlatformCryptography.md +++ b/eng/doc/CrossPlatformCryptography.md @@ -147,10 +147,13 @@ This section includes the following packages: - [crypto/rsa](https://pkg.go.dev/crypto/rsa) [rsa.GenerateKey](https://pkg.go.dev/crypto/rsa#GenerateKey) only supports the following key sizes (in bits): 2048, 3072, 4096. + Multi-prime RSA keys are not supported. + The RSA key size is subject to the limitations of the underlying cryptographic library. For example, on some Windows and SCOSSL configurations, the key size should be multiple of 8. Please refer to the documentation of the underlying cryptographic library for the specific limitations. + Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). | Padding Mode | Windows | Linux | macOS | @@ -284,8 +287,11 @@ ML-KEM is available starting from the Microsoft build of Go 1.26. High-level protocols are algorithms that combine multiple cryptographic primitives to provide a specific functionality, such as TLS or Hybrid Public Key Encryption (HPKE). + These protocols are implemented using native Go code, but they rely on the underlying OS cryptographic libraries for the cryptographic operations. +This section includes the following subsections: + - [Hybrid Public Key Encryption (HPKE)](#hybrid-public-key-encryption-hpke) - [TLS](#tls) From bbd0557ccb8509136323e2647f5320db618a31de Mon Sep 17 00:00:00 2001 From: George Adams Date: Thu, 11 Dec 2025 09:54:04 +0000 Subject: [PATCH 4/7] default to supported to reduce JSON size --- eng/_util/cmd/gencryptodoc/crypto.json | 1547 +++--------------------- eng/_util/cmd/gencryptodoc/main.go | 108 +- eng/_util/cmd/gencryptodoc/schema.json | 20 +- eng/doc/CrossPlatformCryptography.md | 4 +- 4 files changed, 274 insertions(+), 1405 deletions(-) diff --git a/eng/_util/cmd/gencryptodoc/crypto.json b/eng/_util/cmd/gencryptodoc/crypto.json index 52945027b1f..85076144a87 100644 --- a/eng/_util/cmd/gencryptodoc/crypto.json +++ b/eng/_util/cmd/gencryptodoc/crypto.json @@ -11,273 +11,119 @@ "crypto/sha3", "crypto/hmac" ], - "description": "", - "subsections": [], "items": [ { - "name": "MD5", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "MD5" }, { - "name": "SHA-1", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "SHA-1" }, { "name": "SHA-2-224", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } + "windows": { "supported": "false" } } }, { - "name": "SHA-2-256", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "SHA-2-256" }, { - "name": "SHA-2-384", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "SHA-2-384" }, { - "name": "SHA-2-512", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "SHA-2-512" }, { "name": "SHA-2-512_224", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "true", - "notes": [ - "Available starting in the Microsoft build of Go 1.24.", - "Requires OpenSSL 1.1.1 or later." - ] - }, - "macos": { - "supported": "false" - } + "windows": { "supported": "false" }, + "linux": { "minGoVersion": "1.24", "minOpenSSLVersion": "1.1.1" }, + "macos": { "supported": "false" } } }, { "name": "SHA-2-512_256", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "true", - "notes": [ - "Available starting in the Microsoft build of Go 1.24.", - "Requires OpenSSL 1.1.1 or later." - ] - }, - "macos": { - "supported": "false" - } + "windows": { "supported": "false" }, + "linux": { "minGoVersion": "1.24", "minOpenSSLVersion": "1.1.1" }, + "macos": { "supported": "false" } } }, { "name": "SHA-3-224", - "notes": ["Available starting in the Microsoft build of Go 1.26."], + "minGoVersion": "1.26", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "true", - "notes": ["Requires OpenSSL 1.1.1 or later."] - }, - "macos": { - "supported": "false" - } + "windows": { "supported": "false" }, + "linux": { "minOpenSSLVersion": "1.1.1" }, + "macos": { "supported": "false" } } }, { "name": "SHA-3-256", - "notes": ["Available starting in the Microsoft build of Go 1.26."], + "minGoVersion": "1.26", "platforms": { "windows": { - "supported": "true", "notes": ["Available in Windows 11, version 24H2 or later."] }, - "linux": { - "supported": "true", - "notes": ["Requires OpenSSL 1.1.1 or later."] - }, - "macos": { - "supported": "true", - "notes": ["Available starting in macOS 26 (Tahoe)."] - } + "linux": { "minOpenSSLVersion": "1.1.1" }, + "macos": { "minMacOSVersion": "26" } } }, { "name": "SHA-3-384", - "notes": ["Available starting in the Microsoft build of Go 1.26."], + "minGoVersion": "1.26", "platforms": { "windows": { - "supported": "true", "notes": ["Available in Windows 11, version 24H2 or later."] }, - "linux": { - "supported": "true", - "notes": ["Requires OpenSSL 1.1.1 or later."] - }, - "macos": { - "supported": "true", - "notes": ["Available starting in macOS 26 (Tahoe)."] - } + "linux": { "minOpenSSLVersion": "1.1.1" }, + "macos": { "minMacOSVersion": "26" } } }, { "name": "SHA-3-512", - "notes": ["Available starting in the Microsoft build of Go 1.26."], + "minGoVersion": "1.26", "platforms": { "windows": { - "supported": "true", "notes": ["Available in Windows 11, version 24H2 or later."] }, - "linux": { - "supported": "true", - "notes": ["Requires OpenSSL 1.1.1 or later."] - }, - "macos": { - "supported": "true", - "notes": ["Available starting in macOS 26 (Tahoe)."] - } + "linux": { "minOpenSSLVersion": "1.1.1" }, + "macos": { "minMacOSVersion": "26" } } }, { "name": "SHAKE-128", "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true", - "notes": ["Requires OpenSSL 3.3 or later."] - }, - "macos": { - "supported": "false" - } + "linux": { "minOpenSSLVersion": "3.3" }, + "macos": { "supported": "false" } } }, { "name": "SHAKE-256", "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true", - "notes": ["Requires OpenSSL 3.3 or later."] - }, - "macos": { - "supported": "false" - } + "linux": { "minOpenSSLVersion": "3.3" }, + "macos": { "supported": "false" } } }, { "name": "CSHAKE-128", "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "false" - }, - "macos": { - "supported": "false" - } + "linux": { "supported": "false" }, + "macos": { "supported": "false" } } }, { "name": "CSHAKE-256", "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "false" - }, - "macos": { - "supported": "false" - } + "linux": { "supported": "false" }, + "macos": { "supported": "false" } } }, { "name": "HMAC", "notes": [ "Supports only hash algorithms that are supported as standalone hash functions." - ], - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + ] } ] }, @@ -290,166 +136,74 @@ "subsections": [], "items": [ { - "name": "AES-ECB", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "AES-ECB" }, { - "name": "AES-CBC", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "AES-CBC" }, { "name": "AES-CTR", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "false" - } + "windows": { "supported": "false" }, + "macos": { "supported": "false" } } }, { "name": "AES-CFB", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "false" - }, - "macos": { - "supported": "false" - } + "windows": { "supported": "false" }, + "linux": { "supported": "false" }, + "macos": { "supported": "false" } } }, { "name": "AES-OFB", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "false" - }, - "macos": { - "supported": "false" - } + "windows": { "supported": "false" }, + "linux": { "supported": "false" }, + "macos": { "supported": "false" } } }, { "name": "AES-GCM", - "notes": ["AES-GCM supports specific keys, nonces, and tags:"], - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "notes": ["AES-GCM supports specific keys, nonces, and tags:"] }, { "name": "DES-CBC", "platforms": { - "windows": { - "supported": "true" - }, "linux": { "supported": "warn", "notes": [ "When using OpenSSL 3, requires the legacy provider to be enabled." ] - }, - "macos": { - "supported": "true" } } }, { "name": "DES-ECB", "platforms": { - "windows": { - "supported": "true" - }, "linux": { "supported": "warn", "notes": [ "When using OpenSSL 3, requires the legacy provider to be enabled." ] - }, - "macos": { - "supported": "true" } } }, { - "name": "3DES-ECB", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "3DES-ECB" }, { - "name": "3DES-CBC", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "3DES-CBC" }, { "name": "RC4", "platforms": { - "windows": { - "supported": "true" - }, "linux": { "supported": "warn", "notes": [ "When using OpenSSL 3, requires the legacy provider to be enabled." ] - }, - "macos": { - "supported": "true" } } } @@ -471,14 +225,7 @@ { "name": "OAEP (MD5)", "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, "macos": { - "supported": "true", "notes": [ "macOS doesn't support passing a custom label to OAEP functions." ] @@ -488,14 +235,7 @@ { "name": "OAEP (SHA-1)", "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, "macos": { - "supported": "true", "notes": [ "macOS doesn't support passing a custom label to OAEP functions." ] @@ -508,14 +248,7 @@ "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." ], "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, "macos": { - "supported": "true", "notes": [ "macOS doesn't support passing a custom label to OAEP functions." ] @@ -525,48 +258,31 @@ { "name": "OAEP (SHA-3)", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "false" - }, - "macos": { - "supported": "false" - } + "windows": { "supported": "false" }, + "linux": { "supported": "false" }, + "macos": { "supported": "false" } } }, { "name": "PSS (MD5)", "platforms": { "windows": { - "supported": "true", "notes": [ "On Windows, when verifying a PSS signature, [rsa.PSSSaltLengthAuto](https://pkg.go.dev/crypto/rsa#pkg-constants) is not supported." ] }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "false" - } + "macos": { "supported": "false" } } }, { "name": "PSS (SHA-1)", "platforms": { "windows": { - "supported": "true", "notes": [ "On Windows, when verifying a PSS signature, [rsa.PSSSaltLengthAuto](https://pkg.go.dev/crypto/rsa#pkg-constants) is not supported." ] }, - "linux": { - "supported": "true" - }, "macos": { - "supported": "true", "notes": [ "On macOS, custom salt lengths are not supported. PSS always uses the [`rsa.PSSSaltLengthEqualsHash`](https://pkg.go.dev/crypto/rsa#pkg-constants)." ] @@ -580,16 +296,11 @@ ], "platforms": { "windows": { - "supported": "true", "notes": [ "On Windows, when verifying a PSS signature, [rsa.PSSSaltLengthAuto](https://pkg.go.dev/crypto/rsa#pkg-constants) is not supported." ] }, - "linux": { - "supported": "true" - }, "macos": { - "supported": "true", "notes": [ "On macOS, custom salt lengths are not supported. PSS always uses the [`rsa.PSSSaltLengthEqualsHash`](https://pkg.go.dev/crypto/rsa#pkg-constants)." ] @@ -599,142 +310,67 @@ { "name": "PSS (SHA-3)", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "false" - }, - "macos": { - "supported": "false" - } + "windows": { "supported": "false" }, + "linux": { "supported": "false" }, + "macos": { "supported": "false" } } }, { - "name": "PKCS1v15 Signature (Unhashed)", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "PKCS1v15 Signature (Unhashed)" }, { "name": "PKCS1v15 Signature (RIPMED160)", "platforms": { - "windows": { - "supported": "false" - }, + "windows": { "supported": "false" }, "linux": { - "supported": "true", - "notes": [ - "Available starting in the Microsoft build of Go 1.24." - ] + "minGoVersion": "1.24" }, - "macos": { - "supported": "false" - } + "macos": { "supported": "false" } } }, { "name": "PKCS1v15 Signature (MD4)", "platforms": { - "windows": { - "supported": "false" - }, + "windows": { "supported": "false" }, "linux": { - "supported": "true", - "notes": [ - "Available starting in the Microsoft build of Go 1.24." - ] + "minGoVersion": "1.24" }, - "macos": { - "supported": "false" - } + "macos": { "supported": "false" } } }, { "name": "PKCS1v15 Signature (MD5)", "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "false" - } + "macos": { "supported": "false" } } }, { "name": "PKCS1v15 Signature (MD5-SHA1)", "platforms": { "windows": { - "supported": "true", - "notes": [ - "Available starting in the Microsoft build of Go 1.24." - ] + "minGoVersion": "1.24" }, "linux": { - "supported": "true", - "notes": [ - "Available starting in the Microsoft build of Go 1.24." - ] + "minGoVersion": "1.24" }, - "macos": { - "supported": "false" - } + "macos": { "supported": "false" } } }, { - "name": "PKCS1v15 Signature (SHA-1)", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "PKCS1v15 Signature (SHA-1)" }, { "name": "PKCS1v15 Signature (SHA-2)", "notes": [ "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." - ], - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + ] }, { "name": "PKCS1v15 Signature (SHA-3)", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "false" - }, - "macos": { - "supported": "false" - } + "windows": { "supported": "false" }, + "linux": { "supported": "false" }, + "macos": { "supported": "false" } } } ] @@ -749,58 +385,17 @@ { "name": "NIST P-224 (secp224r1)", "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "false" - } + "macos": { "supported": "false" } } }, { - "name": "NIST P-256 (secp256r1)", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "NIST P-256 (secp256r1)" }, { - "name": "NIST P-384 (secp384r1)", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "NIST P-384 (secp384r1)" }, { - "name": "NIST P-521 (secp521r1)", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "NIST P-521 (secp521r1)" } ] }, @@ -814,74 +409,24 @@ { "name": "NIST P-224 (secp224r1)", "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "false" - } + "macos": { "supported": "false" } } }, { - "name": "NIST P-256 (secp256r1)", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "NIST P-256 (secp256r1)" }, { - "name": "NIST P-384 (secp384r1)", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "NIST P-384 (secp384r1)" }, { - "name": "NIST P-521 (secp521r1)", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "NIST P-521 (secp521r1)" }, { "name": "X25519 (curve25519)", - "notes": [ - "Available starting in the Microsoft build of Go 1.26." - ], + "minGoVersion": "1.26", "platforms": { - "windows": { - "supported": "true" - }, "linux": { - "supported": "true", - "notes": ["Requires OpenSSL 1.1.1 or later."] - }, - "macos": { - "supported": "true" + "minOpenSSLVersion": "1.1.1" } } } @@ -897,43 +442,23 @@ { "name": "Ed25519", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } + "windows": { "supported": "false" } } }, { "name": "Ed25519ctx", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "false" - }, - "macos": { - "supported": "false" - } + "windows": { "supported": "false" }, + "linux": { "supported": "false" }, + "macos": { "supported": "false" } } }, { "name": "Ed25519ph", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "false" - }, - "macos": { - "supported": "false" - } + "windows": { "supported": "false" }, + "linux": { "supported": "false" }, + "macos": { "supported": "false" } } } ] @@ -948,57 +473,26 @@ { "name": "L1024N160", "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "false" - } + "macos": { "supported": "false" } } }, { "name": "L2048N224", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "false" - } + "windows": { "supported": "false" }, + "macos": { "supported": "false" } } }, { "name": "L2048N256", "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "false" - } + "macos": { "supported": "false" } } }, { "name": "L3072N256", "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "false" - } + "macos": { "supported": "false" } } } ] @@ -1016,19 +510,16 @@ "name": "PBKDF2", "platforms": { "windows": { - "supported": "true", "notes": [ "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." ] }, "linux": { - "supported": "true", "notes": [ "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." ] }, "macos": { - "supported": "true", "notes": [ "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." ] @@ -1039,19 +530,16 @@ "name": "HKDF", "platforms": { "windows": { - "supported": "true", "notes": [ "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." ] }, "linux": { - "supported": "true", "notes": [ "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." ] }, "macos": { - "supported": "true", "notes": [ "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." ] @@ -1070,25 +558,22 @@ "title": "ML-KEM", "columnHeader": "Parameters", "packages": ["crypto/mlkem"], - "description": "ML-KEM is available starting from the Microsoft build of Go 1.26.", + "minGoVersion": "1.26", "subsections": [], "items": [ { "name": "768", "platforms": { "windows": { - "supported": "true", "notes": [ "Requires Windows Server 2025 or Windows 11 (24H2, 25H2) or later." ] }, "linux": { - "supported": "true", - "notes": ["Requires OpenSSL 3.5.0 or later."] + "minOpenSSLVersion": "3.5.0" }, "macos": { - "supported": "true", - "notes": ["Requires macOS 26 (Tahoe) or later."] + "minMacOSVersion": "26" } } }, @@ -1096,18 +581,15 @@ "name": "1024", "platforms": { "windows": { - "supported": "true", "notes": [ "Requires Windows Server 2025 or Windows 11 (24H2, 25H2) or later." ] }, "linux": { - "supported": "true", - "notes": ["Requires OpenSSL 3.5.0 or later."] + "minOpenSSLVersion": "3.5.0" }, "macos": { - "supported": "true", - "notes": ["Requires macOS 26 (Tahoe) or later."] + "minMacOSVersion": "26" } } } @@ -1136,59 +618,25 @@ "subsections": [], "items": [ { - "name": "AES-128-GCM", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "AES-128-GCM" }, { - "name": "AES-256-GCM", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "AES-256-GCM" }, { "name": "ChaCha20Poly1305", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "false" - }, - "macos": { - "supported": "false" - } + "windows": { "supported": "false" }, + "linux": { "supported": "false" }, + "macos": { "supported": "false" } } }, { "name": "Export-only", "platforms": { - "windows": { - "supported": "N/A" - }, - "linux": { - "supported": "N/A" - }, - "macos": { - "supported": "N/A" - } + "windows": { "supported": "N/A" }, + "linux": { "supported": "N/A" }, + "macos": { "supported": "N/A" } } } ] @@ -1202,46 +650,13 @@ "subsections": [], "items": [ { - "name": "HKDF-SHA256", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "HKDF-SHA256" }, { - "name": "HKDF-SHA384", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "HKDF-SHA384" }, { - "name": "HKDF-SHA512", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "HKDF-SHA512" } ] }, @@ -1254,149 +669,48 @@ "subsections": [], "items": [ { - "name": "DHKEM(P-256, HKDF-SHA256)", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "DHKEM(P-256, HKDF-SHA256)" }, { - "name": "DHKEM(P-384, HKDF-SHA384)", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "DHKEM(P-384, HKDF-SHA384)" }, { - "name": "DHKEM(P-521, HKDF-SHA512)", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "DHKEM(P-521, HKDF-SHA512)" }, { "name": "DHKEM(X25519, HKDF-SHA256)", - "notes": [ - "See the [X25519](#ecdh) section for requirements." - ], - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "notes": ["See the [X25519](#ecdh) section for requirements."] }, { "name": "ML-KEM-768", "notes": [ "See the [ML-KEM](#ml-kem) section for requirements." - ], - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + ] }, { "name": "ML-KEM-1024", "notes": [ "See the [ML-KEM](#ml-kem) section for requirements." - ], - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + ] }, { "name": "MLKEM768-P256", "notes": [ "See the [ML-KEM](#ml-kem) section for requirements." - ], - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + ] }, { "name": "MLKEM1024-P384", "notes": [ "See the [ML-KEM](#ml-kem) section for requirements." - ], - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + ] }, { "name": "MLKEM768-X25519", "notes": [ "See the [X25519](#ecdh) section for requirements.", "See the [ML-KEM](#ml-kem) section for requirements." - ], - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + ] } ] } @@ -1424,72 +738,28 @@ { "name": "SSL 3.0", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "false" - }, - "macos": { - "supported": "false" - } + "windows": { "supported": "false" }, + "linux": { "supported": "false" }, + "macos": { "supported": "false" } } }, { "name": "TLS 1.0", "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "false" - } + "macos": { "supported": "false" } } }, { "name": "TLS 1.1", "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "false" - } + "macos": { "supported": "false" } } }, { - "name": "TLS 1.2", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "TLS 1.2" }, { - "name": "TLS 1.3", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "TLS 1.3" } ] }, @@ -1503,408 +773,155 @@ { "name": "TLS_RSA_WITH_RC4_128_SHA", "platforms": { - "windows": { - "supported": "true" - }, "linux": { "supported": "warn", "notes": [ "When using OpenSSL 3, requires the legacy provider to be enabled." ] - }, - "macos": { - "supported": "true" } } }, { "name": "TLS_RSA_WITH_3DES_EDE_CBC_SHA", "platforms": { - "windows": { - "supported": "true" - }, "linux": { "supported": "warn", "notes": [ "When using OpenSSL 3, requires the legacy provider to be enabled." ] - }, - "macos": { - "supported": "true" } } }, { - "name": "TLS_RSA_WITH_AES_128_CBC_SHA", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "TLS_RSA_WITH_AES_128_CBC_SHA" }, { - "name": "TLS_RSA_WITH_AES_256_CBC_SHA", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "TLS_RSA_WITH_AES_256_CBC_SHA" }, { - "name": "TLS_RSA_WITH_AES_128_CBC_SHA256", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "TLS_RSA_WITH_AES_128_CBC_SHA256" }, { - "name": "TLS_RSA_WITH_AES_128_GCM_SHA256", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "TLS_RSA_WITH_AES_128_GCM_SHA256" }, { - "name": "TLS_RSA_WITH_AES_256_GCM_SHA384", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "TLS_RSA_WITH_AES_256_GCM_SHA384" }, { "name": "TLS_ECDHE_ECDSA_WITH_RC4_128_SHA", "platforms": { - "windows": { - "supported": "true" - }, "linux": { "supported": "warn", "notes": [ "When using OpenSSL 3, requires the legacy provider to be enabled." ] - }, - "macos": { - "supported": "true" } } }, { - "name": "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA" }, { - "name": "TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA" }, { "name": "TLS_ECDHE_RSA_WITH_RC4_128_SHA", "platforms": { - "windows": { - "supported": "true" - }, "linux": { "supported": "warn", "notes": [ "When using OpenSSL 3, requires the legacy provider to be enabled." ] - }, - "macos": { - "supported": "true" } } }, { "name": "TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA", "platforms": { - "windows": { - "supported": "true" - }, "linux": { "supported": "warn", "notes": [ "When using OpenSSL 3, requires the legacy provider to be enabled." ] - }, - "macos": { - "supported": "true" } } }, { - "name": "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA" }, { - "name": "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA" }, { - "name": "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256" }, { - "name": "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256" }, { - "name": "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256" }, { - "name": "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256" }, { - "name": "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384" }, { - "name": "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384" }, { "name": "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "false" - }, - "macos": { - "supported": "false" - } + "windows": { "supported": "false" }, + "linux": { "supported": "false" }, + "macos": { "supported": "false" } } }, { "name": "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "false" - }, - "macos": { - "supported": "false" - } + "windows": { "supported": "false" }, + "linux": { "supported": "false" }, + "macos": { "supported": "false" } } }, { - "name": "TLS_AES_128_GCM_SHA256", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "TLS_AES_128_GCM_SHA256" }, { - "name": "TLS_AES_256_GCM_SHA384", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "TLS_AES_256_GCM_SHA384" }, { "name": "TLS_CHACHA20_POLY1305_SHA256", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "false" - }, - "macos": { - "supported": "false" - } + "windows": { "supported": "false" }, + "linux": { "supported": "false" }, + "macos": { "supported": "false" } } }, { "name": "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "false" - }, - "macos": { - "supported": "false" - } + "windows": { "supported": "false" }, + "linux": { "supported": "false" }, + "macos": { "supported": "false" } } }, { "name": "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "false" - }, - "macos": { - "supported": "false" - } + "windows": { "supported": "false" }, + "linux": { "supported": "false" }, + "macos": { "supported": "false" } } }, { "name": "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "false" - }, - "macos": { - "supported": "false" - } + "windows": { "supported": "false" }, + "linux": { "supported": "false" }, + "macos": { "supported": "false" } } } ] @@ -1917,115 +934,36 @@ "subsections": [], "items": [ { - "name": "CurveP256", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "CurveP256" }, { - "name": "CurveP384", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "CurveP384" }, { - "name": "CurveP521", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "CurveP521" }, { "name": "X25519", - "notes": [ - "See the [X25519](#ecdh) section for requirements." - ], - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "notes": ["See the [X25519](#ecdh) section for requirements."] }, { "name": "X25519MLKEM768", "notes": [ "See the [X25519](#ecdh) section for requirements.", "See the [ML-KEM](#ml-kem) section for requirements." - ], - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + ] }, { "name": "SecP256r1MLKEM768", "notes": [ "See the [ML-KEM](#ml-kem) section for requirements." - ], - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + ] }, { "name": "SecP384r1MLKEM1024", "notes": [ "See the [ML-KEM](#ml-kem) section for requirements." - ], - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + ] } ] }, @@ -2037,171 +975,42 @@ "subsections": [], "items": [ { - "name": "PKCS1WithSHA1", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "PKCS1WithSHA1" }, { - "name": "PKCS1WithSHA256", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "PKCS1WithSHA256" }, { - "name": "PKCS1WithSHA384", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "PKCS1WithSHA384" }, { - "name": "PKCS1WithSHA512", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "PKCS1WithSHA512" }, { - "name": "PSSWithSHA256", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "PSSWithSHA256" }, { - "name": "PSSWithSHA384", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "PSSWithSHA384" }, { - "name": "PSSWithSHA512", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "PSSWithSHA512" }, { - "name": "ECDSAWithSHA1", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "ECDSAWithSHA1" }, { - "name": "ECDSAWithP256AndSHA256", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "ECDSAWithP256AndSHA256" }, { - "name": "ECDSAWithP384AndSHA384", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "ECDSAWithP384AndSHA384" }, { - "name": "ECDSAWithP521AndSHA512", - "platforms": { - "windows": { - "supported": "true" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } - } + "name": "ECDSAWithP521AndSHA512" }, { "name": "Ed25519", "platforms": { - "windows": { - "supported": "false" - }, - "linux": { - "supported": "true" - }, - "macos": { - "supported": "true" - } + "windows": { "supported": "false" } } } ] diff --git a/eng/_util/cmd/gencryptodoc/main.go b/eng/_util/cmd/gencryptodoc/main.go index 823c121517e..cd4403e09a6 100644 --- a/eng/_util/cmd/gencryptodoc/main.go +++ b/eng/_util/cmd/gencryptodoc/main.go @@ -21,26 +21,33 @@ import ( var header string type PlatformStatus struct { - Supported string `json:"supported"` - Notes []string `json:"notes,omitempty"` + Supported string `json:"supported"` + MinGoVersion string `json:"minGoVersion,omitempty"` + Notes []string `json:"notes,omitempty"` + MinMacOSVersion string `json:"minMacOSVersion,omitempty"` + MinOpenSSLVersion string `json:"minOpenSSLVersion,omitempty"` } type Item struct { - Name string `json:"name"` - Notes []string `json:"notes,omitempty"` - Platforms map[string]PlatformStatus `json:"platforms"` + Name string `json:"name"` + MinGoVersion string `json:"minGoVersion,omitempty"` + Notes []string `json:"notes,omitempty"` + Platforms map[string]PlatformStatus `json:"platforms"` } type Section struct { - Title string `json:"title"` - ShortTitle string `json:"shortTitle,omitempty"` - ColumnHeader string `json:"columnHeader,omitempty"` - Packages []string `json:"packages,omitempty"` - Description string `json:"description,omitempty"` - Items []Item `json:"items,omitempty"` - Subsections []Section `json:"subsections,omitempty"` - Footnotes []string `json:"footnotes,omitempty"` - Footer string `json:"footer,omitempty"` + Title string `json:"title"` + ShortTitle string `json:"shortTitle,omitempty"` + ColumnHeader string `json:"columnHeader,omitempty"` + Packages []string `json:"packages,omitempty"` + Description string `json:"description,omitempty"` + MinGoVersion string `json:"minGoVersion,omitempty"` + MinMacOSVersion string `json:"minMacOSVersion,omitempty"` + MinOpenSSLVersion string `json:"minOpenSSLVersion,omitempty"` + Items []Item `json:"items,omitempty"` + Subsections []Section `json:"subsections,omitempty"` + Footnotes []string `json:"footnotes,omitempty"` + Footer string `json:"footer,omitempty"` } type Document struct { @@ -117,6 +124,21 @@ func printSection(section Section, level int) { fmt.Println() } + // Prepend version requirements to description if present + var versionSentences []string + if section.MinGoVersion != "" { + versionSentences = append(versionSentences, fmt.Sprintf("%s is available starting from the Microsoft build of Go %s.", section.Title, section.MinGoVersion)) + } + if section.MinOpenSSLVersion != "" { + versionSentences = append(versionSentences, fmt.Sprintf("%s requires OpenSSL %s or later.", section.Title, section.MinOpenSSLVersion)) + } + if section.MinMacOSVersion != "" { + versionSentences = append(versionSentences, fmt.Sprintf("%s is available starting in macOS %s (Tahoe) or later.", section.Title, section.MinMacOSVersion)) + } + if len(versionSentences) > 0 { + fmt.Println(strings.Join(versionSentences, " ")) + fmt.Println() + } if section.Description != "" { fmt.Println(section.Description) fmt.Println() @@ -210,7 +232,14 @@ func printTable(section Section) { for _, item := range section.Items { name := item.Name - nameNotes := getFootnotes(item.Notes) + + itemNotes := item.Notes + if item.MinGoVersion != "" { + note := fmt.Sprintf("Available starting in the Microsoft build of Go %s.", item.MinGoVersion) + itemNotes = append([]string{note}, itemNotes...) + } + + nameNotes := getFootnotes(itemNotes) row := []string{name + nameNotes} @@ -228,14 +257,35 @@ func printTable(section Section) { symbol = "❌" } - notes := getFootnotes(status.Notes) - // Space before notes? Original: ✔️1 or ✔️ 1 - // Looking at original: ✔️1 (no space usually, but sometimes yes) - // "✔️ 4" in SHA-3-256 - // "✔️1" in PBKDF2 - // I'll use no space for now, or maybe check if I can detect it. - // The JSON doesn't store formatting. - // I'll use no space as it's cleaner. + statusNotes := status.Notes + // Prepend version notes in preferred order: minGoVersion, minOpenSSLVersion, minMacOSVersion + var versionNotes []string + if status.MinGoVersion != "" { + versionNotes = append(versionNotes, fmt.Sprintf("Available starting in the Microsoft build of Go %s.", status.MinGoVersion)) + } + if status.MinOpenSSLVersion != "" { + versionNotes = append(versionNotes, fmt.Sprintf("Requires OpenSSL %s or later.", status.MinOpenSSLVersion)) + } + if status.MinMacOSVersion != "" { + versionNotes = append(versionNotes, fmt.Sprintf("Requires macOS %s or later.", status.MinMacOSVersion)) + } + // Remove duplicates from notes + filtered := []string{} + for _, n := range statusNotes { + duplicate := false + for _, vn := range versionNotes { + if n == vn { + duplicate = true + break + } + } + if !duplicate { + filtered = append(filtered, n) + } + } + statusNotes = append(versionNotes, filtered...) + + notes := getFootnotes(statusNotes) row = append(row, symbol+notes) } @@ -269,19 +319,23 @@ func validateSection(section Section) error { return fmt.Errorf("section missing title") } - for _, item := range section.Items { + for i := range section.Items { + item := §ion.Items[i] if item.Name == "" { return fmt.Errorf("item missing name in section %q", section.Title) } if item.Platforms == nil { - return fmt.Errorf("item %q missing platforms in section %q", item.Name, section.Title) + item.Platforms = make(map[string]PlatformStatus) } - for _, p := range []string{"windows", "linux", "macos"} { status, ok := item.Platforms[p] if !ok { - return fmt.Errorf("item %q missing platform %q in section %q", item.Name, p, section.Title) + status = PlatformStatus{} + } + if status.Supported == "" { + status.Supported = "true" } + item.Platforms[p] = status switch status.Supported { case "true", "false", "warn", "N/A": // ok diff --git a/eng/_util/cmd/gencryptodoc/schema.json b/eng/_util/cmd/gencryptodoc/schema.json index a4ebef9516b..7b7af2e6cee 100644 --- a/eng/_util/cmd/gencryptodoc/schema.json +++ b/eng/_util/cmd/gencryptodoc/schema.json @@ -17,7 +17,10 @@ "packages": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/definitions/item" } }, - "subsections": { "type": "array", "items": { "$ref": "#/definitions/section" } }, + "subsections": { + "type": "array", + "items": { "$ref": "#/definitions/section" } + }, "footnotes": { "type": "array", "items": { "type": "string" } }, "footer": { "type": "string" } }, @@ -27,6 +30,7 @@ "type": "object", "properties": { "name": { "type": "string" }, + "minGoVersion": { "type": "string" }, "notes": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "object", @@ -34,19 +38,21 @@ "windows": { "$ref": "#/definitions/platformStatus" }, "linux": { "$ref": "#/definitions/platformStatus" }, "macos": { "$ref": "#/definitions/platformStatus" } - }, - "required": ["windows", "linux", "macos"] + } } }, - "required": ["name", "platforms"] + "required": ["name"] }, "platformStatus": { "type": "object", "properties": { - "supported": { "type": "string", "enum": ["true", "false", "warn", "N/A"] }, + "supported": { + "type": "string", + "enum": ["false", "warn", "N/A"] + }, + "minGoVersion": { "type": "string" }, "notes": { "type": "array", "items": { "type": "string" } } - }, - "required": ["supported"] + } } } } diff --git a/eng/doc/CrossPlatformCryptography.md b/eng/doc/CrossPlatformCryptography.md index bb5a318cd41..d81b1dcc294 100644 --- a/eng/doc/CrossPlatformCryptography.md +++ b/eng/doc/CrossPlatformCryptography.md @@ -85,7 +85,7 @@ This section includes the following packages: 4Available in Windows 11, version 24H2 or later. -5Available starting in macOS 26 (Tahoe). +5Requires macOS 26 or later. 6Requires OpenSSL 3.3 or later. @@ -281,7 +281,7 @@ ML-KEM is available starting from the Microsoft build of Go 1.26. 2Requires OpenSSL 3.5.0 or later. -3Requires macOS 26 (Tahoe) or later. +3Requires macOS 26 or later. ## Higher-level protocols From 4b46ecbf83ad12701640dc4efe2b072b9669e345 Mon Sep 17 00:00:00 2001 From: George Adams Date: Thu, 11 Dec 2025 10:08:42 +0000 Subject: [PATCH 5/7] improve schema --- eng/_util/cmd/gencryptodoc/crypto.json | 5 - eng/_util/cmd/gencryptodoc/schema.json | 12 +- eng/doc/CrossPlatformCryptography.md | 442 ------------------------- 3 files changed, 9 insertions(+), 450 deletions(-) diff --git a/eng/_util/cmd/gencryptodoc/crypto.json b/eng/_util/cmd/gencryptodoc/crypto.json index 85076144a87..0894de81b52 100644 --- a/eng/_util/cmd/gencryptodoc/crypto.json +++ b/eng/_util/cmd/gencryptodoc/crypto.json @@ -213,7 +213,6 @@ "title": "Asymmetric encryption", "packages": ["RSA", "ECDSA", "ECDH", "Ed25519", "DSA"], "description": "", - "table": null, "subsections": [ { "title": "RSA", @@ -552,7 +551,6 @@ "title": "Key Encapsulation Mechanisms (KEMs)", "packages": ["ML-KEM"], "description": "", - "table": null, "subsections": [ { "title": "ML-KEM", @@ -601,13 +599,11 @@ "title": "Higher-level protocols", "packages": ["HPKE", "TLS"], "description": "High-level protocols are algorithms that combine multiple cryptographic primitives to provide a specific functionality,\nsuch as TLS or Hybrid Public Key Encryption (HPKE).\n\nThese protocols are implemented using native Go code, but they rely on the underlying OS cryptographic libraries for the cryptographic operations.\n\nThis section includes the following subsections:", - "table": null, "subsections": [ { "title": "Hybrid Public Key Encryption (HPKE)", "packages": ["AEAD Functions", "KDFs", "KEMs", "crypto/hpke"], "description": "", - "table": null, "subsections": [ { "title": "HPKE Authenticated Encryption with Associated Data (AEAD) Functions", @@ -726,7 +722,6 @@ "crypto/tls" ], "description": "", - "table": null, "subsections": [ { "title": "TLS Versions", diff --git a/eng/_util/cmd/gencryptodoc/schema.json b/eng/_util/cmd/gencryptodoc/schema.json index 7b7af2e6cee..f633ff0a946 100644 --- a/eng/_util/cmd/gencryptodoc/schema.json +++ b/eng/_util/cmd/gencryptodoc/schema.json @@ -17,6 +17,7 @@ "packages": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/definitions/item" } }, + "minGoVersion": { "type": "string" }, "subsections": { "type": "array", "items": { "$ref": "#/definitions/section" } @@ -24,7 +25,8 @@ "footnotes": { "type": "array", "items": { "type": "string" } }, "footer": { "type": "string" } }, - "required": ["title"] + "required": ["title"], + "additionalProperties": false }, "item": { "type": "object", @@ -41,7 +43,8 @@ } } }, - "required": ["name"] + "required": ["name"], + "additionalProperties": false }, "platformStatus": { "type": "object", @@ -51,8 +54,11 @@ "enum": ["false", "warn", "N/A"] }, "minGoVersion": { "type": "string" }, + "minOpenSSLVersion": { "type": "string", "description": "Only meaningful for linux platform." }, + "minMacOSVersion": { "type": "string", "description": "Only meaningful for macOS platform." }, "notes": { "type": "array", "items": { "type": "string" } } - } + }, + "additionalProperties": false } } } diff --git a/eng/doc/CrossPlatformCryptography.md b/eng/doc/CrossPlatformCryptography.md index d81b1dcc294..e69de29bb2d 100644 --- a/eng/doc/CrossPlatformCryptography.md +++ b/eng/doc/CrossPlatformCryptography.md @@ -1,442 +0,0 @@ - - -# Cross-Platform Cryptography in the Microsoft build of Go - -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. - -This article assumes you have a working familiarity with cryptography in Go. - -## Platform support - -The Microsoft build of Go supports the following platforms: - -### Windows - -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, 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). -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, the Microsoft build of 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. - -## Table legend - -The following legend describes the symbols used in the tables to indicate the level of support for each cryptographic algorithm: - -| Symbol | Meaning | -| ------ | ---------------------------------------------------------------------------------------------------------------------------- | -| ✔️ | Supported, possibly with minor limitations that don't require special configuration when using the latest Go and OS versions | -| ⚠️ | Supported with limitations that require special configuration action | -| ❌ | Not supported | - -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 - -This section includes the following packages: - -- [crypto/md5](https://pkg.go.dev/crypto/md5) -- [crypto/sha1](https://pkg.go.dev/crypto/sha1) -- [crypto/sha256](https://pkg.go.dev/crypto/sha256) -- [crypto/sha512](https://pkg.go.dev/crypto/sha512) -- [crypto/sha3](https://pkg.go.dev/crypto/sha3) -- [crypto/hmac](https://pkg.go.dev/crypto/hmac) - -| Algorithm | Windows | Linux | macOS | -| --------------------- | -------------- | ---------------- | -------------- | -| MD5 | ✔️ | ✔️ | ✔️ | -| SHA-1 | ✔️ | ✔️ | ✔️ | -| SHA-2-224 | ❌ | ✔️ | ✔️ | -| SHA-2-256 | ✔️ | ✔️ | ✔️ | -| SHA-2-384 | ✔️ | ✔️ | ✔️ | -| SHA-2-512 | ✔️ | ✔️ | ✔️ | -| SHA-2-512_224 | ❌ | ✔️1,2 | ❌ | -| SHA-2-512_256 | ❌ | ✔️1,2 | ❌ | -| SHA-3-2243 | ❌ | ✔️2 | ❌ | -| SHA-3-2563 | ✔️4 | ✔️2 | ✔️5 | -| SHA-3-3843 | ✔️4 | ✔️2 | ✔️5 | -| SHA-3-5123 | ✔️4 | ✔️2 | ✔️5 | -| SHAKE-128 | ✔️ | ✔️6 | ❌ | -| SHAKE-256 | ✔️ | ✔️6 | ❌ | -| CSHAKE-128 | ✔️ | ❌ | ❌ | -| CSHAKE-256 | ✔️ | ❌ | ❌ | -| HMAC7 | ✔️ | ✔️ | ✔️ | - -1Available starting in the Microsoft build of Go 1.24. - -2Requires OpenSSL 1.1.1 or later. - -3Available starting in the Microsoft build of Go 1.26. - -4Available in Windows 11, version 24H2 or later. - -5Requires macOS 26 or later. - -6Requires OpenSSL 3.3 or later. - -7Supports only hash algorithms that are supported as standalone hash functions. - -## Symmetric encryption - -This section includes the following packages: - -- [crypto/aes](https://pkg.go.dev/crypto/aes) -- [crypto/cipher](https://pkg.go.dev/crypto/cipher) -- [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 | ✔️ | - -1AES-GCM supports specific keys, nonces, and tags: - -2When using OpenSSL 3, requires the legacy provider to be enabled. - -- Key Sizes - - AES-GCM works with 128, 192, and 256-bit keys. - -- Nonce Sizes - - AES-GCM works with 12-byte nonces. - -- Tag Sizes - - AES-GCM works with 16-byte tags. - -## Asymmetric encryption - -This section includes the following subsections: - -- [RSA](#rsa) -- [ECDSA](#ecdsa) -- [ECDH](#ecdh) -- [Ed25519](#ed25519) -- [DSA](#dsa) - -### RSA - -This section includes the following packages: - -- [crypto/rsa](https://pkg.go.dev/crypto/rsa) - -[rsa.GenerateKey](https://pkg.go.dev/crypto/rsa#GenerateKey) only supports the following key sizes (in bits): 2048, 3072, 4096. - -Multi-prime RSA keys are not supported. - -The RSA key size is subject to the limitations of the underlying cryptographic library. -For example, on some Windows and SCOSSL configurations, the key size should be multiple of 8. -Please refer to the documentation of the underlying cryptographic library for the specific limitations. - -Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). - -| Padding Mode | Windows | Linux | macOS | -| -------------------------------------- | -------------- | -------------- | -------------- | -| OAEP (MD5) | ✔️ | ✔️ | ✔️1 | -| OAEP (SHA-1) | ✔️ | ✔️ | ✔️1 | -| OAEP (SHA-2)2 | ✔️ | ✔️ | ✔️1 | -| OAEP (SHA-3) | ❌ | ❌ | ❌ | -| PSS (MD5) | ✔️3 | ✔️ | ❌ | -| PSS (SHA-1) | ✔️3 | ✔️ | ✔️4 | -| PSS (SHA-2)2 | ✔️3 | ✔️ | ✔️4 | -| PSS (SHA-3) | ❌ | ❌ | ❌ | -| PKCS1v15 Signature (Unhashed) | ✔️ | ✔️ | ✔️ | -| PKCS1v15 Signature (RIPMED160) | ❌ | ✔️5 | ❌ | -| PKCS1v15 Signature (MD4) | ❌ | ✔️5 | ❌ | -| PKCS1v15 Signature (MD5) | ✔️ | ✔️ | ❌ | -| PKCS1v15 Signature (MD5-SHA1) | ✔️5 | ✔️5 | ❌ | -| PKCS1v15 Signature (SHA-1) | ✔️ | ✔️ | ✔️ | -| PKCS1v15 Signature (SHA-2)2 | ✔️ | ✔️ | ✔️ | -| PKCS1v15 Signature (SHA-3) | ❌ | ❌ | ❌ | - -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). - -3On Windows, when verifying a PSS signature, [rsa.PSSSaltLengthAuto](https://pkg.go.dev/crypto/rsa#pkg-constants) is not supported. - -4On macOS, custom salt lengths are not supported. PSS always uses the [`rsa.PSSSaltLengthEqualsHash`](https://pkg.go.dev/crypto/rsa#pkg-constants). - -5Available starting in the Microsoft build of Go 1.24. - -### ECDSA - -This section includes the following packages: - -- [crypto/ecdsa](https://pkg.go.dev/crypto/ecdsa) -- [crypto/elliptic](https://pkg.go.dev/crypto/elliptic) - -Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). - -| Elliptic Curve | Windows | Linux | macOS | -| ---------------------- | ------- | ----- | ----- | -| NIST P-224 (secp224r1) | ✔️ | ✔️ | ❌ | -| NIST P-256 (secp256r1) | ✔️ | ✔️ | ✔️ | -| NIST P-384 (secp384r1) | ✔️ | ✔️ | ✔️ | -| NIST P-521 (secp521r1) | ✔️ | ✔️ | ✔️ | - -### ECDH - -This section includes the following packages: - -- [crypto/ecdh](https://pkg.go.dev/crypto/ecdh) - -Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). - -| Elliptic Curve | Windows | Linux | macOS | -| ------------------------------- | ------- | -------------- | ----- | -| NIST P-224 (secp224r1) | ✔️ | ✔️ | ❌ | -| NIST P-256 (secp256r1) | ✔️ | ✔️ | ✔️ | -| NIST P-384 (secp384r1) | ✔️ | ✔️ | ✔️ | -| NIST P-521 (secp521r1) | ✔️ | ✔️ | ✔️ | -| X25519 (curve25519)1 | ✔️ | ✔️2 | ✔️ | - -1Available starting in the Microsoft build of Go 1.26. - -2Requires OpenSSL 1.1.1 or later. - -### Ed25519 - -This section includes the following packages: - -- [crypto/ed25519](https://pkg.go.dev/crypto/ed25519) - -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 | ❌ | ❌ | ❌ | - -### DSA - -| Parameters | Windows | Linux | macOS | -| ---------- | ------- | ----- | ----- | -| L1024N160 | ✔️ | ✔️ | ❌ | -| L2048N224 | ❌ | ✔️ | ❌ | -| L2048N256 | ✔️ | ✔️ | ❌ | -| L3072N256 | ✔️ | ✔️ | ❌ | - -## Key derivation functions (KDFs) - -This section includes the following packages: - -- [crypto/hkdf](https://pkg.go.dev/crypto/hkdf) -- [crypto/pbkdf2](https://pkg.go.dev/crypto/pbkdf2) - -| Functions | Windows | Linux | macOS | -| --------- | -------------- | -------------- | -------------- | -| PBKDF2 | ✔️1 | ✔️1 | ✔️1 | -| HKDF | ✔️1 | ✔️1 | ✔️1 | - -1Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms). - -## Key Encapsulation Mechanisms (KEMs) - -This section includes the following subsections: - -- [ML-KEM](#ml-kem) - -### ML-KEM - -This section includes the following packages: - -- [crypto/mlkem](https://pkg.go.dev/crypto/mlkem) - -ML-KEM is available starting from the Microsoft build of Go 1.26. - -| Parameters | Windows | Linux | macOS | -| ---------- | -------------- | -------------- | -------------- | -| 768 | ✔️1 | ✔️2 | ✔️3 | -| 1024 | ✔️1 | ✔️2 | ✔️3 | - -1Requires Windows Server 2025 or Windows 11 (24H2, 25H2) or later. - -2Requires OpenSSL 3.5.0 or later. - -3Requires macOS 26 or later. - -## Higher-level protocols - -High-level protocols are algorithms that combine multiple cryptographic primitives to provide a specific functionality, -such as TLS or Hybrid Public Key Encryption (HPKE). - -These protocols are implemented using native Go code, but they rely on the underlying OS cryptographic libraries for the cryptographic operations. - -This section includes the following subsections: - -- [Hybrid Public Key Encryption (HPKE)](#hybrid-public-key-encryption-hpke) -- [TLS](#tls) - -### Hybrid Public Key Encryption (HPKE) - -This section includes the following packages: - -- [crypto/hpke](https://pkg.go.dev/crypto/hpke) - -This section includes the following subsections: - -- [AEAD Functions](#hpke-authenticated-encryption-with-associated-data-aead-functions) -- [KDFs](#hpke-key-derivation-functions-kdfs) -- [KEMs](#hpke-key-encapsulation-mechanisms-kems) - -#### HPKE Authenticated Encryption with Associated Data (AEAD) Functions - -| Functions | Windows | Linux | macOS | -| ---------------- | ------- | ----- | ----- | -| AES-128-GCM | ✔️ | ✔️ | ✔️ | -| AES-256-GCM | ✔️ | ✔️ | ✔️ | -| ChaCha20Poly1305 | ❌ | ❌ | ❌ | -| Export-only | N/A | N/A | N/A | - -#### HPKE Key Derivation Functions (KDFs) - -| Functions | Windows | Linux | macOS | -| ----------- | ------- | ----- | ----- | -| HKDF-SHA256 | ✔️ | ✔️ | ✔️ | -| HKDF-SHA384 | ✔️ | ✔️ | ✔️ | -| HKDF-SHA512 | ✔️ | ✔️ | ✔️ | - -#### HPKE Key Encapsulation Mechanisms (KEMs) - -| Functions | Windows | Linux | macOS | -| -------------------------------------- | ------- | ----- | ----- | -| DHKEM(P-256, HKDF-SHA256) | ✔️ | ✔️ | ✔️ | -| DHKEM(P-384, HKDF-SHA384) | ✔️ | ✔️ | ✔️ | -| DHKEM(P-521, HKDF-SHA512) | ✔️ | ✔️ | ✔️ | -| DHKEM(X25519, HKDF-SHA256)1 | ✔️ | ✔️ | ✔️ | -| ML-KEM-7682 | ✔️ | ✔️ | ✔️ | -| ML-KEM-10242 | ✔️ | ✔️ | ✔️ | -| MLKEM768-P2562 | ✔️ | ✔️ | ✔️ | -| MLKEM1024-P3842 | ✔️ | ✔️ | ✔️ | -| MLKEM768-X255191,2 | ✔️ | ✔️ | ✔️ | - -1See the [X25519](#ecdh) section for requirements. - -2See the [ML-KEM](#ml-kem) section for requirements. - -### TLS - -This section includes the following packages: - -- [crypto/tls](https://pkg.go.dev/crypto/tls) - -This section includes the following subsections: - -- [TLS Versions](#tls-versions) -- [TLS Cipher Suites](#tls-cipher-suites) -- [TLS Curves and Groups](#tls-curves-and-groups) -- [TLS Signature Schemes](#tls-signature-schemes) - -#### TLS Versions - -The TLS stack is implemented using native Go code but the crypto primitives are provided by the system cryptographic libraries. - -| Version | Windows | Linux | macOS | -| ------- | ------- | ----- | ----- | -| SSL 3.0 | ❌ | ❌ | ❌ | -| TLS 1.0 | ✔️ | ✔️ | ❌ | -| TLS 1.1 | ✔️ | ✔️ | ❌ | -| TLS 1.2 | ✔️ | ✔️ | ✔️ | -| TLS 1.3 | ✔️ | ✔️ | ✔️ | - -#### TLS Cipher Suites - -| Name | Windows | Linux | macOS | -| --------------------------------------------- | ------- | -------------- | ----- | -| TLS_RSA_WITH_RC4_128_SHA | ✔️ | ⚠️1 | ✔️ | -| TLS_RSA_WITH_3DES_EDE_CBC_SHA | ✔️ | ⚠️1 | ✔️ | -| TLS_RSA_WITH_AES_128_CBC_SHA | ✔️ | ✔️ | ✔️ | -| TLS_RSA_WITH_AES_256_CBC_SHA | ✔️ | ✔️ | ✔️ | -| TLS_RSA_WITH_AES_128_CBC_SHA256 | ✔️ | ✔️ | ✔️ | -| TLS_RSA_WITH_AES_128_GCM_SHA256 | ✔️ | ✔️ | ✔️ | -| TLS_RSA_WITH_AES_256_GCM_SHA384 | ✔️ | ✔️ | ✔️ | -| TLS_ECDHE_ECDSA_WITH_RC4_128_SHA | ✔️ | ⚠️1 | ✔️ | -| TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA | ✔️ | ✔️ | ✔️ | -| TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA | ✔️ | ✔️ | ✔️ | -| TLS_ECDHE_RSA_WITH_RC4_128_SHA | ✔️ | ⚠️1 | ✔️ | -| TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA | ✔️ | ⚠️1 | ✔️ | -| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA | ✔️ | ✔️ | ✔️ | -| TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA | ✔️ | ✔️ | ✔️ | -| TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 | ✔️ | ✔️ | ✔️ | -| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 | ✔️ | ✔️ | ✔️ | -| TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 | ✔️ | ✔️ | ✔️ | -| TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 | ✔️ | ✔️ | ✔️ | -| TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 | ✔️ | ✔️ | ✔️ | -| TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 | ✔️ | ✔️ | ✔️ | -| TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 | ❌ | ❌ | ❌ | -| TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 | ❌ | ❌ | ❌ | -| TLS_AES_128_GCM_SHA256 | ✔️ | ✔️ | ✔️ | -| TLS_AES_256_GCM_SHA384 | ✔️ | ✔️ | ✔️ | -| TLS_CHACHA20_POLY1305_SHA256 | ❌ | ❌ | ❌ | -| TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 | ❌ | ❌ | ❌ | -| TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 | ❌ | ❌ | ❌ | -| TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305 | ❌ | ❌ | ❌ | - -1When using OpenSSL 3, requires the legacy provider to be enabled. - -On Windows, it is possible to restrict and reorder the cipher suites following the [Schannel preferences](https://learn.microsoft.com/en-us/windows/win32/secauthn/cipher-suites-in-schannel) by building with the `ms_tls_config_schannel` goexperiment enabled. - -#### TLS Curves and Groups - -Below are the supported [`tls.CurveIDs`](https://pkg.go.dev/crypto/tls#CurveID). - -| Name | Windows | Linux | macOS | -| ------------------------------ | ------- | ----- | ----- | -| CurveP256 | ✔️ | ✔️ | ✔️ | -| CurveP384 | ✔️ | ✔️ | ✔️ | -| CurveP521 | ✔️ | ✔️ | ✔️ | -| X255191 | ✔️ | ✔️ | ✔️ | -| X25519MLKEM7681,2 | ✔️ | ✔️ | ✔️ | -| SecP256r1MLKEM7682 | ✔️ | ✔️ | ✔️ | -| SecP384r1MLKEM10242 | ✔️ | ✔️ | ✔️ | - -1See the [X25519](#ecdh) section for requirements. - -2See the [ML-KEM](#ml-kem) section for requirements. - -#### TLS Signature Schemes - -Below are the supported [`tls.SignatureSchemes`](https://pkg.go.dev/crypto/tls#SignatureScheme). - -| Name | Windows | Linux | macOS | -| ---------------------- | ------- | ----- | ----- | -| PKCS1WithSHA1 | ✔️ | ✔️ | ✔️ | -| PKCS1WithSHA256 | ✔️ | ✔️ | ✔️ | -| PKCS1WithSHA384 | ✔️ | ✔️ | ✔️ | -| PKCS1WithSHA512 | ✔️ | ✔️ | ✔️ | -| PSSWithSHA256 | ✔️ | ✔️ | ✔️ | -| PSSWithSHA384 | ✔️ | ✔️ | ✔️ | -| PSSWithSHA512 | ✔️ | ✔️ | ✔️ | -| ECDSAWithSHA1 | ✔️ | ✔️ | ✔️ | -| ECDSAWithP256AndSHA256 | ✔️ | ✔️ | ✔️ | -| ECDSAWithP384AndSHA384 | ✔️ | ✔️ | ✔️ | -| ECDSAWithP521AndSHA512 | ✔️ | ✔️ | ✔️ | -| Ed25519 | ❌ | ✔️ | ✔️ | From 85d8cad384d1d3e6d359cc9d15dc9cb905cf9fa9 Mon Sep 17 00:00:00 2001 From: George Adams Date: Thu, 11 Dec 2025 10:12:38 +0000 Subject: [PATCH 6/7] further tighten schema --- eng/_util/cmd/gencryptodoc/schema.json | 25 +- eng/doc/CrossPlatformCryptography.md | 442 +++++++++++++++++++++++++ 2 files changed, 462 insertions(+), 5 deletions(-) diff --git a/eng/_util/cmd/gencryptodoc/schema.json b/eng/_util/cmd/gencryptodoc/schema.json index f633ff0a946..ef8f7269c9b 100644 --- a/eng/_util/cmd/gencryptodoc/schema.json +++ b/eng/_util/cmd/gencryptodoc/schema.json @@ -17,7 +17,10 @@ "packages": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/definitions/item" } }, - "minGoVersion": { "type": "string" }, + "minGoVersion": { + "type": "string", + "description": "The minimum supported Go version e.g 1.24." + }, "subsections": { "type": "array", "items": { "$ref": "#/definitions/section" } @@ -32,7 +35,10 @@ "type": "object", "properties": { "name": { "type": "string" }, - "minGoVersion": { "type": "string" }, + "minGoVersion": { + "type": "string", + "description": "The minimum supported Go version e.g 1.24." + }, "notes": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "object", @@ -53,9 +59,18 @@ "type": "string", "enum": ["false", "warn", "N/A"] }, - "minGoVersion": { "type": "string" }, - "minOpenSSLVersion": { "type": "string", "description": "Only meaningful for linux platform." }, - "minMacOSVersion": { "type": "string", "description": "Only meaningful for macOS platform." }, + "minGoVersion": { + "type": "string", + "description": "The minimum supported Go version e.g 1.24." + }, + "minOpenSSLVersion": { + "type": "string", + "description": "The minimum supported OpenSSL version e.g 1.1.1." + }, + "minMacOSVersion": { + "type": "string", + "description": "The minimum supported macOS version e.g 26." + }, "notes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false diff --git a/eng/doc/CrossPlatformCryptography.md b/eng/doc/CrossPlatformCryptography.md index e69de29bb2d..d81b1dcc294 100644 --- a/eng/doc/CrossPlatformCryptography.md +++ b/eng/doc/CrossPlatformCryptography.md @@ -0,0 +1,442 @@ + + +# Cross-Platform Cryptography in the Microsoft build of Go + +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. + +This article assumes you have a working familiarity with cryptography in Go. + +## Platform support + +The Microsoft build of Go supports the following platforms: + +### Windows + +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, 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). +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, the Microsoft build of 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. + +## Table legend + +The following legend describes the symbols used in the tables to indicate the level of support for each cryptographic algorithm: + +| Symbol | Meaning | +| ------ | ---------------------------------------------------------------------------------------------------------------------------- | +| ✔️ | Supported, possibly with minor limitations that don't require special configuration when using the latest Go and OS versions | +| ⚠️ | Supported with limitations that require special configuration action | +| ❌ | Not supported | + +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 + +This section includes the following packages: + +- [crypto/md5](https://pkg.go.dev/crypto/md5) +- [crypto/sha1](https://pkg.go.dev/crypto/sha1) +- [crypto/sha256](https://pkg.go.dev/crypto/sha256) +- [crypto/sha512](https://pkg.go.dev/crypto/sha512) +- [crypto/sha3](https://pkg.go.dev/crypto/sha3) +- [crypto/hmac](https://pkg.go.dev/crypto/hmac) + +| Algorithm | Windows | Linux | macOS | +| --------------------- | -------------- | ---------------- | -------------- | +| MD5 | ✔️ | ✔️ | ✔️ | +| SHA-1 | ✔️ | ✔️ | ✔️ | +| SHA-2-224 | ❌ | ✔️ | ✔️ | +| SHA-2-256 | ✔️ | ✔️ | ✔️ | +| SHA-2-384 | ✔️ | ✔️ | ✔️ | +| SHA-2-512 | ✔️ | ✔️ | ✔️ | +| SHA-2-512_224 | ❌ | ✔️1,2 | ❌ | +| SHA-2-512_256 | ❌ | ✔️1,2 | ❌ | +| SHA-3-2243 | ❌ | ✔️2 | ❌ | +| SHA-3-2563 | ✔️4 | ✔️2 | ✔️5 | +| SHA-3-3843 | ✔️4 | ✔️2 | ✔️5 | +| SHA-3-5123 | ✔️4 | ✔️2 | ✔️5 | +| SHAKE-128 | ✔️ | ✔️6 | ❌ | +| SHAKE-256 | ✔️ | ✔️6 | ❌ | +| CSHAKE-128 | ✔️ | ❌ | ❌ | +| CSHAKE-256 | ✔️ | ❌ | ❌ | +| HMAC7 | ✔️ | ✔️ | ✔️ | + +1Available starting in the Microsoft build of Go 1.24. + +2Requires OpenSSL 1.1.1 or later. + +3Available starting in the Microsoft build of Go 1.26. + +4Available in Windows 11, version 24H2 or later. + +5Requires macOS 26 or later. + +6Requires OpenSSL 3.3 or later. + +7Supports only hash algorithms that are supported as standalone hash functions. + +## Symmetric encryption + +This section includes the following packages: + +- [crypto/aes](https://pkg.go.dev/crypto/aes) +- [crypto/cipher](https://pkg.go.dev/crypto/cipher) +- [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 | ✔️ | + +1AES-GCM supports specific keys, nonces, and tags: + +2When using OpenSSL 3, requires the legacy provider to be enabled. + +- Key Sizes + + AES-GCM works with 128, 192, and 256-bit keys. + +- Nonce Sizes + + AES-GCM works with 12-byte nonces. + +- Tag Sizes + + AES-GCM works with 16-byte tags. + +## Asymmetric encryption + +This section includes the following subsections: + +- [RSA](#rsa) +- [ECDSA](#ecdsa) +- [ECDH](#ecdh) +- [Ed25519](#ed25519) +- [DSA](#dsa) + +### RSA + +This section includes the following packages: + +- [crypto/rsa](https://pkg.go.dev/crypto/rsa) + +[rsa.GenerateKey](https://pkg.go.dev/crypto/rsa#GenerateKey) only supports the following key sizes (in bits): 2048, 3072, 4096. + +Multi-prime RSA keys are not supported. + +The RSA key size is subject to the limitations of the underlying cryptographic library. +For example, on some Windows and SCOSSL configurations, the key size should be multiple of 8. +Please refer to the documentation of the underlying cryptographic library for the specific limitations. + +Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). + +| Padding Mode | Windows | Linux | macOS | +| -------------------------------------- | -------------- | -------------- | -------------- | +| OAEP (MD5) | ✔️ | ✔️ | ✔️1 | +| OAEP (SHA-1) | ✔️ | ✔️ | ✔️1 | +| OAEP (SHA-2)2 | ✔️ | ✔️ | ✔️1 | +| OAEP (SHA-3) | ❌ | ❌ | ❌ | +| PSS (MD5) | ✔️3 | ✔️ | ❌ | +| PSS (SHA-1) | ✔️3 | ✔️ | ✔️4 | +| PSS (SHA-2)2 | ✔️3 | ✔️ | ✔️4 | +| PSS (SHA-3) | ❌ | ❌ | ❌ | +| PKCS1v15 Signature (Unhashed) | ✔️ | ✔️ | ✔️ | +| PKCS1v15 Signature (RIPMED160) | ❌ | ✔️5 | ❌ | +| PKCS1v15 Signature (MD4) | ❌ | ✔️5 | ❌ | +| PKCS1v15 Signature (MD5) | ✔️ | ✔️ | ❌ | +| PKCS1v15 Signature (MD5-SHA1) | ✔️5 | ✔️5 | ❌ | +| PKCS1v15 Signature (SHA-1) | ✔️ | ✔️ | ✔️ | +| PKCS1v15 Signature (SHA-2)2 | ✔️ | ✔️ | ✔️ | +| PKCS1v15 Signature (SHA-3) | ❌ | ❌ | ❌ | + +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). + +3On Windows, when verifying a PSS signature, [rsa.PSSSaltLengthAuto](https://pkg.go.dev/crypto/rsa#pkg-constants) is not supported. + +4On macOS, custom salt lengths are not supported. PSS always uses the [`rsa.PSSSaltLengthEqualsHash`](https://pkg.go.dev/crypto/rsa#pkg-constants). + +5Available starting in the Microsoft build of Go 1.24. + +### ECDSA + +This section includes the following packages: + +- [crypto/ecdsa](https://pkg.go.dev/crypto/ecdsa) +- [crypto/elliptic](https://pkg.go.dev/crypto/elliptic) + +Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). + +| Elliptic Curve | Windows | Linux | macOS | +| ---------------------- | ------- | ----- | ----- | +| NIST P-224 (secp224r1) | ✔️ | ✔️ | ❌ | +| NIST P-256 (secp256r1) | ✔️ | ✔️ | ✔️ | +| NIST P-384 (secp384r1) | ✔️ | ✔️ | ✔️ | +| NIST P-521 (secp521r1) | ✔️ | ✔️ | ✔️ | + +### ECDH + +This section includes the following packages: + +- [crypto/ecdh](https://pkg.go.dev/crypto/ecdh) + +Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). + +| Elliptic Curve | Windows | Linux | macOS | +| ------------------------------- | ------- | -------------- | ----- | +| NIST P-224 (secp224r1) | ✔️ | ✔️ | ❌ | +| NIST P-256 (secp256r1) | ✔️ | ✔️ | ✔️ | +| NIST P-384 (secp384r1) | ✔️ | ✔️ | ✔️ | +| NIST P-521 (secp521r1) | ✔️ | ✔️ | ✔️ | +| X25519 (curve25519)1 | ✔️ | ✔️2 | ✔️ | + +1Available starting in the Microsoft build of Go 1.26. + +2Requires OpenSSL 1.1.1 or later. + +### Ed25519 + +This section includes the following packages: + +- [crypto/ed25519](https://pkg.go.dev/crypto/ed25519) + +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 | ❌ | ❌ | ❌ | + +### DSA + +| Parameters | Windows | Linux | macOS | +| ---------- | ------- | ----- | ----- | +| L1024N160 | ✔️ | ✔️ | ❌ | +| L2048N224 | ❌ | ✔️ | ❌ | +| L2048N256 | ✔️ | ✔️ | ❌ | +| L3072N256 | ✔️ | ✔️ | ❌ | + +## Key derivation functions (KDFs) + +This section includes the following packages: + +- [crypto/hkdf](https://pkg.go.dev/crypto/hkdf) +- [crypto/pbkdf2](https://pkg.go.dev/crypto/pbkdf2) + +| Functions | Windows | Linux | macOS | +| --------- | -------------- | -------------- | -------------- | +| PBKDF2 | ✔️1 | ✔️1 | ✔️1 | +| HKDF | ✔️1 | ✔️1 | ✔️1 | + +1Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms). + +## Key Encapsulation Mechanisms (KEMs) + +This section includes the following subsections: + +- [ML-KEM](#ml-kem) + +### ML-KEM + +This section includes the following packages: + +- [crypto/mlkem](https://pkg.go.dev/crypto/mlkem) + +ML-KEM is available starting from the Microsoft build of Go 1.26. + +| Parameters | Windows | Linux | macOS | +| ---------- | -------------- | -------------- | -------------- | +| 768 | ✔️1 | ✔️2 | ✔️3 | +| 1024 | ✔️1 | ✔️2 | ✔️3 | + +1Requires Windows Server 2025 or Windows 11 (24H2, 25H2) or later. + +2Requires OpenSSL 3.5.0 or later. + +3Requires macOS 26 or later. + +## Higher-level protocols + +High-level protocols are algorithms that combine multiple cryptographic primitives to provide a specific functionality, +such as TLS or Hybrid Public Key Encryption (HPKE). + +These protocols are implemented using native Go code, but they rely on the underlying OS cryptographic libraries for the cryptographic operations. + +This section includes the following subsections: + +- [Hybrid Public Key Encryption (HPKE)](#hybrid-public-key-encryption-hpke) +- [TLS](#tls) + +### Hybrid Public Key Encryption (HPKE) + +This section includes the following packages: + +- [crypto/hpke](https://pkg.go.dev/crypto/hpke) + +This section includes the following subsections: + +- [AEAD Functions](#hpke-authenticated-encryption-with-associated-data-aead-functions) +- [KDFs](#hpke-key-derivation-functions-kdfs) +- [KEMs](#hpke-key-encapsulation-mechanisms-kems) + +#### HPKE Authenticated Encryption with Associated Data (AEAD) Functions + +| Functions | Windows | Linux | macOS | +| ---------------- | ------- | ----- | ----- | +| AES-128-GCM | ✔️ | ✔️ | ✔️ | +| AES-256-GCM | ✔️ | ✔️ | ✔️ | +| ChaCha20Poly1305 | ❌ | ❌ | ❌ | +| Export-only | N/A | N/A | N/A | + +#### HPKE Key Derivation Functions (KDFs) + +| Functions | Windows | Linux | macOS | +| ----------- | ------- | ----- | ----- | +| HKDF-SHA256 | ✔️ | ✔️ | ✔️ | +| HKDF-SHA384 | ✔️ | ✔️ | ✔️ | +| HKDF-SHA512 | ✔️ | ✔️ | ✔️ | + +#### HPKE Key Encapsulation Mechanisms (KEMs) + +| Functions | Windows | Linux | macOS | +| -------------------------------------- | ------- | ----- | ----- | +| DHKEM(P-256, HKDF-SHA256) | ✔️ | ✔️ | ✔️ | +| DHKEM(P-384, HKDF-SHA384) | ✔️ | ✔️ | ✔️ | +| DHKEM(P-521, HKDF-SHA512) | ✔️ | ✔️ | ✔️ | +| DHKEM(X25519, HKDF-SHA256)1 | ✔️ | ✔️ | ✔️ | +| ML-KEM-7682 | ✔️ | ✔️ | ✔️ | +| ML-KEM-10242 | ✔️ | ✔️ | ✔️ | +| MLKEM768-P2562 | ✔️ | ✔️ | ✔️ | +| MLKEM1024-P3842 | ✔️ | ✔️ | ✔️ | +| MLKEM768-X255191,2 | ✔️ | ✔️ | ✔️ | + +1See the [X25519](#ecdh) section for requirements. + +2See the [ML-KEM](#ml-kem) section for requirements. + +### TLS + +This section includes the following packages: + +- [crypto/tls](https://pkg.go.dev/crypto/tls) + +This section includes the following subsections: + +- [TLS Versions](#tls-versions) +- [TLS Cipher Suites](#tls-cipher-suites) +- [TLS Curves and Groups](#tls-curves-and-groups) +- [TLS Signature Schemes](#tls-signature-schemes) + +#### TLS Versions + +The TLS stack is implemented using native Go code but the crypto primitives are provided by the system cryptographic libraries. + +| Version | Windows | Linux | macOS | +| ------- | ------- | ----- | ----- | +| SSL 3.0 | ❌ | ❌ | ❌ | +| TLS 1.0 | ✔️ | ✔️ | ❌ | +| TLS 1.1 | ✔️ | ✔️ | ❌ | +| TLS 1.2 | ✔️ | ✔️ | ✔️ | +| TLS 1.3 | ✔️ | ✔️ | ✔️ | + +#### TLS Cipher Suites + +| Name | Windows | Linux | macOS | +| --------------------------------------------- | ------- | -------------- | ----- | +| TLS_RSA_WITH_RC4_128_SHA | ✔️ | ⚠️1 | ✔️ | +| TLS_RSA_WITH_3DES_EDE_CBC_SHA | ✔️ | ⚠️1 | ✔️ | +| TLS_RSA_WITH_AES_128_CBC_SHA | ✔️ | ✔️ | ✔️ | +| TLS_RSA_WITH_AES_256_CBC_SHA | ✔️ | ✔️ | ✔️ | +| TLS_RSA_WITH_AES_128_CBC_SHA256 | ✔️ | ✔️ | ✔️ | +| TLS_RSA_WITH_AES_128_GCM_SHA256 | ✔️ | ✔️ | ✔️ | +| TLS_RSA_WITH_AES_256_GCM_SHA384 | ✔️ | ✔️ | ✔️ | +| TLS_ECDHE_ECDSA_WITH_RC4_128_SHA | ✔️ | ⚠️1 | ✔️ | +| TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA | ✔️ | ✔️ | ✔️ | +| TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA | ✔️ | ✔️ | ✔️ | +| TLS_ECDHE_RSA_WITH_RC4_128_SHA | ✔️ | ⚠️1 | ✔️ | +| TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA | ✔️ | ⚠️1 | ✔️ | +| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA | ✔️ | ✔️ | ✔️ | +| TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA | ✔️ | ✔️ | ✔️ | +| TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 | ✔️ | ✔️ | ✔️ | +| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 | ✔️ | ✔️ | ✔️ | +| TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 | ✔️ | ✔️ | ✔️ | +| TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 | ✔️ | ✔️ | ✔️ | +| TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 | ✔️ | ✔️ | ✔️ | +| TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 | ✔️ | ✔️ | ✔️ | +| TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 | ❌ | ❌ | ❌ | +| TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 | ❌ | ❌ | ❌ | +| TLS_AES_128_GCM_SHA256 | ✔️ | ✔️ | ✔️ | +| TLS_AES_256_GCM_SHA384 | ✔️ | ✔️ | ✔️ | +| TLS_CHACHA20_POLY1305_SHA256 | ❌ | ❌ | ❌ | +| TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 | ❌ | ❌ | ❌ | +| TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 | ❌ | ❌ | ❌ | +| TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305 | ❌ | ❌ | ❌ | + +1When using OpenSSL 3, requires the legacy provider to be enabled. + +On Windows, it is possible to restrict and reorder the cipher suites following the [Schannel preferences](https://learn.microsoft.com/en-us/windows/win32/secauthn/cipher-suites-in-schannel) by building with the `ms_tls_config_schannel` goexperiment enabled. + +#### TLS Curves and Groups + +Below are the supported [`tls.CurveIDs`](https://pkg.go.dev/crypto/tls#CurveID). + +| Name | Windows | Linux | macOS | +| ------------------------------ | ------- | ----- | ----- | +| CurveP256 | ✔️ | ✔️ | ✔️ | +| CurveP384 | ✔️ | ✔️ | ✔️ | +| CurveP521 | ✔️ | ✔️ | ✔️ | +| X255191 | ✔️ | ✔️ | ✔️ | +| X25519MLKEM7681,2 | ✔️ | ✔️ | ✔️ | +| SecP256r1MLKEM7682 | ✔️ | ✔️ | ✔️ | +| SecP384r1MLKEM10242 | ✔️ | ✔️ | ✔️ | + +1See the [X25519](#ecdh) section for requirements. + +2See the [ML-KEM](#ml-kem) section for requirements. + +#### TLS Signature Schemes + +Below are the supported [`tls.SignatureSchemes`](https://pkg.go.dev/crypto/tls#SignatureScheme). + +| Name | Windows | Linux | macOS | +| ---------------------- | ------- | ----- | ----- | +| PKCS1WithSHA1 | ✔️ | ✔️ | ✔️ | +| PKCS1WithSHA256 | ✔️ | ✔️ | ✔️ | +| PKCS1WithSHA384 | ✔️ | ✔️ | ✔️ | +| PKCS1WithSHA512 | ✔️ | ✔️ | ✔️ | +| PSSWithSHA256 | ✔️ | ✔️ | ✔️ | +| PSSWithSHA384 | ✔️ | ✔️ | ✔️ | +| PSSWithSHA512 | ✔️ | ✔️ | ✔️ | +| ECDSAWithSHA1 | ✔️ | ✔️ | ✔️ | +| ECDSAWithP256AndSHA256 | ✔️ | ✔️ | ✔️ | +| ECDSAWithP384AndSHA384 | ✔️ | ✔️ | ✔️ | +| ECDSAWithP521AndSHA512 | ✔️ | ✔️ | ✔️ | +| Ed25519 | ❌ | ✔️ | ✔️ | From 98f363d4b5a2f3d2c65dba1ea58d51047535f648 Mon Sep 17 00:00:00 2001 From: George Adams Date: Thu, 11 Dec 2025 10:15:43 +0000 Subject: [PATCH 7/7] fix header --- eng/_util/cmd/gencryptodoc/header.md | 2 +- eng/doc/CrossPlatformCryptography.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/eng/_util/cmd/gencryptodoc/header.md b/eng/_util/cmd/gencryptodoc/header.md index 7c2690cc914..c2ef73d0739 100644 --- a/eng/_util/cmd/gencryptodoc/header.md +++ b/eng/_util/cmd/gencryptodoc/header.md @@ -26,7 +26,7 @@ OpenSSL 3 implements all the cryptographic algorithms using [Providers](https:// 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 +### macOS On macOS, the Microsoft build of 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. diff --git a/eng/doc/CrossPlatformCryptography.md b/eng/doc/CrossPlatformCryptography.md index d81b1dcc294..99cd629e88e 100644 --- a/eng/doc/CrossPlatformCryptography.md +++ b/eng/doc/CrossPlatformCryptography.md @@ -28,7 +28,7 @@ OpenSSL 3 implements all the cryptographic algorithms using [Providers](https:// 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 +### macOS On macOS, the Microsoft build of 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.