Crate libmoshpit

Expand description

Core library powering the moshpit suite of tools (mp, mps, mpa).

moshpit provides encrypted, resilient remote terminal sessions. A client (mp) authenticates to a server (mps) over TCP, then switches to an encrypted UDP channel for low-latency terminal I/O that survives IP roaming, NAT rebinding, and short network outages.

§Connection model

Phase 1 — TCP key exchange: the client opens a TCP connection and performs mutual asymmetric-key authentication. A per-session AEAD key is derived via KDF and the TCP connection is closed. See run_key_exchange, Kex, KexStateMachine.

Phase 2 — UDP session: all terminal I/O is encrypted with the negotiated AEAD cipher and delivered over UDP. The server maintains a full VT100 emulator state and sends a clean screen snapshot on reconnect. See UdpClient, UdpSender, UdpReader, DiffMode.

§Cryptography

All crypto goes through aws-lc-rs (no system OpenSSL).

Layer	Default	Alternatives
Identity key exchange	X25519 (`KEX_X25519_SHA256`)	P-384, P-256, ML-KEM-512/768/1024
Session encryption (AEAD)	AES-256-GCM-SIV (`AEAD_AES256_GCM_SIV`)	AES-256-GCM, ChaCha20-Poly1305, AES-128-GCM-SIV
Frame authentication (MAC)	HMAC-SHA-512 (`MAC_HMAC_SHA512`)	HMAC-SHA-256
Key derivation (KDF)	HKDF-SHA-256 (`KDF_HKDF_SHA256`)	HKDF-SHA-384, HKDF-SHA-512

Algorithm negotiation follows SSH “first-match-wins” semantics (negotiate).

§Wire protocol and framing

Two bincode-serialized frame enums carry everything on the wire. Frame (frames/frame.rs) is the TCP key-exchange message; EncryptedFrame (frames/encframe.rs) is the payload of every encrypted UDP datagram. Each UDP packet is laid out as [nonce (12)] [seq (8)] [hmac tag] [length (8)] [ciphertext]; the sequence number is authenticated by the HMAC and reused as the AEAD AAD, so a frame can be retransmitted verbatim without re-encryption. See EncryptedFrame::parse.

Both peers advertise a ProtocolSupport range (min/max) in their Frame::KexInit frame, and negotiate_protocol_version picks the highest commonly supported PROTOCOL_VERSION. Any change to a Frame or EncryptedFrame variant is a wire-format change: bump PROTOCOL_VERSION (leaving MIN_PROTOCOL_VERSION in place so older peers still negotiate) and gate the new behaviour on the negotiated value, reachable via Kex::protocol_version / ServerKex::protocol_version — never on the crate version. See kex/negotiate.rs for the full bump/retirement policy.

§Terminal emulation and prediction

The server runs a VT100 state machine (Emulator) on the PTY output and sends compressed diffs to the client. The client optionally renders predicted keystrokes (PredictionEngine, DisplayPreference) to eliminate perceived latency.

§Key agent

mpa is an optional key-agent daemon. The agent module provides the Unix-socket protocol types (AgentRequest, AgentResponse) and an async client (AgentClient) that mp uses to delegate identity-key operations without reading key files directly.

§Feature flags

Flag	Effect
`unstable`	Enables ML-DSA post-quantum identity key support (`KEY_ALGORITHM_ML_DSA_44`, `KEY_ALGORITHM_ML_DSA_65`, `KEY_ALGORITHM_ML_DSA_87`)

Re-exports§

pub use self::agent::AgentClient;Unix
pub use self::agent::AgentIdentityInfo;
pub use self::agent::AgentRequest;
pub use self::agent::AgentResponse;

Modules§

agent: moshpit agent protocol types and async Unix-socket client.

Structs§

