# apple/swift-nio-ssh architecture

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

- Interactive diagram: https://gitdiagram.com/apple/swift-nio-ssh
- Repository: https://github.com/apple/swift-nio-ssh

## Overview

##### Project Type and Purpose
- This is a modular Swift library (“SwiftNIO SSH”) built on top of SwiftNIO and Swift Crypto, not a monolithic application.
- It exposes core SSH protocol building blocks (NIOSSHHandler, state machines, channel multiplexers) and ships three sample executables: a client (NIOSSHClient), a server (NIOSSHServer), and a performance tester (NIOSSHPerformanceTester).
- Its mission: let Swift programs speak SSH directly (like libssh2), providing an API-driven SSH implementation rather than standalone SSH binaries.

##### Key Architectural Components (to represent
a. External Dependencies
- SwiftNIO (networking/event loop)
- Swift Crypto (cryptographic primitives, CSPRNG)
b. Transport Layer (bottom layer)
- NIO Channel ↔ ByteBuffer
- SSHPacketParser & SSHPacketSerializer
- TransportProtection (AESGCM, SSHTransportProtection)
c. Core Protocol Engine (middle layer)
- NIOSSHHandler (entry point ChannelHandler)
- Connection State Machine (key exchange, authentication, version)
- Key Exchange State Machine (ECDH, curve choices)
- User Authentication State Machine & Delegates
- Channel Multiplexer & Child Channels
- ChildChannelStateMachine, Options, Window Manager, Flow Controller
- SSHChannelData (data vs. stderr, extended data)
d. Sample Executables (top layer)
- NIOSSHClient (ExecHandler, PortForwardingServer, CLI parser, user auth delegate)
- NIOSSHServer (GlueHandler, ExecHandler, RemotePortForwarding handler)
- NIOSSHPerformanceTester (benchmarks, handshake tests, throughput tests)
e. Configuration & Usage
- SSHClientConfiguration & SSHServerConfiguration
- GlobalRequestDelegate (for remote port forwarding)

##### Relationships & Data Flow
- Inbound TCP bytes → NIO Channel → SSHPacketParser → TransportProtection → Connection State Machine
- State Machine commands → SSHPacketSerializer → TransportProtection → NIO Channel → Remote peer
- Once SSH handshake/authentication completes, child channels spawn: each child channel has its own NIO Channel pipeline, carrying SSHChannelData up to user handlers.
- Sample executables implement user delegates upstream of NIOSSHHandler to react to events (exec requests, shell requests, port-forwarding requests).

