Support certificate lookup by thumbprint in 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
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