Module rosenpass::protocol

Expand description

Module containing the cryptographic protocol implementation

§Overview

The most important types in this module probably are PollResult & CryptoServer. Once a CryptoServer is created, the server is provided with new messages via the CryptoServer::handle_msg method. The CryptoServer::poll method can be used to let the server work, which will eventually yield a PollResult. Said PollResult contains prescriptive activities to be carried out. CryptoServer::osk can than be used to extract the shared key for two peers, once a key-exchange was successful.

TODO explain briefly the role of epki

§Example Handshake

This example illustrates a minimal setup for a key-exchange between two CryptoServer.

use rosenpass::{
    pqkem::{StaticKEM, KEM},
    protocol::{SSk, SPk, MsgBuf, PeerPtr, CryptoServer, SymKey},
};

// always init libsodium before anything
rosenpass::sodium::sodium_init()?;

// initialize secret and public key for peer a ...
let (mut peer_a_sk, mut peer_a_pk) = (SSk::zero(), SPk::zero());
StaticKEM::keygen(peer_a_sk.secret_mut(), peer_a_pk.secret_mut())?;

// ... and for peer b
let (mut peer_b_sk, mut peer_b_pk) = (SSk::zero(), SPk::zero());
StaticKEM::keygen(peer_b_sk.secret_mut(), peer_b_pk.secret_mut())?;

// initialize server and a pre-shared key
let psk = SymKey::random();
let mut a = CryptoServer::new(peer_a_sk, peer_a_pk.clone());
let mut b = CryptoServer::new(peer_b_sk, peer_b_pk.clone());

// introduce peers to each other
a.add_peer(Some(psk.clone()), peer_b_pk)?;
b.add_peer(Some(psk), peer_a_pk)?;

// declare buffers for message exchange
let (mut a_buf, mut b_buf) = (MsgBuf::zero(), MsgBuf::zero());

// let a initiate a handshake
let mut maybe_len = Some(a.initiate_handshake(PeerPtr(0), a_buf.as_mut_slice())?);

// let a and b communicate
while let Some(len) = maybe_len {
   maybe_len = b.handle_msg(&a_buf[..len], &mut b_buf[..])?.resp;
   std::mem::swap(&mut a, &mut b);
   std::mem::swap(&mut a_buf, &mut b_buf);
}

// all done! Extract the shared keys and ensure they are identical
let a_key = a.osk(PeerPtr(0))?;
let b_key = b.osk(PeerPtr(0))?;
assert_eq!(a_key.secret(), b_key.secret(),
    "the key exchanged failed to establish a shared secret");

Structs§

BiscuitKey
A Biscuit is like a fancy cookie. To avoid state disruption attacks, the responder doesn’t store state. Instead the state is stored in a Biscuit, that is encrypted using the BiscuitKey which is only known to the Responder. Thus secrecy of the Responder state is not violated, still the responder can avoid storing this state.
BiscuitKeyPtr
Valid index to CryptoServer::biscuit_keys
CryptoServer
Implementation of the cryptographic protocol
HandleMsgResult
HandshakeState
IniHsPtr
Valid index to CryptoServer::peers
InitiatorHandshake
Peer
PeerPtr
Valid index to CryptoServer::peers
Session
SessionPtr
Valid index to CryptoServer::peers
Wait