tlsn/
lib.rs

1//! TLSNotary protocol implementation.
2//!
3//! This crate provides the core protocol for generating and verifying proofs
4//! of TLS sessions. A prover can demonstrate to a verifier that specific data
5//! was exchanged with a TLS server, without revealing the full transcript.
6//!
7//! # Overview
8//!
9//! The protocol involves two parties:
10//!
11//! - **Prover** ([`Prover`](prover::Prover)): connects to a TLS server and
12//!   generates proofs about the session.
13//! - **Verifier** ([`Verifier`](verifier::Verifier)): collaborates with the
14//!   prover during the TLS session and verifies the resulting proofs.
15//!
16//! Both parties communicate through an established [`Session`].
17//!
18//! # Workflow
19//!
20//! The protocol has two main phases:
21//!
22//! **Commitment**: The prover and verifier collaborate to construct a TLS
23//! transcript commitment from the prover's communication with a TLS server.
24//! This authenticates the transcript for the verifier, without the verifier
25//! learning the contents.
26//!
27//! **Selective Disclosure**: The prover selectively reveals portions of the
28//! committed transcript to the verifier, proving statements about the data
29//! exchanged with the server.
30//!
31//! ## Steps
32//!
33//! 1. Establish a communication channel between prover and verifier.
34//! 2. Create a [`Session`] on each side from the channel.
35//! 3. Create a [`Prover`](prover::Prover) or [`Verifier`](verifier::Verifier).
36//! 4. Run the commitment phase: the prover connects to the TLS server and
37//!    exchanges data to obtain a commitment to the TLS transcript.
38//! 5. (Optional) Perform selective disclosure: the prover provably reveals
39//!    selected data to the verifier.
40//!
41//! # Performance
42//!
43//! The MPC-TLS protocol is highly interactive: prover and verifier exchange
44//! many small messages, and each one is on the critical path. On such traffic,
45//! Nagle's algorithm — enabled by default on TCP sockets — coalesces small
46//! writes and waits for outstanding ACKs before sending, adding a round-trip's
47//! worth of delay to each exchange and significantly slowing the protocol.
48//!
49//! For this reason you should **disable Nagle's algorithm** by enabling
50//! `TCP_NODELAY` on every TCP socket you hand to this crate, namely:
51//!
52//! - the prover ↔ verifier channel passed to [`Session::new`];
53//! - the connection to the TLS server passed to
54//!   [`Prover::connect`](prover::Prover::connect) (MPC mode);
55//! - the connection to the TLS server passed to
56//!   [`Verifier::run`](verifier::Verifier::run) (proxy mode).
57//!
58//! With [`tokio`](https://docs.rs/tokio) this is done via
59//! [`TcpStream::set_nodelay`](https://docs.rs/tokio/latest/tokio/net/struct.TcpStream.html#method.set_nodelay):
60//!
61//! ```ignore
62//! let socket = tokio::net::TcpStream::connect(addr).await?;
63//! socket.set_nodelay(true)?;
64//! ```
65//!
66//! This setting has no effect on non-TCP transports (e.g. WebSocket relays or
67//! in-memory duplex streams).
68
69#![deny(missing_docs, unreachable_pub, unused_must_use)]
70#![deny(clippy::all)]
71#![forbid(unsafe_code)]
72
73mod deps;
74mod error;
75pub(crate) mod ghash;
76pub(crate) mod map;
77pub(crate) mod msg;
78pub mod prover;
79mod proxy;
80mod session;
81pub(crate) mod tag;
82pub(crate) mod transcript_internal;
83pub mod verifier;
84
85pub use error::Error;
86pub use rangeset;
87pub use session::{Session, SessionDriver, SessionHandle};
88pub use tlsn_attestation as attestation;
89pub use tlsn_core::{config, connection, hash, transcript, webpki};
90pub use tlsn_mux::Stream;
91
92/// Result type.
93pub type Result<T, E = Error> = core::result::Result<T, E>;
94
95use mpc_tls::SessionKeys;
96use semver::Version;
97use std::sync::LazyLock;
98use tlsn_core::{
99    config::tls_commit::{TlsCommitConfig, mpc::MpcTlsConfig, proxy::ProxyTlsConfig},
100    transcript::TlsTranscript,
101};
102
103// Package version.
104pub(crate) static VERSION: LazyLock<Version> = LazyLock::new(|| {
105    Version::parse(env!("CARGO_PKG_VERSION")).expect("cargo pkg version should be a valid semver")
106});
107
108// Prefix for the proxy stream id between prover and verifier.
109pub(crate) const PROXY_STREAM_PREFIX: &[u8] = b"proxy_stream";
110
111/// The party's role in the TLSN protocol.
112///
113/// A Notary is classified as a Verifier.
114#[derive(Debug, Clone, Copy, PartialEq, Eq)]
115pub(crate) enum Role {
116    /// The prover.
117    Prover,
118    /// The verifier.
119    Verifier,
120}
121
122/// Output of a TLS session.
123pub(crate) struct TlsOutput {
124    pub(crate) keys: SessionKeys,
125    pub(crate) tls_transcript: TlsTranscript,
126}
127
128/// Protocol variant.
129pub trait ProtocolConfig: Clone + Into<TlsCommitConfig> + sealed::Sealed {
130    /// TLS commitment protocol.
131    type Commit;
132}
133
134impl ProtocolConfig for MpcTlsConfig {
135    type Commit = Mpc;
136}
137
138impl ProtocolConfig for ProxyTlsConfig {
139    type Commit = Proxy;
140}
141
142/// MPC-TLS commitment protocol.
143#[derive(Debug)]
144pub struct Mpc {}
145
146/// Proxy-TLS commitment protocol.
147#[derive(Debug)]
148pub struct Proxy {}
149
150mod sealed {
151    pub trait Sealed {}
152
153    impl Sealed for super::MpcTlsConfig {}
154    impl Sealed for super::ProxyTlsConfig {}
155}
tlsn/lib.rs

tlsn/
lib.rs
