Struct MessageSession 

pub struct MessageSession { /* private fields */ }

MessageSession manages the cryptographic state for secure message exchange between two parties using post-quantum cryptographic algorithms.

Each session contains:

• A KEM keypair for key encapsulation mechanism
• A digital signature keypair for signing messages
• A shared secret established with the other party
• A verifier for validating messages from the other party
• A nonce for preventing replay attacks

Implementations

impl MessageSession

pub fn to_bytes(&self) -> Result<Vec<u8>, CryptoError>

Serializes the session to a byte array

Returns

• Result<Vec<u8>, CryptoError>: The serialized session or an error

Security Note

The serialized data contains sensitive cryptographic material including private keys. It should be stored securely and only deserialized in a trusted environment.

pub fn from_bytes(bytes: &[u8]) -> Result<Self, CryptoError>

Deserializes a session from a byte array

Arguments

• bytes - The serialized session bytes

Returns

• Result<Self, CryptoError>: The deserialized session or an error

Errors

Returns an error if the byte array is not the correct length or format

pub fn new_initiator( my_keypair: KEMPair, my_signer: SignerPair, base_nonce: [u8; 24], target_pubkey: &[u8; 1568], target_verifier: &[u8; 1793], ) -> Result<(Self, [u8; 1568]), CryptoError>

Creates a new session as the initiator

Arguments

• my_keypair - Your own KEM keypair
• my_signer - Your own signer pair
• base_nonce - Base nonce (0..16 session id, 16..24 counter)
• target_pubkey - KEM public key of the target
• target_verifier - Falcon verifier containing the public key of the target

Returns

• Result<(Self, [u8; PQCLEAN_MLKEM1024_CLEAN_CRYPTO_CIPHERTEXTBYTES]), CryptoError>: The session and ciphertext for the responder, or an error

Examples found in repository

examples/full_exchange.rs (lines 17-23)

fn main() {
    let alice_kem = KEMPair::create();
    let alice_signer = SignerPair::create();

    let bob_kem = KEMPair::create();
    let bob_signer = SignerPair::create();

    // Create a base nonce with a new session id, and a counter of
    let base_nonce = create_nonce(&gen_session_id(), 0);

    // Lets create the message session for Alice first
    let (mut alice_session, ciphertext) = MessageSession::new_initiator(
        alice_kem,
        alice_signer.clone(),
        base_nonce,
        &bob_kem.to_bytes().unwrap().0,    // Bob's public KEM key
        &bob_signer.to_bytes().unwrap().0, // Bob's public signer key
    )
    .unwrap();

    // Now for Bob it would look like this
    let mut bob_session = MessageSession::new_responder(
        bob_kem,
        bob_signer.clone(),
        base_nonce,
        &ciphertext,
        &alice_signer.to_bytes().unwrap().0, // Alice's public signer key
    )
    .unwrap();

    // Now both sessions contain a shared secret they use to encrypt and decrypt messages
    // and a nonce that is incremented with each message sent or received.

    // Alice creates a mesasge and prepares to send it to Bob
    let message = b"Hello, Bob! This is a secret message.";
    let encrypted_message = alice_session.craft_message(message).unwrap();

    // Bob decrypts and verifies Alice's message
    let raw_message = bob_session.validate_message(&encrypted_message).unwrap();

    // Both message and raw_message are equal, let's print them out to illustrate
    let message_str = String::from_utf8_lossy(message);
    let raw_message_str = String::from_utf8_lossy(&raw_message);

    println!("[1] Alice's message: {}", message_str);
    println!("[2] Bob's decrypted message: {}", raw_message_str);

    // Bob crafts a reply message to Alice
    let reply = b"Hello, Alice! I received your message safely.";
    let encrypted_reply = bob_session.craft_message(reply).unwrap();

    // Alice decrypts and verifies Bob's reply
    let raw_reply = alice_session.validate_message(&encrypted_reply).unwrap();

    // Both reply and raw_reply are equal, let's print them again
    let reply_str = String::from_utf8_lossy(reply);
    let raw_reply_str = String::from_utf8_lossy(&raw_reply);

    println!("[3] Bob's reply: {}", reply_str);
    println!("[4] Alice's decrypted reply: {}", raw_reply_str);
}

