Struct Keypair 

pub struct Keypair { /* private fields */ }

Keypair holds an Ed25519 keypair used to authenticate a NWEP node.

The keypair is stored in a heap-allocated Box so that its memory address remains stable when the Keypair value is moved. The C library keeps a raw pointer to the keypair for TLS signing during handshakes; if the data were allowed to move, that pointer would become dangling.

Key material is zeroed on drop via [nwep_keypair_clear].

Examples

use nwep::Keypair;
nwep::init().unwrap();
let kp = Keypair::generate().unwrap();
println!("node id: {}", kp.node_id().unwrap());

Implementations

impl Keypair

pub fn generate() -> Result<Self, Error>

generate creates a new Ed25519 keypair from OS-provided randomness.

Errors

Returns an Error if the underlying C library call fails.

Examples found in repository

examples/server.rs (line 25)

fn load_or_generate_keypair(path: &str) -> Result<Keypair, Box<dyn std::error::Error>> {
    match fs::read_to_string(path) {
        Ok(contents) => {
            let hex = contents.trim();
            if hex.len() != 64 {
                return Err(format!("invalid key file {path}: expected 64 hex chars").into());
            }
            let bytes: Vec<u8> = (0..32)
                .map(|i| u8::from_str_radix(&hex[i * 2..i * 2 + 2], 16))
                .collect::<Result<_, _>>()?;
            let mut seed = [0u8; 32];
            seed.copy_from_slice(&bytes);
            Ok(Keypair::from_seed(&seed)?)
        }
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
            let kp = Keypair::generate()?;
            let hex: String = kp.seed().iter().map(|b| format!("{b:02x}")).collect();
            fs::write(path, format!("{hex}\n"))
                .map_err(|e| format!("saving key file: {e}"))?;
            Ok(kp)
        }
        Err(e) => Err(e.into()),
    }
}

examples/client.rs (line 24)

fn main() {
    let url = std::env::args().nth(1).unwrap_or_else(|| {
        eprintln!("usage: client <web://url/path>");
        process::exit(1);
    });

    nwep::init().unwrap_or_else(|e| {
        eprintln!("init: {e}");
        process::exit(1);
    });

    nwep::log::set_level(nwep::log::LogLevel::Warn);
    nwep::log::set_stderr(true);

    let parsed = Url::parse(&url).unwrap_or_else(|e| {
        eprintln!("parse url: {e}");
        process::exit(1);
    });
    let path = if parsed.path.is_empty() { "/".to_string() } else { parsed.path.clone() };

    let keypair = Keypair::generate().unwrap_or_else(|e| {
        eprintln!("keygen: {e}");
        process::exit(1);
    });

    let client = ClientBuilder::new()
        .connect(keypair, &url)
        .unwrap_or_else(|e| {
            eprintln!("connect: {e}");
            process::exit(1);
        });

    let resp = client.get(&path).unwrap_or_else(|e| {
        eprintln!("get: {e}");
        process::exit(1);
    });

    println!("{}", resp.status);
    println!("{}", String::from_utf8_lossy(&resp.body));

    client.close();
}

pub fn from_seed(seed: &[u8; 32]) -> Result<Self, Error>

from_seed derives an Ed25519 keypair from a 32-byte seed.

The seed is the first 32 bytes of the standard 64-byte Ed25519 private key representation (seed || pubkey). Passing the same seed always produces the same keypair.

Errors

Returns an Error if the C library call fails.

Examples found in repository

examples/server.rs (line 22)

fn load_or_generate_keypair(path: &str) -> Result<Keypair, Box<dyn std::error::Error>> {
    match fs::read_to_string(path) {
        Ok(contents) => {
            let hex = contents.trim();
            if hex.len() != 64 {
                return Err(format!("invalid key file {path}: expected 64 hex chars").into());
            }
            let bytes: Vec<u8> = (0..32)
                .map(|i| u8::from_str_radix(&hex[i * 2..i * 2 + 2], 16))
                .collect::<Result<_, _>>()?;
            let mut seed = [0u8; 32];
            seed.copy_from_slice(&bytes);
            Ok(Keypair::from_seed(&seed)?)
        }
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
            let kp = Keypair::generate()?;
            let hex: String = kp.seed().iter().map(|b| format!("{b:02x}")).collect();
            fs::write(path, format!("{hex}\n"))
                .map_err(|e| format!("saving key file: {e}"))?;
            Ok(kp)
        }
        Err(e) => Err(e.into()),
    }
}

