Hpke Class
Definition
- Namespace
- Bodu.Security.Cryptography
- Assembly
- Bodu.Security.Cryptography.dll
- Package
- Bodu.Security.Cryptography 1.3.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
-
Hpke
- Inherited Members
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.
The AES-GCM suites seal with the library's own GcmModeTransform, but the ChaCha20Poly1305 suite uses the platform's ChaCha20Poly1305. Where IsSupported is false, sealing or opening with that suite throws PlatformNotSupportedException.
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
suiteHpkeSuiteThe cipher suite.
recipientKeyX25519The recipient's X25519 key holding the private key.
encapsulationReadOnlySpan<byte>The encapsulated key received from the sender.
infoReadOnlySpan<byte>The application-supplied context; must match the value used to seal.
associatedDataReadOnlySpan<byte>The associated data; must match the value used to seal.
ciphertextReadOnlySpan<byte>The ciphertext followed by the authentication tag.
Returns
- byte[]
The recovered plaintext.
Exceptions
- ArgumentNullException
suiteorrecipientKeyis null.- ArgumentException
encapsulationis not exactly 32 bytes, orciphertextis shorter than the authentication tag.- NotSupportedException
The suite is export-only.
- CryptographicException
recipientKeyhas no private key,encapsulationis 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
suiteHpkeSuiteThe cipher suite.
recipientKeyX25519The recipient's X25519 key holding the private key.
encapsulationReadOnlySpan<byte>The encapsulated key received from the sender.
infoReadOnlySpan<byte>The application-supplied context; must match the value used to seal.
senderPublicKeyReadOnlySpan<byte>The sender's 32-byte X25519 public key, used to verify authentication.
associatedDataReadOnlySpan<byte>The associated data; must match the value used to seal.
ciphertextReadOnlySpan<byte>The ciphertext followed by the authentication tag.
Returns
- byte[]
The recovered plaintext.
Exceptions
- ArgumentNullException
suiteorrecipientKeyis null.- ArgumentException
encapsulationorsenderPublicKeyis not exactly 32 bytes, orciphertextis shorter than the authentication tag.- NotSupportedException
The suite is export-only.
- CryptographicException
recipientKeyhas 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
suiteHpkeSuiteThe cipher suite.
recipientKeyX25519The recipient's X25519 key holding the private key.
encapsulationReadOnlySpan<byte>The encapsulated key received from the sender.
infoReadOnlySpan<byte>The application-supplied context; must match the value used to seal.
senderPublicKeyReadOnlySpan<byte>The sender's 32-byte X25519 public key, used to verify authentication.
pskReadOnlySpan<byte>The pre-shared key, shared out of band with the sender.
pskIdReadOnlySpan<byte>The identifier of the pre-shared key.
associatedDataReadOnlySpan<byte>The associated data; must match the value used to seal.
ciphertextReadOnlySpan<byte>The ciphertext followed by the authentication tag.
Returns
- byte[]
The recovered plaintext.
Exceptions
- ArgumentNullException
suiteorrecipientKeyis null.- ArgumentException
encapsulationorsenderPublicKeyis not exactly 32 bytes, orciphertextis shorter than the authentication tag.- NotSupportedException
The suite is export-only.
- CryptographicException
The PSK inputs are inconsistent,
recipientKeyhas 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
suiteHpkeSuiteThe cipher suite.
recipientKeyX25519The recipient's X25519 key holding the private key.
encapsulationReadOnlySpan<byte>The encapsulated key received from the sender.
infoReadOnlySpan<byte>The application-supplied context; must match the value used to seal.
pskReadOnlySpan<byte>The pre-shared key, shared out of band with the sender.
pskIdReadOnlySpan<byte>The identifier of the pre-shared key.
associatedDataReadOnlySpan<byte>The associated data; must match the value used to seal.
ciphertextReadOnlySpan<byte>The ciphertext followed by the authentication tag.
Returns
- byte[]
The recovered plaintext.
Exceptions
- ArgumentNullException
suiteorrecipientKeyis null.- ArgumentException
encapsulationis not exactly 32 bytes, orciphertextis shorter than the authentication tag.- NotSupportedException
The suite is export-only.
- CryptographicException
The PSK inputs are inconsistent,
recipientKeyhas no private key,encapsulationis 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
suiteHpkeSuiteThe cipher suite.
recipientPublicKeyReadOnlySpan<byte>The recipient's 32-byte X25519 public key.
infoReadOnlySpan<byte>The application-supplied context binding the exchange.
associatedDataReadOnlySpan<byte>The associated data authenticated but not encrypted.
plaintextReadOnlySpan<byte>The data to encrypt.
Returns
- (byte[] Encapsulation, byte[] Ciphertext)
The encapsulated key and the ciphertext (ciphertext followed by the authentication tag).
Exceptions
- ArgumentNullException
suiteis null.- ArgumentException
recipientPublicKeyis not exactly 32 bytes.- NotSupportedException
The suite is export-only.
- CryptographicException
recipientPublicKeyis 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
suiteHpkeSuiteThe cipher suite.
recipientPublicKeyReadOnlySpan<byte>The recipient's 32-byte X25519 public key.
infoReadOnlySpan<byte>The application-supplied context binding the exchange.
senderKeyX25519The sender's X25519 key holding the static private key.
associatedDataReadOnlySpan<byte>The associated data authenticated but not encrypted.
plaintextReadOnlySpan<byte>The data to encrypt.
Returns
- (byte[] Encapsulation, byte[] Ciphertext)
The encapsulated key and the ciphertext (ciphertext followed by the authentication tag).
Exceptions
- ArgumentNullException
suiteorsenderKeyis null.- ArgumentException
recipientPublicKeyis not exactly 32 bytes.- NotSupportedException
The suite is export-only.
- CryptographicException
senderKeyhas no private key, orrecipientPublicKeyis 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
suiteHpkeSuiteThe cipher suite.
recipientPublicKeyReadOnlySpan<byte>The recipient's 32-byte X25519 public key.
infoReadOnlySpan<byte>The application-supplied context binding the exchange.
senderKeyX25519The sender's X25519 key holding the static private key.
pskReadOnlySpan<byte>The pre-shared key, shared out of band with the recipient.
pskIdReadOnlySpan<byte>The identifier of the pre-shared key.
associatedDataReadOnlySpan<byte>The associated data authenticated but not encrypted.
plaintextReadOnlySpan<byte>The data to encrypt.
Returns
- (byte[] Encapsulation, byte[] Ciphertext)
The encapsulated key and the ciphertext (ciphertext followed by the authentication tag).
Exceptions
- ArgumentNullException
suiteorsenderKeyis null.- ArgumentException
recipientPublicKeyis not exactly 32 bytes.- NotSupportedException
The suite is export-only.
- CryptographicException
The PSK inputs are inconsistent,
senderKeyhas no private key, orrecipientPublicKeyis 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
suiteHpkeSuiteThe cipher suite.
recipientPublicKeyReadOnlySpan<byte>The recipient's 32-byte X25519 public key.
infoReadOnlySpan<byte>The application-supplied context binding the exchange.
pskReadOnlySpan<byte>The pre-shared key, shared out of band with the recipient.
pskIdReadOnlySpan<byte>The identifier of the pre-shared key.
associatedDataReadOnlySpan<byte>The associated data authenticated but not encrypted.
plaintextReadOnlySpan<byte>The data to encrypt.
Returns
- (byte[] Encapsulation, byte[] Ciphertext)
The encapsulated key and the ciphertext (ciphertext followed by the authentication tag).
Exceptions
- ArgumentNullException
suiteis null.- ArgumentException
recipientPublicKeyis not exactly 32 bytes.- NotSupportedException
The suite is export-only.
- CryptographicException
The PSK inputs are inconsistent, or
recipientPublicKeyis a low-order point.
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |