HpkeSender Class

Definition

Namespace

Bodu.Security.Cryptography

Assembly

Bodu.Security.Cryptography.dll

Package

Bodu.Security.Cryptography 1.2.0

Source

HpkeSender.cs

Represents the sender side of an HPKE exchange (RFC 9180 §5.2): a session that encapsulates a shared secret to a recipient once and then seals any number of messages and exports any number of secrets under that secret. This class cannot be inherited.

public sealed class HpkeSender : IDisposable

Inheritance

object

HpkeSender

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, which return the sender and yield the encapsulated key that the recipient needs to reconstruct the matching context. Each Seal(ReadOnlySpan<byte>, ReadOnlySpan<byte>) call advances the message sequence number, so the recipient's Open(ReadOnlySpan<byte>, ReadOnlySpan<byte>) calls must occur in the same order. Dispose the instance to zero the derived key material.

For one-off encryption 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.

Seal(ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Encrypts and authenticates plaintext with the next message nonce.

public byte[] Seal(ReadOnlySpan<byte> associatedData, ReadOnlySpan<byte> plaintext)

Parameters

associatedData ReadOnlySpan<byte>

The associated data authenticated but not encrypted.

plaintext ReadOnlySpan<byte>

The data to encrypt.

Returns

byte[]

The ciphertext followed by the authentication tag.

Exceptions

ObjectDisposedException

The instance has been disposed.

NotSupportedException

The suite is export-only.

InvalidOperationException

The message sequence number has reached its maximum.

SetupAuth(HpkeSuite, ReadOnlySpan<byte>, ReadOnlySpan<byte>, X25519, out byte[])

Sets up an auth-mode sender that authenticates itself with a static key (RFC 9180 §5.1.3 SetupAuthS).

public static HpkeSender SetupAuth(HpkeSuite suite, ReadOnlySpan<byte> recipientPublicKey, ReadOnlySpan<byte> info, X25519 senderKey, out byte[] encapsulation)

Parameters

suite HpkeSuite

The cipher suite.

recipientPublicKey ReadOnlySpan<byte>

The recipient's 32-byte X25519 public key.

info ReadOnlySpan<byte>

The application-supplied context binding the exchange.

senderKey X25519

The sender's X25519 key holding the static private key.

encapsulation byte[]

Receives the encapsulated key to transmit to the recipient.

Returns

HpkeSender

A sender context ready to seal messages.

Exceptions

ArgumentNullException

suite or senderKey is null.

ArgumentException

recipientPublicKey is not exactly 32 bytes.

CryptographicException

senderKey has no private key, or recipientPublicKey is a low-order point.

SetupAuthPsk(HpkeSuite, ReadOnlySpan<byte>, ReadOnlySpan<byte>, X25519, ReadOnlySpan<byte>, ReadOnlySpan<byte>, out byte[])

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

public static HpkeSender SetupAuthPsk(HpkeSuite suite, ReadOnlySpan<byte> recipientPublicKey, ReadOnlySpan<byte> info, X25519 senderKey, ReadOnlySpan<byte> psk, ReadOnlySpan<byte> pskId, out byte[] encapsulation)

Parameters

suite HpkeSuite

The cipher suite.

recipientPublicKey ReadOnlySpan<byte>

The recipient's 32-byte X25519 public key.

info ReadOnlySpan<byte>

The application-supplied context binding the exchange.

senderKey X25519

The sender's X25519 key holding the static private key.

psk ReadOnlySpan<byte>

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

pskId ReadOnlySpan<byte>

The identifier of the pre-shared key.

encapsulation byte[]

Receives the encapsulated key to transmit to the recipient.

Returns

HpkeSender

A sender context ready to seal messages.

Exceptions

ArgumentNullException

suite or senderKey is null.

ArgumentException

recipientPublicKey is not exactly 32 bytes.

CryptographicException

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

SetupBase(HpkeSuite, ReadOnlySpan<byte>, ReadOnlySpan<byte>, out byte[])

Sets up a base-mode sender for the given recipient (RFC 9180 §5.1.1 SetupBaseS).

public static HpkeSender SetupBase(HpkeSuite suite, ReadOnlySpan<byte> recipientPublicKey, ReadOnlySpan<byte> info, out byte[] encapsulation)

Parameters

suite HpkeSuite

The cipher suite.

recipientPublicKey ReadOnlySpan<byte>

The recipient's 32-byte X25519 public key.

info ReadOnlySpan<byte>

The application-supplied context binding the exchange.

encapsulation byte[]

Receives the encapsulated key to transmit to the recipient.

Returns

HpkeSender

A sender context ready to seal messages.

Exceptions

ArgumentNullException

suite is null.

ArgumentException

recipientPublicKey is not exactly 32 bytes.

CryptographicException

recipientPublicKey is a low-order point.

SetupPsk(HpkeSuite, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>, out byte[])

Sets up a PSK-mode sender for the given recipient (RFC 9180 §5.1.2 SetupPSKS).

public static HpkeSender SetupPsk(HpkeSuite suite, ReadOnlySpan<byte> recipientPublicKey, ReadOnlySpan<byte> info, ReadOnlySpan<byte> psk, ReadOnlySpan<byte> pskId, out byte[] encapsulation)

Parameters

suite HpkeSuite

The cipher suite.

recipientPublicKey ReadOnlySpan<byte>

The recipient's 32-byte X25519 public key.

info ReadOnlySpan<byte>

The application-supplied context binding the exchange.

psk ReadOnlySpan<byte>

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

pskId ReadOnlySpan<byte>

The identifier of the pre-shared key.

encapsulation byte[]

Receives the encapsulated key to transmit to the recipient.

Returns

HpkeSender

A sender context ready to seal messages.

Exceptions

ArgumentNullException

suite is null.

ArgumentException

recipientPublicKey is not exactly 32 bytes.

CryptographicException

The PSK inputs are inconsistent, or recipientPublicKey is a low-order point.

Applies to

Product	Versions
.NET	8, 10