AlgorithmList: Ordered list of algorithm names offered during KEX negotiation.
ClientRenderCtx: Shared client-side render state threaded through UdpReader::client_frame_loop and its per-frame helpers (handle_state_chunk, process_bytes_with_prediction).
ConnectionReader: A reader over a ReadHalf and BytesMut buffer.
ConnectionWriter: A writer over a WriteHalf and BytesMut buffer.
Emulator: A VT100/VT220 terminal emulator that tracks screen state.
EncryptedKeyPair: A moshpit encrypted key pair. A password is required to decrypt the private key.
FileLayer: Tracing configuration
IdentityKeyPair: Algorithm-aware identity key material loaded from a moshpit private key file.
Kex: The moshpit key exchange result
KexReader: The key exchange reader for the moshpit
KexSender: The key exchange sender for the moshpit
KexStateMachine: The moshpit key exchange state machine
KeyPair: A moshpit key pair consisting of a private and public key.
Layer: Tracing configuration
Mps: Used in bartoc configuration to define the bartos instance to connect to
NegotiatedAlgorithms: The result of negotiate: the single algorithm chosen for each category.
OverlayCell: A cell to be painted on top of the real screen when rendering.
OverlayCursor: Predicted cursor position to be applied after rendering overlay cells.
PredictionEngine: Local-echo prediction engine.
ProtocolSupport: The inclusive range of wire protocol versions an endpoint supports, advertised in its Frame::KexInit frame so the peer can negotiate a common version.
Renderer: A stateful differential renderer.
ServerKex: Extended key exchange for the moshpits side of the exchange
Tracing: Tracing configuration
UdpClient: UDP client data
UdpReader: UDP reader for encrypted frames
UdpSender: UDP sender for encrypted frames
UnencryptedKeyPair: A moshpit unencrypted key pair consisting of a private and public key.
UuidWrapper: A Uuid wrapper that implements bincode::Encode and bincode::Decode

Enums§

AEADCipher: The AEAD cipher algorithms supported by moshpit key generation.
DiffMode: Controls the UDP transport delivery strategy for diff packets.
DisplayPreference: How aggressively to display local-echo predictions.
EncryptedFrame: A moshpit frame — the bincode-serialized payload of an encrypted UDP datagram.
Frame: A moshpit frame — the bincode-serialized payload of a TCP key-exchange message.
KexEvent: The key exchange events
KexMode: The key exchange mode
KexState: The moshpit key exchange state
MoshpitError: Errors that can occur in moshpit
TerminalMessage: A message for the moshpits psuedo-terminal

Constants§

AEAD_AES128_GCM_SIV: AES-128-GCM-SIV authenticated encryption (16-byte key)
AEAD_AES256_GCM: AES-256-GCM authenticated encryption
AEAD_AES256_GCM_SIV: AES-256-GCM-SIV authenticated encryption (nonce-misuse resistant)
AEAD_CHACHA20_POLY1305: ChaCha20-Poly1305 authenticated encryption (fast on no-AES-NI CPUs)
KDF_HKDF_SHA256: HKDF-SHA256 key expansion
KDF_HKDF_SHA384: HKDF-SHA384 key expansion (natural pairing with P-384)
KDF_HKDF_SHA512: HKDF-SHA512 key expansion (higher security margin)
KEX_ML_KEM_512_SHA256: NIST FIPS 203 ML-KEM-512 with HKDF-SHA256 key extraction
KEX_ML_KEM_768_SHA256: NIST FIPS 203 ML-KEM-768 with HKDF-SHA256 key extraction
KEX_ML_KEM_1024_SHA256: NIST FIPS 203 ML-KEM-1024 with HKDF-SHA256 key extraction
KEX_P256_SHA256: NIST P-256 ECDH with HKDF-SHA256 (FIPS-compliant environments)
KEX_P384_SHA384: NIST P-384 ECDH with HKDF-SHA384 key extraction (higher security margin)
KEX_X25519_SHA256: X25519 ECDH with HKDF-SHA256 key extraction
KEY_ALGORITHM_ML_DSA_44unstable: The experimental key algorithm string for ML-DSA-44 identity keys.
KEY_ALGORITHM_ML_DSA_65unstable: The experimental key algorithm string for ML-DSA-65 identity keys.
KEY_ALGORITHM_ML_DSA_87unstable: The experimental key algorithm string for ML-DSA-87 identity keys.
KEY_ALGORITHM_P256: The key algorithm string for ECDH P-256 keys.
KEY_ALGORITHM_P384: The key algorithm string for ECDH P-384 keys.
KEY_ALGORITHM_X25519: The key algorithm string for X25519 (Curve25519) ECDH keys.
MAC_HMAC_SHA256: HMAC-SHA256 packet authentication (32-byte tag, saves 32 B/packet)
MAC_HMAC_SHA512: HMAC-SHA512 packet authentication (64-byte tag)
MAX_UDP_PAYLOAD: Maximum payload size for UDP frames to avoid IP fragmentation. Accounts for ~140 bytes of wire overhead (nonce, seq, HMAC, length, UUID, AEAD tag, bincode) subtracted from a conservative 1400-byte UDP payload target (below 1500-byte Ethernet MTU minus IP/UDP headers).
MIN_PROTOCOL_VERSION: Lowest wire protocol version this build can implement.
PROTOCOL_VERSION: Highest wire protocol version this build speaks.

