Add Cross-Platform Cryptography document
#1471
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,336 @@ | ||||||||||
| # Cross-Platform Cryptography in Microsoft Go | ||||||||||
|
|
||||||||||
| Cryptographic operations in Microsoft Go are done by operating system (OS) libraries. This dependency has advantages: | ||||||||||
|
|
||||||||||
| * Go apps benefit from OS reliability. Keeping cryptography libraries safe from vulnerabilities is a high priority for OS vendors. To do that, they provide updates that system administrators should be applying. | ||||||||||
qmuntal marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||||||
| * Go apps have access to FIPS-validated algorithms if the OS libraries are FIPS-validated. | ||||||||||
|
|
||||||||||
| > [!NOTE] | ||||||||||
| > Starting with Go 1.24, Go will also be FIPS 140-3 compliant, see https://github.com/golang/go/issues/69536. | ||||||||||
| > If the only reason you are using Microsoft Go is for FIPS 140-3 compliance, you should consider using Microsoft Go 1.24 or later. | ||||||||||
qmuntal marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||||||
|
|
||||||||||
| Go apps will fall back to native Go implementations if the OS libraries doesn't support the algorithm. | ||||||||||
qmuntal marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||||||
| 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 [Cryptography API: Next Generation](https://learn.microsoft.com/en-us/windows/win32/seccng/cng-portal) library, CNG from now on, for cryptographic operations. | ||||||||||
qmuntal marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||||||
| 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/) library, OpenSSL from now on, for cryptographic operations. | ||||||||||
qmuntal marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||||||
| 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 the [SymCrypt provider](https://github.com/microsoft/SymCrypt-OpenSSL), SCOSSL from now on. | ||||||||||
qmuntal marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||||||
| The minimum SCOSSL version required is v1.6.1. | ||||||||||
| The following tables assume that the SCOSSL provider is used together with the built-in providers. | ||||||||||
qmuntal marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||||||
|
|
||||||||||
| ## 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>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>The supported hash algorithms are the same as the ones supported as standalone hash functions. | ||||||||||
qmuntal marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||||||
|
|
||||||||||
| ## 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. | ||||||||||
qmuntal marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
|
|
||||||||||
| ### 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> | ✔️ <sup>1</sup> | | ||||||||||
| | OAEP (SHA-3) | ❌ | ❌ | | ||||||||||
| | PSS (MD5) | ✔️ | ✔️ | | ||||||||||
| | PSS (SHA-1) | ✔️ | ✔️ | | ||||||||||
| | PSS (SHA-2) | ✔️ <sup>1</sup> | ✔️ <sup>1</sup> | | ||||||||||
| | PSS (SHA-3) | ❌ | ❌ | | ||||||||||
| | PKCS1v15 Signature (Unhashed) | ✔️ | ✔️ | | ||||||||||
| | PKCS1v15 Signature (RIPMED160) | ❌ <sup>2</sup> | ✔️ <sup>2</sup> | | ||||||||||
| | PKCS1v15 Signature (MD4) | ❌ <sup>2</sup> | ✔️ <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> | ✔️ <sup>1</sup> | | ||||||||||
| | PKCS1v15 Signature (SHA-3) | ❌ | ❌ | | ||||||||||
|
|
||||||||||
| <sup>1</sup>The supported hash algorithms are the same as the ones supported as standalone hash functions. | ||||||||||
qmuntal marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||||||
|
|
||||||||||
| <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 Windows and when using SCOSSL, the key size should be multiple of 8. | ||||||||||
|
||||||||||
| The RSA key size is subject to the limitations of the underlying cryptographic library. For example, on Windows and when using SCOSSL, the key size should be multiple of 8. | |
| The RSA key size is subject to the limitations of the underlying cryptographic library: | |
| * On Windows or when using SCOSSL, the key size must be a multiple of 8 (in bits). |
But now I wonder if this was intended to be saying something about algorithms implemented by SCOSSL vs. by the built-in OpenSSL provider...
Member
Author
There was a problem hiding this comment.
I intentionally didn't want to enumerate a possible limitations, as can vary in time and are normally not part of the public documentation of the crypto libraries.
Member
There was a problem hiding this comment.
Ah, makes sense. I think the doc probably should state that variability pretty clearly, because otherwise it might be a bit confusing why more detail isn't provided. Also, it sounds like the user is meant to get a hint that they should avoid depending on exact details here.
Member
Author
There was a problem hiding this comment.
I've rephrased the paragraph to be less confusing.
qmuntal marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
qmuntal marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
qmuntal marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
qmuntal marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
qmuntal marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
qmuntal marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
qmuntal marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
qmuntal marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
qmuntal marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
qmuntal marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
qmuntal marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
qmuntal marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
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.