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).

§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.
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.
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.
Frame: A moshpit frame.
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).

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.
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.
negotiate: SSH-style “first match wins” algorithm negotiation.
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
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.