Traits§

KexConfig: Trait for key exchange configuration
PathDefaults: Trait to allow default paths to be supplied to load
TracingConfigExt: Extension trait for TracingConfig to add additional configuration options

Functions§

clap_or_error: Converts an anyhow::Error into a suitable exit code or clap message for a CLI application.
config_file_path: Resolve the absolute path to the configuration file for the given defaults.
decrypt_private_key: Decrypts the provided encrypted private key bytes in place using the
env_var_matches: Returns true if name matches any pattern in patterns.
extract_public_key_bytes: Extract the public key bytes from a moshpit public key reader
fingerprint: Generate the fingerprint for the given key bytes
init_tracing: Initialize tracing
is_exit_title: Check if a terminal title indicates an exit command
load: Load the configuration.
load_identity_key: Load and validate identity key material, decrypting it with passphrase when needed.
load_private_key: Load a moshpit key pair from the provided private key path.
load_public_key: Load a moshpit public key from the provided public key path.
local_protocol_support: The build-default support range: min is MIN_PROTOCOL_VERSION and max is PROTOCOL_VERSION.
negotiate: SSH-style “first match wins” algorithm negotiation.
negotiate_protocol_version: Negotiate the highest wire protocol version both peers support.
new_session_registry: Create a new, empty SessionRegistry.
paint_overlays_to_ansi: Emit the ANSI sequences for overlays and cursor without touching any renderer state. Used by the stdin forwarder to preview predicted keystrokes on top of whatever is currently displayed — without modifying the differential-render baseline.
parse_server_destination: Parse the server destination command line option into a SocketAddr
randomart: Get the randomart image for the given key bytes
render_prediction_update: Render a single clean update reflecting a locally-predicted keystroke.
render_server_update: Render a single clean update to the terminal after the server has changed the emulator’s screen state.
run_key_exchange: Run the client side of the key exchange
success: Indicates successful execution of a function, returning exit code 0.
supported_algorithms: Returns the complete set of algorithms supported by this build, in server-default preference order (strongest / most broadly compatible first).
to_path_buf: Convert a string to a PathBuf
validate_identity_key_pair: Validate decrypted identity key material against the public key stored in the key file.
verify_fingerprint: Verify a public key fingerprint against the provided key bytes

Type Aliases§

HostKeyMismatchFn: Callback invoked when a known host presents a different key than pinned.
SessionRegistry: Minimal session registry used during key exchange.
TofuFn: The callback type for TOFU (Trust-On-First-Use) interactive host key validation.