skip to content

When an SFTP session starts over SSH, what do SSH_FXP_INIT and SSH_FXP_VERSION carry, and how does a client learn which extensions an OpenSSH server supports?

level: middleimportance: nice to knowfreq 13%

answer

  1. length, type, then payload
  2. the lower version wins
  3. name and data pairs
  4. ignore what you do not know
  5. SSH_FXP_EXTENDED makes the call

basics

~20 s

The client's SSH_FXP_INIT carries its protocol version; the server's SSH_FXP_VERSION answers with the version to use (3 for OpenSSH) and a list of extension name and data pairs. A client calls only listed extensions, through SSH_FXP_EXTENDED.

solid answer

~40 s

Every SFTP packet is a `uint32` length, a one-byte type and a payload, and requests then carry a `uint32` id that the reply echoes. The first packet is the client's `SSH_FXP_INIT` with its version number; the server answers `SSH_FXP_VERSION` with the version both will use (OpenSSH 10.5's `sftp-server` always answers 3), followed by pairs of strings: an extension name such as `[email protected]` and its data, which OpenSSH uses as the extension's own version (`"1"`, or `"2"` for `[email protected]`). Unknown names must be ignored. The client then calls an extension with `SSH_FXP_EXTENDED`, naming it, and gets `SSH_FXP_STATUS` or `SSH_FXP_EXTENDED_REPLY` back; a server that does not recognise the name answers `SSH_FX_OP_UNSUPPORTED`. OpenSSH's server treats any other request before `SSH_FXP_INIT` as fatal.

code

pseudocode · 8 lines
pseudocode
C -> S  length | SSH_FXP_INIT (1)    | version 3
S -> C  length | SSH_FXP_VERSION (2) | version 3
          | "[email protected]" "1"
          | "[email protected]" "2" | "[email protected]" "2"
          | ... | "[email protected]" "1" | ... | "copy-data" "1" | ...
C -> S  length | SSH_FXP_EXTENDED (200) | id 7 | "[email protected]"
S -> C  length | SSH_FXP_EXTENDED_REPLY (201) | id 7
          | max-packet-length | max-read-length | max-write-length | max-open-handles

go deeper

for a junior

Recall that an SFTP session opens with SSH_FXP_INIT from the client and SSH_FXP_VERSION from the server, and that OpenSSH speaks version 3.

for a middle

Explain the framing of length, type and request id, and how name and data pairs in SSH_FXP_VERSION advertise extensions the client may then call.

for a senior

Use the negotiation in practice: check the advertised list and its version strings before relying on posix-rename or limits, and expect older servers to lack newer ones.

for a principal

Judge interoperability with partners' servers: negotiate features rather than assume them, and decide what your integrations do when an extension is missing.

