Enum snow::Session

pub enum Session {
    Handshake(HandshakeState),
    Transport(TransportState),
}

A state machine for the entire Noise session.

Enums provide a convenient interface as it's how Rust implements union structs, meaning this is a sized object.

Variants

Handshake(HandshakeState)Transport(TransportState)

Methods

impl Session

pub fn is_payload_encrypted(&self) -> bool

If the payload will be encrypted or not. In a future version of Snow, this interface may change to more proactively prevent unauthenticated, plaintext payloads during handshakes.

See Payload Security Properties for more information.

pub fn is_handshake_finished(&self) -> bool

True if the handshake is finished and the Session state machine is ready to be transitioned to transport mode. This function also returns a vacuous true if already in transport mode.

Examples

let mut session = Builder::new("Noise_NN_25519_AESGCM_SHA256".parse()?)
    .build_initiator()?;

if (session.is_handshake_finished()) {
    session = session.into_transport_mode()?;
}

pub fn is_initiator(&self) -> bool

pub fn write_message(     &mut self,     payload: &[u8],     output: &mut [u8] ) -> Result<usize, SnowError>

Construct a message from payload (and pending handshake tokens if in handshake state), and writes it to the output buffer.

Returns the size of the written payload.

Errors

Will result in SnowError::Input if the size of the output exceeds the max message length in the Noise Protocol (65535 bytes).

pub fn read_message(     &mut self,     input: &[u8],     payload: &mut [u8] ) -> Result<usize, SnowError>

Reads a noise message from input

Returns the size of the payload written to payload.

Errors

Will result in SnowError::Decrypt if the contents couldn't be decrypted and/or the authentication tag didn't verify.

Panics

This function will panic if there is no key, or if there is a nonce overflow.

pub fn rekey(     &mut self,     initiator: Option<&[u8]>,     responder: Option<&[u8]> ) -> Result<(), SnowError>

Set a new key for the one or both of the initiator-egress and responder-egress symmetric ciphers.

Errors

Will result in SnowError::State if not in transport mode.

pub fn receiving_nonce(&self) -> Result<u64, SnowError>

Get the forthcoming inbound nonce value.

Errors

Will result in SnowError::State if not in transport mode.

pub fn sending_nonce(&self) -> Result<u64, SnowError>

Get the forthcoming outbound nonce value.

Errors

Will result in SnowError::State if not in transport mode.

pub fn get_remote_static(&self) -> Option<&[u8]>

Get the remote static key that was possibly encrypted in the first payload.

Returns a slice of length Dh.pub_len() (i.e. DHLEN for the chosen DH function).

pub fn get_handshake_hash(&self) -> Result<&[u8], SnowError>

Get the handshake hash.

Returns a slice of length Hasher.hash_len() (i.e. HASHLEN for the chosen Hash function).

pub fn set_receiving_nonce(&mut self, nonce: u64) -> Result<(), SnowError>

Set the forthcoming incoming nonce value.

Errors

Will result in SnowError::State if not in transport mode.

pub fn set_psk(&mut self, location: usize, key: &[u8]) -> Result<(), SnowError>

Set the preshared key at the specified location. It is up to the caller to correctly set the location based on the specified handshake - Snow won't stop you from placing a PSK in an unused slot.

Errors

Will result in SnowError::Input if the PSK is not the right length or the location is out of bounds. Will result in SnowError::State if in transport mode.

pub fn into_transport_mode(self) -> Result<Self, SnowError>

Transition the session into transport mode. This can only be done once the handshake has finished.

Consumes the previous state, and returns the new transport state object, thereby freeing any material only used during the handshake phase.

Errors

Will result in SnowError::State if the handshake is not finished.

Examples

let mut session = Builder::new("Noise_NN_25519_AESGCM_SHA256".parse()?)
                  .build_initiator()?;

// ... complete handshake ...

session = session.into_transport_mode()?;

Trait Implementations

impl Debug for Session

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.