# eugeny/russh architecture

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

- Interactive diagram: https://gitdiagram.com/eugeny/russh
- Repository: https://github.com/eugeny/russh

## Overview

##### Project type and purpose
- This is an open-source Rust library/toolset providing a low-level, async Tokio-based SSH2 client and server implementation, plus related crates for config, utilities, and SSH agent integration.

##### File structure
- Top‐level crates (each in its own folder with Cargo.toml):
- cryptovec – low‐level secure byte buffer abstraction
- pageant – Windows Pageant (SSH agent) integration
- russh-config – config builder and parser for SSH options
- russh-util – helper routines (runtime abstraction, time, etc.)
- russh – core SSH protocol implementation (client, server, kex, ciphers, MACs, keys, channels, parsing)
- Directories under russh/src break out protocol subsystems: auth, kex, cipher, mac, keys, channels, session, parsing, negotiation, etc.
- Examples and tests in russh/examples and russh/tests demonstrate usage of client/server API.

##### README for additional insights
- Purpose: full coverage of SSH2 protocol features (ciphers, KEX, auth methods, forwarding, agent forwarding)
- Safety guarantees: panic safety and minimal unsafe for performance.
- Ecosystem extensions: russh-sftp, async-ssh2-tokio, plus many adopters.

##### Components & relationships
a. Main components (grouped by crates):
- Cryptographic buffer layer (cryptovec)
- OS/Agent integration (pageant)
- Configuration layer (russh-config)
- Utility layer (russh-util)
- Core SSH protocol engine (russh)
- Application layer (examples or downstream clients/servers)
- External runtime: Tokio async reactor, OS sockets, SSH agent, network
b. Relationships & data flows:
- Application → russh-config: builds client/server config
- russh & russh-config → russh-util & cryptovec: use helpers and secure buffers
- russh → pageant (on Windows) for agent forwarding
- russh → Tokio / OS sockets: network I/O via AsyncRead/AsyncWrite
- Data traversal inside russh:
– Network socket I/O → parsing → negotiation (KEX, algorithms) → session management → channel multiplexing → cipher/MAC → back to network
c. Architectural patterns & design principles:
- Layered architecture (config → core → transport → socket)
- Modular design with clear crate boundaries
- Async trait–based APIs for client/server engines
- Separation of concerns: KEX, ciphers, MACs, keys, channels each in its own module
- Minimal unsafe code isolated in cryptovec for performance
d. Key technologies & frameworks:
- Rust async/await + Tokio runtime
- Traits for generic AsyncRead/AsyncWrite channels
- Crypto primitives (ChaCha20, AES-GCM, HMAC, Curve25519, Diffie-Hellman)
- OS APIs for mlock/munlock (memory safety) and Pageant agent

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Application Layer"
        AppExamples["Example Applications"]:::application
    end

    subgraph "Support Crates"
        Cryptovec["Cryptographic Buffer Layer\n(cryptovec)"]:::support
        Pageant["OS/Agent Integration\n(pageant)"]:::support
        Config["Configuration Layer\n(russh-config)"]:::support
        Util["Utility Layer\n(russh-util)"]:::support
    end

    subgraph "Core Library (russh)"
        Russh["russh crate"]:::core
        subgraph "Protocol Submodules"
            IO["SSH I/O & Buffering"]:::core
            Parsing["Parsing"]:::core
            Negotiation["Negotiation"]:::core
            Auth["Authentication"]:::core
            KEX["Key Exchange"]:::core
            SessionM["Session Management"]:::core
            Channels["Channel Multiplexing"]:::core
            Cipher["Ciphers"]:::core
            MAC["Message Authentication Codes"]:::core
            Keys["Keys & Formats"]:::core
        end
    end

    subgraph "External Runtime & Network"
        Tokio["Tokio Async Runtime"]:::runtime
        OSSockets["OS Sockets"]:::runtime
        SSHAgent["SSH Agent"]:::runtime
        Network["Network"]:::runtime
    end

    %% Application to config to core
    AppExamples -->|"uses API"| Config
    Config -->|"builds config"| Russh

    %% Core uses support crates
    Russh -->|"uses helpers"| Util
    Russh -->|"uses secure buffers"| Cryptovec
    Russh -->|"agent forwarding"| Pageant

    %% Core to runtime and network
    Russh -->|"spawns tasks on"| Tokio
    Tokio -->|"opens"| OSSockets
    OSSockets -->|"sends/receives packets on"| Network
    Russh -->|"agent I/O"| SSHAgent

    %% Internal protocol flow
    IO -->|"reads packets"| Parsing
    Parsing -->|"parses messages"| Negotiation
    Negotiation -->|"performs KEX"| KEX
    KEX -->|"establishes session"| SessionM
    SessionM -->|"opens"| Channels
    Channels -->|"encrypts/decrypts"| Cipher
    Cipher -->|"calculates MAC"| MAC
    MAC -->|"buffers data"| IO

    %% Click Events
    click Cryptovec "https://github.com/eugeny/russh/tree/main/cryptovec/"
    click Pageant "https://github.com/eugeny/russh/tree/main/pageant/"
    click Config "https://github.com/eugeny/russh/tree/main/russh-config/"
    click Util "https://github.com/eugeny/russh/tree/main/russh-util/"
    click Russh "https://github.com/eugeny/russh/tree/main/russh/src/"
    click IO "https://github.com/eugeny/russh/blob/main/russh/src/ssh_read.rs"
    click Parsing "https://github.com/eugeny/russh/blob/main/russh/src/parsing.rs"
    click Negotiation "https://github.com/eugeny/russh/blob/main/russh/src/negotiation.rs"
    click Auth "https://github.com/eugeny/russh/blob/main/russh/src/auth.rs"
    click KEX "https://github.com/eugeny/russh/tree/main/russh/src/kex/"
    click Cipher "https://github.com/eugeny/russh/tree/main/russh/src/cipher/"
    click MAC "https://github.com/eugeny/russh/tree/main/russh/src/mac/"
    click Keys "https://github.com/eugeny/russh/tree/main/russh/src/keys/"
    click Channels "https://github.com/eugeny/russh/tree/main/russh/src/channels/"
    click SessionM "https://github.com/eugeny/russh/blob/main/russh/src/session.rs"
    click Tokio "https://github.com/eugeny/russh/blob/main/russh-util/src/runtime.rs"
    click AppExamples "https://github.com/eugeny/russh/tree/main/russh/examples/"

    %% Styles
    classDef support fill:#a8ddb5,stroke:#31a354,color:#000
    classDef core fill:#9ecae1,stroke:#3182bd,color:#000
    classDef runtime fill:#fdae6b,stroke:#e6550d,color:#000
    classDef application fill:#d9d9d9,stroke:#636363,color:#000
```
