# thetorproject/stegotorus architecture

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

- Interactive diagram: https://gitdiagram.com/thetorproject/stegotorus
- Repository: https://github.com/thetorproject/stegotorus

## Overview

##### Project’s Main Components
- Chopper Protocol: This is at the heart of the system. It splits the network traffic into small chunks, manages retransmission (if needed), and encrypts data using OpenSSL.
- Steg Modules: These components (e.g., NoSteg and various HTTP steg flavors) take the chopped, encrypted data and encode it into “cover” formats that blend in with benign traffic. They should be represented as independent modules that plug into the chopper mechanism.
- Network Communication Components: This includes code managing TCP/IP-like connections (see files like connections.cc, network.cc, transparent_proxy.cc) and handling client/server interactions.
- Configuration & Deployment: The conf.d directory (and related test config files) indicate how different operational profiles (such as HTTP Apache client/server or test configurations) are set up and used by the system.
- External Dependencies: Incorporate dependencies like libevent (for event handling), libcurl (for HTTP connectivity), yaml-cpp (for configuration handling), boost libraries (for file system and system functions), libssl (OpenSSL for encryption), and zlib (for compression).

##### Establish the Relationships and Interactions
- From there, illustrate how the connection data proceeds to the chopper protocol. Mark this layer as performing encryption, data chunking, and retransmission logic.
- Next, split out the flow into one or more steg modules. Indicate that the chopper protocol “plugs” data off to a chosen steg module based on configuration (with options like NoSteg, HTTP with various encoding strategies, etc.).
- Feedback path where the steg module may interact with external cover media (like an HTTP payload or file-based cover for Apache) that ‘hides’ the traffic.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clearly delineate the network and protocol management responsibilities (handled by the chopper and network classes) versus the encoding/decoding responsibilities (handled by distinct steg module classes).

##### Incorporate Relevant Technologies
- External library with its role (e.g., “OpenSSL for encryption”, “libevent for asynchronous operations”, “curl for HTTP functionalities”).
- For build and deployment, indicate that the system uses GNU Autotools (autoconf/automake), with platform-specific build scripts under scripts (e.g., build-linux.sh, build-android.sh, build-windows.sh).

- From that, create a block for the network/connection handling layer that interfaces with system calls or socket libraries.
- Next, position the chopper protocol component, indicating its roles (chunking, encryption, retransmission).
- An additional block to represent external “cover” services such as an HTTP server with which steg modules interact.
- Optionally, include notes regarding platform choices like Linux, Windows, and Android, as illustrated through the dedicated build scripts.

