dotnet / dotnet/dotnet-api-docs

X509ChainPolicy behavior with Custom Certificate Authorities Not Well Documented

Open
#7,084 2 comments 0 reactions 0 assignees View on GitHub
area-System.Security Pri3 untriaged
Dominant language
C#
Stars
949
Forks
1.7k
Avg merge
3d 27m
Merged PRs (30d)
49

Description

It's unclear from the documentation how verify if a certificate from a custom CA.

In .NET 5, a user can:
- Add the custom CA to `ChainPolicy.CustomTrustStore`
- Set `ChainPolicy.TrustMode` to `CustomTrustRoot`
- Verify the certificate as normal using `X509Chain.Build`

However, prior versions did not have a `CustomTrustStore`. While a user could still add CAs to `ChainPolicy.ExtraStore`, the `X509Chain.Build` method would still return false unless the user set `X509VerificationFlags.AllowUnknownCertificateAuthority` (which has the effect of completely ignoring the CA entirely).

To verify, it seems like (from StackOverflow and other posts), you need to:
- Add the custom CA to the Extra Store
- Run `chain.Build(cert_to_verify)` - this will return false (or alternatively set `AllowUnknownCertificateAuthority` to force it to true)
- Manually confirm the last element of the chain is identical to the CA by reviewing the last element in the chain.

However, this process isn't documented for either .NET 5 or prior versions.

It would be great if the documentation could be updated to provide more details on these types of validation, and how it differs in .NET 5 vs earlier versions.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.