dotnet / dotnet/runtime

[API Proposal]: Inspecting an EVP_PKEY's provider

Open
#131,426 4 comments 0 reactions 0 assignees View on GitHub
api-suggestion area-System.Security
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.