Crate clatter

Source
Expand description

§Clatter 🔊

⚠️ Work in progress ⚠️

no_std compatible, pure Rust implementation of the Noise framework with support for Post Quantum (PQ) extensions as presented by Yawning Angel, Benjamin Dowling, Andreas Hülsing, Peter Schwabe, and Fiona Johanna Weber.

From user perspective, everything in this crate is built around three types:

Users will pick and instantiate the desired handshake state machine with the crypto primitives and handshakepattern::HandshakePattern they wish to use and complete the handshake using the methods provided by the common Handshaker trait:

Handshake messages are exchanged by the peers until the handshake is completed. After completion, Handshaker::finalize is called and the handshake state machine is consumed into a transportstate::TransportState instance, which can be used to decrypt and encrypt communication between the peers.

§Crypto Vendors

Currently Clatter has frozen the vendor selection for DH, Cipher and Hash algorithms, but users can select from multiple KEM vendors.

Concrete implementations of the crypto algorithms are in the crypto module and users can even use their own implementations using the definitions in the traits module.

§Features

To improve build times and produce more optimized binaries, Clatter can be heavily configured by enabling and disabling crate features. Below is a listing of the available features:

Feature flagDescriptionDefaultDetails
use-25519Enable X25519 DHyes
use-aes-gcmEnable AES-GCM cipheryes
use-chacha20poly1305Enable ChaCha20-Poly1305 cipheryes
use-shaEnable SHA-256 and SHA-512 hashingyes
use-blake2Enable BLAKE2 hashingyes
use-rust-crypto-kyberEnable Kyber KEMs by RustCryptoyes
use-argyle-kyber512Eable Kyber512 KEM by Argyle-Softwareno
use-argyle-kyber768Eable Kyber768 KEM by Argyle-Softwareno
use-argyle-kyber1024Eable Kyber1024 KEM by Argyle-Softwareno
stdEnable standard library supportnoCurrently only affects dependencies
allocEnable allocator supportnoReserved for future use

§Example

Simplified example with the most straightforward (and unsecure) PQ handshake pattern and no handshake payload data at all:

ⓘ
use clatter::crypto::cipher::ChaChaPoly;
use clatter::crypto::hash::Sha512;
use clatter::crypto::kem::rust_crypto_kyber::Kyber512;
use clatter::handshakepattern::noise_pqnn;
use clatter::traits::Handshaker;
use clatter::PqHandshake;

fn main() {
    let mut rng_alice = rand::thread_rng();

    // Instantiate initiator handshake
    let mut alice = PqHandshake::<Kyber512, Kyber512, ChaChaPoly, Sha512, _>::new(
        noise_pqnn(),   // Handshake pattern
        &[],            // Prologue data
        true,           // Are we the initiator
        None,           // Pre-shared keys..
        None,           // ..
        None,           // ..
        None,           // ..
        &mut rng_alice, // RNG instance
    ).unwrap();

    let mut buf_alice_send = [0u8; 4096];
    let mut buf_alice_receive = [0u8; 4096];

    // Write handshake message and deliver to peer
    let n = alice.write_message(&[], &mut buf_alice_send).unwrap();
    my_send_function(&buf_alice_send[..n]);

    // Receive handshake message and process it
    let n = my_receive_function(&mut buf_alice_receive);
    let _ = alice.read_message(&buf_alice_receive[..n], &mut[]).unwrap();

    assert!(alice.is_finished());

    // Move to transport state
    let mut alice = alice.finalize().unwrap();

    // All done! Use .send() and .receive() on the transport state to communicate
    // with the peer
    let n = alice.send(b"Hello from Alice", &mut buf_alice_send).unwrap();
    my_send_function(& buf_alice_send[..n]);   
}

Re-exports§

Modules§

Structs§