dotnet · gewarren · Apr 23, 2020 · Apr 23, 2020 · Apr 23, 2020 · Apr 23, 2020
diff --git 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
@@ -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
@@ -1,14 +1,15 @@
 ---
 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
 
 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
@@ -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 <xref:System.Security.Cryptography.X509Certificates.X509Chain?displayProperty=fullName> 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, <xref:System.Security.Cryptography.X509Certificates.X509Chain> may have reported that the chain trust was explicitly disallowed (<xref:System.Security.Cryptography.X509Certificates.X509ChainStatusFlags.ExplicitDistrust?displayProperty=nameWithType>). 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 <xref:System.Security.Cryptography.X509Certificates.X509Chain> reports that the root is not trusted (<xref:System.Security.Cryptography.X509Certificates.X509ChainStatusFlags.UntrustedRoot?displayProperty=nameWithType>).
+
+#### 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
+
+- <xref:System.Security.Cryptography.X509Certificates.X509Chain?displayProperty=fullName>
+
+<!--
+
+### Affected APIs
+
+- `T:System.Security.Cryptography.X509Certificates.X509Chain`
+
+-->