Crate tlspuffin

TODO: Write intro: https://github.com/tlspuffin/tlspuffin/issues/94

Used protocol and cryptographic libraries

In order to easily implement concrete functions, we use several libraries which provide us with predefined encoders for TLS packets, cryptographic primitives, as well as higher level cryptographic operations specific for TLS.

We forked the rustls library for cryptographic operations like deriving secrets. We also use it to encode and decode TLS messages.

The cryptographic library ring allows us to use the derived secrets to encrypt and decrypt TLS messages.

Example

use puffin::agent::{AgentName, AgentDescriptor, TLSVersion::*};
use puffin::trace::{Step, Source, TraceContext, Trace, Action, InputAction, OutputAction, Query};
use puffin::algebra::{Term, signature::Signature};
use tlspuffin::tls::fn_impl::fn_client_hello;
use tlspuffin::tls::rustls::msgs::handshake::{SessionID, Random, ClientExtension};
use tlspuffin::tls::rustls::msgs::enums::{ProtocolVersion, CipherSuite, Compression, HandshakeType};
use tlspuffin::query::TlsQueryMatcher;


let client: AgentName = AgentName::first();
let server: AgentName = client.next();

let trace = Trace {
    prior_traces: vec![],
    descriptors: vec![
        AgentDescriptor::new_client(client, V1_3),
        AgentDescriptor::new_server(server, V1_3),
    ],
    steps: vec![
            OutputAction::new_step(client),
            // Client: Hello Client -> Server
            Step {
                agent: server,
                action: Action::Input(InputAction {
                    recipe: Term::Application(
                        Signature::new_function(&fn_client_hello),
                        vec![
                            Term::Variable(Signature::new_var_with_type::<ProtocolVersion, _>(
                                    Some(Source::Agent(client)),  
                                    Some(TlsQueryMatcher::Handshake(Some(HandshakeType::ClientHello))),
                                    0
                            )),
                            Term::Variable(Signature::new_var_with_type::<Random, _>(
                                    Some(Source::Agent(client)),  
                                    Some(TlsQueryMatcher::Handshake(Some(HandshakeType::ClientHello))),
                                    0
                            )),
                            Term::Variable(Signature::new_var_with_type::<SessionID, _>(
                                    Some(Source::Agent(client)),
                                    Some(TlsQueryMatcher::Handshake(Some(HandshakeType::ClientHello))),
                                    0
                            )),
                            Term::Variable(Signature::new_var_with_type::<Vec<CipherSuite>, _>(
                                    Some(Source::Agent(client)),
                                    Some(TlsQueryMatcher::Handshake(Some(HandshakeType::ClientHello))),
                                    0
                            )),
                            Term::Variable(Signature::new_var_with_type::<Vec<Compression>, _>(
                                    Some(Source::Agent(client)),
                                    Some(TlsQueryMatcher::Handshake(Some(HandshakeType::ClientHello))),
                                    0
                            )),
                            Term::Variable(Signature::new_var_with_type::<Vec<ClientExtension>, _>(
                                    Some(Source::Agent(client)),
                                    Some(TlsQueryMatcher::Handshake(Some(HandshakeType::ClientHello))),
                                    0
                            )),
                        ],
                    ),
                }),
            },
    // further steps here
    ]
};

Example with term! macro

use puffin::agent::AgentName;
use puffin::term;
use tlspuffin::tls::fn_impl::fn_client_hello;
use tlspuffin::tls::rustls::msgs::handshake::{SessionID, Random, ClientExtension};
use tlspuffin::tls::rustls::msgs::enums::{Compression, HandshakeType, ProtocolVersion, CipherSuite};
use puffin::algebra::Term;
use tlspuffin::query::TlsQueryMatcher;
use puffin::trace::Source;

let client = AgentName::first();
let term: Term<TlsQueryMatcher> = term! {
    fn_client_hello(
        ((client, 0)/ProtocolVersion),
        ((client, 0)/Random),
        ((client, 0)/SessionID),
        ((client, 0)/Vec<CipherSuite>),
        ((client, 0)/Vec<Compression>),
        ((client, 0)/Vec<ClientExtension>)
    )
};

Modules

claims

debug

protocol 🔒

put

put_registry

query

static_certs

tcp

tls

The tls module provides concrete implementations for the functions used in the term. The module offers a variety of DynamicFunctions which can be used in the fuzzing.

Macros

nyi_fn