Crate clavis

Clavis is a robust, asynchronous Rust library for establishing secure, encrypted communication channels over network streams. Built on Tokio, it provides high-level abstractions for encrypted packet-based communication while maintaining strong security guarantees through modern cryptographic primitives.

The library implements XChaCha20-Poly1305 encryption and features a type-safe protocol DSL macro for defining custom communication protocols and includes built-in serialization support.

Quick Start

Add Clavis to your Cargo.toml:

[dependencies]
clavis = { git = "https://github.com/pyrohost/clavis" }

Define your protocol using the protocol! macro:

use clavis::protocol;

protocol! {
    pub enum Message {
        Ping(PingPongData),
        Pong(PingPongData),
        Shutdown,
    }
}

#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct PingPongData {
    pub message: String,
}

Create an encrypted connection:

use clavis::{EncryptedStream, EncryptedPacket};
use tokio::net::TcpStream;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let stream = TcpStream::connect("127.0.0.1:7272").await?;
    let mut encrypted = EncryptedStream::new(stream, None).await?;

    let ping = Message::Ping(PingPongData {
        message: "Hello!".into(),
    });
    encrypted.write_packet(&ping).await?;

    if let Message::Pong(pong) = encrypted.read_packet().await? {
        println!("Received pong: {:?}", pong);
    }

    Ok(())
}

Core Types

The main types in Clavis are EncryptedStream for wrapping any AsyncRead + AsyncWrite stream, EncryptedPacket for defining the packet communication interface, and PacketTrait for protocol message serialization.

Configure streams with EncryptedStreamOptions:

use clavis::EncryptedStreamOptions;

let options = EncryptedStreamOptions {
    max_packet_size: 1024 * 1024,  // 1MB packet size limit
    psk: Some(vec![/* 32 bytes of secure random data */]),
};

Modules

prelude

Macros

protocol

Structs

EncryptedStream

Stream wrapper that handles both reading and writing encrypted data

EncryptedStreamOptions

Options for configuring an encrypted stream

Enums

ClavisError

Main error type for the Clavis library

CryptoError

Represents cryptographic errors

CryptoOperation

Represents the type of a cryptographic operation that failed

MessageError

Represents message format and processing errors

StreamError

Represents stream operation errors

Traits

EncryptedPacket

Trait for handling encrypted packet operations

PacketTrait

Type Aliases

ClavisResult

Type alias for Result with ClavisError as the error type