Struct noise_protocol::HandshakeState

pub struct HandshakeState<D: DH, C: Cipher, H: Hash> { /* private fields */ }

Noise handshake state.

Implementations

impl<D, C, H> HandshakeState<D, C, H>where
    D: DH,
    C: Cipher,
    H: Hash,

pub fn new<P>(
    pattern: HandshakePattern,
    is_initiator: bool,
    prologue: P,
    s: Option<D::Key>,
    e: Option<D::Key>,
    rs: Option<D::Pubkey>,
    re: Option<D::Pubkey>
) -> Selfwhere
    P: AsRef<[u8]>,

Initialize a handshake state.

If e is None, a new ephemeral key will be generated if necessary when write_message.

Setting Explicit Ephemeral Key

An explicit e should only be specified for testing purposes, or in fallback patterns. If you do pass in an explicit e, HandshakeState will use it as is and will not generate new ephemeral keys in write_message.

pub fn get_next_message_overhead(&self) -> usize

Calculate the size overhead of the next message.

Panics

If these is no more message to read/write, i.e., if the handshake is already completed.

pub fn write_message_vec(&mut self, payload: &[u8]) -> Result<Vec<u8>, Error>

Like write_message, but returns a Vec.

pub fn write_message(
    &mut self,
    payload: &[u8],
    out: &mut [u8]
) -> Result<(), Error>

Takes a payload and write the generated handshake message to out.

Error Kinds

• DH: DH operation failed.
• NeedPSK: A PSK token is encountered but none is available.

Panics

• If a required static key is not set.

• If out.len() != payload.len() + self.get_next_message_overhead().

• If it is not our turn to write.

• If the handshake has already completed.

pub fn read_message(&mut self, data: &[u8], out: &mut [u8]) -> Result<(), Error>

Takes a handshake message, process it and update our internal state, and write the encapsulated payload to out.

Error Kinds

• DH: DH operation failed.
• NeedPSK: A PSK token is encountered but none is available.
• Decryption: Decryption failed.

Error Recovery

If read_message fails, the whole HandshakeState may be in invalid state and should not be used to read or write any further messages. (But get_re() and get_rs() is allowed.) In case error recovery is desirable, clone the HandshakeState before calling read_message.

Panics

• If out.len() + self.get_next_message_overhead() != data.len().

  (Notes that this implies data.len() >= overhead.)

• If a required static key is not set.

• If it is not our turn to read.

• If the handshake has already completed.

pub fn read_message_vec(&mut self, data: &[u8]) -> Result<Vec<u8>, Error>

Similar to read_message, but returns result as a Vec.

In addition to possible errors from read_message, TooShort may be returned.

pub fn push_psk(&mut self, psk: &[u8])

Push a PSK to the PSK-queue.

Panics

If the PSK-queue becomes longer than 4.

pub fn completed(&self) -> bool

Whether handshake has completed.

pub fn get_hash(&self) -> &[u8]

Get handshake hash. Useful for e.g., channel binding.

pub fn get_ciphers(&self) -> (CipherState<C>, CipherState<C>)

Get ciphers that can be used to encrypt/decrypt further messages. The first CipherState is for initiator to responder, and the second for responder to initiator.

Should be called after handshake is completed.

pub fn get_rs(&self) -> Option<D::Pubkey>

Get remote static pubkey, if available.

pub fn get_re(&self) -> Option<D::Pubkey>

Get remote semi-ephemeral pubkey.

Returns None if we do not know.

Useful for noise-pipes.

pub fn get_is_initiator(&self) -> bool

Get whether this HandshakeState is created as initiator.

pub fn get_pattern(&self) -> &HandshakePattern

Get handshake pattern this HandshakeState uses.

Trait Implementations

impl<D, C, H> Clone for HandshakeState<D, C, H>where
    D: DH,
    C: Cipher,
    H: Hash,

fn clone(&self) -> Self

Returns a copy of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.