tlspuffin/lib.rs
1//! TODO: Write intro: <https://github.com/tlspuffin/tlspuffin/issues/94>
2//!
3//! ### Used protocol and cryptographic libraries
4//!
5//! In order to easily implement concrete functions, we use several libraries which provide us with
6//! predefined encoders for TLS packets, cryptographic primitives, as well as higher level
7//! cryptographic operations specific for TLS.
8//!
9//! We forked the [rustls](https://github.com/ctz/rustls) library for cryptographic operations like deriving secrets. We also use it to encode and decode TLS messages.
10//!
11//! The cryptographic library [ring](https://github.com/briansmith/ring) allows us to use the derived secrets to encrypt and decrypt TLS messages.
12//! # Example
13//!
14//! ```rust
15//! use puffin::agent::{AgentDescriptor, AgentName};
16//! use puffin::algebra::signature::Signature;
17//! use puffin::algebra::{DYTerm, Term};
18//! use puffin::input_action;
19//! use puffin::trace::{
20//! Action, InputAction, OutputAction, Query, Source, Step, Trace, TraceContext,
21//! };
22//! use tlspuffin::protocol::TLSVersion::*;
23//! use tlspuffin::protocol::{TLSDescriptorConfig, TLSProtocolTypes};
24//! use tlspuffin::query::TlsQueryMatcher;
25//! use tlspuffin::tls::fn_impl::fn_client_hello;
26//! use tlspuffin::tls::rustls::msgs::enums::{
27//! CipherSuite, Compression, HandshakeType, ProtocolVersion,
28//! };
29//! use tlspuffin::tls::rustls::msgs::handshake::{ClientExtension, Random, SessionID};
30//!
31//! let client: AgentName = AgentName::first();
32//! let server: AgentName = client.next();
33//!
34//! let trace = Trace::<TLSProtocolTypes> {
35//! prior_traces: vec![],
36//! descriptors: vec![
37//! TLSDescriptorConfig::new_client(client, V1_3),
38//! TLSDescriptorConfig::new_server(server, V1_3),
39//! ],
40//! steps: vec![
41//! OutputAction::new_step(client),
42//! // Client: Hello Client -> Server
43//! Step {
44//! agent: server,
45//! action: Action::Input(input_action! {
46//! (Term::from(DYTerm::Application(
47//! Signature::new_function(&fn_client_hello),
48//! vec![
49//! Term::from(DYTerm::Variable(Signature::new_var_with_type::<
50//! ProtocolVersion,
51//! _,
52//! >(
53//! Some(Source::Agent(client)),
54//! Some(TlsQueryMatcher::Handshake(Some(HandshakeType::ClientHello))),
55//! 0,
56//! ))),
57//! Term::from(DYTerm::Variable(
58//! Signature::new_var_with_type::<Random, _>(
59//! Some(Source::Agent(client)),
60//! Some(TlsQueryMatcher::Handshake(Some(
61//! HandshakeType::ClientHello,
62//! ))),
63//! 0,
64//! ),
65//! )),
66//! Term::from(DYTerm::Variable(Signature::new_var_with_type::<
67//! SessionID,
68//! _,
69//! >(
70//! Some(Source::Agent(client)),
71//! Some(TlsQueryMatcher::Handshake(Some(HandshakeType::ClientHello))),
72//! 0,
73//! ))),
74//! Term::from(DYTerm::Variable(Signature::new_var_with_type::<
75//! Vec<CipherSuite>,
76//! _,
77//! >(
78//! Some(Source::Agent(client)),
79//! Some(TlsQueryMatcher::Handshake(Some(HandshakeType::ClientHello))),
80//! 0,
81//! ))),
82//! Term::from(DYTerm::Variable(Signature::new_var_with_type::<
83//! Vec<Compression>,
84//! _,
85//! >(
86//! Some(Source::Agent(client)),
87//! Some(TlsQueryMatcher::Handshake(Some(HandshakeType::ClientHello))),
88//! 0,
89//! ))),
90//! Term::from(DYTerm::Variable(Signature::new_var_with_type::<
91//! Vec<ClientExtension>,
92//! _,
93//! >(
94//! Some(Source::Agent(client)),
95//! Some(TlsQueryMatcher::Handshake(Some(HandshakeType::ClientHello))),
96//! 0,
97//! ))),
98//! ],
99//! )))
100//! }),
101//! },
102//! // further steps here
103//! ],
104//! ..Default::default()
105//! };
106//! ```
107//!
108//! # Example with `term!` macro
109//! ```rust
110//! use puffin::agent::AgentName;
111//! use puffin::algebra::Term;
112//! use puffin::term;
113//! use puffin::trace::Source;
114//! use tlspuffin::protocol::TLSProtocolTypes;
115//! use tlspuffin::query::TlsQueryMatcher;
116//! use tlspuffin::tls::fn_impl::fn_client_hello;
117//! use tlspuffin::tls::rustls::msgs::enums::{
118//! CipherSuite, Compression, HandshakeType, ProtocolVersion,
119//! };
120//! use tlspuffin::tls::rustls::msgs::handshake::{ClientExtension, Random, SessionID};
121//!
122//! let client = AgentName::first();
123//! let term: Term<TLSProtocolTypes> = term! {
124//! fn_client_hello(
125//! ((client, 0)/ProtocolVersion),
126//! ((client, 0)/Random),
127//! ((client, 0)/SessionID),
128//! ((client, 0)/Vec<CipherSuite>),
129//! ((client, 0)/Vec<Compression>),
130//! ((client, 0)/Vec<ClientExtension>)
131//! )
132//! };
133//! ```
134
135pub mod claims;
136pub mod debug;
137pub mod protocol;
138pub mod put;
139pub mod put_registry;
140pub mod query;
141pub mod static_certs;
142pub mod tcp;
143pub mod tls;
144
145#[cfg(feature = "test-utils")]
146pub mod test_utils;