HpkeReceiver Class

Definition

Namespace

Bodu.Security.Cryptography

Assembly

Bodu.Security.Cryptography.dll

Package

Bodu.Security.Cryptography 1.2.0

Source

HpkeReceiver.cs

Represents the recipient side of an HPKE exchange (RFC 9180 §5.2): a session that reconstructs the shared secret from an encapsulated key and then opens any number of sealed messages and exports any number of secrets under that secret. This class cannot be inherited.

public sealed class HpkeReceiver : IDisposable

Inheritance

object

HpkeReceiver

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Remarks

Obtain an instance from one of the Setup* factory methods, supplying the recipient's private key and the encapsulated key produced by the matching HpkeSender setup. Each Open(ReadOnlySpan<byte>, ReadOnlySpan<byte>) call advances the message sequence number, so messages must be opened in the order they were sealed. Dispose the instance to zero the derived key material.

For one-off decryption of a single message, prefer the single-shot Hpke façade.

Like the rest of the library, this implementation offers best-effort side-channel resistance and has not been independently audited.

Methods

Dispose()

Releases the resources used by this instance, zeroing the derived key material.

public void Dispose()

Export(ReadOnlySpan<byte>, int)

Derives length bytes of secret keying material bound to exporterContext.

public byte[] Export(ReadOnlySpan<byte> exporterContext, int length)

Parameters

exporterContext ReadOnlySpan<byte>

The application-supplied context that scopes the exported secret.

length int

The number of bytes to export.

Returns

byte[]

The exported secret.

Exceptions

ObjectDisposedException

The instance has been disposed.

ArgumentOutOfRangeException

length is negative or exceeds 255 times the KDF hash length.

Open(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Verifies and decrypts the next sealed message.

public byte[] Open(ReadOnlySpan<byte> associatedData, ReadOnlySpan<byte> ciphertext)

Parameters

associatedData ReadOnlySpan<byte>

The associated data that must match what the sender supplied.

ciphertext ReadOnlySpan<byte>

The ciphertext followed by the authentication tag.

Returns

byte[]

The recovered plaintext.

Exceptions

ObjectDisposedException

The instance has been disposed.

NotSupportedException

The suite is export-only.

ArgumentException

ciphertext is shorter than the authentication tag.

CryptographicException

Authentication failed.

InvalidOperationException

The message sequence number has reached its maximum.

SetupAuth(HpkeSuite, X25519, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Sets up an auth-mode receiver that verifies the sender's static-key authentication (RFC 9180 §5.1.3 SetupAuthR).

public static HpkeReceiver SetupAuth(HpkeSuite suite, X25519 recipientKey, ReadOnlySpan<byte> encapsulation, ReadOnlySpan<byte> info, ReadOnlySpan<byte> senderPublicKey)

Parameters

suite HpkeSuite

The cipher suite.

recipientKey X25519

The recipient's X25519 key holding the private key.

encapsulation ReadOnlySpan<byte>

The encapsulated key received from the sender.

info ReadOnlySpan<byte>

The application-supplied context binding the exchange; must match the sender's.

senderPublicKey ReadOnlySpan<byte>

The sender's 32-byte X25519 public key, used to verify authentication.

Returns

HpkeReceiver

A receiver context ready to open messages.

Exceptions

ArgumentNullException

suite or recipientKey is null.

ArgumentException

encapsulation or senderPublicKey is not exactly 32 bytes.

CryptographicException

recipientKey has no private key, or an input is a low-order point.

SetupAuthPsk(HpkeSuite, X25519, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Sets up an auth-PSK-mode receiver combining sender authentication with a pre-shared key (RFC 9180 §5.1.4 SetupAuthPSKR).

public static HpkeReceiver SetupAuthPsk(HpkeSuite suite, X25519 recipientKey, ReadOnlySpan<byte> encapsulation, ReadOnlySpan<byte> info, ReadOnlySpan<byte> senderPublicKey, ReadOnlySpan<byte> psk, ReadOnlySpan<byte> pskId)

Parameters

suite HpkeSuite

The cipher suite.

recipientKey X25519

The recipient's X25519 key holding the private key.

encapsulation ReadOnlySpan<byte>

The encapsulated key received from the sender.

info ReadOnlySpan<byte>

The application-supplied context binding the exchange; must match the sender's.

senderPublicKey ReadOnlySpan<byte>

The sender's 32-byte X25519 public key, used to verify authentication.

psk ReadOnlySpan<byte>

The pre-shared key, shared out of band with the sender.

pskId ReadOnlySpan<byte>

The identifier of the pre-shared key.

Returns

HpkeReceiver

A receiver context ready to open messages.

Exceptions

ArgumentNullException

suite or recipientKey is null.

ArgumentException

encapsulation or senderPublicKey is not exactly 32 bytes.

CryptographicException

The PSK inputs are inconsistent, recipientKey has no private key, or an input is a low-order point.

SetupBase(HpkeSuite, X25519, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Sets up a base-mode receiver (RFC 9180 §5.1.1 SetupBaseR).

public static HpkeReceiver SetupBase(HpkeSuite suite, X25519 recipientKey, ReadOnlySpan<byte> encapsulation, ReadOnlySpan<byte> info)

Parameters

suite HpkeSuite

The cipher suite.

recipientKey X25519

The recipient's X25519 key holding the private key.

encapsulation ReadOnlySpan<byte>

The encapsulated key received from the sender.

info ReadOnlySpan<byte>

The application-supplied context binding the exchange; must match the sender's.

Returns

HpkeReceiver

A receiver context ready to open messages.

Exceptions

ArgumentNullException

suite or recipientKey is null.

ArgumentException

encapsulation is not exactly 32 bytes.

CryptographicException

recipientKey has no private key, or encapsulation is a low-order point.

SetupPsk(HpkeSuite, X25519, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Sets up a PSK-mode receiver (RFC 9180 §5.1.2 SetupPSKR).

public static HpkeReceiver SetupPsk(HpkeSuite suite, X25519 recipientKey, ReadOnlySpan<byte> encapsulation, ReadOnlySpan<byte> info, ReadOnlySpan<byte> psk, ReadOnlySpan<byte> pskId)

Parameters

suite HpkeSuite

The cipher suite.

recipientKey X25519

The recipient's X25519 key holding the private key.

encapsulation ReadOnlySpan<byte>

The encapsulated key received from the sender.

info ReadOnlySpan<byte>

The application-supplied context binding the exchange; must match the sender's.

psk ReadOnlySpan<byte>

The pre-shared key, shared out of band with the sender.

pskId ReadOnlySpan<byte>

The identifier of the pre-shared key.

Returns

HpkeReceiver

A receiver context ready to open messages.

Exceptions

ArgumentNullException

suite or recipientKey is null.

ArgumentException

encapsulation is not exactly 32 bytes.

CryptographicException

The PSK inputs are inconsistent, recipientKey has no private key, or encapsulation is a low-order point.

Applies to

Product	Versions
.NET	8, 10