diff --git a/src/handshake.rs b/src/handshake.rs index 36a77b8..6b56519 100644 --- a/src/handshake.rs +++ b/src/handshake.rs @@ -13,7 +13,7 @@ use zeroize::Zeroize; use crate::{ Role, WHARRGHARBL_PROTO, - transport::{AeadNeko, AeadTranport}, + transport::{AeadNeko, AeadTransport}, }; pub struct ClientHandshake { @@ -58,7 +58,7 @@ where Ok(()) } - pub fn receive(&mut self, ciphertext: &[u8]) -> aead::Result> { + pub fn receive(&mut self, ciphertext: &[u8]) -> aead::Result> { let decap = self.decap.as_ref().ok_or(aead::Error)?; let tag = ciphertext @@ -80,7 +80,7 @@ where Ok(self.finish(shared)) } - fn finish(&mut self, mut shared: SharedKey) -> AeadTranport { + fn finish(&mut self, mut shared: SharedKey) -> AeadTransport { self.neko.key(&shared); shared.zeroize(); @@ -95,7 +95,7 @@ where entropy.zeroize(); - AeadTranport::new(key, outbound, inbound, Role::Sender) + AeadTransport::new(key, outbound, inbound, Role::Sender) } } @@ -126,7 +126,7 @@ impl + ParameterSet> ServerHandshake aead::Result> { + ) -> aead::Result> { let slice = buf.as_ref(); let tag = slice @@ -154,7 +154,7 @@ impl + ParameterSet> ServerHandshake AeadTranport { + fn finish(&mut self, mut shared: SharedKey) -> AeadTransport { self.neko.key(&shared); shared.zeroize(); @@ -169,7 +169,7 @@ impl + ParameterSet> ServerHandshake zeroize::Zeroize for AeadNeko { } } -pub struct AeadTranport { +pub struct AeadTransport { pub(crate) aead: AeadNeko, pub(crate) epstein: aead::Nonce>, pub(crate) trump: aead::Nonce>, handshake_role: Role, } -impl zeroize::Zeroize for AeadTranport { +impl zeroize::Zeroize for AeadTransport { fn zeroize(&mut self) { self.aead.zeroize(); self.epstein.zeroize(); @@ -87,15 +87,15 @@ impl zeroize::Zeroize for AeadTranport { } } -impl zeroize::ZeroizeOnDrop for AeadTranport {} +impl zeroize::ZeroizeOnDrop for AeadTransport {} -impl Drop for AeadTranport { +impl Drop for AeadTransport { fn drop(&mut self) { zeroize::Zeroize::zeroize(self); } } -impl AeadTranport { +impl AeadTransport { pub(crate) fn new( key: Key>, outbound: aead::Nonce>, @@ -152,7 +152,7 @@ impl AeadTranport { } pub struct SendState<'a, S: NekoSec> { - transport: &'a AeadTranport, + transport: &'a AeadTransport, counter: u64, } @@ -174,7 +174,7 @@ impl SendState<'_, S> { } pub struct RecvState<'a, S: NekoSec> { - transport: &'a AeadTranport, + transport: &'a AeadTransport, counter: u64, } @@ -213,13 +213,13 @@ mod tests { let outbound = 123u128.to_ne_bytes(); let inbound = 234u128.to_ne_bytes(); - let alice = AeadTranport::::new( + let alice = AeadTransport::::new( shared_secret.into(), outbound.into(), inbound.into(), Role::Sender, ); - let bob = AeadTranport::::new( + let bob = AeadTransport::::new( shared_secret.into(), outbound.into(), inbound.into(), @@ -286,13 +286,13 @@ mod tests { let outbound = 123u128.to_ne_bytes(); let inbound = 234u128.to_ne_bytes(); - let alice = AeadTranport::::new( + let alice = AeadTransport::::new( shared_secret.into(), outbound.into(), inbound.into(), Role::Sender, ); - let bob = AeadTranport::::new( + let bob = AeadTransport::::new( shared_secret.into(), outbound.into(), inbound.into(), diff --git a/wharrgarbl-neko/src/lib.rs b/wharrgarbl-neko/src/lib.rs index 832c0a9..85cefce 100644 --- a/wharrgarbl-neko/src/lib.rs +++ b/wharrgarbl-neko/src/lib.rs @@ -167,26 +167,29 @@ impl NekoState { self.position += ratchet_bytes; } + /// Sets a provided key into the cipher state. pub fn key(&mut self, data: &NekoKey) { self.begin_op(ops::KEY); self.overwrite(data); } + /// Absorbs a nonce value into the cipher state pub fn nonce(&mut self, data: &NekoNonce) { self.begin_op(ops::NONCE); self.absorb(data); } - /// Absorb associated data into the cipher. This should include a nonce at least, - /// along with other data coming from the app. + /// Absorb associated data into the cipher. pub fn ad(&mut self, data: &[u8]) { self.begin_op(ops::AD); self.absorb(data); } + /// Pseudo-random Function. Used to generate new keys/nonces from the + /// cipher state. pub fn prf(&mut self, data: &mut [u8]) { self.begin_op(ops::PRF); @@ -195,6 +198,8 @@ impl NekoState { self.squeeze(data); } + /// Create a message authentication code (MAC). This is used to validate the resulting + /// state after ingesting/encrypting data. pub fn create_mac(&mut self) -> NekoTag { self.begin_op(ops::MAC); @@ -207,6 +212,9 @@ impl NekoState { tag } + /// Validates a provided MAC. After ingesting/decrypting data, the resulting state + /// of the cipher should be the same as the sender's. The MAC validates that this + /// is correct. Any differences in length/bits/etc, should result in an invalid MAC. pub fn verify_mac(&mut self, data: &NekoTag) -> aead::Result<()> { self.begin_op(ops::MAC); @@ -225,6 +233,7 @@ impl NekoState { } } + /// Takes a cleartext buffer, and encrypts it in place. pub fn encrypt(&mut self, data: &mut [u8]) { self.begin_op(ops::ENC); @@ -233,6 +242,7 @@ impl NekoState { self.absorb_and_set(data); } + /// Takes a ciphertext buffer, and decrypts it in place. pub fn decrypt(&mut self, data: &mut [u8]) { self.begin_op(ops::ENC); @@ -252,6 +262,8 @@ impl NekoState { self.absorb(data); } + /// Permutes and zeros a portion of the cipher state in order to provide forward secrecy. + /// The amount of bits zeroed is dependent on the cipher strength (128/256). pub fn ratchet(&mut self) { self.begin_op(ops::RATCHET);