Crate hpke[−][src]
Expand description
hpke
WARNING: This code has not been audited. Use at your own discretion.
This is a pure Rust implementation of the HPKE hybrid encryption scheme. 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:
// These types define the ciphersuite Alice and Bob will be using
type Kem = X25519HkdfSha256;
type Aead = ChaCha20Poly1305;
type Kdf = HkdfSha384;
let mut csprng = StdRng::from_entropy();
// 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 initiates a session with Bob. OpModeS::Base means that Alice is not authenticating
// herself at all. If she had a public key herself, or 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, &mut csprng)
.expect("invalid server pubkey!");
// Alice encrypts a message to Bob. msg gets encrypted in place, and aad is authenticated
// associated data that is not encrypted.
let mut msg = *b"fronthand or backhand?";
let aad = b"a gentleman's game";
let auth_tag = encryption_context
.seal(&mut msg, aad)
.expect("encryption failed!");
// The msg was encrypted in-place. So rename it for clarity
let ciphertext = msg;
// ~~~
// 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!");
decryption_context.open(&mut ciphertext, aad, &auth_tag).expect("invalid ciphertext!");
// The ciphertext was decrypted in-place. So rename it for clarity
let plaintext = ciphertext;
assert_eq!(&plaintext, b"fronthand or backhand?");
Re-exports
pub use generic_array;
Modules
Structs
The HPKE receiver’s context. This is what you use to open
ciphertexts and export
secrets.
The HPKE senders’s context. This is what you use to seal
plaintexts and export
secrets.
Holds the content of an encapsulated secret. This is what the receiver uses to derive the shared secret.
Contains preshared key bytes and an identifier. This is intended to go inside an OpModeR
or
OpModeS
struct.
Enums
Describes things that can go wrong in the HPKE protocol
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.
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
Implemented by types that can be deserialized from byte representation
Defines a combination of key exchange mechanism and a KDF, which together form a KEM
Implemented by types that have a fixed-length byte representation
Functions
Initiates a decryption context given a private key sk_recip
and an encapsulated key which
was encapsulated to sk_recip
’s corresponding public key
Initiates an encryption context to the given recipient public key
Does a setup_receiver
and AeadCtx::open
in one shot. That is, it does a key decapsulation
for the specified recipient and decrypts the provided ciphertext in-place. See
setup::setup_reciever
and AeadCtx::open
for more detail.
Does a setup_sender
and AeadCtx::seal
in one shot. That is, it does a key encapsulation to
the specified recipient and encrypts the provided plaintext in place. See setup::setup_sender
and AeadCtx::seal
for more detail.