Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ actor main(env):
# Verify info.fingerprint against a known value in production.
c.accept_hostkey()

def on_connect(c: ssh.Client, err: ?str):
def on_connect(c: ssh.Client, err: ?Exception):
if err is not None:
print("connect failed:", err)
env.exit(1)
Expand Down Expand Up @@ -231,7 +231,12 @@ the server generates an ephemeral in-memory key using `host_key_type` and
and/or `private_keys: list[PrivateKey]`. Tunables: `port`, in-memory
`known_hosts`, `transport`, `connect_timeout`, `auth_timeout`,
`keepalive_interval`, `keepalive_enabled`, `close_timeout`,
`max_write_buffer`.
`max_write_buffer`. A failed connect reports `on_connect(client, err)` with
an `OSError` when it failed before the server's SSH banner, like a refused
TCP connect, and otherwise an `SshError`: `KeyExchangeError` when client
and server share no algorithm, `HostKeyError` when the host key is not
trusted, `AuthenticationError` when the server refuses the credentials.
`SshPipe` reports the same errors.
- **`Channel(client, on_open, on_stdout, on_stderr, on_exit, on_close)`** —
`request_exec(cmd)`, `request_shell(...)`, `request_subsystem(name)`,
`write(data)`, `send_eof()`, `close()`. `?bytes` callbacks deliver `None`
Expand Down
4 changes: 2 additions & 2 deletions src/bench_echo.act
Original file line number Diff line number Diff line change
Expand Up @@ -69,9 +69,9 @@ actor main(env):
def on_hostkey(c: ssh.Client, state: str, info: ssh.HostKeyInfo):
c.accept_hostkey()

def on_connect(c: ssh.Client, err: ?str):
def on_connect(c: ssh.Client, err: ?Exception):
if err is not None:
fail("connect: " + err)
fail("connect: " + str(err))
return
t_connect = time.monotonic()
ssh.Channel(c, ch_open, ch_out, ch_err, ch_exit, ch_close)
Expand Down
2 changes: 1 addition & 1 deletion src/example_client.act
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ actor main(env):
print("host key [" + state + "]", info.key_type, info.fingerprint)
c.accept_hostkey()

def on_connect(c: ssh.Client, err: ?str):
def on_connect(c: ssh.Client, err: ?Exception):
if err is not None:
print("connect error:", err)
env.exit(1)
Expand Down
2 changes: 1 addition & 1 deletion src/interop_client.act
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ actor main(env):
print("HOSTKEY", state, info.key_type, info.fingerprint)
c.accept_hostkey()

def on_connect(c: ssh.Client, err: ?str):
def on_connect(c: ssh.Client, err: ?Exception):
if err is not None:
print("CONNECT-ERROR", err)
env.exit(1)
Expand Down
45 changes: 41 additions & 4 deletions src/lib.act
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,10 @@ Authentication (client):
- If neither is given, the connection fails.

Callback ordering and semantics:
- All operations are async actor actions; callbacks receive errors as ?str.
- All operations are async actor actions. Client.on_connect receives an
error as ?Exception: SshError or one of its subclasses, or OSError for a
failure before the server's SSH banner. Other callbacks receive errors
as ?str.
- ?bytes data callbacks use None to signal EOF (end of that stream).
- On channel teardown the delivery order is: on_exit (if the remote sent an
exit status), then on_stdout(None) / on_stderr(None) for streams that have
Expand Down Expand Up @@ -69,6 +72,36 @@ Notes:
import net


class SshError(Exception):
"""An SSH connection failed after the server's SSH banner arrived.

Client.on_connect reports a failure before the banner, like a refused
TCP connect, as an OSError. The subclasses are the failures that need a
change on one side to go away.
"""
pass


class KeyExchangeError(SshError):
"""The key exchange failed, as when client and server share no key
exchange, host key, cipher or MAC algorithm. Client's transport sets
what the client offers."""
pass


class HostKeyError(SshError):
"""The client did not trust the server's host key: the key does not match
known_hosts, on_hostkey rejected it or did not answer in time, or there
is no on_hostkey to ask."""
pass


class AuthenticationError(SshError):
"""The server refused every credential the client offered, or the client
had none to offer."""
pass


class Algorithm:
"""An algorithm supported by the bundled libssh build."""
_name: str
Expand Down Expand Up @@ -587,7 +620,7 @@ class AuthRequest():
actor Client(cap: net.TCPConnectCap,
host: str,
username: str,
on_connect: action(Client, ?str) -> None,
on_connect: action(Client, ?Exception) -> None,
on_close: action(Client, str) -> None,
on_hostkey: ?action(Client, str, HostKeyInfo) -> None=None,
password: ?str=None,
Expand All @@ -605,7 +638,11 @@ actor Client(cap: net.TCPConnectCap,
"""SSH Client

Connects to host:port as username. on_connect(err) fires exactly once:
err is None on success, otherwise a description of the failure.
err is None on success. A failure before the server's SSH banner, like a
refused TCP connect, is an OSError. After the banner it is a
KeyExchangeError while client and server agree on algorithms and keys, a
HostKeyError when the host key is not trusted, an AuthenticationError
when the server refuses the credentials, and otherwise an SshError.
on_close(reason) fires exactly once after a successful connect when the
session ends. on_hostkey is invoked for host key verification when the
key is not already trusted via the in-memory known_hosts data; respond
Expand Down Expand Up @@ -648,7 +685,7 @@ actor Client(cap: net.TCPConnectCap,
var _keepalive_enabled: bool = keepalive_enabled
var _close_timeout: float = close_timeout
var _max_write_buffer: int = max_write_buffer
var _on_connect: action(Client, ?str) -> None = on_connect
var _on_connect: action(Client, ?Exception) -> None = on_connect
var _on_close: action(Client, str) -> None = on_close
var _on_hostkey: ?action(Client, str, HostKeyInfo) -> None = on_hostkey

Expand Down
Loading
Loading