Rust · Noise Keys

Noise Keys

use ucall::Security;use ucall::*; 1.0.0-rc.1 · 60202332

Interfaces and calls can run over the Noise protocol instead of plain TCP, authenticating both sides by 32-byte Curve25519 static keys.

use std::sync::Arc;
use ucall::*;

let (server_private_key, server_public_key) = generate_noise_keypair()?;
let (client_private_key, _) = generate_noise_keypair()?;
let client_public_key = derive_noise_public_key(&client_private_key);

let sealed = Interface::new("0.0.0.0:8546")
    .security(Security::NoiseXX, server_private_key)
    .peer_authorizer(move |key: &NoiseKey| *key == client_public_key);
let server = Server::new(&[sealed])?;

let client = Client::new(ClientOptions {
    connections: 1,
    noise_private_key: Some(client_private_key),
    peer_authorizer: Some(Arc::new(move |key: &NoiseKey| *key == server_public_key)),
    ..Default::default()
})?;

generate_noise_keypair draws from the operating system’s entropy and fails with Status::IO when it is refused. derive_noise_public_key recovers the public half of a stored private key, which peers compare in their authorizers. Under Noise XX both sides learn each other’s key during the handshake, so both need an authorizer; Noise IK has the client name the server’s key in advance through ClientCallOptions::noise_peer_key. Noise KK has both sides know each other in advance: the interface admits the one key Interface::noise_peer_key names, and the call presents ClientCallOptions::noise_private_key or the client’s own key. An http+noise:// URL implies Noise XX, and a handler reads the client’s authenticated key through Request::peer.

API

Types

NoiseKeyA 32-byte Curve25519 key, private or public, as every Noise handshake takes it.
lib.rs:467 ↗
pub type NoiseKey = [u8; 32];
PeerAuthorizerDecides whether a peer presenting an authenticated static key may proceed past the handshake.
lib.rs:835 ↗
pub type PeerAuthorizer = dyn Fn(&NoiseKey) -> bool + Send + Sync;

A server runs it on the polling thread completing the handshake, and a client on its owner thread inside Client::take_completed. A panic rejects the peer.

EnumSecurityThe transport security of a server interface or a client call.
types.rs:812 ↗
pub enum Security

Values

NonePlain TCP.
NoiseXXNoise XX: both parties learn each other's static keys during the handshake.
NoiseIKNoise IK: the client knows the server's static key in advance.
NoiseKKNoise KK: both parties know each other's static keys in advance; client calls only.

Implements

Clone, Copy, StructuralPartialEq, PartialEq, Eq, Debug, Hash, Default

Functions

generate_noise_keypairDraws a fresh (private_key, public_key) pair from the operating system's entropy.
lib.rs:480 ↗
pub fn generate_noise_keypair() -> Result<(NoiseKey, NoiseKey)>

Fails with Status::IO when the operating system refuses entropy.

use ucall::{derive_noise_public_key, generate_noise_keypair};

let (private_key, public_key) = generate_noise_keypair()?;
assert_eq!(derive_noise_public_key(&private_key), public_key);
derive_noise_public_keyThe public key of private_key, as a PeerAuthorizer on the other side sees it.
lib.rs:494 ↗
pub fn derive_noise_public_key(private_key: &NoiseKey) -> NoiseKey