Crate hpke 

hpke

This is a pure Rust implementation of the HPKE hybrid encryption scheme (RFC 9180), and post-quantum extensions. The purpose of hybrid encryption is to use allow someone to send secure messages to an entity whose public key they know. Here’s an example of Alice and Bob, where Alice knows Bob’s public key:

use hpke::{
    aead::ChaCha20Poly1305,
    kdf::KdfTurboShake128,
    kem::XWing,
    Deserializable, Kem as KemTrait, OpModeR, OpModeS, Serializable, setup_receiver,
    setup_sender,
};
// These types define the ciphersuite Alice and Bob will be using
type Kem = XWing;
type Aead = ChaCha20Poly1305;
type Kdf = KdfTurboShake128;

// Bob generates his keypair
let (bob_sk, bob_pk) = Kem::gen_keypair();
let bob_pk_bytes = bob_pk.to_bytes();

// This is a description string for the session. Both Alice and Bob need to know this value.
// It's not secret.
let info_str = b"Alice and Bob's weekly chat";

// Alice downloads Bob's public key from a trusted source and deserializes it
let bob_pk = <Kem as KemTrait>::PublicKey::from_bytes(&bob_pk_bytes)
    .expect("Bob's pk is invalid");

// Alice initiates a session with Bob. OpModeS::Base means that Alice is not authenticating
// herself at all. If she had a public key herself (and was using an elliptic curve KEM), or
// had a pre-shared secret that Bob also knew, she'd be able to authenticate herself. See the
// OpModeS and OpModeR types for more detail.
let (encapsulated_key, mut encryption_context) =
    hpke::setup_sender::<Aead, Kdf, Kem>(&OpModeS::Base, &bob_pk, info_str)
        .expect("invalid server pubkey!");

// Alice encrypts a message to Bob. `aad` is authenticated associated data that is not
// encrypted.
let msg = b"fronthand or backhand?";
let aad = b"a gentleman's game";
// To seal without allocating:
//   use hpke::inout::InOutBuf;
//   let auth_tag = encryption_context.seal_inout_detached(InOutBuf::from(&mut msg), aad)?;
// To seal with allocating:
let ciphertext: Vec<u8> = encryption_context.seal(msg, aad).expect("encryption failed!");

// ~~~
// Alice sends the encapsulated key, message ciphertext, AAD, and auth tag to Bob over the
// internet. Alice doesn't care if it's an insecure connection, because only Bob can read
// her ciphertext.
// ~~~

// Somewhere far away, Bob receives the data and makes a decryption session
let mut decryption_context =
    hpke::setup_receiver::<Aead, Kdf, Kem>(
        &OpModeR::Base,
        &bob_sk,
        &encapsulated_key,
        info_str,
    ).expect("failed to set up receiver!");
// To open without allocating:
//   use hpke::inout::InOutBuf;
//   decryption_context.open_inout_detached(InOutBuf::from(&mut ciphertext), aad, &auth_tag)
// To open with allocating:
let plaintext = decryption_context.open(&ciphertext, aad).expect("invalid ciphertext!");

assert_eq!(&plaintext, b"fronthand or backhand?");

Re-exports

pub use ::aead::inout;

pub use hybrid_array;

pub use rand_core;

Modules

aead

Traits and structs for authenticated encryption schemes

danger

⚠️ WARNING: Do NOT use this module unless you really know what you’re doing. Read further inside.

kdf

Traits and structs for key derivation functions

kem

Traits and structs for key encapsulation mechanisms

Structs

PskBundle

Contains preshared key bytes and an identifier. This is intended to go inside an OpModeR or OpModeS struct.

Enums

HpkeError

Describes things that can go wrong in the HPKE protocol

OpModeR

The operation mode of the HPKE session (receiver’s view). This is how the sender authenticates their identity to the receiver. This authentication information can include a preshared key, the identity key of the sender, both, or neither. Base is the only mode that does not provide any kind of sender identity authentication.

OpModeS

The operation mode of the HPKE session (sender’s view). This is how the sender authenticates their identity to the receiver. This authentication information can include a preshared key, the identity key of the sender, both, or neither. Base is the only mode that does not provide any kind of sender identity authentication.

Traits

Deserializable

Implemented by types that can be deserialized from byte representation

Kem

Represents authenticated encryption functionality

Serializable

Implemented by types that have a fixed-length byte representation

Functions

setup_receiver

Initiates a decryption context given a private key sk_recip and an encapsulated key which was encapsulated to sk_recip’s corresponding public key. info is a domain separator.

setup_sendergetrandom

Initiates an encryption context to the given recipient public key. info is a domain separator.

setup_sender_with_rng

Initiates an encryption context to the given recipient public key. info is a domain separator.

single_shot_openalloc

Does a setup_receiver and AeadCtxR::open in one shot. That is, it does a key decapsulation for the specified recipient and decrypts the provided ciphertext.

single_shot_open_inout_detached

Does a setup_receiver and AeadCtxR::open_inout_detached in one shot. That is, it does a key decapsulation for the specified recipient and decrypts the provided ciphertext in place.

single_shot_sealalloc and getrandom

Does a crate::setup_sender and AeadCtxS::seal in one shot. That is, it does a key encapsulation to the specified recipient and encrypts the provided plaintext.

single_shot_seal_inout_detachedgetrandom

Does a crate::setup_sender and AeadCtxS::seal_inout_detached in one shot. That is, it does a key encapsulation to the specified recipient and encrypts the provided plaintext in place.

single_shot_seal_inout_detached_with_rng

Does a setup_sender_with_rng and AeadCtxS::seal_inout_detached in one shot. That is, it does a key encapsulation to the specified recipient and encrypts the provided plaintext in place.

single_shot_seal_with_rngalloc

Does a crate::setup_sender and AeadCtxS::seal in one shot. That is, it does a key encapsulation to the specified recipient and encrypts the provided plaintext.