Information for agents

Rules for changes

Don't add comments saying what's happening when it's obvious from the code
Comments should only be added if they will be useful in the future. Don't comment that something was added or that this is new code and that is old code.
Update README.md and CLAUDE.md to reflect the changes if relevant. Keep this concise.
ALWAYS update cargoHash in flake.nix to ensure the nix build works.

Reverse engineered specs

The KVM and mount protocols have been reverse engineered from the original client and server. The results have been documented in KVM_PROTOCOL.md and MOUNT_PROTOCOL.md. General reverse engineering notes (function addresses, data structures, class hierarchies) are in REVERSING_CLIENT.md and REVERSING_SERVER.md (for the server BMC firmware).

The original_binaries/client directory contain the original Java app (iKVM v1.69.21) and native libraries. The original_binaries/server directory contain the full extracted BMC firmware for Supermicro X9DRD-7LN4F server version 3.39.

There are two ghidra MCP servers available. ghidra-server has the server binaries loaded, ghidra-client has the client app and libraries.

Project structure

Rust workspace with four crates:

crates/aten-mount — library implementing the ATEN virtual media protocol
crates/aten-mount-cli — CLI binary (thin wrapper around the mount library)
crates/aten-kvm — library implementing the ATEN KVM/RFB protocol (Hermon decoder)
crates/aten-gui — Slint GUI app (winit backend, KVM console viewer with keyboard input)

Module responsibilities (aten-kvm)

protocol.rs — RFB handshake, ATEN auth, message dispatch, keepalive, key event builder
hermon.rs — Hermon video decoder (encoding 0x59, RGB555/8bpp tile decoding)

Module responsibilities (aten-gui)

keymap.rs — Physical key (winit KeyCode) to USB HID keycode mapping
ui/main.slint — Window layout: left toolbar (Ctrl/Alt toggles, Ctrl+Alt+Del), framebuffer display, error dialog overlay

Module responsibilities (aten-mount)

protocol.rs — PDU packet builders, header parsing, TCP session state machine
scsi.rs — SCSI command dispatch; emulates a CD-ROM device (14 commands)
usb.rs — Static USB descriptor data for the virtual CD-ROM device
crypto.rs — RC4 encryption for the authentication packet

Key design decisions

Sector size is always 2048 bytes (CD-ROM only, no floppy/HDD support)
RC4 key is hardcoded (BX80570E3110Q814A447) — matches the firmware's hardcoded key
Unknown SCSI opcodes return success with no data (matches firmware behavior)
File I/O uses read_at() (unix-only) so there's no shared seek position
Authentication is plaintext (RC4 with a known key); this matches the original — there is no better option

Build and test

cargo test
nix build .#aten-mount   # CLI mount tool
nix build .#aten-gui     # KVM console viewer (winit backend)

2.9 KiB Raw Blame History