pub fn from_privkey(privkey: &[u8; 64]) -> Result<Self, Error>

from_privkey reconstructs a keypair from a 64-byte Ed25519 private key.

The 64-byte private key is the concatenation seed || pubkey. The public key is re-derived from the seed by the C library and the provided public-key suffix is used for validation.

Errors

Returns an Error if the key material is invalid or the C library call fails.

pub fn public_key(&self) -> [u8; 32]

public_key returns the 32-byte Ed25519 public key.

pub fn seed(&self) -> [u8; 32]

seed returns the 32-byte Ed25519 seed (first half of the private key).

The seed is sufficient to fully reconstruct the keypair via Keypair::from_seed.

Examples found in repository

examples/server.rs (line 26)

fn load_or_generate_keypair(path: &str) -> Result<Keypair, Box<dyn std::error::Error>> {
    match fs::read_to_string(path) {
        Ok(contents) => {
            let hex = contents.trim();
            if hex.len() != 64 {
                return Err(format!("invalid key file {path}: expected 64 hex chars").into());
            }
            let bytes: Vec<u8> = (0..32)
                .map(|i| u8::from_str_radix(&hex[i * 2..i * 2 + 2], 16))
                .collect::<Result<_, _>>()?;
            let mut seed = [0u8; 32];
            seed.copy_from_slice(&bytes);
            Ok(Keypair::from_seed(&seed)?)
        }
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
            let kp = Keypair::generate()?;
            let hex: String = kp.seed().iter().map(|b| format!("{b:02x}")).collect();
            fs::write(path, format!("{hex}\n"))
                .map_err(|e| format!("saving key file: {e}"))?;
            Ok(kp)
        }
        Err(e) => Err(e.into()),
    }
}

pub fn private_key(&self) -> [u8; 64]

private_key returns the full 64-byte Ed25519 private key (seed || pubkey).

pub fn node_id(&self) -> Result<NodeId, Error>

node_id derives the NodeId for this keypair by hashing the public key.

The NodeId uniquely identifies a node on the network and is embedded in NWEP addresses, ensuring that connection targets cannot be impersonated.

Errors

Returns an Error if the C library call fails.

Examples found in repository

examples/server.rs (line 47)

fn main() {
    nwep::init().unwrap_or_else(|e| {
        eprintln!("init: {e}");
        process::exit(1);
    });

    let key_file = std::env::var("NWEP_KEY_FILE").unwrap_or_else(|_| DEFAULT_KEY_FILE.into());
    let keypair = load_or_generate_keypair(&key_file).unwrap_or_else(|e| {
        eprintln!("keypair: {e}");
        process::exit(1);
    });

    let node_id = keypair.node_id().unwrap_or_else(|e| {
        eprintln!("node_id: {e}");
        process::exit(1);
    });
    eprintln!("node id: {node_id}");

    let mut router = Router::new();
    router.handle_func("/hello", |w: &mut ResponseWriter, _r: &Request| {
        let _ = w.respond("ok", b"hello from nwep-rust");
    });

    let addr = std::env::args().nth(1).unwrap_or_else(|| DEFAULT_ADDR.into());

    let (server, event_loop) = ServerBuilder::new(&addr, keypair)
        .on_connect(|info| eprintln!("connected: {}", info.node_id))
        .on_disconnect(|info, code| eprintln!("disconnected: {} (code {code})", info.node_id))
        .build(router)
        .unwrap_or_else(|e| {
            eprintln!("server: {e}");
            process::exit(1);
        });

    let url = server.url("/hello");
    eprintln!("listening on {}", server.addr());
    println!("{url}"); // URL printed to stdout for the client to read

    if let Err(e) = event_loop.run() {
        eprintln!("server run: {e}");
        process::exit(1);
    }
}

pub fn clear(&mut self)

clear zeroes the key material held by this keypair.

This is called automatically on drop. Call it explicitly when you need to erase key material before the value goes out of scope, for example before passing ownership elsewhere.

Trait Implementations

impl Drop for Keypair

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Keypair