dotnet / dotnet/aspnetcore

Support certificate lookup by thumbprint in Kestrel

Open
#67,920 3 comments 0 reactions 0 assignees View on GitHub
area-networking design-proposal feature-kestrel
Dominant language
C#
Stars
38.4k
Forks
10.9k
Avg merge
2d 10h
Merged PRs (30d)
281

Description

## Summary
Add support for selecting certificate store certificates by thumbprint in Kestrel configuration.

## Motivation and goals
Currently, Kestrel can only load certificates from the certificate store by subject name using `CertificateLoader.LoadFromStoreCert()`. A subject name is not guaranteed to uniquely identify a certificate, and modern certificates frequently rely on Subject Alternative Names (SANs), with the Common Name (CN) sometimes left empty. As a result, Kestrel configuration cannot always select the intended certificate from the certificate store.

Adding the ability to specify a certificate's thumbprint addresses this limitation. The .NET runtime already exposes `X509FindType.FindByThumbprint`, making the implementation of this proposal a relatively small change.

## In scope
- Adding the `Thumbprint` property to `Kestrel.Core.Internal.CertificateConfig`.
- Extending `CertificateLoader.LoadFromStoreCert()` to support thumbprint lookup.

## Out of scope
- Adding support for other lookup criteria such as Subject Alternative Name(s), Subject Distinguished Name, Issuer Distinguished Name or other certificate attributes.
- SAN-based lookup could address some scenarios, but it introduces ambiguity when multiple certificates contain the same SAN entry and would require substantially broader changes. Thumbprint lookup provides deterministic certificate selection while keeping this proposal narrowly scoped.

## Risks / unknowns
- By specifying neither `Subject` nor `Thumbprint`.
- By specifying both `Subject` and `Thumbprint`, which necessitates an order of precedence. Should this behavior be allowed at all?
- By specifying thumbprints containing separators such as whitespace or colons. Should thumbprints be normalized?

## Examples
- In code using the proposed API: `var cert = LoadFromStoreCert(null, "8DDCFD0A1DA98A48B1A8A882CF68C5DC94A02C5A", "My", StoreLocation.LocalMachine, false);`
- In an `appsettings.json` configuration:
```json
{
"Kestrel": {
"Endpoints": {
"Http": {
"Url": "http://localhost:8080"
},
"Https": {
"Url": "https://localhost:8443",
"Certificate": {
"Thumbprint": "8DDCFD0A1DA98A48B1A8A882CF68C5DC94A02C5A",
"Store": "My",
"Location": "LocalMachine"
}
}
}
}
}
```

Contributor guide

Open the contributing guide

Research direction

Start with Kestrel.Core.Internal.CertificateConfig and CertificateLoader.LoadFromStoreCert(), then compare the existing subject-name path with the runtime's X509FindType.FindByThumbprint support. Define and verify the behavior for neither field, both fields, and formatted thumbprints; done means Kestrel configuration accepts Thumbprint and selects the intended store certificate.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
backend, security
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.