# pion/dtls architecture

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

- Interactive diagram: https://gitdiagram.com/pion/dtls
- Repository: https://github.com/pion/dtls

## Overview

This project is Pion DTLS – a native Go implementation of Datagram Transport Layer Security (DTLS) version 1.2. The primary purpose of the project is to provide both DTLS client and server functionality (including handling packet loss, reordering, and support for various cipher suites) by using a layered, modular design that mirrors the DTLS protocol’s structure as described in RFC 6347 and related RFCs.

##### Main Components
- DTLS Endpoint Components: Represent separate DTLS client and server roles. These are the entry points which interact with the underlying network.
- Handshake/Flight Handlers: The project splits the DTLS handshake into multiple “flights” (flight0handler, flight1handler, … flight6handler). These manage the sequential steps in the handshake process.
- Protocol Layers:
- Record Layer: Handles encryption/decryption, fragmentation (see files like recordlayer.go and associated tests).
- Handshake and Alert Layers: Manage handshake messages, alerts, and error handling.
- Cryptographic Components:
- Cipher Suite Implementations: Under “internal/ciphersuite” and “pkg/crypto/ciphersuite,” multiple cipher suites (AES-CCM, AES-GCM, etc.) are implemented.
- Key Exchange Modules: Support for ECDHE (using curves like curve25519, nistp256, nistp384) and PSK based exchanges.
- Other Crypto Utilities: Modules for self-signing, client certificates, hashing, and fingerprinting located in “pkg/crypto” and “internal/util.”
- Session Management & Resumption:
- Session and handshake cache functionalities (files like session.go, handshake_cache.go) for managing state and resumption.
- Network Layer Components:
- UDP / Packet Layer: Components for handling UDP connections, packet buffering, and fragmentation (see “internal/net/udp”).
- Connection management and reconnection logic (e.g., conn.go, connection_id.go).
- Configuration and Error Handling:
- Overall configuration (config.go) and centralized error reporting modules (errors.go and its variants).
- Testing, Examples, and Auxiliary:
- “examples”: Demonstrate usage strategies (client dialing, server listening) including support for self-signed certificates, PSK mode, and OpenSSL interoperability.
- “e2e”: End-to-end tests through Docker and test workflows.
- Build and CI/CD configuration (GitHub workflows, goreleaser config) support continuous integration, linting, and versioning.

##### Relationships and Data Flow
- That the Handshake Manager interacts with the Flight Handlers sequentially to exchange handshake messages.
- Handshake Manager with Cryptographic Components for operations such as key generation, cipher suite selection, and message signing.
- That once the handshake is complete, the Record Layer processes and secures the DTLS application data.
- Configuration and error handling as cross-cutting concerns that feed into almost every layer.
- Testing and example modules as external “usage” points that interact with the core DTLS library.

##### Architectural Patterns and Design Principles
- Modular Design: Each layer (handshake, record, crypto, network) is clearly separated into its own package or internal module.
- Separation of Concerns: Flight handlers, cryptographic functions, network communication, and protocol message parsing are isolated to improve maintainability and testing.
- Extensibility: The clear separation into “internal” and “pkg” directories suggests that the project is designed to allow future expansion (for example, planned support for ChaCha20Poly1305).
- Testability: The presence of numerous test files and fuzz tests implies a design that encourages testing at every level.

## Diagram (Mermaid)