##### Additional Details
- Auxiliary components such as testing and configuration modules in a separate area or as annotations if needed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Client("Client Connection"):::client
    end

    %% Network Communication Layer
    subgraph "Network Communication Layer"
        NetMgmt("Connection Management"):::network
        NetHandle("Network Handling"):::network
        TransProxy("Transparent Proxy"):::network
        Socks("SOCKS Handling"):::network
    end

    %% Chopper Protocol Layer
    subgraph "Chopper Protocol Layer"
        Chopper("Chopper Protocol"):::core
    end

    %% Steg Modules Layer
    subgraph "Steg Modules Layer"
        NoSteg("NoSteg Module"):::steg
        HTTPSteg("HTTP Steg Modules"):::steg
        ApachePayload("Apache Payload Server"):::steg
        PayloadServer("Payload Server"):::steg
        TracePayload("Trace Payload Server"):::steg
    end

    %% HTTP Steg SubModules
    subgraph "HTTP Steg SubModules"
        HttpGeneral("HTTP Steg General"):::steg
        FileSteg("File Steg"):::steg
        GifSteg("GIF Steg"):::steg
        HtmlSteg("HTML Steg"):::steg
        JpgSteg("JPG Steg"):::steg
        JsSteg("JS Steg"):::steg
        PdfSteg("PDF Steg"):::steg
        PngSteg("PNG Steg"):::steg
        SwfSteg("SWF Steg"):::steg
    end

    %% Configuration & Deployment
    subgraph "Configuration & Deployment"
        Config("Configuration Files (conf.d)"):::config
        TestConfig("Test Config (src/test/test_conf.d)"):::config
    end

    %% External Dependencies
    subgraph "External Dependencies"
        OpenSSL("OpenSSL"):::external
        LibEvent("libevent"):::external
        LibCurl("libcurl"):::external
        YamlCpp("yaml-cpp"):::external
        Boost("Boost Libraries"):::external
        Zlib("zlib"):::external
    end

    %% Build Tools
    subgraph "Build Tools"
        Autotools("GNU Autotools"):::build
        BuildScripts("Platform Build Scripts"):::build
    end

    %% Data Flow
    Client -->|"connection"| NetMgmt
    NetMgmt -->|"setup"| NetHandle
    NetMgmt -->|"manages"| Socks
    NetHandle -->|"routes"| Chopper
    Chopper -->|"chunks/encrypts"| NoSteg
    Chopper -->|"chunks/encrypts"| HTTPSteg
    HTTPSteg -->|"general encoding"| HttpGeneral
    HTTPSteg -->|"file encoding"| FileSteg
    HTTPSteg -->|"gif encoding"| GifSteg
    HTTPSteg -->|"html encoding"| HtmlSteg
    HTTPSteg -->|"jpg encoding"| JpgSteg
    HTTPSteg -->|"js encoding"| JsSteg
    HTTPSteg -->|"pdf encoding"| PdfSteg
    HTTPSteg -->|"png encoding"| PngSteg
    HTTPSteg -->|"swf encoding"| SwfSteg
    NoSteg -->|"sends data"| NetHandle
    HTTPSteg -->|"sends data"| NetHandle
    ApachePayload -->|"provides cover"| HTTPSteg
    PayloadServer -->|"provides cover"| HTTPSteg
    TracePayload -->|"provides cover"| HTTPSteg
    NetHandle -->|"utilizes"| TransProxy

    %% External Dependencies Integration
    Chopper -->|"encryption"| OpenSSL
    NetMgmt -->|"async events"| LibEvent
    NetHandle -->|"HTTP transport"| LibCurl

    %% Build Tools Relationship
    Autotools -->|"generates"| BuildScripts

    %% Styles
    classDef client fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef network fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef core fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef steg fill:#abebc6,stroke:#333,stroke-width:2px;
    classDef config fill:#d6eaf8,stroke:#333,stroke-width:2px;
    classDef external fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef build fill:#d2b4de,stroke:#333,stroke-width:2px;

    %% Click Events for Chopper Protocol Components
    click Chopper "https://github.com/thetorproject/stegotorus/blob/master/src/protocol/chop.cc"
    click Chopper "https://github.com/thetorproject/stegotorus/blob/master/src/protocol/chop_blk.cc"
    click Chopper "https://github.com/thetorproject/stegotorus/blob/master/src/protocol/chop_blk.h"
    click Chopper "https://github.com/thetorproject/stegotorus/blob/master/src/protocol/chop_handshaker.h"

    %% Click Events for Steg Modules
    click NoSteg "https://github.com/thetorproject/stegotorus/blob/master/src/steg/nosteg.cc"
    click NoSteg "https://github.com/thetorproject/stegotorus/blob/master/src/steg/nosteg_rr.cc"
    click HTTPSteg "https://github.com/thetorproject/stegotorus/blob/master/src/steg/http.cc"
    click HTTPSteg "https://github.com/thetorproject/stegotorus/blob/master/src/steg/http_apache.cc"
    click FileSteg "https://github.com/thetorproject/stegotorus/blob/master/src/steg/http_steg_mods/file_steg.cc"
    click GifSteg "https://github.com/thetorproject/stegotorus/blob/master/src/steg/http_steg_mods/gifSteg.cc"
    click HtmlSteg "https://github.com/thetorproject/stegotorus/blob/master/src/steg/http_steg_mods/htmlSteg.cc"
    click JpgSteg "https://github.com/thetorproject/stegotorus/blob/master/src/steg/http_steg_mods/jpgSteg.cc"
    click JsSteg "https://github.com/thetorproject/stegotorus/blob/master/src/steg/http_steg_mods/jsSteg.cc"
    click PdfSteg "https://github.com/thetorproject/stegotorus/blob/master/src/steg/http_steg_mods/pdfSteg.cc"
    click PngSteg "https://github.com/thetorproject/stegotorus/blob/master/src/steg/http_steg_mods/pngSteg.cc"
    click SwfSteg "https://github.com/thetorproject/stegotorus/blob/master/src/steg/http_steg_mods/swfSteg.cc"
    click ApachePayload "https://github.com/thetorproject/stegotorus/blob/master/src/steg/apache_payload_server.cc"
    click PayloadServer "https://github.com/thetorproject/stegotorus/blob/master/src/steg/payload_server.cc"
    click TracePayload "https://github.com/thetorproject/stegotorus/blob/master/src/steg/trace_payload_server.cc"

    %% Click Events for Network Components
    click NetMgmt "https://github.com/thetorproject/stegotorus/blob/master/src/connections.cc"
    click NetHandle "https://github.com/thetorproject/stegotorus/blob/master/src/network.cc"
    click TransProxy "https://github.com/thetorproject/stegotorus/blob/master/src/transparent_proxy.cc"
    click Socks "https://github.com/thetorproject/stegotorus/blob/master/src/socks.cc"

    %% Click Events for Configuration
    click Config "https://github.com/thetorproject/stegotorus/blob/master/conf.d"
    click TestConfig "https://github.com/thetorproject/stegotorus/blob/master/src/test/test_conf.d"

    %% Click Events for Build Tools
    click BuildScripts "https://github.com/thetorproject/stegotorus/blob/master/scripts/build-linux.sh"
    click Autotools "https://github.com/thetorproject/stegotorus/blob/master/Makefile.am"
```
