Hpke Class

Definition

Namespace

Bodu.Security.Cryptography

Assembly

Bodu.Security.Cryptography.dll

Package

Bodu.Security.Cryptography 1.2.0

Source

Hpke.Auth.cs

Provides the single-shot Hybrid Public Key Encryption (HPKE) operations of RFC 9180 §6, encrypting or decrypting one message to or from a public key in a single call. This class cannot be instantiated.

public static class Hpke

Inheritance

object

Hpke

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

using var recipient = X25519.Create();
recipient.GenerateKey();
HpkeSuite suite = HpkeSuite.X25519_HkdfSha256_Aes128Gcm;

var (enc, ciphertext) = Hpke.Seal(suite, recipient.ExportPublicKey(), info, aad, plaintext);
byte[] recovered = Hpke.Open(suite, recipient, enc, info, aad, ciphertext);

Remarks

Each Seal* method performs a complete HPKE exchange - encapsulate a fresh shared secret to the recipient, run the key schedule, and seal one message - returning both the encapsulated key and the ciphertext. The matching Open* method reverses it. There is one method pair per establishment mode (HpkeMode): base, PSK, auth, and auth-PSK. For sending several messages under one encapsulation, use HpkeSender and HpkeReceiver instead.

Recipient and sender private keys are supplied as X25519 instances so the caller controls their lifetime; public keys are passed as raw 32-byte spans, which is their on-the-wire form.

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

Methods

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

Decrypts a base-mode message produced by Seal(HpkeSuite, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>) (RFC 9180 §6.1 OpenBase).

public static byte[] Open(HpkeSuite suite, X25519 recipientKey, ReadOnlySpan<byte> encapsulation, ReadOnlySpan<byte> info, ReadOnlySpan<byte> associatedData, ReadOnlySpan<byte> ciphertext)

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; must match the value used to seal.

associatedData ReadOnlySpan<byte>

The associated data; must match the value used to seal.

ciphertext ReadOnlySpan<byte>

The ciphertext followed by the authentication tag.

Returns

byte[]

The recovered plaintext.

Exceptions

ArgumentNullException

suite or recipientKey is null.

ArgumentException

encapsulation is not exactly 32 bytes, or ciphertext is shorter than the authentication tag.

NotSupportedException

The suite is export-only.

CryptographicException

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

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

Decrypts an auth-mode message produced by SealAuth(HpkeSuite, ReadOnlySpan<byte>, ReadOnlySpan<byte>, X25519, ReadOnlySpan<byte>, ReadOnlySpan<byte>) and verifies sender authentication (RFC 9180 §6.1 OpenAuth).

public static byte[] OpenAuth(HpkeSuite suite, X25519 recipientKey, ReadOnlySpan<byte> encapsulation, ReadOnlySpan<byte> info, ReadOnlySpan<byte> senderPublicKey, ReadOnlySpan<byte> associatedData, ReadOnlySpan<byte> ciphertext)

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; must match the value used to seal.

senderPublicKey ReadOnlySpan<byte>

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

associatedData ReadOnlySpan<byte>

The associated data; must match the value used to seal.

ciphertext ReadOnlySpan<byte>

The ciphertext followed by the authentication tag.

Returns

byte[]

The recovered plaintext.

Exceptions

ArgumentNullException

suite or recipientKey is null.

ArgumentException

encapsulation or senderPublicKey is not exactly 32 bytes, or ciphertext is shorter than the authentication tag.

NotSupportedException

The suite is export-only.

CryptographicException

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

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

Decrypts an auth-PSK-mode message produced by SealAuthPsk(HpkeSuite, ReadOnlySpan<byte>, ReadOnlySpan<byte>, X25519, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>) and verifies sender authentication (RFC 9180 §6.1 OpenAuthPSK).

public static byte[] OpenAuthPsk(HpkeSuite suite, X25519 recipientKey, ReadOnlySpan<byte> encapsulation, ReadOnlySpan<byte> info, ReadOnlySpan<byte> senderPublicKey, ReadOnlySpan<byte> psk, ReadOnlySpan<byte> pskId, ReadOnlySpan<byte> associatedData, ReadOnlySpan<byte> ciphertext)

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; must match the value used to seal.

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.

associatedData ReadOnlySpan<byte>

The associated data; must match the value used to seal.

ciphertext ReadOnlySpan<byte>

The ciphertext followed by the authentication tag.

Returns

byte[]

The recovered plaintext.

Exceptions

ArgumentNullException

suite or recipientKey is null.

ArgumentException

encapsulation or senderPublicKey is not exactly 32 bytes, or ciphertext is shorter than the authentication tag.

NotSupportedException

The suite is export-only.

CryptographicException

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

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

Decrypts a PSK-mode message produced by SealPsk(HpkeSuite, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>) (RFC 9180 §6.1 OpenPSK).

