lib.rs

Overview

This file provides abstractions and implementations for network transport, security credentials, and TLS certificate handling within the system. It defines traits for network transports, listeners, connections, and incoming requests, enabling asynchronous communication over secure channels. The file also manages cryptographic credentials, including self-signed certificates and trust verification, using Ed25519 keys and TLS certificates.

The primary focus is on secure network communication by leveraging cryptographic identities, certificate verification, and extensible transport mechanisms.

Modules and Imports

• msquic, quinn, server, wtransport: Public modules exposing various network transport implementations or server components.

• pkcs12, tls, utils: Internal modules handling TLS certificate management, PKCS#12 format parsing, and utility functions.

• Re-exports from ed25519_dalek for cryptographic primitives like SigningKey, VerifyingKey, and related types.

• Re-exports from tls module for certificate creation, verification, and key resolution.

Structs

CertHash

pub struct CertHash(pub [u8; 32]);

• Represents a SHA-256 digest of a TLS certificate (CertificateDer).

• Implements From<&CertificateDer> for easy creation from a certificate.

• Implements Display to convert the hash into a hexadecimal string.

Usage Example:

let cert_hash = CertHash::from(&certificate_der);
println!("Cert hash: {}", cert_hash);

NetCredential

pub struct NetCredential {
    pub my_key: PrivateKeyDer<'static>,
    pub my_certs: Vec<CertificateDer<'static>>,
    pub trusted_cert_hashes: HashSet<CertHash>,
    pub trusted_pubkeys: HashSet<VerifyingKey>,
}

• Holds the private key and certificate chain used by a network endpoint.

• Contains sets of trusted certificate hashes and public keys for verifying peers.

• Provides methods for generating self-signed credentials, obtaining identities, and verifying certificates.

Methods

• generate_self_signed(subjects: Option<Vec<String>>, ed_signing_keys: &[SigningKey]) -> anyhow::Result<Self>

  Generates a self-signed TLS certificate and private key using Ed25519 signing keys.

  Parameters:

  • subjects: Optional list of certificate subject names.

  • ed_signing_keys: Slice of Ed25519 signing keys used for signing.

  Returns: A new NetCredential with the generated key and certificate.

• identity(&self) -> String

  Returns the full hexadecimal string representation of the SHA-256 hash of the first certificate in my_certs.

• identity_prefix(&self) -> String

  Returns the first 4 characters of the identity string, useful for concise display.

