dotnet / dotnet/runtime

[API Proposal]: Hpke improvements

Open
#133,320 2 comments 0 reactions 1 assignee Claimed by @vcsjones View on GitHub
api-approved area-System.Security
Dominant language
C#
Stars
18.3k
Forks
5.6k
PR merge metrics
PR metrics pending

Description

### Background and motivation

There are two things that are missing from the [HPKE](https://github.com/dotnet/runtime/issues/129308) proposal. This is a proposal to close two gaps.

1. We missed P-521 for DH-KEM.

2. We don't have an API matching `DeriveKeyPair(ikm)`, we only have `GenerateKeyPair()` (exposed as `GenerateKey`). The former allows you to specify the input keying material used for HPKE. This allows for deterministic HPKE key generation. This has two uses: First it's required by some specifications like MLS. From [RFC 9420](https://www.rfc-editor.org/rfc/rfc9420.txt)

> Section 7.4: `node_priv[n], node_pub[n] = KEM.DeriveKeyPair(node_secret[n])`
> The node secret is derived as a temporary intermediate secret so that each secret is only used with one algorithm: The path secret is used as an input to DeriveSecret, and the node secret is used as an input to DeriveKeyPair.

The lack of DeriveKeyPair makes it impossible to implement MLS with the current HPKE shape.

The second purpose is testing - much of HPKE's test suite relies on deterministic input keying material.

### API Proposal

```diff
namespace System.Security.Cryptography;

public partial enum HpkeKem
{
DHKEM_P384_HKDF_SHA384 = 17,
+ DHKEM_P521_HKDF_SHA512 = 18,
}

public partial class Hpke
{
public static Hpke GenerateKey(HpkeSuite suite);
+ public static Hpke DeriveKey(HpkeSuite suite, byte[] ikm); // or inputKeyingMaterial
+ public static Hpke DeriveKey(HpkeSuite suite, ReadOnlySpan ikm); // or inputKeyingMaterial
}
```

### API Usage

```C#
HpkeSuite suite = new(
HpkeKem.DHKEM_P521_HKDF_SHA512,
HpkeKdf.HKDF_SHA512,
HpkeAead.AES_256_GCM);

byte[] ikm = RandomNumberGenerator.GetBytes(suite.DecapsulationKeySizeInBytes);
using Hpke hpke = Hpke.DeriveKey(ikm);
```

### Alternative Designs

_No response_

### Risks

_No response_

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.