dosh/docs/THREAT_MODEL.md

Dosh Threat Model

This is the published threat model for Dosh native v1, derived from docs/NATIVE_V1_SPEC.md sections 4-6. It states the assets Dosh protects, the attackers it does and does not defend against, the security properties Dosh claims relative to SSH, the cryptographic building blocks actually in use, and an honest list of accepted residual risks and known gaps.

Dosh is a remote-login transport for Dosh-installed servers. It is intended to replace the day-to-day ssh host workflow for terminals and TCP forwarding while keeping OpenSSH as a recovery and bootstrap fallback. Dosh is not an RFC-compatible SSH implementation and does not claim SSH's entire protocol security surface. It claims security that is equivalent to, and in some respects stronger than, SSH for the Dosh terminal and forwarding use case on hosts running dosh-server.

1. Assets

Dosh protects:

• Terminal session contents. Keystrokes, command output, and the authoritative screen state for every named or generated session.
• Forwarded TCP streams. Bytes carried over -L, -R, and -D channels.
• User authentication credentials. The user's SSH/Dosh private keys and any ssh-agent identities. Dosh never sees private key material in plaintext on the wire; signatures are produced locally or by the agent.
• Server-issued credentials. Session keys, ClientId association state, server-sealed attach tickets, and the client-held attach-ticket PSK.
• Server identity. The persistent Dosh host key (~/.config/dosh/host_key) and the server secret used to seal attach tickets and derive bootstrap material.
• Host-trust state. The client's pinned known-hosts file (~/.config/dosh/known_hosts).
• Authorization policy. ~/.ssh/authorized_keys / ~/.config/dosh/authorized_keys and the forwarding policy they encode.

2. Attackers

In scope (Dosh must defend against these)

• Passive network observer. May record all UDP traffic between client and server.
• Active network attacker. May spoof, drop, replay, reorder, or modify any packet, and may attempt to inject forged packets in either direction.
• NAT rebinding / roaming. Client source IP and port may change mid-session, including across sleep, network switch, and NAT timeout.
• Stolen attach-ticket cache without the user's private key. An attacker who reads a client cache copies a server-sealed ticket plus its PSK but does not have the user's SSH private key.
• Server restart and key rotation. Stale session keys, tickets, and replay state must not be usable after the server rotates its secret or host key.
• Malicious unauthenticated client flooding auth attempts. A peer that has no authorized key tries to exhaust server resources or guess credentials.
• Compromised low-privilege local user on a shared client. A different local user attempts to read Dosh credential caches on the same machine.

Out of scope (explicitly not defended against)

• Compromised client machine. If the endpoint running dosh-client is owned by the attacker, the attacker has the user's keys and terminal.
• Compromised server account. If the login account on the server is owned, the attacker already has the shell Dosh would have given them.
• Malicious kernel, terminal emulator, or PTY implementation on either side.
• A server that was legitimately authorized and later turns malicious. Host-key pinning detects a substituted server, not a trusted server that decides to misbehave.

These exclusions match SSH's own boundaries: SSH likewise cannot protect a compromised endpoint or a malicious authorized peer.

3. Security Properties Claimed vs SSH

Property	SSH	Dosh native v1	Notes
Server authentication before trusting session data	yes	yes	Host key signs the handshake transcript; client verifies before sending user auth or accepting terminal bytes.
User authentication by private-key possession	yes	yes	Ed25519 via ssh-agent or encrypted OpenSSH key; signature binds the full transcript.
Forward secrecy	yes	yes	Ephemeral X25519 per connection; long-term host/user keys never derive the traffic key.
AEAD on every post-handshake packet	yes	yes	ChaCha20-Poly1305 with per-direction, per-sequence nonces.
Replay protection	yes	yes	Sliding replay window over the AEAD packet counter, plus transcript-bound handshake.
Host-key pinning with explicit first use	TOFU, weakly tied to transport	yes, with explicit policy	Default refuses unknown host keys; TOFU only when trust_on_first_use is set; mismatch hard-fails and never auto-replaces.
No plaintext terminal bytes after handshake	yes	yes	All Frame/Input/stream packets are AEAD-sealed.
No custom cryptographic primitives	yes	yes	Standard X25519/HKDF-SHA256/ChaCha20-Poly1305/Ed25519 crates only.
Fail-closed downgrade behavior	yes	yes	Native auth failure surfaces an explicit error and SSH fallback is explicit; it never silently drops to an unauthenticated mode.
Fast resumption without re-auth	ControlMaster only	yes, native	Cached session/ticket attach skips a fresh round of public-key proof; this is a deliberate speed/security trade discussed in section 6.

