ddn.api.net.ssh

Result codes for raw transport operations.

Mirrors the convention used by the other ddn.api.net transports, declared locally so this module does not depend on the TLS API.

Progress indicator for non-blocking SSH operations.

Every potentially-blocking operation returns or reports an SshProgress value instead of blocking. The caller checks the result and re-drives the owning session when the corresponding wait is satisfiable.

Typed error information for SSH operations.

Used by SshResult, operations, channels, and sessions to report failures without exceptions. Error reporting is per operation or per channel; a session-level error only exists for conditions that make the whole connection unusable.

Result of an SSH read or write operation.

Combines a byte count with progress information, optional typed error details, and an end-of-stream flag.

Result conventions:

• Positive bytes: number of bytes transferred.
• progress == DONE with bytes == 0 and

  eof == true unambiguously means end of stream. Idle reads with nothing available never report DONE; they report NEED_READ or WAIT.

• A zero-length buffer is a no-op that returns immediately with

  DONE and bytes == 0; it is distinct from both an idle read and end of stream.

• Bytes reported as accepted by a write must never be resubmitted

  by the caller; the sender tracks the remainder.

Ordered byte transport underlying an SSH connection.

Implementations wrap a socket, a pipe, an in-memory buffer, or any other ordered stream. The SSH protocol engine performs all of its network interaction through this interface; it never opens sockets by itself, which keeps it embeddable in any event loop and testable on memory transports.

Return Value Convention:

• Positive value: number of bytes read/written.
• Zero (0): clean end-of-file, peer closed the connection.
• Negative value: an SshIoResult code indicating

  error or would-block.

Lifecycle states of an SSH session.

A session moves forward through these states as SshSession.pump is driven; it never moves backward except to FAILED or DISCONNECTED, which are terminal.

Kinds of waits an SSH session can report to its driver.

What the driver of a session should wait for when pumping cannot progress without external action.

For SshWaitKind.IO the flags select the readiness events of the session transport supplied by the application. Agent or signer I/O is application-owned and surfaces as SshWaitKind.DECISION; the application queries its signer for the concrete readiness it needs.

Algorithm preference lists for session negotiation.

Lists are ordered from most to least preferred. Cipher and MAC preferences apply to both directions. MAC preferences are used only when the selected cipher requires a separate MAC.

Names are SSH wire names (for example curve25519-sha256); unknown peer names are parsed safely and reported through negotiation results and diagnostics rather than crashing the session.

Algorithms actually negotiated for a session.

Directional entries reflect the independent per-direction negotiation of the SSH transport protocol.

An SSH-2 client connection driven by explicit pumping.

Ownership and threading rules:

• The session owns all protocol state for the connection and

  advances all channels, key exchange, rekey, authentication operations, and control messages when pumped.

• Sessions are single-threaded and non-reentrant: callbacks

  invoked during pump must not call back into the session.

• The session references - but does not own - the supplied

  SshTransport; the application keeps the transport alive until the session reaches a terminal state.

Driving model:

• Call pump whenever any wait reported by

  waitState is satisfied, or to make initial progress.

• pump performs pending non-blocking I/O on the session

  transport and returns the aggregate progress; when it cannot proceed, waitState describes what the driver should wait for (transport readiness, an application decision, or a timer deadline).

• A blocked channel write may require reading the session

  transport (window adjustment), not transport writability; the session accounts for this when reporting waits.

Global request replies arrive in request order without identifiers, so the session issues them strictly one reply at a time.

A remote TCP/IP forward request (tcpip-forward).

Identity of an incoming forwarded TCP/IP channel (RFC 4254 7.2).

Decision states for an incoming forwarded channel.

The caller's decision for an incoming forwarded channel.

Caller-controlled bind/accept policy for remote TCP forwarding.

The handler decides every incoming forwarded channel; the session never accepts one on its own. While decideForwardedChannel reports PENDING the request stays queued and is asked again on later pump calls; the queue is bounded and overflow is refused.

Information about a server host key offered for verification.

Verdict of an application host-key policy.

Application-supplied host trust policy.

The session consults the verifier during the initial key exchange and on every rekey, always before any credential or signing request. Implementations must not block; interactions that need user input return SshVerdict.PENDING and answer on a later poll.

A public key offered for public-key authentication.

Result of an asynchronous signing request.

Application-owned signer for public-key authentication.

Implementations wrap an in-memory private key or - asynchronously - an ssh-agent. Signatures cover the exact session-bound authentication request data supplied by the session, so a signature can never be replayed against another session.

Implementations must not block. An agent-backed signer reports SshProgress.WAIT while its own transport is pending; the application drives that transport independently of the session.

Outcome of polling a password provider.

Result of polling an SshPasswordProvider.

Application-owned password source.

Implementations must not block; user interaction returns SshPasswordStatus.PENDING until the answer is available. Password-change-required responses from the server are surfaced as a distinct authentication error; the provider is never re-polled indefinitely for them.

One RFC 4256 keyboard-interactive prompt.

One bounded RFC 4256 challenge round from the server.

A zero-length prompts array is valid: providers still receive the round so they can surface instruction, then return an empty answer array.

Outcome of polling a keyboard-interactive provider.

Result of polling an SshKeyboardInteractiveProvider.

Application-owned keyboard-interactive challenge provider.

Implementations own all UI decisions and must not block. The SSH library never logs answers and discards provider results immediately after serializing one response. Providers should likewise avoid retaining answers after returning them.

SSH user authentication methods, used for server capability discovery.

A user authentication operation driven by session pumping.

The handle is stable for the lifetime of the attempt: resuming or retrying the same operation never duplicates protocol requests. A partialSuccess result means the server accepted one factor and requires another; start the next method with a new authenticate call.

Channel types offered by this API.

Flow-control parameters of a channel as requested by the client.

An in-flight channel-open operation driven by session pumping.

Channel request types carryable by SshChannel.request.

Terminal-mode opcodes for pseudo-terminal allocation (RFC 4254 section 8).

Each opcode takes one uint32 argument; boolean modes use 0/1. The encoded mode stream ends with TTY_OP_END, which the implementation appends automatically.

One terminal-mode pair of a pseudo-terminal request (RFC 4254 section 8).

A request on a session channel.

Field applicability follows SshChannelRequestType; unused fields are ignored. Requests are issued in order; a reply-bearing request is not overtaken by later requests on the same channel because SSH ties replies to channels, not requests.

An in-flight channel request driven by session pumping.

Exit information of a session channel, when the peer reported it.

An opened SSH channel.

Data conventions follow SshResult: reads return standard or extended data separately, idle reads report NEED_READ or WAIT, end-of-stream is DONE with the eof flag set, and a zero-length buffer is an immediate no-op. Bytes accepted by write must never be resubmitted.

Flow control: the SSH implementation owns protocol window accounting and grants receive credit as the application consumes buffered data. Consumers observe backpressure through canWrite and pendingWriteBytes; they never manage window adjustments themselves.

Ownership: the channel belongs to its session; closing the session closes all channels.