Struct ModeAuth

Source

pub struct ModeAuth<S> { /* private fields */ }

Expand description

HPKE Auth mode. Encrypt data to a public key with sender authentication.

§Parameters:

pubkey_r: Public key of the recipient.
pubkey_s: Public key of the sender.
info: Optional additional information for HPKE state. Must be identical for sender and recipient.
enc: Encapsulated key, generated by the sender.
secret_key_r: Secret key of the recipient.
secret_key_s: Secret key of the sender.
exporter_context: Contextual information used during secret export.
secret_ephemeral: Ephemeral private key for deterministic encapsulation.

§Errors:

An error will be returned if:

info is longer than 64 bytes
out buffer is longer than S::EXPORT_SECRET_MAXLEN when exporting secrets with Self::export_secret()
exporter_context is longer than 64 bytes
The internal counter reaches u64::MAX and a call to Self::seal()/Self::open() is made
Calling Self::seal() when the role is Role::Recipient
Calling Self::open() when the role is Role::Sender
Calling Self::open() on a set of messages that does not match the order of how they were Self::seal()’ed (re-ordering)
If a shared secret is all-zero.
If ikm.len() < 32 when calling derive_keypair() on a suite’s KEM.

§Panics:

A panic will occur if:

getrandom panics during Self::new_sender() or Self::auth_seal().

§Security:

When deriving a keypair deterministically instead of generating it randomly, the input ikm must have at least as much entropy as the security level that is desired. For DHKEM_X25519_SHA256_CHACHA20 this means 256 bits.
The ikm used as input for derive_keypair() must never be reused.
The secret_ephemeral must never be reused.

§Example:

use orion::hazardous::hpke::{ModeAuth, DHKEM_X25519_SHA256_CHACHA20};
use orion::hazardous::kem::x25519_hkdf_sha256::DhKem;

let (sender_secret, sender_public) = DhKem::generate_keypair()?;
let (recipient_secret, recipient_public) = DhKem::generate_keypair()?;

// Streaming-based API
let mut aead_ct_out0 = [0u8; 32];
let mut aead_ct_out1 = [0u8; 32];
let mut aead_ct_out2 = [0u8; 32];

let (mut hpke_sender, enc) = ModeAuth::<DHKEM_X25519_SHA256_CHACHA20>::new_sender(&recipient_public, b"info parameter", &sender_secret)?;
hpke_sender.seal(&[0u8; 16], b"aad parameter 0", &mut aead_ct_out0)?;
hpke_sender.seal(&[1u8; 16], b"aad parameter 1", &mut aead_ct_out1)?;
hpke_sender.seal(&[2u8; 16], b"aad parameter 2", &mut aead_ct_out2)?;

let mut hpke_recipient = ModeAuth::<DHKEM_X25519_SHA256_CHACHA20>::new_recipient(&enc, &recipient_secret, b"info parameter", &sender_public)?;
let mut aead_pt_out0 = [0u8; 16];
let mut aead_pt_out1 = [0u8; 16];
let mut aead_pt_out2 = [0u8; 16];
hpke_recipient.open(&aead_ct_out0, b"aad parameter 0", &mut aead_pt_out0)?;
hpke_recipient.open(&aead_ct_out1, b"aad parameter 1", &mut aead_pt_out1)?;
hpke_recipient.open(&aead_ct_out2, b"aad parameter 2", &mut aead_pt_out2)?;

assert_eq!(&aead_pt_out0, &[0u8; 16]);
assert_eq!(&aead_pt_out1, &[1u8; 16]);
assert_eq!(&aead_pt_out2, &[2u8; 16]);

// One-shot API
let enc = ModeAuth::<DHKEM_X25519_SHA256_CHACHA20>::auth_seal(&recipient_public, b"info parameter", &sender_secret, &[3u8; 16], b"aad", &mut aead_ct_out0)?;
ModeAuth::<DHKEM_X25519_SHA256_CHACHA20>::auth_open(&enc, &recipient_secret, b"info parameter", &sender_public, &aead_ct_out0, b"aad", &mut aead_pt_out0)?;
assert_eq!(&aead_pt_out0, &[3u8; 16]);