[API Proposal]: Support Passing Full Certificate Chain with HttpClientHandler.ClientCertificates

[tyb-dev]

Background and motivation

Background

Currently, it's not possible to explicitly pass a client certificate with its full chain to HttpClientHandler, even though mTLS clients are expected to send the full chain.

The full chain will be sent with .NET today, however it relies on the following external sources to retrieve the CA certificates:

1. CA certificates are downloaded from the internet through the AIA endpoint.
2. CA certificates are read from the respective X509Store (StoreName.CertificateAuthority).

While this approach works in many cases, it can lead to challenges in specific scenarios:

• Restricted Connectivity: Systems without direct internet access cannot rely on the automatic chain download.
• AIA Endpoint Dependency: Users may not want to depend on the availability or reliability of the AIA endpoint.
• Control Over Intermediates: Storing certificates in the X509Store limits user control. In cases with multiple possible chains (e.g., cross-signing scenarios), the system might select an unintended chain.

Request

We propose adding an API to explicitly pass the full certificate chain alongside the client certificate in HttpClientHandler.ClientCertificates. This would eliminate the need for automatic downloads or storing certificates in the X509Store beforehand. Users would retain full control over the certificate chain and ensure it aligns with their specific requirements.

Current Limitations

The HttpClientHandler.ClientCertificates API does not currently allow the explicit inclusion of the full certificate chain. As noted in the discussion quoted below, this would require introducing a new API to support this functionality:

Triage: Question seems to be answered.

We still might want to file a new issue to capture the ask to use cert chain without putting it in store -- new API would be required. (@wfurt to file a mega-issue linking the issues)

Originally posted by @karelz in #47680

Benefits of the Proposed API

1. Avoids reliance on AIA endpoints or internet connectivity.
2. Gives users complete control over the certificate chain, ensuring predictable behavior in complex scenarios.
3. Improves support for mTLS use cases where the full chain is mandatory.
4. Avoids usage errors of HttpClientHandler.ClientCertificates where one might expect that a chain can be supplied.
5. It is common practice to be able to supply the chain explicitly, when the certificate is provided explicitly.

API Proposal

    public class HttpClientHandler : HttpMessageHandler
    {
        public X509Certificate2Collection ClientCertificatesExtraStore { get; }
    }

API Usage

    var handler = new HttpClientHandler();

    var extraStore = new X509Certificate2Collection();
    extraStore.Add(new X509Certificate2("path/to/intermediate-cert.pem"));
    handler.ClientCertificatesExtraStore = extraStore;

    handler.ClientCertificates.Add(new X509Certificate2("path/to/client-cert.pem"));

Alternative Designs

It might make sense to introduce a way to influence whether the system store should be consulted or not, either via an extension to the ClientCertificateOptions enum or a dedicated property.

Risks

No response

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/ncl, @bartonjs, @vcsjones
See info in area-owners.md if you want to be subscribed.