public static byte[] OpenPsk(HpkeSuite suite, X25519 recipientKey, ReadOnlySpan<byte> encapsulation, ReadOnlySpan<byte> info, ReadOnlySpan<byte> psk, ReadOnlySpan<byte> pskId, ReadOnlySpan<byte> associatedData, ReadOnlySpan<byte> ciphertext)

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; must match the value used to seal.

psk ReadOnlySpan<byte>

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

pskId ReadOnlySpan<byte>

The identifier of the pre-shared key.

associatedData ReadOnlySpan<byte>

The associated data; must match the value used to seal.

ciphertext ReadOnlySpan<byte>

The ciphertext followed by the authentication tag.

Returns

byte[]

The recovered plaintext.

Exceptions

ArgumentNullException

suite or recipientKey is null.

ArgumentException

encapsulation is not exactly 32 bytes, or ciphertext is shorter than the authentication tag.

NotSupportedException

The suite is export-only.

CryptographicException

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

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

Encrypts plaintext to a recipient public key in base mode (RFC 9180 §6.1 SealBase).

public static (byte[] Encapsulation, byte[] Ciphertext) Seal(HpkeSuite suite, ReadOnlySpan<byte> recipientPublicKey, ReadOnlySpan<byte> info, ReadOnlySpan<byte> associatedData, ReadOnlySpan<byte> plaintext)

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.

associatedData ReadOnlySpan<byte>

The associated data authenticated but not encrypted.

plaintext ReadOnlySpan<byte>

The data to encrypt.

Returns

(byte[] Encapsulation, byte[] Ciphertext)

The encapsulated key and the ciphertext (ciphertext followed by the authentication tag).

Exceptions

ArgumentNullException

suite is null.

ArgumentException

recipientPublicKey is not exactly 32 bytes.

NotSupportedException

The suite is export-only.

CryptographicException

recipientPublicKey is a low-order point.

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

Encrypts plaintext to a recipient public key while authenticating the sender (RFC 9180 §6.1 SealAuth).

public static (byte[] Encapsulation, byte[] Ciphertext) SealAuth(HpkeSuite suite, ReadOnlySpan<byte> recipientPublicKey, ReadOnlySpan<byte> info, X25519 senderKey, ReadOnlySpan<byte> associatedData, ReadOnlySpan<byte> plaintext)

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.

associatedData ReadOnlySpan<byte>

The associated data authenticated but not encrypted.

plaintext ReadOnlySpan<byte>

The data to encrypt.

Returns

(byte[] Encapsulation, byte[] Ciphertext)

The encapsulated key and the ciphertext (ciphertext followed by the authentication tag).

Exceptions

ArgumentNullException

suite or senderKey is null.

ArgumentException

recipientPublicKey is not exactly 32 bytes.

NotSupportedException

The suite is export-only.

CryptographicException

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

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

Encrypts plaintext to a recipient public key with both sender authentication and a pre-shared key (RFC 9180 §6.1 SealAuthPSK).

public static (byte[] Encapsulation, byte[] Ciphertext) SealAuthPsk(HpkeSuite suite, ReadOnlySpan<byte> recipientPublicKey, ReadOnlySpan<byte> info, X25519 senderKey, ReadOnlySpan<byte> psk, ReadOnlySpan<byte> pskId, ReadOnlySpan<byte> associatedData, ReadOnlySpan<byte> plaintext)

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.

associatedData ReadOnlySpan<byte>

The associated data authenticated but not encrypted.

plaintext ReadOnlySpan<byte>

The data to encrypt.

Returns

(byte[] Encapsulation, byte[] Ciphertext)

The encapsulated key and the ciphertext (ciphertext followed by the authentication tag).

Exceptions

ArgumentNullException

suite or senderKey is null.

ArgumentException

recipientPublicKey is not exactly 32 bytes.

NotSupportedException

The suite is export-only.

CryptographicException

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

SealPsk(HpkeSuite, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>, ReadOnlySpan<byte>)

Encrypts plaintext to a recipient public key in PSK mode (RFC 9180 §6.1 SealPSK).

public static (byte[] Encapsulation, byte[] Ciphertext) SealPsk(HpkeSuite suite, ReadOnlySpan<byte> recipientPublicKey, ReadOnlySpan<byte> info, ReadOnlySpan<byte> psk, ReadOnlySpan<byte> pskId, ReadOnlySpan<byte> associatedData, ReadOnlySpan<byte> plaintext)

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.

associatedData ReadOnlySpan<byte>

The associated data authenticated but not encrypted.

plaintext ReadOnlySpan<byte>

The data to encrypt.

Returns

(byte[] Encapsulation, byte[] Ciphertext)

The encapsulated key and the ciphertext (ciphertext followed by the authentication tag).

Exceptions

ArgumentNullException

suite is null.

ArgumentException

recipientPublicKey is not exactly 32 bytes.

NotSupportedException

The suite is export-only.

CryptographicException

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

Applies to

Product	Versions
.NET	8, 10