Home / Docs / SSH Client Design

Historical engineering note. This is a point-in-time design and feasibility document from the project archive, written before the SSH client was built; the plan, gaps, and phasing described here may not reflect the current system. Since this was written, an SSH-2 client and server were built (kernel/net/ssh/ssh2.c, ssh2_server.c, and a userland ssh app), so most items under "Gaps to implement" below have since been closed: curve25519-sha256 KEX and ssh-ed25519 host-key signing (Ed25519) are both implemented and in use, not merely proposed. See SSH Subsystem for the confirmed current algorithm set.

MayteraOS SSH client - design

Goal: a fully functional SSH client launched from the MayteraOS terminal to connect to a real Linux server for an interactive shell, with SSH key auth and the functionality expected of a modern client. The proposed invocation syntax is ssh [user@]host. The primary interop target is a standard Linux host running OpenSSH.

Building blocks already present (from the feasibility review)

  • TCP client transport: tcp_connect / tcp_send / tcp_recv (net/tcp).
  • Ciphers SSH uses: AES (CBC/GCM) plus ChaCha20-Poly1305 (crypto/aes.c, crypto/chacha20.c), covering [email protected] and [email protected]. Plus HMAC-SHA256.
  • Hash: SHA-256; RSA (crypto/rsa.c); CSPRNG (crypto/rng.c, RDRAND plus an entropy pool).
  • TLS 1.3 stack (net/tls): a reference for KEX, transcript-hash, and KDF patterns.
  • Terminal, PTY, termios, and VT100 support (gui/terminal.c, drivers/tty.c, drivers/pty.c) to host the remote shell.

Gaps to implement

  • X25519 (curve25519 ECDH) for curve25519-sha256 KEX. (Fallback: diffie-hellman-group14-sha256 via the existing bignum/RSA math.) Verify whether net/tls already has X25519; if so, reuse it.
  • Ed25519 sign and verify (for ssh-ed25519 host keys AND key-based client auth). RSA host keys (rsa-sha2-256/512) can be done with the existing rsa.c as an MVP fallback, but modern servers default to ed25519, so add it.
  • SSH transport layer: version banner exchange, binary packet protocol (RFC 4253), KEXINIT algorithm negotiation, key exchange plus the SSH-specific key derivation (exchange hash H and session keys), NEWKEYS, rekey.
  • Userauth (RFC 4252): password first, then publickey (sign with the user key).
  • Connection/channels (RFC 4254): open session, pty-req, shell, window-change, data; stderr; exit-status.
  • Key and host-key handling: parse OpenSSH private keys (and PEM), known_hosts read/verify/append-on-trust, key generation optional.
  • SHA-512 (commonly needed by ed25519 / rsa-sha2-512): add if missing.
  • VT100 polish: a full-enough CSI/SGR parser plus keystroke encoder in the terminal to host a remote shell (the terminal already has VT100; extend as needed).

Architecture

  • A userland ssh app that BUNDLES the freestanding crypto/*.c sources (cleanest: avoids a big new kernel crypto syscall surface), uses the TCP syscalls, and renders the remote session through the terminal/VT100.
  • Invoked from the terminal with the planned syntax ssh user@host [-i keyfile] [-p port]: either an ssh builtin in the terminal app or a standalone app under /APPS that the terminal launches with stdio wired to the terminal's PTY.
  • Keys/config on the FAT disk under a home dir (e.g. ~/.ssh: id_ed25519, known_hosts, config); 8.3 filename caveats apply (use short names).

Phases

  1. MVP: TCP + version exchange + curve25519-sha256 KEX (or group14) + a host key (RSA or ed25519 verify) + chacha20-poly1305 + password auth + a session/shell channel wired to the terminal. Goal: connect to a stock Linux OpenSSH server, accept the host key, type the password, get an interactive shell, and run commands. Byte-exact KEX and key derivation tested against a reference OpenSSH server with packet logging.
  2. Public-key auth: parse OpenSSH ed25519 (and RSA) private keys, sign the userauth request; known_hosts verify plus trust-on-first-use; algorithm negotiation for multiple ciphers/KEX/host-key types; rekey.
  3. Stretch: scp/sftp (file transfer), local/remote port forwarding, ssh-agent, keepalives, ~-escape commands.

Test plan

  • Interop against a standard Linux host running OpenSSH: connect, run typical remote commands (uname -a, ls on the remote Linux shell), hold an interactive session, and verify the VT100 rendering with full-screen programs (vi, top) in Phases 1 and 2.
  • Validate each crypto step against known test vectors; log packets and compare the exchange hash and derived keys against a reference implementation if the first MAC check fails.

Risk

  • Byte-exactness: the exchange hash and derived keys must match the server exactly or the first MAC check fails with no useful error. Build incrementally with packet logging against a real sshd. This (not the cipher code) is where the time goes.
  • Scope: comparable to the TLS or Win16 efforts; a focused multi-build subsystem. DPMI-style protected-mode concerns do not apply (pure userland plus existing crypto).