feat!: compile-time safety for handshake

Author: nyonson

protocol/benches/cipher_session.rs

@@ -1,60 +1,69 @@
+// SPDX-License-Identifier: CC0-1.0
+
 #![feature(test)]
 
 extern crate test;
 
-use bip324::{CipherSession, Handshake, InboundCipher, Network, OutboundCipher, PacketType, Role};
+use bip324::{
+    CipherSession, Handshake, HandshakeAuthentication, InboundCipher, Initialized, Network,
+    OutboundCipher, PacketType, ReceivedKey, Role, NUM_INITIAL_HANDSHAKE_BUFFER_BYTES,
+};
 use test::{black_box, Bencher};
 
 fn create_cipher_session_pair() -> (CipherSession, CipherSession) {
-    // Create a proper handshake between Alice and Bob.
-    let mut alice_init_buffer = vec![0u8; 64];
-    let mut alice_handshake = Handshake::new(
-        Network::Bitcoin,
-        Role::Initiator,
-        None,
-        &mut alice_init_buffer,
-    )
-    .unwrap();
-
-    let mut bob_init_buffer = vec![0u8; 100];
-    let mut bob_handshake = Handshake::new(
-        Network::Bitcoin,
-        Role::Responder,
-        None,
-        &mut bob_init_buffer,
-    )
-    .unwrap();
-
-    // Bob completes materials with Alice's key.
-    bob_handshake
-        .complete_materials(
-            alice_init_buffer[..64].try_into().unwrap(),
-            &mut bob_init_buffer[64..],
-            None,
-        )
+    // Send Alice's key.
+    let alice_handshake = Handshake::<Initialized>::new(Network::Bitcoin, Role::Initiator).unwrap();
+    let mut alice_key_buffer = vec![0u8; Handshake::<Initialized>::send_key_len(None)];
+    let alice_handshake = alice_handshake
+        .send_key(None, &mut alice_key_buffer)
         .unwrap();
 
-    // Alice completes materials with Bob's key.
-    let mut alice_response_buffer = vec![0u8; 36];
-    alice_handshake
-        .complete_materials(
-            bob_init_buffer[..64].try_into().unwrap(),
-            &mut alice_response_buffer,
-            None,
-        )
+    // Send Bob's key
+    let bob_handshake = Handshake::<Initialized>::new(Network::Bitcoin, Role::Responder).unwrap();
+    let mut bob_key_buffer = vec![0u8; Handshake::<Initialized>::send_key_len(None)];
+    let bob_handshake = bob_handshake.send_key(None, &mut bob_key_buffer).unwrap();
+
+    // Alice receives Bob's key.
+    let alice_handshake = alice_handshake
+        .receive_key(bob_key_buffer.try_into().unwrap())
         .unwrap();
 
-    // Authenticate.
-    let mut packet_buffer = vec![0u8; 4096];
-    alice_handshake
-        .authenticate_garbage_and_version(&bob_init_buffer[64..], &mut packet_buffer)
+    // Bob receives Alice's key.
+    let bob_handshake = bob_handshake
+        .receive_key(alice_key_buffer.try_into().unwrap())
         .unwrap();
-    bob_handshake
-        .authenticate_garbage_and_version(&alice_response_buffer, &mut packet_buffer)
+
+    // Alice sends version.
+    let mut alice_version_buffer = vec![0u8; Handshake::<ReceivedKey>::send_version_len(None)];
+    let alice_handshake = alice_handshake
+        .send_version(&mut alice_version_buffer, None)
+        .unwrap();
+
+    // Bob sends version.
+    let mut bob_version_buffer = vec![0u8; Handshake::<ReceivedKey>::send_version_len(None)];
+    let bob_handshake = bob_handshake
+        .send_version(&mut bob_version_buffer, None)
         .unwrap();
 
-    let alice = alice_handshake.finalize().unwrap();
-    let bob = bob_handshake.finalize().unwrap();
+    let mut packet_buffer = vec![0u8; NUM_INITIAL_HANDSHAKE_BUFFER_BYTES];
+
+    // Alice receives Bob's version.
+    let alice = match alice_handshake
+        .receive_version(&bob_version_buffer, &mut packet_buffer)
+        .unwrap()
+    {
+        HandshakeAuthentication::Complete { cipher, .. } => cipher,
+        HandshakeAuthentication::NeedMoreData(_) => panic!("Should have completed"),
+    };
+
+    // Bob receives Alice's version.
+    let bob = match bob_handshake
+        .receive_version(&alice_version_buffer, &mut packet_buffer)
+        .unwrap()
+    {
+        HandshakeAuthentication::Complete { cipher, .. } => cipher,
+        HandshakeAuthentication::NeedMoreData(_) => panic!("Should have completed"),
+    };
 
     (alice, bob)
 }

protocol/fuzz/fuzz_targets/handshake.rs

