How eugeny/russh works
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