• verify_cert(&self, cert: &CertificateDer<'static>) -> Result<(), StartError>

  Verifies a peer certificate against the trusted certificate hashes and public keys.

• verify_cert_hash_and_pubkeys(&self, hash: &CertHash, pubkeys: &[VerifyingKey]) -> Result<(), StartError>

  Verifies a certificate hash and associated public keys against trusted sets.

• my_cert_pubkeys(&self) -> anyhow::Result<HashSet<VerifyingKey>>

  Extracts and returns the public keys from the stored certificates.

• clone(&self) -> Self

  Implements deep cloning of NetCredential, including cloning the private key.

Usage Example:

let credential = NetCredential::generate_self_signed(None, &my_signing_keys)?;
println!("My identity: {}", credential.identity());

Traits

NetTransport

#[async_trait]
pub trait NetTransport: Clone + Send + Sync {
    type Connection: NetConnection;
    type Listener: NetListener<Connection = Self::Connection>;

    async fn create_listener(
        &self,
        bind_addr: SocketAddr,
        alpn_supported: &[&str],
        credential: NetCredential,
    ) -> anyhow::Result<Self::Listener>;

    async fn connect(
        &self,
        addr: SocketAddr,
        alpn_preferred: &[&str],
        credential: NetCredential,
    ) -> anyhow::Result<Self::Connection>;
}

• Abstracts a network transport capable of creating listeners and establishing connections.

• Supports asynchronous operations.

• Uses NetCredential to supply cryptographic credentials.

• Supports ALPN (Application-Layer Protocol Negotiation) to specify or negotiate protocols.

NetListener

#[async_trait]
pub trait NetListener: Send + Sync {
    type Connection: NetConnection;
    type IncomingRequest: NetIncomingRequest<Connection = Self::Connection>;

    async fn accept(&self) -> anyhow::Result<Self::IncomingRequest>;
}

• Represents a network listener accepting incoming connection requests.

• Asynchronously accepts incoming connection requests wrapped in NetIncomingRequest.

NetIncomingRequest

#[async_trait]
pub trait NetIncomingRequest: Send + Sync {
    type Connection: NetConnection;

    fn remote_addr(&self) -> anyhow::Result<SocketAddr>;

    async fn accept(self) -> anyhow::Result<Self::Connection>;
}

• Represents an incoming connection request that can be accepted or rejected.

• Provides the remote address of the connecting peer.

NetConnection

#[async_trait]
pub trait NetConnection: Clone + Send + Sync {
    fn local_addr(&self) -> SocketAddr;
    fn remote_addr(&self) -> SocketAddr;

    fn local_identity(&self) -> String;
    fn remote_identity(&self) -> String;

    fn remote_certificate(&self) -> Option<CertificateDer<'static>>;

    fn alpn_negotiated(&self) -> Option<String>;

    fn alpn_negotiated_is(&self, protocol: &str) -> bool;

    async fn send(&self, data: &[u8]) -> anyhow::Result<()>;
    async fn recv(&self) -> anyhow::Result<(Vec<u8>, Duration)>;
    async fn close(&self, code: usize);
    async fn watch_close(&self);
}

• Represents an established network connection.

• Provides access to local and remote socket addresses.

• Provides unique identities of local and remote endpoints (usually TLS cert hashes).

• Allows sending and receiving data asynchronously.

• Supports closing the connection and watching for connection closure events.

• Supports querying negotiated ALPN protocol and checking if a specific protocol was negotiated.

Important Implementation Details

• Certificates are handled in DER format (CertificateDer), enabling compatibility with TLS libraries.

• Certificate hashes use SHA-256 to uniquely identify certificates.

• Trust verification uses sets of trusted certificate hashes and verifying public keys to validate peers.

• Self-signed certificates can be generated with Ed25519 keys, facilitating identity creation without external CAs.

• The asynchronous traits use async_trait for async function support.

• NetTransport is designed to be clonable to enable multiple concurrent listeners or connections with similar configurations.

• ALPN support allows protocol negotiation between peers during connection establishment.

Interaction with Other Components

• The file imports and re-exports cryptographic primitives (SigningKey, VerifyingKey) from ed25519_dalek and TLS certificate utilities from the internal tls module.

• The msquic and quinn modules provide concrete implementations of the NetTransport trait using different QUIC libraries.

• The server and wtransport modules likely build on top of these abstractions to implement server-side networking and WebTransport support.

• The TLS certificate functions (generate_self_signed_cert, verify_cert, etc.) are used within NetCredential to manage and verify credentials.

• The traits define a flexible abstraction layer allowing multiple transport protocols and implementations to coexist.

Visual Diagram

classDiagram
class CertHash {
+[u8; 32] hash
+from(&CertificateDer)
+fmt(&self)
}
class NetCredential {
+my_key: PrivateKeyDer
+my_certs: Vec<CertificateDer>
+trusted_cert_hashes: HashSet<CertHash>
+trusted_pubkeys: HashSet<VerifyingKey>
+generate_self_signed()
+identity()
+identity_prefix()
+verify_cert()
+verify_cert_hash_and_pubkeys()
+my_cert_pubkeys()
}
class NetTransport {
<<trait>>
+create_listener()
+connect()
}
class NetListener {
<<trait>>
+accept()
}
class NetIncomingRequest {
<<trait>>
+remote_addr()
+accept()
}
class NetConnection {
<<trait>>
+local_addr()
+remote_addr()
+local_identity()
+remote_identity()
+remote_certificate()
+alpn_negotiated()
+alpn_negotiated_is()
+send()
+recv()
+close()
+watch_close()
}
NetTransport --> NetListener : creates
NetListener --> NetIncomingRequest : accepts
NetIncomingRequest --> NetConnection : accepts