Skip to content
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.

Sign up for GitHub

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

Add Cross-Platform Cryptography document #1471

Open
wants to merge 18 commits into
base: microsoft/main
Choose a base branch
from
+341 −0
Open

Add Cross-Platform Cryptography document #1471

Show file tree
Hide file tree
Changes from 14 commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
b92dd20
first pass
qmuntal Jan 8, 2025
cd24039
add platform info
qmuntal Jan 9, 2025
1e82e05
update symmetric encryption table
qmuntal Jan 9, 2025
979900e
add RSA
qmuntal Jan 9, 2025
7b56e5e
add missing algos
qmuntal Jan 9, 2025
35bb486
add doc link
qmuntal Jan 9, 2025
a1f907d
add tls and ed25519
qmuntal Jan 9, 2025
ee1fdf6
remove TLS 1.3 warning
qmuntal Jan 10, 2025
95d7029
add sep lines
qmuntal Jan 10, 2025
3f36c68
cross Ed25519 on Windows
qmuntal Jan 10, 2025
2a58d04
fix typo
qmuntal Jan 10, 2025
080aaab
fix table format
qmuntal Jan 10, 2025
5d9507a
formating
qmuntal Jan 10, 2025
bbe10b1
Apply suggestions from code review
qmuntal Jan 10, 2025
dd0ed6e
Apply suggestions from code review
qmuntal Jan 14, 2025
dc251a6
remove advantage bullets
qmuntal Jan 14, 2025
a46f62a
add legend
qmuntal Jan 14, 2025
b9ae603
Apply suggestions from code review
qmuntal Jan 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
336 changes: 336 additions & 0 deletions eng/doc/CrossPlatformCryptography.md
View file
Open in desktop
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 delegated to the operating system (OS) libraries. This dependency has advantages:
qmuntal marked this conversation as resolved.
Show resolved Hide resolved

* 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.
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.
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.
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.
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/), OpenSSL from now on, for cryptographic operations.
qmuntal marked this conversation as resolved.
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.
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.
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>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.
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> | ✔️ | ✔️ |
| 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>The supported hash algorithms are the same as the ones supported as standalone hash functions.
qmuntal marked this conversation as resolved.
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it worth being more exact? Are there more potential situations than this one example?

Suggested change
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...

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


#### 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

For those operations that require random numbers, only the [rand.Reader](https://pkg.go.dev/crypto/rand#Reader) is supported.
qmuntal marked this conversation as resolved.
Show resolved Hide resolved

### 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

For those operations that require random numbers, only the [rand.Reader](https://pkg.go.dev/crypto/rand#Reader) is supported.
qmuntal marked this conversation as resolved.
Show resolved Hide resolved

### 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

For those operations that require random numbers, only the [rand.Reader](https://pkg.go.dev/crypto/rand#Reader) is supported.
qmuntal marked this conversation as resolved.
Show resolved Hide resolved

### Ed25519

This section includes the following packages:

* [crypto/ed25519](https://pkg.go.dev/crypto/ed25519)

| Schemes | Windows | Linux |
|-------------|------------|---------------|
| Ed25519 | ❌ | ✔️ |
| Ed25519ctx | ❌ | ❌ |
| Ed25519ph | ❌ | ❌ |

#### Random number generation

For those operations that require random numbers, only the [rand.Reader](https://pkg.go.dev/crypto/rand#Reader) is supported.
qmuntal marked this conversation as resolved.
Show resolved Hide resolved

### 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>The supported hash algorithms are the same as the ones supported as standalone hash functions.
qmuntal marked this conversation as resolved.
Show resolved Hide resolved

## ML-KEM

This section includes the following packages:

* [crypto/mlkem](https://pkg.go.dev/crypto/mlkem)

| Parameters | Windows | Linux |
|---------------|-------------|--------------|
|768 | ❌ | ❌ |
|1024 | ❌ | ❌ |
qmuntal marked this conversation as resolved.
Show resolved Hide resolved

## 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 | ✔️ | ✔️ |
1 change: 1 addition & 0 deletions eng/doc/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ This directory, `/eng/doc`, contains documents describing the Microsoft
infrastructure used to build Go, in particular any designs that are not obvious
by reading the infrastructure code itself.

For cryptography information, see the [CrossPlatformCryptography.md](CrossPlatformCryptography.md) doc.
For dev scenario documentation, see the [DeveloperGuide.md](DeveloperGuide.md) doc.

The [Downloads.md](Downloads.md) doc contains a table of links to the latest assets for each supported Go release branch.
Expand Down
Loading