-
Notifications
You must be signed in to change notification settings - Fork 40
Add Cross-Platform Cryptography document
#1471
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
19 commits
Select commit
Hold shift + click to select a range
b92dd20
first pass
qmuntal cd24039
add platform info
qmuntal 1e82e05
update symmetric encryption table
qmuntal 979900e
add RSA
qmuntal 7b56e5e
add missing algos
qmuntal 35bb486
add doc link
qmuntal a1f907d
add tls and ed25519
qmuntal ee1fdf6
remove TLS 1.3 warning
qmuntal 95d7029
add sep lines
qmuntal 3f36c68
cross Ed25519 on Windows
qmuntal 2a58d04
fix typo
qmuntal 080aaab
fix table format
qmuntal 5d9507a
formating
qmuntal bbe10b1
Apply suggestions from code review
qmuntal dd0ed6e
Apply suggestions from code review
qmuntal dc251a6
remove advantage bullets
qmuntal a46f62a
add legend
qmuntal b9ae603
Apply suggestions from code review
qmuntal 500e3f5
clarify docs
qmuntal File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,342 @@ | ||
| # Cross-Platform Cryptography in Microsoft Go | ||
|
|
||
| Cryptographic operations in Microsoft Go are delegated to the operating system (OS) libraries in some conditions described. | ||
| The high level conditions and the benefits of delegating cryptographic operations are described in the [Microsoft Go FIPS README](./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 | ||
|
|
||
| Microsoft Go supports the following platforms: | ||
|
|
||
| ### Windows | ||
|
|
||
| On Windows, Microsoft 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, Microsoft 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). | ||
| Microsoft 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)). | ||
|
|
||
| ## 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, Microsoft 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/golang.org/x/crypto/sha3) | ||
| * [crypto/hmac](https://pkg.go.dev/crypto/hmac) | ||
|
|
||
| |Algorithm |Windows |Linux | | ||
| |---------------------------|--------------------|---------------------| | ||
| | MD5 | ✔️ | ✔️ | | ||
| | SHA-1 | ✔️ | ✔️ | | ||
| | SHA-2-224 | ❌ | ✔️ | | ||
| | SHA-2-256 | ✔️ | ✔️ | | ||
| | SHA-2-384 | ✔️ | ✔️ | | ||
| | SHA-2-512 | ✔️ | ✔️ | | ||
| | SHA-2-512_224 | ❌ | ✔️<sup>1, 2</sup> | | ||
| | SHA-2-512_256 | ❌ | ✔️<sup>1, 2</sup> | | ||
| | SHA-3-224 | ❌ | ❌ | | ||
| | SHA-3-256 | ❌ | ❌ | | ||
| | SHA-3-384 | ❌ | ❌ | | ||
| | SHA-3-512 | ❌ | ❌ | | ||
| | SHAKE-128 | ❌ | ❌ | | ||
| | SHAKE-256 | ❌ | ❌ | | ||
| | CSHAKE-128 | ❌ | ❌ | | ||
| | CSHAKE-256 | ❌ | ❌ | | ||
| | HMAC<sup>3</sup> | ✔️ | ✔️ | | ||
|
|
||
| <sup>1</sup>Available starting in Microsoft Go 1.24. | ||
|
|
||
| <sup>2</sup>Requires OpenSSL 1.1.1 or later. | ||
|
|
||
| <sup>3</sup>Supports 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 | | ||
| |---------------|----------|------------------| | ||
| | AES-ECB | ✔️ | ✔️ | | ||
| | AES-CBC | ✔️ | ✔️ | | ||
| | AES-CTR | ❌ | ✔️ | | ||
| | AES-CFB | ❌ | ❌ | | ||
| | AES-OFB | ❌ | ❌ | | ||
| | AES-GCM | ✔️ | ✔️ | | ||
| | DES-CBC | ✔️ | ⚠️<sup>1</sup> | | ||
| | DES-ECB | ✔️ | ⚠️<sup>1</sup> | | ||
| | 3DES-ECB | ✔️ | ✔️ | | ||
| | 3DES-CBC | ✔️ | ✔️ | | ||
| | RC4 | ✔️ | ⚠️<sup>1</sup> | | ||
|
|
||
| <sup>1</sup>When using OpenSSL 3, requires the legacy provider to be enabled. | ||
|
|
||
| ### AES-GCM keys, nonces, and tags | ||
|
|
||
| * 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) | ||
|
|
||
| | Padding Mode | Windows | Linux | | ||
| |----------------------------------------|----------------------|---------------------| | ||
| | OAEP (MD5) | ✔️ | ✔️ | | ||
| | OAEP (SHA-1) | ✔️ | ✔️ | | ||
| | OAEP (SHA-2)<sup>1</sup> | ✔️ | ✔️ | | ||
| | OAEP (SHA-3) | ❌ | ❌ | | ||
| | PSS (MD5) | ✔️ | ✔️ | | ||
| | PSS (SHA-1) | ✔️ | ✔️ | | ||
| | PSS (SHA-2)<sup>1</sup> | ✔️ | ✔️ | | ||
| | PSS (SHA-3) | ❌ | ❌ | | ||
| | PKCS1v15 Signature (Unhashed) | ✔️ | ✔️ | | ||
| | PKCS1v15 Signature (RIPMED160) | ❌ | ✔️<sup>2</sup> | | ||
| | PKCS1v15 Signature (MD4) | ❌ | ✔️<sup>2</sup> | | ||
| | PKCS1v15 Signature (MD5) | ✔️ | ✔️ | | ||
| | PKCS1v15 Signature (MD5-SHA1) | ✔️<sup>2</sup> | ✔️<sup>2</sup> | | ||
| | PKCS1v15 Signature (SHA-1) | ✔️ | ✔️ | | ||
| | PKCS1v15 Signature (SHA-2)<sup>1</sup> | ✔️ | ✔️ | | ||
| | PKCS1v15 Signature (SHA-3) | ❌ | ❌ | | ||
|
|
||
| <sup>1</sup>Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms). | ||
|
|
||
| <sup>2</sup>Available starting in Microsoft Go 1.24. | ||
|
|
||
| #### RSA key sizes | ||
|
|
||
| [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. | ||
|
|
||
| #### PSS salt length | ||
|
|
||
| On Windows, when verifying a PSS signature, [rsa.PSSSaltLengthAuto](https://pkg.go.dev/crypto/rsa#pkg-constants) is not supported. | ||
|
|
||
| #### Random number generation | ||
|
|
||
| Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). | ||
|
|
||
| ### ECDSA | ||
|
|
||
| This section includes the following packages: | ||
|
|
||
| * [crypto/ecdsa](https://pkg.go.dev/crypto/ecdsa) | ||
| * [crypto/elliptic](https://pkg.go.dev/crypto/elliptic) | ||
|
|
||
| | Elliptic Curve | Windows | Linux | | ||
| |---------------------------|-------------|--------------| | ||
| | NIST P-224 (secp224r1) | ✔️ | ✔️ | | ||
| | NIST P-256 (secp256r1) | ✔️ | ✔️ | | ||
| | NIST P-384 (secp384r1) | ✔️ | ✔️ | | ||
| | NIST P-521 (secp521r1) | ✔️ | ✔️ | | ||
|
|
||
| #### Random number generation | ||
|
|
||
| Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). | ||
|
|
||
| ### ECDH | ||
|
|
||
| This section includes the following packages: | ||
|
|
||
| * [crypto/ecdh](https://pkg.go.dev/crypto/ecdsa) | ||
|
|
||
| | Elliptic Curve | Windows | Linux | | ||
| |---------------------------|-------------|--------------| | ||
| | NIST P-224 (secp224r1) | ✔️ | ✔️ | | ||
| | NIST P-256 (secp256r1) | ✔️ | ✔️ | | ||
| | NIST P-384 (secp384r1) | ✔️ | ✔️ | | ||
| | NIST P-521 (secp521r1) | ✔️ | ✔️ | | ||
| | X25519 (curve25519) | ❌ | ❌ | | ||
|
|
||
| #### Random number generation | ||
|
|
||
| Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). | ||
|
|
||
| ### Ed25519 | ||
|
|
||
| This section includes the following packages: | ||
|
|
||
| * [crypto/ed25519](https://pkg.go.dev/crypto/ed25519) | ||
|
|
||
| | Schemes | Windows | Linux | | ||
| |-------------|------------|---------------| | ||
| | Ed25519 | ❌ | ✔️ | | ||
| | Ed25519ctx | ❌ | ❌ | | ||
| | Ed25519ph | ❌ | ❌ | | ||
|
|
||
| #### Random number generation | ||
|
|
||
| Operations that require random numbers (rand io.Reader) only support [rand.Reader](https://pkg.go.dev/crypto/rand#Reader). | ||
|
|
||
| ### DSA | ||
|
|
||
| | Parameters | Windows | Linux | | ||
| |---------------|-------------|--------------| | ||
| | L1024N160 | ✔️ | ✔️ | | ||
| | L2048N224 | ❌ | ✔️ | | ||
| | L2048N256 | ✔️ | ✔️ | | ||
| | L3072N256 | ✔️ | ✔️ | | ||
|
|
||
| ## KDF | ||
|
|
||
| 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 | | ||
| |---------------|------------------|-------------------| | ||
| | PBKDF2 | ✔️ <sup>1</sup> | ✔️ <sup>1</sup> | | ||
| | HKDF | ✔️ <sup>1</sup> | ✔️ <sup>1</sup> | | ||
|
|
||
| <sup>1</sup>Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms). | ||
|
|
||
| ## ML-KEM | ||
|
|
||
| This section includes the following packages: | ||
|
|
||
| * [crypto/mlkem](https://pkg.go.dev/crypto/mlkem) | ||
|
|
||
| | Parameters | Windows | Linux | | ||
| |---------------|-------------|--------------| | ||
| | 768 | ❌ | ❌ | | ||
| | 1024 | ❌ | ❌ | | ||
|
|
||
| ## TLS | ||
|
|
||
| This section includes the following subsections: | ||
|
|
||
| * [TLS Versions](#tls-versions) | ||
| * [Cipher Suites](#cipher-suites) | ||
| * [Curves and Groups](#curves-and-groups) | ||
| * [Signature Algorithms](#signature-algorithms) | ||
|
|
||
| This section includes the following packages: | ||
|
|
||
| * [crypto/tls](https://pkg.go.dev/crypto/tls) | ||
|
|
||
| ### TLS Versions | ||
|
|
||
| | Version | Windows | Linux | | ||
| |----------------|-------------|---------| | ||
| | SSL 3.0 | ❌ | ❌ | | ||
| | TLS 1.0 | ✔️ | ✔️ | | ||
| | TLS 1.2 | ✔️ | ✔️ | | ||
| | TLS 1.3 | ✔️ | ✔️ | | ||
|
|
||
| ### Cipher Suites | ||
|
|
||
| | Name | Windows | Linux | | ||
| |---------------------------------------------------|-------------|-------------------| | ||
| | TLS_RSA_WITH_RC4_128_SHA | ✔️ | ⚠️<sup>1</sup> | | ||
| | TLS_RSA_WITH_3DES_EDE_CBC_SHA | ✔️ | ⚠️<sup>1</sup> | | ||
| | 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 | ✔️ | ⚠️<sup>1</sup> | | ||
| | TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA | ✔️ | ✔️ | | ||
| | TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA | ✔️ | ✔️ | | ||
| | TLS_ECDHE_RSA_WITH_RC4_128_SHA | ✔️ | ⚠️<sup>1</sup> | | ||
| | TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA | ✔️ | ⚠️<sup>1</sup> | | ||
| | 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 | ❌ | ❌ | | ||
|
|
||
| <sup>1</sup>When using OpenSSL 3, requires the legacy provider to be enabled. | ||
|
|
||
| ### Curves and Groups | ||
|
|
||
| | Name | Windows | Linux | | ||
| |-----------------|-------------|--------------| | ||
| | CurveP256 | ✔️ | ✔️ | | ||
| | CurveP384 | ✔️ | ✔️ | | ||
| | CurveP521 | ✔️ | ✔️ | | ||
| | X25519 | ❌ | ❌ | | ||
| | X25519MLKEM768 | ❌ | ❌ | | ||
|
|
||
| ### Signature Algorithms | ||
|
|
||
| | Name | Windows | Linux | | ||
| |---------------------------|-------------|--------------| | ||
| | PKCS1WithSHA256 | ✔️ | ✔️ | | ||
| | PKCS1WithSHA384 | ✔️ | ✔️ | | ||
| | PKCS1WithSHA512 | ✔️ | ✔️ | | ||
| | PSSWithSHA256 | ✔️ | ✔️ | | ||
| | PSSWithSHA384 | ✔️ | ✔️ | | ||
| | PSSWithSHA512 | ✔️ | ✔️ | | ||
| | ECDSAWithP256AndSHA256 | ✔️ | ✔️ | | ||
| | ECDSAWithP384AndSHA384 | ✔️ | ✔️ | | ||
| | ECDSAWithP521AndSHA512 | ✔️ | ✔️ | | ||
| | Ed25519 | ❌ | ✔️ | | ||
| | PKCS1WithSHA1 | ✔️ | ✔️ | | ||
| | ECDSAWithSHA1 | ✔️ | ✔️ | | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.