@@ -1,58 +1,60 @@
+// SPDX-License-Identifier: CC0-1.0
+
+//! ## Expected Outcomes
+//!
+//! * Most runs will fail with invalid EC points or handshake failures.
+//! * No panics, crashes, or memory safety issues should occur.
+//! * The implementation should handle all inputs gracefully.
+
 #![no_main]
-use bip324::{Handshake, Network, Role, NUM_INITIAL_HANDSHAKE_BUFFER_BYTES};
+use bip324::{
+    Handshake, HandshakeAuthentication, Initialized, Network, ReceivedKey, Role,
+    NUM_INITIAL_HANDSHAKE_BUFFER_BYTES,
+};
 use libfuzzer_sys::fuzz_target;
 
 fuzz_target!(|data: &[u8]| {
-    // Skip if data is too small for an interesting test.
-    if data.len() < 64 {
+    // Skip if data is too small for a meaningful test.
+    // We need at least 64 bytes for the public key and at
+    // least 30 more for some interesting garbage, decoy, version bytes.
+    if data.len() < 100 {
         return;
     }
 
-    let mut initiator_pubkey = [0u8; 64];
-    let mut handshake = Handshake::new(
-        Network::Bitcoin,
-        Role::Initiator,
-        None,
-        &mut initiator_pubkey,
-    )
-    .unwrap();
-
-    let mut responder_pubkey = [0u8; 64];
-    let _responder_handshake = Handshake::new(
-        Network::Bitcoin,
-        Role::Responder,
-        None,
-        &mut responder_pubkey,
-    )
-    .unwrap();
-
-    // Create a mutation of the responder's bytes.
-    let mut garbage_and_version = [0u8; 36];
-    let copy_len = std::cmp::min(data.len(), garbage_and_version.len());
-    garbage_and_version[..copy_len].copy_from_slice(&data[..copy_len]);
-
-    // Create mutation of the responder's public key.
-    // The key is either completely random or slightly tweaked.
+    // Initiator side of the handshake.
+    let handshake = Handshake::<Initialized>::new(Network::Bitcoin, Role::Initiator).unwrap();
+    let mut initiator_pubkey = vec![0u8; Handshake::<Initialized>::send_key_len(None)];
+    let handshake = handshake.send_key(None, &mut initiator_pubkey).unwrap();
+
+    // Use the first 64 bytes of fuzz data as the responder's public key.
     let mut fuzzed_responder_pubkey = [0u8; 64];
-    if data.len() >= 128 {
-        fuzzed_responder_pubkey.copy_from_slice(&data[64..128]);
-    } else {
-        fuzzed_responder_pubkey.copy_from_slice(&responder_pubkey);
-        for (i, b) in data
-            .iter()
-            .enumerate()
-            .take(fuzzed_responder_pubkey.len())
-            .skip(copy_len)
-        {
-            fuzzed_responder_pubkey[i % 64] ^= b; // XOR to make controlled changes.
+    fuzzed_responder_pubkey.copy_from_slice(&data[..64]);
+
+    // Attempt to receive the fuzzed key.
+    let handshake = match handshake.receive_key(fuzzed_responder_pubkey) {
+        Ok(h) => h,
+        Err(_) => return, // Invalid key rejected successfully.
+    };
+
+    // Send version message just to move the state of the handshake along.
+    let mut version_buffer = vec![0u8; Handshake::<ReceivedKey>::send_version_len(None)];
+    let handshake = handshake.send_version(&mut version_buffer, None).unwrap();
+
+    // Try to receive and authenticate the fuzzed garbage and version data.
+    let garbage_and_version = Vec::from(&data[64..]);
+    let mut packet_buffer = vec![0u8; NUM_INITIAL_HANDSHAKE_BUFFER_BYTES];
+    match handshake.receive_version(&garbage_and_version, &mut packet_buffer) {
+        Ok(HandshakeAuthentication::Complete { .. }) => {
+            // Handshake completed successfully.
+            // This should only happen with some very lucky random bytes.
+        }
+        Ok(HandshakeAuthentication::NeedMoreData(_)) => {
+            // Handshake needs more ciphertext.
+            // This is an expected outcome for fuzzed inputs.
+        }
+        Err(_) => {
+            // Authentication or parsing failed.
+            // This is an expected outcome for fuzzed inputs.
         }
     }
-
-    // Try to complete the materials and authenticate with the fuzzed key and data.
-    // Exercising malformed public key handling.
-    let _ = handshake.complete_materials(fuzzed_responder_pubkey, &mut garbage_and_version, None);
-    // Check how a broken handshake is handled.
-    let mut packet_buffer = vec![0u8; NUM_INITIAL_HANDSHAKE_BUFFER_BYTES]; // Initial buffer for decoy and version packets
-    let _ = handshake.authenticate_garbage_and_version(&garbage_and_version, &mut packet_buffer);
-    let _ = handshake.finalize();
 });