[API Proposal]: Inspecting an EVP_PKEY's provider
- Dominant language
- C#
- Stars
- 18.3k
- Forks
- 5.6k
- PR merge metrics
- PR metrics pending
Description
### Background and motivation
Sometimes you may want to inspect an EVP_PKEY's provider to understand some basic information about where it came from. We can expose some basic properties from an EVP_PKEY's handle to get some basic information about the key's provider.
This is a proposal to expose an EVP_PKEY's provider information, namely `OSSL_PROV_PARAM_NAME`, `OSSL_PROV_PARAM_VERSION`, and `OSSL_PROV_PARAM_BUILDINFO`.
OpenSSL exposes these as strings - so that is how we will expose them as well. VERSION and BUILDINFO can contain any valid string, so that is why they should not be represented as `System.Version` or otherwise. It is up to the application developer to interpret this information.
For OpenSSL < 3.0 or keys that are backed by an ENGINE, this will throw a `CryptographicException`. Both OpenSSL 1.1.1 and ENGINEs are largely going away and are strongly discouraged from use, so providing a similar API or experience for ENGINEs doesn't seem worthwhile.
### API Proposal
```csharp
namespace System.Security.Cryptography;
public sealed partial class SafeEvpPKeyHandle
{
// true if the key is backed by a PROVIDER. All values are nullable because they are not strictly required to be set by the provider. they are recommended.
public bool TryGetProviderInformation(
out string? name,
out string? version,
out string? buildInfo);
}
```
### API Usage
```csharp
using ECDsaOpenSsl ecdsa = new();
using SafeEvpPKeyHandle key = ecdsa.DuplicateKeyHandle();
SafeEvpPKeyHandle.GetProviderInformation(out string name, out _, out _);
bool isDefault = name == "OpenSSL Default Provider"; // vs. FIPS, vs. SCOSSL, etc.
```
### Alternative Designs
Considered, but something I reject was returning a tuple:
```csharp
public (string Name, string Version, string BuildInfo) GetProviderInformation();
```
I rejected this because it makes it impossible to overload it in the future, and we can't increase the tuple arity without it being a breaking change.
### Risks
Perhaps prone to misuse. Providers can do what they want here, but it is helpful in debugging and logging scenarios, or unit tests.
Contributor guide
Research direction
Start by reviewing the proposed SafeEvpPKeyHandle.TryGetProviderInformation API and the OpenSSL provider parameters named in the issue: OSSL_PROV_PARAM_NAME, OSSL_PROV_PARAM_VERSION, and OSSL_PROV_PARAM_BUILDINFO. Confirm the behavior for provider-backed keys, OpenSSL versions below 3.0, and ENGINE-backed keys; done means the proposed API and its documented exception behavior are implemented and covered by tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- api, cryptography
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100