diff --git a/docs/core/compatibility/2.2-3.0.md b/docs/core/compatibility/2.2-3.0.md index 6a19b2d941433..07ec61f515d94 100644 --- a/docs/core/compatibility/2.2-3.0.md +++ b/docs/core/compatibility/2.2-3.0.md @@ -335,11 +335,16 @@ If you're migrating from version 2.2 to version 3.0 of .NET Core, ASP.NET Core, ## Cryptography +- [BEGIN TRUSTED CERTIFICATE syntax no longer supported on Linux](#begin-trusted-certificate-syntax-no-longer-supported-for-root-certificates-on-linux) - [EnvelopedCms defaults to AES-256 encryption](#envelopedcms-defaults-to-aes-256-encryption) - [Minimum size for RSAOpenSsl key generation has increased](#minimum-size-for-rsaopenssl-key-generation-has-increased) - [.NET Core 3.0 prefers OpenSSL 1.1.x to OpenSSL 1.0.x](#net-core-30-prefers-openssl-11x-to-openssl-10x) - [Better argument validation in the Pkcs8PrivateKeyInfo constructor](#better-argument-validation-in-the-pkcs8privatekeyinfo-constructor) +[!INCLUDE [begin-trusted-cert-linux](~/includes/core-changes/cryptography/3.0/begin-trusted-cert-linux.md)] + +*** + [!INCLUDE[EnvelopedCms defaults to AES-256 encryption](~/includes/core-changes/cryptography/3.0/envelopedcms-defaults-to-aes256.md)] *** diff --git a/docs/core/compatibility/2.2-3.1.md b/docs/core/compatibility/2.2-3.1.md index edc6d3e19def9..38bef24ac15e0 100644 --- a/docs/core/compatibility/2.2-3.1.md +++ b/docs/core/compatibility/2.2-3.1.md @@ -338,11 +338,16 @@ If you're migrating from version 2.2 to version 3.1 of .NET Core, ASP.NET Core, ## Cryptography +- [BEGIN TRUSTED CERTIFICATE syntax no longer supported on Linux](#begin-trusted-certificate-syntax-no-longer-supported-for-root-certificates-on-linux) - [EnvelopedCms defaults to AES-256 encryption](#envelopedcms-defaults-to-aes-256-encryption) - [Minimum size for RSAOpenSsl key generation has increased](#minimum-size-for-rsaopenssl-key-generation-has-increased) - [.NET Core 3.0 prefers OpenSSL 1.1.x to OpenSSL 1.0.x](#net-core-30-prefers-openssl-11x-to-openssl-10x) - [Better argument validation in the Pkcs8PrivateKeyInfo constructor](#better-argument-validation-in-the-pkcs8privatekeyinfo-constructor) +[!INCLUDE [begin-trusted-cert-linux](~/includes/core-changes/cryptography/3.0/begin-trusted-cert-linux.md)] + +*** + [!INCLUDE[EnvelopedCms defaults to AES-256 encryption](~/includes/core-changes/cryptography/3.0/envelopedcms-defaults-to-aes256.md)] *** diff --git a/docs/core/compatibility/cryptography.md b/docs/core/compatibility/cryptography.md index 104c5e230a6a9..f8f1e03986073 100644 --- a/docs/core/compatibility/cryptography.md +++ b/docs/core/compatibility/cryptography.md @@ -1,7 +1,7 @@ --- title: Cryptography breaking changes description: Lists cryptography-related breaking changes in .NET Core. -ms.date: 02/10/2020 +ms.date: 04/22/2020 --- # Cryptography breaking changes @@ -9,6 +9,7 @@ The following breaking changes are documented on this page: | Breaking change | Version introduced | | - | :-: | +| [BEGIN TRUSTED CERTIFICATE syntax no longer supported on Linux](#begin-trusted-certificate-syntax-no-longer-supported-for-root-certificates-on-linux) | 3.0 | | [EnvelopedCms defaults to AES-256 encryption](#envelopedcms-defaults-to-aes-256-encryption) | 3.0 | | [Minimum size for RSAOpenSsl key generation has increased](#minimum-size-for-rsaopenssl-key-generation-has-increased) | 3.0 | | [.NET Core 3.0 prefers OpenSSL 1.1.x to OpenSSL 1.0.x](#net-core-30-prefers-openssl-11x-to-openssl-10x) | 3.0 | @@ -17,6 +18,10 @@ The following breaking changes are documented on this page: ## .NET Core 3.0 +[!INCLUDE [begin-trusted-cert-linux](~/includes/core-changes/cryptography/3.0/begin-trusted-cert-linux.md)] + +*** + [!INCLUDE[EnvelopedCms defaults to AES-256 encryption](~/includes/core-changes/cryptography/3.0/envelopedcms-defaults-to-aes256.md)] *** diff --git a/includes/core-changes/cryptography/3.0/begin-trusted-cert-linux.md b/includes/core-changes/cryptography/3.0/begin-trusted-cert-linux.md new file mode 100644 index 0000000000000..d3fe3d8338f32 --- /dev/null +++ b/includes/core-changes/cryptography/3.0/begin-trusted-cert-linux.md @@ -0,0 +1,50 @@ +### "BEGIN TRUSTED CERTIFICATE" syntax no longer supported for root certificates on Linux + +Root certificates on Linux and other Unix-like systems (but not macOS) can be presented in two forms: the standard `BEGIN CERTIFICATE` PEM header, and the OpenSSL-specific `BEGIN TRUSTED CERTIFICATE` PEM header. The latter syntax allows for additional configuration that has caused compatibility issues with .NET Core's class. `BEGIN TRUSTED CERTIFICATE` root certificate contents are no longer loaded by the chain engine starting in .NET Core 3.0. + +#### Change description + +Previously, both the `BEGIN CERTIFICATE` and `BEGIN TRUSTED CERTIFICATE` syntaxes were used to populate the root trust list. If the `BEGIN TRUSTED CERTIFICATE` syntax was used and additional options were specified in the file, may have reported that the chain trust was explicitly disallowed (). However, if the certificate was also specified with the `BEGIN CERTIFICATE` syntax in a previously loaded file, the chain trust was allowed. + +Starting in .NET Core 3.0, `BEGIN TRUSTED CERTIFICATE` contents are no longer read. If the certificate is not also specified via a standard `BEGIN CERTIFICATE` syntax, the reports that the root is not trusted (). + +#### Version introduced + +3.0 + +#### Recommended action + +Most applications are unaffected by this change, but applications that cannot see both root certificate sources because of permissions problems may experience unexpected `UntrustedRoot` errors after upgrading. + +Many Linux distributions (or distros) write root certificates into two locations: a one-certificate-per-file directory, and a one-file concatenation. On some distros, the one-certificate-per-file directory uses the `BEGIN TRUSTED CERTIFICATE` syntax while the file concatenation uses the standard `BEGIN CERTIFICATE` syntax. Ensure that any custom root certificates are added as `BEGIN CERTIFICATE` in at least one of these locations, and that both locations can be read by your application. + +The typical directory is */etc/ssl/certs/* and the typical concatenated file is */etc/ssl/cert.pem*. Use the command `openssl version -d` to determine the platform-specific root, which may differ from */etc/ssl/*. For example, on Ubuntu 18.04, the directory is */usr/lib/ssl/certs/* and the file is */usr/lib/ssl/cert.pem*. However, */usr/lib/ssl/certs/* is a symlink to */etc/ssl/certs/* and */usr/lib/ssl/cert.pem* does not exist. + +```bash +$ openssl version -d +OPENSSLDIR: "/usr/lib/ssl" +$ ls -al /usr/lib/ssl +total 12 +drwxr-xr-x 3 root root 4096 Dec 12 17:10 . +drwxr-xr-x 73 root root 4096 Feb 20 15:18 .. +lrwxrwxrwx 1 root root 14 Mar 27 2018 certs -> /etc/ssl/certs +drwxr-xr-x 2 root root 4096 Dec 12 17:10 misc +lrwxrwxrwx 1 root root 20 Nov 12 16:58 openssl.cnf -> /etc/ssl/openssl.cnf +lrwxrwxrwx 1 root root 16 Mar 27 2018 private -> /etc/ssl/private +``` + +### Category + +Cryptography + +### Affected APIs + +- + +