jerboa-ssh

An SSH client and in-process SSH agent for Jerboa. It implements SSH agent protocol support with Ed25519 keys plus SSH transport, auth, command execution, SFTP, and port-forwarding modules.

Private key seeds are stored in pinned C memory when supported and zeroed on removal and shutdown. Signing happens in C via OpenSSL; only signatures and public metadata cross the FFI boundary.

Features

• SSH agent protocol compatible with ssh, git, scp, and ssh-add.
• Ed25519 OpenSSH private key parsing, including encrypted key prompting.
• SSH client transport with Curve25519 key exchange, Ed25519 host keys, ChaCha20-Poly1305, AES-256-CTR, and HMAC-SHA2-256.
• Background Unix-domain socket agent server.
• Statically registered production native symbols plus an explicit development-only dynamic-loader opt-in.
• Collect-safe, pinned-buffer TCP I/O with connect, per-operation, and total handshake/SFTP deadlines.

Prerequisites

• Jerboa jerbuild (make can bootstrap v0.2.3 into .jerboa/bin).
• A supported, patched OpenSSL development package. Release evidence currently accepts OpenSSL 4.0.1+, 3.6.3+, 3.5.7+, 3.4.6+, or 3.0.21+.
• C compiler and pthreads.
• ssh-keygen/ssh-add for the agent test.

Building And Testing

make build
make test-all
make audit
make sbom
make reproducibility-report
make target-evidence
make release-evidence

make test-integration requires a configured localhost SSHD and ~/.ssh/id_ed25519; it is intentionally not part of deterministic CI.

Usage

(import (jerboa-ssh))

(ssh-agent-load-key-file "~/.ssh/id_ed25519")
(ssh-agent-start)

;; ssh, git, and other child processes can now use SSH_AUTH_SOCK.

(ssh-agent-list-keys)
(ssh-agent-stop)

(import (jerboa-ssh))

(let ([conn (ssh-connect "example.com" 22 "user" "~/.ssh/id_ed25519")])
  (ssh-run conn "id -u")
  (ssh-disconnect conn))

The default verifier rejects unknown hosts. Pre-seed the applicable known_hosts file after authenticating the displayed host-key fingerprint; the library never silently converts an unknown, hashed, revoked, or unsupported entry into TOFU acceptance.

Security

This repository is still experimental. See SECURITY.md and docs/ffi-boundary.md for release gates, FFI ownership rules, socket behavior, known-host policy, and production-readiness requirements.

Production support is blocked until make target-evidence records a marker-complete proof through JSSH_TARGET_PROOF_FILE; production release hosts should set JSSH_REQUIRE_TARGET_PROOF=1. The proof covers target localhost auth fixture evidence, OpenSSL advisory/linkage review, platform CVE review, external SSH protocol review, agent key-material review, known-hosts policy review, and cross-platform smoke. It must not contain private keys, tokens, raw SSH session captures, private paths, hostnames, customer data, or raw command output.

License

Apache License 2.0. See LICENSE.