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;