##### Architectural Patterns & Design Principles
- Layered pipeline: clear separation of transport, framing (parser/serializer), crypto, protocol logic, and user handlers.
- State machines for connection, key exchange, user authentication, and child channel lifecycles.
- Delegate pattern: authentication and global-request delegates plug into the core protocol engine.
- Multiplexing: one physical channel hosts multiple logical child channels (session vs. TCP forwarding).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Dependencies"
        SwiftNIO["SwiftNIO"]:::external
        SwiftCrypto["Swift Crypto"]:::external
    end

    %% Transport Layer
    subgraph "Transport Layer"
        ByteBuffer["ByteBuffer+SSH Adapter"]:::transport
        Parser["SSHPacketParser"]:::transport
        Serializer["SSHPacketSerializer"]:::transport
        subgraph "TransportProtection"
            AESGCM["AESGCM"]:::transport
            SSHTP["SSHTransportProtection"]:::transport
        end
    end

    %% Core Library
    subgraph "Core Library"
        NIOSSHHandler["NIOSSHHandler"]:::core
        subgraph "State Machines & Multiplexing"
            ConnSM["Connection State Machine"]:::core
            KexSM["Key Exchange State Machine"]:::core
            AuthSM["User Authentication State Machine"]:::core
            AuthDel["UserAuthDelegate"]:::core
            Multiplexer["SSHChannelMultiplexer"]:::core
            ChildSM["ChildChannelStateMachine"]:::core
            ChannelData["SSHChannelData"]:::core
        end
    end

    %% Sample Executables
    subgraph "Sample Executables"
        Client["NIOSSHClient"]:::exec
        Server["NIOSSHServer"]:::exec
        Perf["NIOSSHPerformanceTester"]:::exec
    end

    %% Configuration & Delegates
    SSHClientConfig["SSHClientConfiguration"]:::core
    SSHServerConfig["SSHServerConfiguration"]:::core
    GlobalReqDel["GlobalRequestDelegate"]:::core

    %% Data Flow
    SwiftNIO --> ByteBuffer
    ByteBuffer --> Parser
    Parser --> AESGCM
    AESGCM --> SSHTP
    SSHTP --> Serializer
    Serializer --> ByteBuffer

    SSHTP --> NIOSSHHandler
    NIOSSHHandler --> ConnSM
    NIOSSHHandler --> KexSM
    NIOSSHHandler --> AuthSM
    NIOSSHHandler --> Multiplexer

    Multiplexer --> ChildSM
    ChildSM --> ChannelData
    ChannelData --> Client
    ChannelData --> Server
    ChannelData --> Perf

    %% Delegate Callbacks
    Client -.-> AuthSM
    Server -.-> AuthSM
    Client -.-> GlobalReqDel
    Server -.-> GlobalReqDel

    %% Configuration Injection
    SSHClientConfig --> Client
    SSHServerConfig --> Server
    GlobalReqDel --> NIOSSHHandler

    %% Click Events
    click SwiftNIO "https://github.com/apple/swift-nio-ssh/blob/main/Package.swift"
    click SwiftCrypto "https://github.com/apple/swift-nio-ssh/blob/main/Package.swift"
    click ByteBuffer "https://github.com/apple/swift-nio-ssh/blob/main/Sources/NIOSSH/ByteBuffer+SSH.swift"
    click Parser "https://github.com/apple/swift-nio-ssh/blob/main/Sources/NIOSSH/SSHPacketParser.swift"
    click Serializer "https://github.com/apple/swift-nio-ssh/blob/main/Sources/NIOSSH/SSHPacketSerializer.swift"
    click AESGCM "https://github.com/apple/swift-nio-ssh/blob/main/Sources/NIOSSH/TransportProtection/AESGCM.swift"
    click SSHTP "https://github.com/apple/swift-nio-ssh/blob/main/Sources/NIOSSH/TransportProtection/SSHTransportProtection.swift"
    click NIOSSHHandler "https://github.com/apple/swift-nio-ssh/blob/main/Sources/NIOSSH/NIOSSHHandler.swift"
    click ConnSM "https://github.com/apple/swift-nio-ssh/blob/main/Sources/NIOSSH/Connection State Machine/SSHConnectionStateMachine.swift"
    click KexSM "https://github.com/apple/swift-nio-ssh/blob/main/Sources/NIOSSH/Key Exchange/SSHKeyExchangeStateMachine.swift"
    click AuthSM "https://github.com/apple/swift-nio-ssh/blob/main/Sources/NIOSSH/User Authentication/UserAuthenticationStateMachine.swift"
    click AuthDel "https://github.com/apple/swift-nio-ssh/blob/main/Sources/NIOSSH/User Authentication/UserAuthDelegate.swift"
    click Multiplexer "https://github.com/apple/swift-nio-ssh/blob/main/Sources/NIOSSH/Child Channels/SSHChannelMultiplexer.swift"
    click ChildSM "https://github.com/apple/swift-nio-ssh/blob/main/Sources/NIOSSH/Child Channels/ChildChannelStateMachine.swift"
    click ChannelData "https://github.com/apple/swift-nio-ssh/blob/main/Sources/NIOSSH/Child Channels/SSHChannelData.swift"
    click SSHClientConfig "https://github.com/apple/swift-nio-ssh/blob/main/Sources/NIOSSH/SSHClientConfiguration.swift"
    click SSHServerConfig "https://github.com/apple/swift-nio-ssh/blob/main/Sources/NIOSSH/SSHServerConfiguration.swift"
    click GlobalReqDel "https://github.com/apple/swift-nio-ssh/blob/main/Sources/NIOSSH/GlobalRequestDelegate.swift"
    click Client "https://github.com/apple/swift-nio-ssh/tree/main/Sources/NIOSSHClient"
    click Server "https://github.com/apple/swift-nio-ssh/tree/main/Sources/NIOSSHServer"
    click Perf "https://github.com/apple/swift-nio-ssh/tree/main/Sources/NIOSSHPerformanceTester"

    %% Styles
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:1px;
    classDef transport fill:#FFD700,stroke:#333,stroke-width:1px;
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef exec fill:#90EE90,stroke:#333,stroke-width:1px;
```