## The packet format underneath everything SFTP runs over a byte stream, the SSH session channel opened by the `sftp` subsystem request, so it needs its own framing. In version 3 (`draft-ietf-secsh-filexfer-02`) every packet is: ```pseudocode uint32 length # bytes that follow, not counting this field byte type # SSH_FXP_INIT = 1, SSH_FXP_VERSION = 2, SSH_FXP_EXTENDED = 200 byte[length-1] payload # requests start with a uint32 request id ``` - **Requests** begin their payload with a `uint32` **request id** chosen by the client, and the response carries the same id. That is what lets a client keep many requests outstanding and match replies that come back in any order. - **`SSH_FXP_INIT` and `SSH_FXP_VERSION` carry no request id.** They are the handshake, not requests. - The draft says servers **should accept packets of at least 34,000 bytes**, enough for 32,768-byte reads and writes. OpenSSH's server ends the session if a packet declares a length above its own maximum. ## The handshake 1. **Client to server:** `SSH_FXP_INIT`, holding `uint32 version`, the version the client speaks (3 for OpenSSH's `sftp`). The draft also allows extension data here. 2. **Server to client:** `SSH_FXP_VERSION`, holding `uint32 version` and the server's extension list. The draft says the server supplies the lower of its own and the client's version; OpenSSH's `sftp-server` answers 3, the only version it implements. 3. **Both sides use that version from then on.** OpenSSH's server treats any other request that arrives before `SSH_FXP_INIT` as fatal. OpenSSH stopped at version 3 on purpose: its `PROTOCOL` notes say newer drafts will not be supported and that selected later features are implemented as extensions instead. Version 6 (draft `-13`) added its own `versions` and `version-select` mechanism for renegotiation, which OpenSSH does not use. ## Extension negotiation The extension data in `SSH_FXP_VERSION` is a sequence of **name and data string pairs**. Vendor names take the form `name@domain`, and a client **must silently ignore** any name it does not recognise. OpenSSH 10.5's `sftp-server` advertises eleven extensions: | Extension | Data | What it offers | |---|---|---| | `[email protected]` | "1" | rename with POSIX semantics | | `[email protected]`, `[email protected]` | "2" | file-system statistics | | `[email protected]` | "1" | hard links | | `[email protected]` | "1" | flush an open file to disk | | `[email protected]` | "1" | set attributes without following symlinks | | `[email protected]` | "1" | maximum packet, read and write lengths, open handles | | `[email protected]` | "1" | expand `~` and relative paths | | `copy-data` | "1" | server-side copy between two handles | | `home-directory` | "1" | a user's home directory | | `[email protected]` | "1" | names for user and group ids | OpenSSH uses the data string as the extension's **own version number**, written in ASCII, and its notes tell clients to check it before using the extension, because an incompatible change would raise it. `copy-data` and `home-directory` carry no `@domain` because they follow a later IETF extensions draft rather than an OpenSSH-only design. What each request does once called belongs to the material on SFTP requests and handles; the point here is how the client finds out it may call it. ## Reading the list correctly - **Absence means "do not call it".** A client checks the list first; a server without `[email protected]` is not broken, it is simply older or different. - **The version string matters.** OpenSSH's notes allow a server to advertise the same extension more than once with different versions, and a client must check the version it implements is among them. - **Unknown names are harmless.** The rule to ignore unrecognised names is what lets servers add extensions without breaking older clients. ## Calling an extension - The client sends `SSH_FXP_EXTENDED` (type 200): request id, extension name, then the extension's own fields. - The server answers with an ordinary response such as `SSH_FXP_STATUS`, or with `SSH_FXP_EXTENDED_REPLY` (type 201) for extension-specific data; `[email protected]` returns its four limits that way. - A server that does not recognise the name must answer `SSH_FXP_STATUS` with `SSH_FX_OP_UNSUPPORTED`. ## Why the release matters The list grows with OpenSSH releases: `[email protected]` arrived in 8.6, when OpenSSH's `sftp` also began using it to choose transfer lengths; `copy-data` came in 9.0 with the client's `cp` command; `home-directory` and `[email protected]` came in 9.1. A client that reads the list instead of assuming it keeps working against older servers that lack the newer entries.

  • Why does OpenSSH's sftp client care whether the server advertised [email protected]?
    The reply gives the server's maximum packet length, read and write lengths and open handles, so the client can size its reads and writes to what the server accepts instead of guessing; OpenSSH's notes warn that a server may sever the connection when a client exceeds them. Without the extension, the client keeps to its defaults.
  • An SFTP client sends SSH_FXP_EXTENDED for an extension the server never listed; what should happen?
    A server that does not recognise the name must answer `SSH_FXP_STATUS` with `SSH_FX_OP_UNSUPPORTED`, and the session carries on. A well-behaved client should not have sent it at all: the `SSH_FXP_VERSION` list, including each extension's version string, exists so clients check before they call.

  • OpenSSH negotiates SFTP version 6 with modern clients
  • Every SFTP packet, SSH_FXP_INIT included, starts with a request id
  • A client must reject a server that lists an unknown extension
  • SFTP extensions are listed in SSH_MSG_KEXINIT beside the ciphers
  • SFTP packets begin with a magic string that marks the protocol

Assumes OpenSSH 10.5, whose sftp-server answers version 3 with eleven extensions; [email protected] arrived in 8.6, copy-data in 9.0, home-directory and [email protected] in 9.1.