Files
faceclaw/native/ssh/faceclawssh.go
T

305 lines
9.6 KiB
Go

// 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:<base64>".
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
}