Crate mushi

Mushi is point-to-point QUIC networking with application-defined mutual authentication.

It takes inspiration from Iroh and its APIs are based on WebTransport.

In Mushi, peers are identified by a persistent key pair (ECDSA or ED25519). Connecting to peers is done by DNS or IP addresses (it doesn’t have peer discovery or NAT traversal). Endpoints define a trust policy, which is given a public key (which may be considered an opaque binary blob). Endpoints handle both outgoing (client) and incoming (server) function: typically, a single Endpoint is started per application. Connecting to (or accepting an incoming connection from) another peer creates a Session, which supports sending and receiving unreliable datagrams as well as multiple concurrent unidirectional and bidirectional streams.

All communications are secured with TLS 1.3, with RSA suites explicitly disabled. Endpoints have a key pair (which may be generated on startup), and each connection uses a unique just-in-time short-lived certificate (valid for 2 minutes).

This provides authentication: peers are guaranteed to have control over their own key pair, and it’s unfeasible for an attacker in possession of a public key to obtain the associate private key to be able to successfully spoof an endpoint.

However, it does not provide authorisation. Mushi applications should implement this with one or two layers: the AllowConnection trait provides an application with a simple peer trust policy (“should we allow this peer to connect or be connected to”), and application-specific schemes layered on top of connections. This latter layer is not provided nor facilitated by Mushi (except to the extent that an established session can retrieve its remote peer’s public key using Session::peer_key()): it is the responsibility of application implementers to decide whether authorisation beyond peer public key trust is required, and how.

Example

#[tokio::main]
async fn main() {
    mushi::install_crypto_provider();

    let key = mushi::EndpointKey::generate().unwrap();
    let policy = Arc::new(mushi::AllowAllConnections);
    let end = Endpoint::new("[::]:0", key, policy, None).unwrap();

    let mut session = end.connect("remotepeer.example.com:1310").await.unwrap();
    session.send_datagram("Hello world".into()).unwrap();

    let (mut s, mut r) = session.open_bi().await.unwrap();
    s.write(b"How are you today?").await.unwrap();
    let response = r.read(1024).await.unwrap();
    println!("peer said: {response:x?}");
}

Re-exports

pub use rcgen;

pub use web_transport_quinn as web_transport;

pub use web_transport_quinn::quinn;

pub use web_transport_quinn::quinn::rustls;

Structs

AllowAllConnections

A convenience allower which accepts all public keys.

Endpoint

The main entrypoint to create connections to, and accept connections from other Mushi peers.

EndpointKey

A key pair that identifies and authenticates an Endpoint.

RecvStream

An incoming stream of bytes from the peer.

SendStream

An outgoing stream of bytes to the peer.

Session

A Session, able to accept/create streams and send/recv datagrams.

SubjectPublicKeyInfoDer

A DER-encoded SubjectPublicKeyInfo (SPKI), as specified in RFC 5280.

UnixTime

A timestamp, tracking the number of non-leap seconds since the Unix epoch.

Url

A parsed URL record.

Enums

CertificateError

The ways in which certificate validators can express errors.

Error

A Mushi error.

Constants

SIGSCHEME_ECDSA256

Keys using the ECDSA scheme and the NIST P-256 curve.

SIGSCHEME_ECDSA384

Keys using the ECDSA scheme and the NIST P-384 curve.

SIGSCHEME_ED25519

Small keys using the Ed25519 scheme.

Traits

AllowConnection

The “allower” trait, which defines a peer trust policy.

Functions

install_crypto_provider

Install a default CryptoProvider specialised for Mushi applications.

Type Aliases

SigScheme

A signature scheme for generating and using an EndpointKey.