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..0894de81b52 --- /dev/null +++ b/eng/_util/cmd/gencryptodoc/crypto.json @@ -0,0 +1,1018 @@ +{ + "$schema": "./schema.json", + "sections": [ + { + "title": "Hash and Message Authentication Algorithms", + "packages": [ + "crypto/md5", + "crypto/sha1", + "crypto/sha256", + "crypto/sha512", + "crypto/sha3", + "crypto/hmac" + ], + "items": [ + { + "name": "MD5" + }, + { + "name": "SHA-1" + }, + { + "name": "SHA-2-224", + "platforms": { + "windows": { "supported": "false" } + } + }, + { + "name": "SHA-2-256" + }, + { + "name": "SHA-2-384" + }, + { + "name": "SHA-2-512" + }, + { + "name": "SHA-2-512_224", + "platforms": { + "windows": { "supported": "false" }, + "linux": { "minGoVersion": "1.24", "minOpenSSLVersion": "1.1.1" }, + "macos": { "supported": "false" } + } + }, + { + "name": "SHA-2-512_256", + "platforms": { + "windows": { "supported": "false" }, + "linux": { "minGoVersion": "1.24", "minOpenSSLVersion": "1.1.1" }, + "macos": { "supported": "false" } + } + }, + { + "name": "SHA-3-224", + "minGoVersion": "1.26", + "platforms": { + "windows": { "supported": "false" }, + "linux": { "minOpenSSLVersion": "1.1.1" }, + "macos": { "supported": "false" } + } + }, + { + "name": "SHA-3-256", + "minGoVersion": "1.26", + "platforms": { + "windows": { + "notes": ["Available in Windows 11, version 24H2 or later."] + }, + "linux": { "minOpenSSLVersion": "1.1.1" }, + "macos": { "minMacOSVersion": "26" } + } + }, + { + "name": "SHA-3-384", + "minGoVersion": "1.26", + "platforms": { + "windows": { + "notes": ["Available in Windows 11, version 24H2 or later."] + }, + "linux": { "minOpenSSLVersion": "1.1.1" }, + "macos": { "minMacOSVersion": "26" } + } + }, + { + "name": "SHA-3-512", + "minGoVersion": "1.26", + "platforms": { + "windows": { + "notes": ["Available in Windows 11, version 24H2 or later."] + }, + "linux": { "minOpenSSLVersion": "1.1.1" }, + "macos": { "minMacOSVersion": "26" } + } + }, + { + "name": "SHAKE-128", + "platforms": { + "linux": { "minOpenSSLVersion": "3.3" }, + "macos": { "supported": "false" } + } + }, + { + "name": "SHAKE-256", + "platforms": { + "linux": { "minOpenSSLVersion": "3.3" }, + "macos": { "supported": "false" } + } + }, + { + "name": "CSHAKE-128", + "platforms": { + "linux": { "supported": "false" }, + "macos": { "supported": "false" } + } + }, + { + "name": "CSHAKE-256", + "platforms": { + "linux": { "supported": "false" }, + "macos": { "supported": "false" } + } + }, + { + "name": "HMAC", + "notes": [ + "Supports only hash algorithms that are supported as standalone hash functions." + ] + } + ] + }, + { + "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.", + "subsections": [], + "items": [ + { + "name": "AES-ECB" + }, + { + "name": "AES-CBC" + }, + { + "name": "AES-CTR", + "platforms": { + "windows": { "supported": "false" }, + "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:"] + }, + { + "name": "DES-CBC", + "platforms": { + "linux": { + "supported": "warn", + "notes": [ + "When using OpenSSL 3, requires the legacy provider to be enabled." + ] + } + } + }, + { + "name": "DES-ECB", + "platforms": { + "linux": { + "supported": "warn", + "notes": [ + "When using OpenSSL 3, requires the legacy provider to be enabled." + ] + } + } + }, + { + "name": "3DES-ECB" + }, + { + "name": "3DES-CBC" + }, + { + "name": "RC4", + "platforms": { + "linux": { + "supported": "warn", + "notes": [ + "When using OpenSSL 3, requires the legacy provider to be enabled." + ] + } + } + } + ] + }, + { + "title": "Asymmetric encryption", + "packages": ["RSA", "ECDSA", "ECDH", "Ed25519", "DSA"], + "description": "", + "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.\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": [ + { + "name": "OAEP (MD5)", + "platforms": { + "macos": { + "notes": [ + "macOS doesn't support passing a custom label to OAEP functions." + ] + } + } + }, + { + "name": "OAEP (SHA-1)", + "platforms": { + "macos": { + "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": { + "macos": { + "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": { + "notes": [ + "On Windows, when verifying a PSS signature, [rsa.PSSSaltLengthAuto](https://pkg.go.dev/crypto/rsa#pkg-constants) is not supported." + ] + }, + "macos": { "supported": "false" } + } + }, + { + "name": "PSS (SHA-1)", + "platforms": { + "windows": { + "notes": [ + "On Windows, when verifying a PSS signature, [rsa.PSSSaltLengthAuto](https://pkg.go.dev/crypto/rsa#pkg-constants) is not supported." + ] + }, + "macos": { + "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": { + "notes": [ + "On Windows, when verifying a PSS signature, [rsa.PSSSaltLengthAuto](https://pkg.go.dev/crypto/rsa#pkg-constants) is not supported." + ] + }, + "macos": { + "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)" + }, + { + "name": "PKCS1v15 Signature (RIPMED160)", + "platforms": { + "windows": { "supported": "false" }, + "linux": { + "minGoVersion": "1.24" + }, + "macos": { "supported": "false" } + } + }, + { + "name": "PKCS1v15 Signature (MD4)", + "platforms": { + "windows": { "supported": "false" }, + "linux": { + "minGoVersion": "1.24" + }, + "macos": { "supported": "false" } + } + }, + { + "name": "PKCS1v15 Signature (MD5)", + "platforms": { + "macos": { "supported": "false" } + } + }, + { + "name": "PKCS1v15 Signature (MD5-SHA1)", + "platforms": { + "windows": { + "minGoVersion": "1.24" + }, + "linux": { + "minGoVersion": "1.24" + }, + "macos": { "supported": "false" } + } + }, + { + "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)." + ] + }, + { + "name": "PKCS1v15 Signature (SHA-3)", + "platforms": { + "windows": { "supported": "false" }, + "linux": { "supported": "false" }, + "macos": { "supported": "false" } + } + } + ] + }, + { + "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": [], + "items": [ + { + "name": "NIST P-224 (secp224r1)", + "platforms": { + "macos": { "supported": "false" } + } + }, + { + "name": "NIST P-256 (secp256r1)" + }, + { + "name": "NIST P-384 (secp384r1)" + }, + { + "name": "NIST P-521 (secp521r1)" + } + ] + }, + { + "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).", + "subsections": [], + "items": [ + { + "name": "NIST P-224 (secp224r1)", + "platforms": { + "macos": { "supported": "false" } + } + }, + { + "name": "NIST P-256 (secp256r1)" + }, + { + "name": "NIST P-384 (secp384r1)" + }, + { + "name": "NIST P-521 (secp521r1)" + }, + { + "name": "X25519 (curve25519)", + "minGoVersion": "1.26", + "platforms": { + "linux": { + "minOpenSSLVersion": "1.1.1" + } + } + } + ] + }, + { + "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": [], + "items": [ + { + "name": "Ed25519", + "platforms": { + "windows": { "supported": "false" } + } + }, + { + "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", + "columnHeader": "Parameters", + "packages": [], + "description": "", + "subsections": [], + "items": [ + { + "name": "L1024N160", + "platforms": { + "macos": { "supported": "false" } + } + }, + { + "name": "L2048N224", + "platforms": { + "windows": { "supported": "false" }, + "macos": { "supported": "false" } + } + }, + { + "name": "L2048N256", + "platforms": { + "macos": { "supported": "false" } + } + }, + { + "name": "L3072N256", + "platforms": { + "macos": { "supported": "false" } + } + } + ] + } + ] + }, + { + "title": "Key derivation functions (KDFs)", + "columnHeader": "Functions", + "packages": ["crypto/hkdf", "crypto/pbkdf2"], + "description": "", + "subsections": [], + "items": [ + { + "name": "PBKDF2", + "platforms": { + "windows": { + "notes": [ + "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." + ] + }, + "linux": { + "notes": [ + "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." + ] + }, + "macos": { + "notes": [ + "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." + ] + } + } + }, + { + "name": "HKDF", + "platforms": { + "windows": { + "notes": [ + "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." + ] + }, + "linux": { + "notes": [ + "Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms)." + ] + }, + "macos": { + "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": "", + "subsections": [ + { + "title": "ML-KEM", + "columnHeader": "Parameters", + "packages": ["crypto/mlkem"], + "minGoVersion": "1.26", + "subsections": [], + "items": [ + { + "name": "768", + "platforms": { + "windows": { + "notes": [ + "Requires Windows Server 2025 or Windows 11 (24H2, 25H2) or later." + ] + }, + "linux": { + "minOpenSSLVersion": "3.5.0" + }, + "macos": { + "minMacOSVersion": "26" + } + } + }, + { + "name": "1024", + "platforms": { + "windows": { + "notes": [ + "Requires Windows Server 2025 or Windows 11 (24H2, 25H2) or later." + ] + }, + "linux": { + "minOpenSSLVersion": "3.5.0" + }, + "macos": { + "minMacOSVersion": "26" + } + } + } + ] + } + ] + }, + { + "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:", + "subsections": [ + { + "title": "Hybrid Public Key Encryption (HPKE)", + "packages": ["AEAD Functions", "KDFs", "KEMs", "crypto/hpke"], + "description": "", + "subsections": [ + { + "title": "HPKE Authenticated Encryption with Associated Data (AEAD) Functions", + "columnHeader": "Functions", + "shortTitle": "AEAD Functions", + "packages": [], + "description": "", + "subsections": [], + "items": [ + { + "name": "AES-128-GCM" + }, + { + "name": "AES-256-GCM" + }, + { + "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)", + "columnHeader": "Functions", + "shortTitle": "KDFs", + "packages": [], + "description": "", + "subsections": [], + "items": [ + { + "name": "HKDF-SHA256" + }, + { + "name": "HKDF-SHA384" + }, + { + "name": "HKDF-SHA512" + } + ] + }, + { + "title": "HPKE Key Encapsulation Mechanisms (KEMs)", + "columnHeader": "Functions", + "shortTitle": "KEMs", + "packages": [], + "description": "", + "subsections": [], + "items": [ + { + "name": "DHKEM(P-256, HKDF-SHA256)" + }, + { + "name": "DHKEM(P-384, HKDF-SHA384)" + }, + { + "name": "DHKEM(P-521, HKDF-SHA512)" + }, + { + "name": "DHKEM(X25519, HKDF-SHA256)", + "notes": ["See the [X25519](#ecdh) section for requirements."] + }, + { + "name": "ML-KEM-768", + "notes": [ + "See the [ML-KEM](#ml-kem) section for requirements." + ] + }, + { + "name": "ML-KEM-1024", + "notes": [ + "See the [ML-KEM](#ml-kem) section for requirements." + ] + }, + { + "name": "MLKEM768-P256", + "notes": [ + "See the [ML-KEM](#ml-kem) section for requirements." + ] + }, + { + "name": "MLKEM1024-P384", + "notes": [ + "See the [ML-KEM](#ml-kem) section for requirements." + ] + }, + { + "name": "MLKEM768-X25519", + "notes": [ + "See the [X25519](#ecdh) section for requirements.", + "See the [ML-KEM](#ml-kem) section for requirements." + ] + } + ] + } + ] + }, + { + "title": "TLS", + "packages": [ + "TLS Versions", + "TLS Cipher Suites", + "TLS Curves and Groups", + "TLS Signature Schemes", + "crypto/tls" + ], + "description": "", + "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": [], + "items": [ + { + "name": "SSL 3.0", + "platforms": { + "windows": { "supported": "false" }, + "linux": { "supported": "false" }, + "macos": { "supported": "false" } + } + }, + { + "name": "TLS 1.0", + "platforms": { + "macos": { "supported": "false" } + } + }, + { + "name": "TLS 1.1", + "platforms": { + "macos": { "supported": "false" } + } + }, + { + "name": "TLS 1.2" + }, + { + "name": "TLS 1.3" + } + ] + }, + { + "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": [], + "items": [ + { + "name": "TLS_RSA_WITH_RC4_128_SHA", + "platforms": { + "linux": { + "supported": "warn", + "notes": [ + "When using OpenSSL 3, requires the legacy provider to be enabled." + ] + } + } + }, + { + "name": "TLS_RSA_WITH_3DES_EDE_CBC_SHA", + "platforms": { + "linux": { + "supported": "warn", + "notes": [ + "When using OpenSSL 3, requires the legacy provider to be enabled." + ] + } + } + }, + { + "name": "TLS_RSA_WITH_AES_128_CBC_SHA" + }, + { + "name": "TLS_RSA_WITH_AES_256_CBC_SHA" + }, + { + "name": "TLS_RSA_WITH_AES_128_CBC_SHA256" + }, + { + "name": "TLS_RSA_WITH_AES_128_GCM_SHA256" + }, + { + "name": "TLS_RSA_WITH_AES_256_GCM_SHA384" + }, + { + "name": "TLS_ECDHE_ECDSA_WITH_RC4_128_SHA", + "platforms": { + "linux": { + "supported": "warn", + "notes": [ + "When using OpenSSL 3, requires the legacy provider to be enabled." + ] + } + } + }, + { + "name": "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA" + }, + { + "name": "TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA" + }, + { + "name": "TLS_ECDHE_RSA_WITH_RC4_128_SHA", + "platforms": { + "linux": { + "supported": "warn", + "notes": [ + "When using OpenSSL 3, requires the legacy provider to be enabled." + ] + } + } + }, + { + "name": "TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA", + "platforms": { + "linux": { + "supported": "warn", + "notes": [ + "When using OpenSSL 3, requires the legacy provider to be enabled." + ] + } + } + }, + { + "name": "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA" + }, + { + "name": "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA" + }, + { + "name": "TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256" + }, + { + "name": "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256" + }, + { + "name": "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256" + }, + { + "name": "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256" + }, + { + "name": "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384" + }, + { + "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" } + } + }, + { + "name": "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256", + "platforms": { + "windows": { "supported": "false" }, + "linux": { "supported": "false" }, + "macos": { "supported": "false" } + } + }, + { + "name": "TLS_AES_128_GCM_SHA256" + }, + { + "name": "TLS_AES_256_GCM_SHA384" + }, + { + "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", + "columnHeader": "Name", + "packages": [], + "description": "Below are the supported [`tls.CurveIDs`](https://pkg.go.dev/crypto/tls#CurveID).", + "subsections": [], + "items": [ + { + "name": "CurveP256" + }, + { + "name": "CurveP384" + }, + { + "name": "CurveP521" + }, + { + "name": "X25519", + "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." + ] + }, + { + "name": "SecP256r1MLKEM768", + "notes": [ + "See the [ML-KEM](#ml-kem) section for requirements." + ] + }, + { + "name": "SecP384r1MLKEM1024", + "notes": [ + "See the [ML-KEM](#ml-kem) section for requirements." + ] + } + ] + }, + { + "title": "TLS Signature Schemes", + "columnHeader": "Name", + "packages": [], + "description": "Below are the supported [`tls.SignatureSchemes`](https://pkg.go.dev/crypto/tls#SignatureScheme).", + "subsections": [], + "items": [ + { + "name": "PKCS1WithSHA1" + }, + { + "name": "PKCS1WithSHA256" + }, + { + "name": "PKCS1WithSHA384" + }, + { + "name": "PKCS1WithSHA512" + }, + { + "name": "PSSWithSHA256" + }, + { + "name": "PSSWithSHA384" + }, + { + "name": "PSSWithSHA512" + }, + { + "name": "ECDSAWithSHA1" + }, + { + "name": "ECDSAWithP256AndSHA256" + }, + { + "name": "ECDSAWithP384AndSHA384" + }, + { + "name": "ECDSAWithP521AndSHA512" + }, + { + "name": "Ed25519", + "platforms": { + "windows": { "supported": "false" } + } + } + ] + } + ] + } + ] + } + ] +} diff --git a/eng/_util/cmd/gencryptodoc/header.md b/eng/_util/cmd/gencryptodoc/header.md new file mode 100644 index 00000000000..c2ef73d0739 --- /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..cd4403e09a6 --- /dev/null +++ b/eng/_util/cmd/gencryptodoc/main.go @@ -0,0 +1,353 @@ +// 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"` + 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"` + 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"` + 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 { + Sections []Section `json:"sections"` +} + +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) + + // 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() + } + + // 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() + } + + // 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() + } + + 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 := section.ColumnHeader + if colHeader == "" { + 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 + + 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} + + 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 = "❌" + } + + 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) + } + + 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 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 { + item.Platforms = make(map[string]PlatformStatus) + } + for _, p := range []string{"windows", "linux", "macos"} { + status, ok := item.Platforms[p] + if !ok { + status = PlatformStatus{} + } + if status.Supported == "" { + status.Supported = "true" + } + item.Platforms[p] = status + 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..ef8f7269c9b --- /dev/null +++ b/eng/_util/cmd/gencryptodoc/schema.json @@ -0,0 +1,79 @@ +{ + "$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" }, + "columnHeader": { "type": "string" }, + "packages": { "type": "array", "items": { "type": "string" } }, + "description": { "type": "string" }, + "items": { "type": "array", "items": { "$ref": "#/definitions/item" } }, + "minGoVersion": { + "type": "string", + "description": "The minimum supported Go version e.g 1.24." + }, + "subsections": { + "type": "array", + "items": { "$ref": "#/definitions/section" } + }, + "footnotes": { "type": "array", "items": { "type": "string" } }, + "footer": { "type": "string" } + }, + "required": ["title"], + "additionalProperties": false + }, + "item": { + "type": "object", + "properties": { + "name": { "type": "string" }, + "minGoVersion": { + "type": "string", + "description": "The minimum supported Go version e.g 1.24." + }, + "notes": { "type": "array", "items": { "type": "string" } }, + "platforms": { + "type": "object", + "properties": { + "windows": { "$ref": "#/definitions/platformStatus" }, + "linux": { "$ref": "#/definitions/platformStatus" }, + "macos": { "$ref": "#/definitions/platformStatus" } + } + } + }, + "required": ["name"], + "additionalProperties": false + }, + "platformStatus": { + "type": "object", + "properties": { + "supported": { + "type": "string", + "enum": ["false", "warn", "N/A"] + }, + "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 1492ecfaea2..99cd629e88e 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. @@ -26,9 +28,9 @@ 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, 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. @@ -83,11 +85,11 @@ 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. -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 @@ -156,32 +158,32 @@ Operations that require random numbers (rand io.Reader) only support [rand.Reade | 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 @@ -203,14 +205,12 @@ Operations that require random numbers (rand io.Reader) only support [rand.Reade This section includes the following packages: -- [crypto/ecdh](https://pkg.go.dev/crypto/ecdsa) +- [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). -X25519 is available starting from the Microsoft build of Go 1.26. - -| Elliptic Curve | Windows | Linux | macOS | -| ------------------------------- | ------- | --------------- | ----- | +| Elliptic Curve | Windows | Linux | macOS | +| ------------------------------- | ------- | -------------- | ----- | | NIST P-224 (secp224r1) | ✔️ | ✔️ | ❌ | | NIST P-256 (secp256r1) | ✔️ | ✔️ | ✔️ | | NIST P-384 (secp384r1) | ✔️ | ✔️ | ✔️ | @@ -251,10 +251,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). @@ -272,16 +272,16 @@ This section includes the following packages: 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. 2Requires OpenSSL 3.5.0 or later. -3Requires macOS 26 (Tahoe) or later. +3Requires macOS 26 or later. ## Higher-level protocols @@ -292,51 +292,51 @@ These protocols are implemented using native Go code, but they rely on the under 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) +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 | -| ---------------- | ------- | ----- | ------| -| 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. @@ -344,6 +344,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) @@ -351,10 +355,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. @@ -409,14 +409,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.