// Package faceclawssh is Faceclaw's SSH transport, bound into the Android and // iOS apps with gomobile. It exposes text-message channels over SSH: // // - "exec": run a command on the host and exchange newline-delimited text // with it (stdin lines in, stdout lines out). Used for tmux control mode // and the tmux session poller. // - "websocket": open a direct-tcpip channel to an address as seen from the // host (normally g2mirror-server on 127.0.0.1:8737) and speak WebSocket // text frames over it. // // Channels to the same host, user and credentials share one SSH connection // (see pool.go). Host keys are pinned by the caller: a connection whose host // presents a key that isn't in the spec's hostKeys fails with a // "hostkey-unknown" or "hostkey-mismatch" failure carrying the presented key, // so the app can show the fingerprint and retry once the user has trusted it. // Authentication uses a platform-held, non-exportable ECDSA P-256 key (the // Signer interface; Android Keystore / iOS Secure Enclave) and, if the server // allows it, a password. // // Everything crossing the gomobile boundary is a string, []byte or one of the // interfaces below; structured values are JSON strings. package faceclawssh import ( "context" "encoding/json" "fmt" "runtime/debug" "sync" "time" ) // Signer is implemented by the platform: an ECDSA P-256 key whose private // half never leaves the device's keystore. type Signer interface { // PublicKey returns the key's public half, either as X.509 // SubjectPublicKeyInfo DER (Android's PublicKey.getEncoded()) or as an // uncompressed X9.62 point, 0x04 || X || Y (iOS's // SecKeyCopyExternalRepresentation). PublicKey() []byte // Sign returns the ASN.1 DER ECDSA signature of SHA-256(data). Sign(data []byte) ([]byte, error) } // Listener receives a channel's events. Calls arrive on arbitrary goroutines // (never concurrently for one channel); the platform wrapper hops them onto // the thread that owns the channel. // // Event kinds and payloads: // - "open": the channel is ready; payload empty. Sends made before this are // queued and delivered once open. // - "text": one message (websocket text frame, or one stdout line without // its newline). Exec lines that aren't valid UTF-8 have every byte >= 0x80 // escaped as a backslash and three octal digits, matching tmux control // mode's escaping of control characters (see escapeLine). // - "stderr": one stderr line of an exec channel, escaped the same way. // - "closed": the channel ended normally; payload is JSON // {"exitStatus": n, "signal": "...", "code": n, "reason": "..."} with the // fields that apply (exec exit status/signal, websocket close code/reason). // Terminal: no events follow. // - "failure": the channel could not be opened or was lost; payload is a // JSON Failure. Terminal: no events follow. type Listener interface { OnEvent(kind string, payload string) } // Failure describes why a channel failed, as the JSON payload of a "failure" // event. type failure struct { // "hostkey-unknown": no host key is pinned yet; HostKey is what the host // presented. "hostkey-mismatch": the host presented a key that isn't // pinned. "auth": the host refused every credential we have. // "network": couldn't reach the host, or the connection dropped. // "channel": the SSH connection is fine but the channel couldn't be // opened (exec refused, nothing listening at the forwarded address...). // "config": the spec was malformed. "internal": a bug. Kind string `json:"kind"` Message string `json:"message"` HostKey *hostKeyInfo `json:"hostKey,omitempty"` // For "auth": the host accepts password (or keyboard-interactive) // authentication, whether a password was sent, and whether our key was // offered. PasswordAllowed bool `json:"passwordAllowed,omitempty"` PasswordTried bool `json:"passwordTried,omitempty"` KeyTried bool `json:"keyTried,omitempty"` } func (f *failure) Error() string { return f.Message } type hostKeyInfo struct { // SSH key type, e.g. "ssh-ed25519". Type string `json:"type"` // OpenSSH-style SHA-256 fingerprint, "SHA256:". Fingerprint string `json:"fingerprint"` // The key in SSH wire format, base64: what goes in a spec's hostKeys. Key string `json:"key"` } type channelSpec struct { // "exec" or "websocket". Type string `json:"type"` // exec: the command line, run by the user's login shell. Command string `json:"command"` // websocket: ws:// URL, resolved on the host's side of the connection. URL string `json:"url"` } type openSpec struct { Host string `json:"host"` Port int `json:"port"` User string `json:"user"` Password string `json:"password"` // Pinned host keys, SSH wire format, base64. Empty: the first connection // fails with "hostkey-unknown". HostKeys []string `json:"hostKeys"` // Offer the platform key (the Signer passed to Open). UseKey bool `json:"useKey"` ConnectTimeoutMs int `json:"connectTimeoutMs"` KeepaliveIntervalMs int `json:"keepaliveIntervalMs"` Channel channelSpec `json:"channel"` } const ( defaultConnectTimeout = 15 * time.Second defaultKeepaliveInterval = 20 * time.Second // Messages queued on a channel before Send starts refusing them. sendQueueCapacity = 4096 // How long Close waits for queued messages to flush and the far end to // finish before tearing the channel down. closeGracePeriod = 2 * time.Second ) // Channel is one open (or opening) channel. Methods are safe to call from // any thread. type Channel struct { listener Listener ctx context.Context cancel context.CancelFunc mu sync.Mutex closed bool // Close was called: no more sends, no more events opened bool sendQ chan string finishOnce sync.Once } // Open starts opening a channel described by spec (a JSON openSpec) and // returns immediately; progress arrives as listener events. signer may be // nil (no key authentication). func Open(spec string, signer Signer, listener Listener) *Channel { ctx, cancel := context.WithCancel(context.Background()) c := &Channel{ listener: listener, ctx: ctx, cancel: cancel, sendQ: make(chan string, sendQueueCapacity), } go c.run(spec, signer) return c } // Send queues one message: a websocket text frame, or a line for an exec // channel's stdin (the newline is added). Returns false if the channel is // closed or its queue is full. func (c *Channel) Send(text string) bool { c.mu.Lock() defer c.mu.Unlock() if c.closed { return false } select { case c.sendQ <- text: return true default: return false } } // Close ends the channel. Messages already queued are still sent (so a // parting "unview" reaches the host), then the channel's write side is // closed and, after a short grace period, the channel is torn down. No // events are delivered after Close. func (c *Channel) Close() { c.mu.Lock() if c.closed { c.mu.Unlock() return } c.closed = true opened := c.opened close(c.sendQ) c.mu.Unlock() if !opened { c.cancel() return } time.AfterFunc(closeGracePeriod, c.cancel) } func (c *Channel) isClosed() bool { c.mu.Lock() defer c.mu.Unlock() return c.closed } func (c *Channel) emit(kind, payload string) { if c.isClosed() { return } c.listener.OnEvent(kind, payload) } func (c *Channel) markOpen() { c.mu.Lock() c.opened = true c.mu.Unlock() c.emit("open", "") } // finish delivers the channel's one terminal event ("closed" or "failure"). func (c *Channel) finish(kind string, payload any) { c.finishOnce.Do(func() { encoded, err := json.Marshal(payload) if err != nil { encoded = []byte(`{"kind":"internal","message":"unencodable event"}`) } c.emit(kind, string(encoded)) c.cancel() }) } func (c *Channel) fail(f *failure) { c.finish("failure", f) } // guard turns a panic in one of our goroutines into a failure event instead // of crashing the app (an unrecovered Go panic kills the whole process). func (c *Channel) guard() { if r := recover(); r != nil { c.fail(&failure{Kind: "internal", Message: fmt.Sprintf("internal error: %v\n%s", r, debug.Stack())}) } } func (c *Channel) run(specJSON string, signer Signer) { defer c.guard() var spec openSpec if err := json.Unmarshal([]byte(specJSON), &spec); err != nil { c.fail(&failure{Kind: "config", Message: "bad channel spec: " + err.Error()}) return } if spec.Host == "" || spec.User == "" { c.fail(&failure{Kind: "config", Message: "host and user are required"}) return } if spec.Port == 0 { spec.Port = 22 } if !spec.UseKey { signer = nil } conn, err := acquire(c.ctx, &spec, signer) if err != nil { if c.ctx.Err() != nil { return } c.fail(asFailure(err)) return } defer conn.release() switch spec.Channel.Type { case "exec": c.runExec(conn, spec.Channel.Command) case "websocket": c.runWebSocket(conn, spec.Channel.URL) default: c.fail(&failure{Kind: "config", Message: fmt.Sprintf("unknown channel type %q", spec.Channel.Type)}) } } func asFailure(err error) *failure { if f, ok := err.(*failure); ok { return f } return &failure{Kind: "network", Message: err.Error()} } // AuthorizedKey formats a platform public key (see Signer.PublicKey) as an // authorized_keys line: "ecdsa-sha2-nistp256 AAAA... comment". func AuthorizedKey(publicKey []byte, comment string) (string, error) { key, err := sshPublicKey(publicKey) if err != nil { return "", err } return authorizedKeyLine(key, comment), nil } // Fingerprint returns the OpenSSH SHA-256 fingerprint ("SHA256:...") of a // platform public key. func Fingerprint(publicKey []byte) (string, error) { key, err := sshPublicKey(publicKey) if err != nil { return "", err } return fingerprint(key), nil }