```mermaid
flowchart TD

    subgraph "DTLS Core"
        dtls["DTLS Endpoints"]:::core
        hm["Handshake Manager"]:::handshake
    end

    subgraph "Flight Handlers"
        h0["Flight0 Handler"]:::flight
        h1["Flight1 Handler"]:::flight
        h2["Flight2 Handler"]:::flight
        h3["Flight3 Handler"]:::flight
        h4["Flight4 Handler"]:::flight
        h4b["Flight4b Handler"]:::flight
        h5["Flight5 Handler"]:::flight
        h5b["Flight5b Handler"]:::flight
        h6["Flight6 Handler"]:::flight
        fgo["Flight.go"]:::flight
        fh["FlightHandler.go"]:::flight
    end

    subgraph "Protocol Layers"
        rl["Record Layer"]:::protocol
        hl["Handshake Layer"]:::protocol
        al["Alert Layer"]:::protocol
    end

    subgraph "Cryptographic Components"
        cs_internal["Cipher Suite (internal)"]:::crypto
        cs_pkg["Cipher Suite (pkg)"]:::crypto
        hash_util["Hash Utilities"]:::crypto
        prf_util["PRF Utilities"]:::crypto
        sig_util["Signature Utilities"]:::crypto
        selfsign_util["Self-sign Utilities"]:::crypto
        crypto_util["Crypto Util (internal)"]:::crypto
    end

    subgraph "Session Management"
        session["Session (session.go)"]:::session
        handshake_cache["Handshake Cache (handshake_cache.go)"]:::session
        resumption["Resumption (resume.go)"]:::session
    end

    subgraph "Network & Config"
        udp["UDP/Packet Layer"]:::network
        conn["Connection Manager (conn.go)"]:::network
        conn_id["Connection ID (connection_id.go)"]:::network
        config["Configuration"]:::config
        errors["Error Handling"]:::config
    end

    subgraph "Testing & Examples"
        ex_dial["Example Dial"]:::examples
        ex_listen["Example Listen"]:::examples
        e2e["End-to-End Tests"]:::examples
    end

    %% Connections between components
    dtls -->|"sends datagrams"| udp
    dtls -->|"initiates handshake"| hm
    udp -->|"manages connection"| conn
    conn -->|"handles IDs"| conn_id

    hm -->|"dispatches flight messages"| h0
    hm --> h1
    hm --> h2
    hm --> h3
    hm --> h4
    hm --> h4b
    hm --> h5
    hm --> h5b
    hm --> h6
    hm -->|"uses flight routines"| fgo
    hm --> fh

    hm -->|"performs key exchange"| cs_internal
    hm -->|"selects cipher suite"| cs_pkg
    hm -->|"verifies handshake"| hl
    hm -->|"handles alerts"| al
    hm -->|"executes hashing"| hash_util
    hm --> prf_util
    hm --> sig_util
    hm --> selfsign_util
    hm --> crypto_util

    hm -->|"manages session state"| session
    session -->|"updates session"| handshake_cache
    handshake_cache --> resumption

    hm -->|"transitions to secure channel"| rl
    rl -->|"secures data"| hm

    config -->|"provides settings"| dtls
    config --> hm
    config --> udp

    errors -->|"reports errors to"| dtls
    errors --> hm
    errors --> udp

    ex_dial -->|"demonstrates usage"| dtls
    ex_listen --> dtls
    e2e --> dtls

    %% Click Events for DTLS Endpoints and Examples
    click dtls "https://github.com/pion/dtls/blob/master/dtls.go"
    click ex_dial "https://github.com/pion/dtls/tree/master/examples/dial"
    click ex_listen "https://github.com/pion/dtls/tree/master/examples/listen"
    click e2e "https://github.com/pion/dtls/tree/master/e2e"

    %% Click Events for Flight Handlers
    click h0 "https://github.com/pion/dtls/blob/master/flight0handler.go"
    click h1 "https://github.com/pion/dtls/blob/master/flight1handler.go"
    click h2 "https://github.com/pion/dtls/blob/master/flight2handler.go"
    click h3 "https://github.com/pion/dtls/blob/master/flight3handler.go"
    click h4 "https://github.com/pion/dtls/blob/master/flight4handler.go"
    click h4b "https://github.com/pion/dtls/blob/master/flight4bhandler.go"
    click h5 "https://github.com/pion/dtls/blob/master/flight5handler.go"
    click h5b "https://github.com/pion/dtls/blob/master/flight5bhandler.go"
    click h6 "https://github.com/pion/dtls/blob/master/flight6handler.go"
    click fgo "https://github.com/pion/dtls/blob/master/flight.go"
    click fh "https://github.com/pion/dtls/blob/master/flighthandler.go"

    %% Click Events for Protocol Layers
    click rl "https://github.com/pion/dtls/blob/master/pkg/protocol/recordlayer/recordlayer.go"
    click hl "https://github.com/pion/dtls/blob/master/pkg/protocol/handshake/handshake.go"
    click al "https://github.com/pion/dtls/blob/master/pkg/protocol/alert/alert.go"

    %% Click Events for Cryptographic Components
    click cs_internal "https://github.com/pion/dtls/tree/master/internal/ciphersuite/"
    click cs_pkg "https://github.com/pion/dtls/tree/master/pkg/crypto/ciphersuite/"
    click hash_util "https://github.com/pion/dtls/blob/master/pkg/crypto/hash/hash.go"
    click prf_util "https://github.com/pion/dtls/blob/master/pkg/crypto/prf/prf.go"
    click sig_util "https://github.com/pion/dtls/blob/master/pkg/crypto/signature/signature.go"
    click selfsign_util "https://github.com/pion/dtls/blob/master/pkg/crypto/selfsign/selfsign.go"
    click crypto_util "https://github.com/pion/dtls/blob/master/internal/util/util.go"

    %% Click Events for Session Management
    click session "https://github.com/pion/dtls/blob/master/session.go"
    click handshake_cache "https://github.com/pion/dtls/blob/master/handshake_cache.go"
    click resumption "https://github.com/pion/dtls/blob/master/resume.go"

    %% Click Events for Network & Config
    click udp "https://github.com/pion/dtls/blob/master/internal/net/udp/packet_conn.go"
    click conn "https://github.com/pion/dtls/blob/master/conn.go"
    click conn_id "https://github.com/pion/dtls/blob/master/connection_id.go"
    click config "https://github.com/pion/dtls/blob/master/config.go"
    click errors "https://github.com/pion/dtls/blob/master/errors.go"

    %% Styles for color coding
    classDef core fill:#FAD7A0,stroke:#333,stroke-width:2px;
    classDef handshake fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef flight fill:#D2B4DE,stroke:#333,stroke-width:2px;
    classDef protocol fill:#A3E4D7,stroke:#333,stroke-width:2px;
    classDef crypto fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef session fill:#F5CBA7,stroke:#333,stroke-width:2px;
    classDef network fill:#82E0AA,stroke:#333,stroke-width:2px;
    classDef config fill:#F1948A,stroke:#333,stroke-width:2px;
    classDef examples fill:#D5DBDB,stroke:#333,stroke-width:2px;
```