Where Dosh aims to exceed SSH for this use case

• Tighter transcript binding. A user-auth signature binds both ephemeral keys, both randoms, the server host key, requested user/session/mode/terminal size, selected algorithms, and protocol version into one transcript. This forecloses cross-protocol and partial-replay confusion classes for the narrow Dosh surface.
• Smaller attack surface. Dosh deliberately omits the full SSH transport/channel machinery, arbitrary subsystems, X11, SFTP/SCP, and forced-command subsystems. Fewer features means fewer parsers and fewer reachable states.
• Explicit, file-pinned host trust. Host trust is a first-class, inspectable known-hosts entry with source provenance (tofu/ssh/manual) and a hard-fail mismatch path, rather than the looser default TOFU behavior most SSH clients ship.
• Modern primitives only. Ed25519 and X25519 by default; no DSA, no SHA-1 signatures, no CBC-and-MAC constructions.

Dosh does not claim generic SSH compatibility and must not be described as an SSH-protocol implementation.

4. Cryptographic Building Blocks (as implemented)

These reflect the code in src/crypto.rs, src/native.rs, src/auth.rs, and src/protocol.rs, not just the spec.

• Key exchange: X25519 ephemeral-ephemeral (x25519-dalek). The shared secret is checked for contributory behaviour; a non-contributory result is rejected.
• Handshake/transport KDF: HKDF-SHA256 (hkdf), salted with the SHA-256 of the serialized ClientHello and ServerHello, binding traffic keys to the transcript.
• AEAD: ChaCha20-Poly1305 (chacha20poly1305) for every encrypted packet and for sealed attach tickets. Nonces are derived as direction || sequence, giving a unique nonce per (key, direction, sequence). AES-GCM is reserved for later and is not selectable today.
• Host-key signatures: Ed25519 (ed25519-dalek) over the handshake transcript.
• User-auth signatures: Ed25519, produced either by ssh-agent over a Unix socket (src/ssh_agent.rs) or from an encrypted/plaintext OpenSSH private key (ssh-key). The signature covers the user-auth transcript described above.
• Bootstrap auth (SSH fallback path): HMAC-SHA256 attach tokens and HKDF-SHA256 derived session keys, with attach tickets sealed under an HKDF-derived ticket key. Token comparison is constant-time.
• Hashing/transcript: SHA-256 (sha2).
• Randomness: OS CSPRNG via rand::thread_rng() / OsRng.

No homegrown ciphers, MACs, padding schemes, or key derivation are used. No nonce or key pair is reused within a direction.

5. How the Properties Are Enforced (handshake and transport)

• Server authentication. ServerHello carries the host public key and an Ed25519 signature over dosh/native/server-hello/v1 || ClientHello || ServerHello(unsigned). The client verifies this signature and checks the host key against its pinned known-hosts entry before sending user auth or accepting terminal bytes. Unknown keys are refused unless TOFU is enabled; mismatches hard-fail with both fingerprints and the file path.
• User authentication. UserAuth carries an Ed25519 signature over dosh/native/user-auth/v1 || ClientHello || ServerHello || UserAuth(unsigned). The server looks the public key up in authorized_keys, enforces authorized-key options, then verifies the signature. A removed key can no longer authenticate.
• Authorization options. from= (with CIDR, glob, and negation), no-port-forwarding, and permitopen= are enforced. command= is rejected for native terminal login. Any unrecognized restrictive option fails closed rather than being silently ignored.
• Forwarding policy. The server enforces allow_tcp_forwarding, allow_remote_forwarding, and a loopback-only default for remote binds (allow_remote_non_loopback_bind), in addition to per-key permitopen= / no-port-forwarding.
• Replay protection. A 128-wide sliding window over the per-direction packet counter rejects duplicates and stale sequences. Sequence 0 is never accepted.
• Stale-key tolerance. Each encrypted packet carries a session_key_id; packets under an old key are dropped as "stale or wrong session key id" rather than treated as fatal decrypt failures, so reconnect after rotation is non-destructive.
• Roaming. The server keys clients by ClientId and session key id, not by source address, and updates the endpoint after any valid encrypted packet from a new address — without weakening authentication, because the packet must still decrypt and verify.

