If --password is omitted, the server prompts for the USSH login password on startup.
On interactive startup, the server asks whether it should install itself as a systemd service. Answer n to run it normally. Use --no-systemd-prompt to skip that question.
The client prompts for the password interactively, like SSH.
The client stores the first seen server X25519 public key in ~/.ussh_known_hosts.json.
If that key changes later, the client aborts with a TOFU mismatch error instead of silently trusting the new key.
If you intentionally rotated the server host key, run the client with --regen-key to allow replacing the stored TOFU key after interactive confirmation.
USSH also supports optional cleartext DATA mode with per-packet HMAC integrity:
Server side: --cleartext auto|on|off
Client side: --cleartext on|off
With server auto, USSH follows the client request.
With server on or off, the server forces the final cleartext mode.
When --cleartext on is used, USSH prints a warning that cleartext is dangerous on the real internet and is only recommended in controlled environments such as a local network.
Underneath USSH, USTPS uses readable ASCII control lines like ACK: 10 MAC:<tag>, NACK: 42 MAC:<tag>, HELLO: ..., CLOSE:, plus binary UPACK (UPAK) DATA frames.
Transport handshake
USSH inherits the same USTPS retry-token handshake as USTP-Secure.
The server first challenges the client with a retry token and session metadata.
The client must echo that token back before the encrypted USSH session is accepted.
The same handshake also negotiates the final AEAD cipher and whether USTPS Congestion is on or off.
The same handshake also negotiates whether DATA uses AEAD encryption or cleartext plus HMAC.
The retry token is only a reachability proof before session creation.
It is not the session key, not a packet nonce, and not a replacement for the later derived AEAD session key.
ACK and NACK stay plaintext for debuggability, but they are authenticated with a per-session HMAC tag to prevent forged ACK/NACK control attacks.
In normal mode, DATA payloads use AEAD encryption.
In cleartext mode, DATA payloads are not encrypted, but they still carry an HMAC so a third party cannot modify them without detection.
USSH inherits the USTPS transport payload ceiling of 900 bytes per UPACK DATA payload.
USSH does not define a second fragmentation layer below USTPS.
Transport-level MTU, PMTU, nonce behavior, duplicate handling, and stale-packet handling are inherited from USTPS.
Automatic network/path migration has been removed.
If the client changes network and its source IP:port changes, the current USSH session is expected to close and the user should reconnect cleanly.
The migration implementation was removed because it caused practical reliability and security problems:
repeated migration floods when NAT or mobile networks changed paths quickly
sessions that appeared recovered but stopped delivering terminal data
long silent periods before the client noticed the path was dead
ambiguity between a real roaming client and spoofed packets claiming an existing session
recovery state that could leave the terminal stuck instead of reconnecting cleanly
Current behavior is intentionally simpler: validate the client on the current IP:port, bind the session to that endpoint, and reconnect if the endpoint changes.
USSH inherits optional USTPS Congestion from the transport.
Server side: --congestion-control auto|on|off
Client side: --congestion-control on|off
With server auto, USSH follows the client request. With server on or off, the server forces the final mode.
USTP-Secure itself remains unordered.
USSH does not turn the transport into an ordered TCP-like channel.
USSH only reassembles the logical stdout byte stream before writing to the terminal.
USSH may also keep application-level ordering for shell input/output chunks where a PTY expects coherent byte-stream behavior.
That reassembly exists because an interactive shell output is a continuous byte stream, and rendering terminal bytes in raw arrival order can corrupt large outputs such as ls, find, or compiler logs.
This means USTP-Secure still avoids transport-level Head-of-Line blocking, while USSH restores only the application-level order required for terminal rendering.
Payloads are encrypted per packet with AEAD.
No static PSK is used.
Each client receives a separate ephemeral AEAD session key through X25519.
The password is used for USSH authentication after the secure session is established.
The server launches a real PTY-backed shell on the machine running ussh_server.py.
The client sends stdin bytes and renders stdout bytes.
The server supports multiple clients, with one shell/session per client.
If --cipher is set on the server, the server uses that exact cipher.
If --cipher is omitted or set to auto, the server uses the cipher requested by the client.
Clients reject unexpected cipher negotiation.
TOFU (Trust On First Use) is enabled on the client to detect unexpected server key changes after the first connection.
The server keeps a persistent X25519 host key in ~/.ussh_host_key by default so TOFU remains stable across reconnects and restarts.
A normal server restart does not change the host key.
Use --regen-key on the server only when you intentionally want to rotate that host key.
TOFU entries are stored per <peer-ip-or-domain>:<peer-port>, so a different server at a different address/port is treated as a different host identity.
x1colegal/ussh
