# rustls/rustls architecture

> Architecture diagram of the GitHub repository rustls/rustls, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rustls/rustls
- Repository: https://github.com/rustls/rustls

## Overview

##### Project type and purpose
- The README clearly states that rustls is a modern TLS (Transport Layer Security) library.
- The purpose is to implement secure TLS communication (versions 1.2 and 1.3) with strong cryptographic support.
- It includes two built-in cryptography providers (aws-lc-rs and ring) plus supports custom provider integration and third-party cryptography options.
- Additional components include example programs (client and server using both blocking and non-blocking I/O), tests (unit, integration, fuzzing) and benchmarking tools.

##### File structure
- The top-level directories (e.g., rustls, examples, fuzz, openssl-tests, provider-example, rustls-bench) indicate a modular layout.
- The “rustls” directory contains the core implementation: individual submodules for client, server, crypto, message encoding/decoding, handshake, and record layer.
- Directories like “admin”, “ci-bench”, “fuzz”, “connect-tests”, and “tests” show that the project also supports continuous integration, benchmarking, fuzzing, and interoperability tests.
- There are additional directories for experimental and provider-related implementations (rustls-fuzzing-provider, rustls-post-quantum, rustls-provider-test).

a. Core TLS Implementation:
- TLS protocol layers (handshake, record layer, alerts, messages).
- Client and server submodules – encapsulating the logic for each side of the TLS connection.
- Cryptographic abstraction (crypto module) providing algorithms and low-level operations.
b. Cryptographic Providers:
- Built-in providers (aws-lc-rs and ring) with mechanisms to plug in custom or third-party alternatives.
- The provider selection layer via the CryptoProvider abstraction that ties to custom providers.
c. Communication and I/O Helpers:
- Modules and examples for both synchronous (stream-based) and asynchronous (mio-based, tokio-rustls) communications.
d. Testing, Benchmarking, and Fuzzing:
- Directories dedicated to fuzzing (fuzz), benchmarks (ci-bench, rustls-bench), connect-tests, and openssl interoperability.
e. Supporting Tools and Documentation:
- Admin scripts, configuration files (like Cargo.toml, rustfmt, taplo, etc.), and website/documentation content.

##### Relationships and interactions
- Dependency from the provider selection mechanism to the built-in providers (aws-lc-rs and ring) as plug-and-play modules.
- That examples, tests, and benchmarks depend on the core library, which itself is divided into protocol, crypto abstraction, and I/O modules.
- Optionally, indicate how administration and repository-wide tools (CI scripts, documentation generators, etc.) interface with the core project for deployment and testing.

##### Architectural patterns and design principles
- Modularity and separation of concerns (separation between TLS protocol handling, cryptography layer, and provider integration).
- Use of abstraction for cryptographic providers. This makes it easy to swap the underlying crypto implementations.
- Dependency inversion (e.g., the provider abstraction allows inversion of control over cryptography).
- The design also separates production code from examples and tests, which clarifies maintenance and extension of the library.

- Clear, labeled blocks for each major component:
– Core TLS implementation (with submodules for handshake, record layer, encryption, decryption, error handling).
– Crypto Provider Abstraction (with submodules or options for aws-lc-rs, ring, and custom extensions).
– Client and Server components (illustrated with their integration to I/O helpers).
– Testing and benchmarking suites (fuzz tests, integration tests, example apps).
– Supporting infrastructure (CI pipelines, admin tools, website/docs repository).
- Annotations to explain key interactions such as “provider selection via CryptoProvider” or “handshake initiates secure channel setup.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core TLS Implementation
    subgraph "Core TLS Implementation"
        core["Core TLS Implementation"]:::coreClass
    end

    %% TLS Operations (Client & Server)
    subgraph "TLS Operations"
        client["Client Implementation"]:::coreClass
        server["Server Implementation"]:::coreClass
    end

    %% Crypto Provider Abstraction
    subgraph "Crypto Provider Abstraction"
        crypto["Crypto Provider Abstraction"]:::providerClass
        aws["aws-lc-rs Provider"]:::providerClass
        ring["ring Provider"]:::providerClass
    end

    %% Communication and I/O Helpers
    subgraph "Communication and I/O Helpers"
        streamIO["Stream I/O"]:::ioClass
        unbufferIO["Unbuffered I/O"]:::ioClass
        asyncClient["Async TLS Client (Mio)"]:::ioClass
        asyncServer["Async TLS Server (Mio)"]:::ioClass
    end

    %% Testing, Fuzzing, and Benchmarking
    subgraph "Testing, Fuzzing, and Benchmarking"
        tlsTests["TLS Tests"]:::testClass
        fuzzTests["Fuzz Tests"]:::testClass
        ciBench["CI Bench"]:::testClass
        rustlsBench["Rustls Bench"]:::testClass
        connectTests["Connect/OpenSSL Tests"]:::testClass
    end

    %% Provider Integration Example
    subgraph "Provider Integration"
        providerIntegration["Provider Integration Example"]:::providerClass
    end

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        admin["Admin Tools"]:::infraClass
        ciConfig["CI Configuration"]:::infraClass
        website["Website & Docs"]:::infraClass
    end

    %% Connections
    core --> client
    core --> server

    client -->|"uses"| crypto
    server -->|"uses"| crypto

    crypto --> aws
    crypto --> ring

    client -->|"I/O"| streamIO
    client -->|"I/O"| asyncClient
    server -->|"I/O"| unbufferIO
    server -->|"I/O"| asyncServer

    providerIntegration -->|"integrates"| crypto

    tlsTests --- core
    fuzzTests --- core
    ciBench --- core
    rustlsBench --- core
    connectTests --- core

    admin --- core
    ciConfig --- core
    website --- core

    %% Styles
    classDef coreClass fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef providerClass fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef ioClass fill:#FFFFE0,stroke:#000,stroke-width:1px;
    classDef testClass fill:#FFC0CB,stroke:#000,stroke-width:1px;
    classDef infraClass fill:#D3D3D3,stroke:#000,stroke-width:1px;

    %% Click Events
    click core "https://github.com/rustls/rustls/tree/main/rustls/src"
    click client "https://github.com/rustls/rustls/tree/main/rustls/src/client"
    click server "https://github.com/rustls/rustls/tree/main/rustls/src/server"
    click aws "https://github.com/rustls/rustls/tree/main/rustls/src/crypto/aws_lc_rs"
    click ring "https://github.com/rustls/rustls/tree/main/rustls/src/crypto/ring"
    click streamIO "https://github.com/rustls/rustls/blob/main/rustls/src/stream.rs"
    click unbufferIO "https://github.com/rustls/rustls/blob/main/rustls/src/conn/unbuffer.rs"
    click asyncClient "https://github.com/rustls/rustls/blob/main/examples/src/bin/tlsclient-mio.rs"
    click asyncServer "https://github.com/rustls/rustls/blob/main/examples/src/bin/tlsserver-mio.rs"
    click tlsTests "https://github.com/rustls/rustls/tree/main/rustls/tests"
    click fuzzTests "https://github.com/rustls/rustls/tree/main/fuzz"
    click ciBench "https://github.com/rustls/rustls/tree/main/ci-bench"
    click rustlsBench "https://github.com/rustls/rustls/tree/main/rustls-bench"
    click providerIntegration "https://github.com/rustls/rustls/tree/main/provider-example"
    click admin "https://github.com/rustls/rustls/tree/main/admin"
    click ciConfig "https://github.com/rustls/rustls/blob/main/.github"
    click website "https://github.com/rustls/rustls/tree/main/website"
```