6. Accepted Residual Risks and Known Gaps

These are stated openly so the public claim gate (NATIVE_V1_SPEC.md section 17) can be evaluated honestly. Items here are not yet "green".

Accepted residual risks (by design)

• Attach tickets prove recent server-issued possession, not fresh private-key possession. A stolen client cache containing both the sealed ticket and its PSK can attach until the ticket expires (default TTL 24h, configurable down to zero) or until the server rotates its secret/host key or the user key is removed. This is the deliberate speed trade. It is bounded by TTL, scoped to host/user/session/mode, and can be disabled. SSH ControlMaster has an analogous live-socket exposure.
• Local cache confidentiality relies on filesystem permissions. Host keys, server secret, known-hosts, and credential caches are written 0600. A same-machine attacker who can already read another user's 0600 files (e.g. via root) is out of scope, as with SSH's ~/.ssh.
• A trusted server that turns malicious is not detected. Host-key pinning detects substitution, not betrayal by an already-authorized server. This matches SSH.

Known gaps / work in progress (must close before the public claim)

• Per-IP rate limiting is partial. The server evicts half-finished native handshakes on a TTL so a flood of ClientHello packets cannot grow the pending map without bound, and it reports a static rate_limit_remaining hint in ServerHello. A full per-source token-bucket limiter is in progress on another track and is not yet enforced. Until it lands, sustained auth flooding is mitigated only by the handshake-eviction TTL and OS-level limits.
• Protocol VERSION negotiation is being hardened. The wire format pins a single protocol version: the packet header rejects any non-matching VERSION byte and the native handshake rejects any non-matching protocol_version. There is no multi-version negotiation yet, so cross-version interop and downgrade-resistance for future versions are still being designed. Today's behavior is fail-closed (reject), not silent downgrade.
• Fuzzing is not yet wired into CI. CI currently runs format, tests, release build, and the Docker SSH benchmark gate. Fuzz targets for packet parsing, authorized-key parsing, known-host parsing, and handshake state (spec milestone 5) are being wired in and are not yet running in CI.
• User-key algorithm coverage is Ed25519-only today. The spec permits ECDSA P-256 and (compatibility-only, SHA-2) RSA, but native auth currently accepts and produces ssh-ed25519 only. ECDSA/RSA support is pending. This is a parity gap, not a weakening of what is supported.
• Hostile-network and long-soak integration tests are partial. Roaming, retransmit, resize, and multi-client tests exist; a dedicated adversarial drop/reorder/replay suite and 30-minute-sleep soak (spec section 16) are still being expanded.
• No external security review yet. The spec's milestone 5 requires an external review checklist before public security claims. That review has not happened.

Auth posture

Native auth is opt-in alongside SSH fallback. auth_preference defaults to native,ssh: Dosh tries the native authenticated path first and falls back to SSH bootstrap explicitly and visibly when native auth is disabled, unavailable, or rejected. Native auth failure never silently degrades to an unauthenticated mode. Forwarding (-L/-R/-D) requires the native authenticated path and refuses to run under --local-auth.

7. Verification and Public-Claim Status

Dosh may claim "native SSH replacement for Dosh-installed servers" only after the conditions in NATIVE_V1_SPEC.md section 17 are met: native auth default on a real host, SSH fallback available, the section 16 checklist green, this threat model published, and benchmarks with raw samples for SSH cold, Dosh native cold, Dosh cached attach, and Mosh startup.

Current status: this threat model is published (this document). The verification checklist is not yet fully green — see the item-by-item status table in docs/PUBLIC_READINESS.md ("Native v1 verification checklist status") and the known gaps in section 6 above. Until the gaps close and an external review is complete, Dosh's defensible public claim remains fast, encrypted native attach/reconnect with SSH-equivalent transport security and SSH bootstrap fallback — not a fully verified, externally reviewed SSH replacement.