pub fn new_responder( my_keypair: KEMPair, my_signer: SignerPair, base_nonce: [u8; 24], ciphertext_bytes: &[u8; 1568], sender_verifier: &[u8; 1793], ) -> Result<Self, CryptoError>

Creates a new session as the responder

Arguments

• my_keypair - Your own KEM keypair
• my_signer - Your own signer pair
• base_nonce - Base nonce (0..16 session id, 16..24 counter)
• ciphertext_bytes - KEM ciphertext sent by the initiator
• sender_verifier - Falcon verifier containing the public key of the initiator

Returns

• Result<Self, CryptoError>: The session or an error

Examples found in repository

examples/full_exchange.rs (lines 27-33)

fn main() {
    let alice_kem = KEMPair::create();
    let alice_signer = SignerPair::create();

    let bob_kem = KEMPair::create();
    let bob_signer = SignerPair::create();

    // Create a base nonce with a new session id, and a counter of
    let base_nonce = create_nonce(&gen_session_id(), 0);

    // Lets create the message session for Alice first
    let (mut alice_session, ciphertext) = MessageSession::new_initiator(
        alice_kem,
        alice_signer.clone(),
        base_nonce,
        &bob_kem.to_bytes().unwrap().0,    // Bob's public KEM key
        &bob_signer.to_bytes().unwrap().0, // Bob's public signer key
    )
    .unwrap();

    // Now for Bob it would look like this
    let mut bob_session = MessageSession::new_responder(
        bob_kem,
        bob_signer.clone(),
        base_nonce,
        &ciphertext,
        &alice_signer.to_bytes().unwrap().0, // Alice's public signer key
    )
    .unwrap();

    // Now both sessions contain a shared secret they use to encrypt and decrypt messages
    // and a nonce that is incremented with each message sent or received.

    // Alice creates a mesasge and prepares to send it to Bob
    let message = b"Hello, Bob! This is a secret message.";
    let encrypted_message = alice_session.craft_message(message).unwrap();

    // Bob decrypts and verifies Alice's message
    let raw_message = bob_session.validate_message(&encrypted_message).unwrap();

    // Both message and raw_message are equal, let's print them out to illustrate
    let message_str = String::from_utf8_lossy(message);
    let raw_message_str = String::from_utf8_lossy(&raw_message);

    println!("[1] Alice's message: {}", message_str);
    println!("[2] Bob's decrypted message: {}", raw_message_str);

    // Bob crafts a reply message to Alice
    let reply = b"Hello, Alice! I received your message safely.";
    let encrypted_reply = bob_session.craft_message(reply).unwrap();

    // Alice decrypts and verifies Bob's reply
    let raw_reply = alice_session.validate_message(&encrypted_reply).unwrap();

    // Both reply and raw_reply are equal, let's print them again
    let reply_str = String::from_utf8_lossy(reply);
    let raw_reply_str = String::from_utf8_lossy(&raw_reply);

    println!("[3] Bob's reply: {}", reply_str);
    println!("[4] Alice's decrypted reply: {}", raw_reply_str);
}

pub fn craft_message(&mut self, message: &[u8]) -> Result<Vec<u8>, CryptoError>

Creates a signed and encrypted message for the other party

Arguments

• message - The plaintext message to encrypt

Returns

• Result<Vec<u8>, CryptoError>: The encrypted message or an error

Security Note

This method automatically increments the nonce counter to ensure uniqueness for each message.

Examples found in repository

examples/full_exchange.rs (line 41)

