Module diem_crypto::noise

Noise is a protocol framework which we use in Diem to encrypt and authenticate communications between nodes of the network.

This file implements a stripped-down version of Noise_IK_25519_AESGCM_SHA256. This means that only the parts that we care about (the IK handshake) are implemented.

Note that to benefit from hardware support for AES, you must build this crate with the following flags: RUSTFLAGS="-Ctarget-cpu=skylake -Ctarget-feature=+aes,+sse2,+sse4.1,+ssse3".

Usage example:

use diem_crypto::{noise, x25519, traits::*};
use rand::prelude::*;

let mut rng = rand::thread_rng();
let initiator_static = x25519::PrivateKey::generate(&mut rng);
let responder_static = x25519::PrivateKey::generate(&mut rng);
let responder_public = responder_static.public_key();

let initiator = noise::NoiseConfig::new(initiator_static);
let responder = noise::NoiseConfig::new(responder_static);

let payload1 = b"the client can send an optional payload in the first message";
let mut buffer = vec![0u8; noise::handshake_init_msg_len(payload1.len())];
let initiator_state = initiator
  .initiate_connection(&mut rng, b"prologue", responder_public, Some(payload1), &mut buffer)?;

let payload2 = b"the server can send an optional payload as well as part of the handshake";
let mut buffer2 = vec![0u8; noise::handshake_resp_msg_len(payload2.len())];
let (received_payload, mut responder_session) = responder
  .respond_to_client_and_finalize(&mut rng, b"prologue", &buffer, Some(payload2), &mut buffer2)?;
assert_eq!(received_payload.as_slice(), &payload1[..]);

let (received_payload, mut initiator_session) = initiator
  .finalize_connection(initiator_state, &buffer2)?;
assert_eq!(received_payload.as_slice(), &payload2[..]);

let message_sent = b"hello world".to_vec();
let mut buffer = message_sent.clone();
let auth_tag = initiator_session
  .write_message_in_place(&mut buffer)?;
buffer.extend_from_slice(&auth_tag);

let received_message = responder_session
  .read_message_in_place(&mut buffer)?;

assert_eq!(received_message, message_sent.as_slice());

Structs

InitiatorHandshakeState

Refer to the Noise protocol framework specification in order to understand these fields.

NoiseConfig

A key holder structure used for both initiators and responders.

NoiseSession

A NoiseSession is produced after a successful Noise handshake, and can be use to encrypt and decrypt messages to the other peer.

ResponderHandshakeState

Refer to the Noise protocol framework specification in order to understand these fields.

Enums

NoiseError

A NoiseError enum represents the different types of error that noise can return to users of the crate

Constants

AES_GCM_TAGLEN

The authentication tag length of AES-GCM.

MAX_SIZE_NOISE_MSG

A noise message cannot be larger than 65535 bytes as per the specification.

Functions

decrypted_len

A handy const fn to get the size of a plaintext from a ciphertext size

encrypted_len

A handy const fn to get the expanded size of a plaintext after encryption

handshake_init_msg_len

A handy const fn to get the size of the first handshake message

handshake_resp_msg_len

A handy const fn to get the size of the second handshake message