fn main() {
    let alice_kem = KEMPair::create();
    let alice_signer = SignerPair::create();

    let bob_kem = KEMPair::create();
    let bob_signer = SignerPair::create();

    // Create a base nonce with a new session id, and a counter of
    let base_nonce = create_nonce(&gen_session_id(), 0);

    // Lets create the message session for Alice first
    let (mut alice_session, ciphertext) = MessageSession::new_initiator(
        alice_kem,
        alice_signer.clone(),
        base_nonce,
        &bob_kem.to_bytes().unwrap().0,    // Bob's public KEM key
        &bob_signer.to_bytes().unwrap().0, // Bob's public signer key
    )
    .unwrap();

    // Now for Bob it would look like this
    let mut bob_session = MessageSession::new_responder(
        bob_kem,
        bob_signer.clone(),
        base_nonce,
        &ciphertext,
        &alice_signer.to_bytes().unwrap().0, // Alice's public signer key
    )
    .unwrap();

    // Now both sessions contain a shared secret they use to encrypt and decrypt messages
    // and a nonce that is incremented with each message sent or received.

    // Alice creates a mesasge and prepares to send it to Bob
    let message = b"Hello, Bob! This is a secret message.";
    let encrypted_message = alice_session.craft_message(message).unwrap();

    // Bob decrypts and verifies Alice's message
    let raw_message = bob_session.validate_message(&encrypted_message).unwrap();

    // Both message and raw_message are equal, let's print them out to illustrate
    let message_str = String::from_utf8_lossy(message);
    let raw_message_str = String::from_utf8_lossy(&raw_message);

    println!("[1] Alice's message: {}", message_str);
    println!("[2] Bob's decrypted message: {}", raw_message_str);

    // Bob crafts a reply message to Alice
    let reply = b"Hello, Alice! I received your message safely.";
    let encrypted_reply = bob_session.craft_message(reply).unwrap();

    // Alice decrypts and verifies Bob's reply
    let raw_reply = alice_session.validate_message(&encrypted_reply).unwrap();

    // Both reply and raw_reply are equal, let's print them again
    let reply_str = String::from_utf8_lossy(reply);
    let raw_reply_str = String::from_utf8_lossy(&raw_reply);

    println!("[3] Bob's reply: {}", reply_str);
    println!("[4] Alice's decrypted reply: {}", raw_reply_str);
}

pub fn validate_message( &mut self, ciphertext: &[u8], ) -> Result<Vec<u8>, CryptoError>

Decrypts and validates a message from the other party

Arguments

• ciphertext - The encrypted message

Returns

• Result<Vec<u8>, CryptoError>: The decrypted and validated message or an error

Security Note

This method automatically increments the nonce counter to match the sender’s nonce. If the nonces are out of sync, validation will fail.

Examples found in repository

examples/full_exchange.rs (line 44)

fn main() {
    let alice_kem = KEMPair::create();
    let alice_signer = SignerPair::create();

    let bob_kem = KEMPair::create();
    let bob_signer = SignerPair::create();

    // Create a base nonce with a new session id, and a counter of
    let base_nonce = create_nonce(&gen_session_id(), 0);

    // Lets create the message session for Alice first
    let (mut alice_session, ciphertext) = MessageSession::new_initiator(
        alice_kem,
        alice_signer.clone(),
        base_nonce,
        &bob_kem.to_bytes().unwrap().0,    // Bob's public KEM key
        &bob_signer.to_bytes().unwrap().0, // Bob's public signer key
    )
    .unwrap();

    // Now for Bob it would look like this
    let mut bob_session = MessageSession::new_responder(
        bob_kem,
        bob_signer.clone(),
        base_nonce,
        &ciphertext,
        &alice_signer.to_bytes().unwrap().0, // Alice's public signer key
    )
    .unwrap();

    // Now both sessions contain a shared secret they use to encrypt and decrypt messages
    // and a nonce that is incremented with each message sent or received.

    // Alice creates a mesasge and prepares to send it to Bob
    let message = b"Hello, Bob! This is a secret message.";
    let encrypted_message = alice_session.craft_message(message).unwrap();

    // Bob decrypts and verifies Alice's message
    let raw_message = bob_session.validate_message(&encrypted_message).unwrap();

    // Both message and raw_message are equal, let's print them out to illustrate
    let message_str = String::from_utf8_lossy(message);
    let raw_message_str = String::from_utf8_lossy(&raw_message);

    println!("[1] Alice's message: {}", message_str);
    println!("[2] Bob's decrypted message: {}", raw_message_str);

    // Bob crafts a reply message to Alice
    let reply = b"Hello, Alice! I received your message safely.";
    let encrypted_reply = bob_session.craft_message(reply).unwrap();

    // Alice decrypts and verifies Bob's reply
    let raw_reply = alice_session.validate_message(&encrypted_reply).unwrap();

    // Both reply and raw_reply are equal, let's print them again
    let reply_str = String::from_utf8_lossy(reply);
    let raw_reply_str = String::from_utf8_lossy(&raw_reply);

    println!("[3] Bob's reply: {}", reply_str);
    println!("[4] Alice's decrypted reply: {}", raw_reply_str);
}

pub fn get_counter(&self) -> u64

Gets the current nonce counter value

Returns

• u64: The current nonce counter value