Home | History | Annotate | Line # | Download | only in dist
PROTOCOL revision 1.22
      1   1.1  christos This documents OpenSSH's deviations and extensions to the published SSH
      2   1.1  christos protocol.
      3   1.1  christos 
      4   1.1  christos Note that OpenSSH's sftp and sftp-server implement revision 3 of the SSH
      5   1.1  christos filexfer protocol described in:
      6   1.1  christos 
      7   1.1  christos http://www.openssh.com/txt/draft-ietf-secsh-filexfer-02.txt
      8   1.1  christos 
      9   1.2  christos Newer versions of the draft will not be supported, though some features
     10   1.2  christos are individually implemented as extensions described below.
     11   1.1  christos 
     12   1.1  christos The protocol used by OpenSSH's ssh-agent is described in the file
     13   1.1  christos PROTOCOL.agent
     14   1.1  christos 
     15   1.2  christos 1. Transport protocol changes
     16   1.2  christos 
     17   1.2  christos 1.1. transport: Protocol 2 MAC algorithm "umac-64 (a] openssh.com"
     18   1.1  christos 
     19   1.1  christos This is a new transport-layer MAC method using the UMAC algorithm
     20   1.1  christos (rfc4418). This method is identical to the "umac-64" method documented
     21   1.1  christos in:
     22   1.1  christos 
     23   1.1  christos http://www.openssh.com/txt/draft-miller-secsh-umac-01.txt
     24   1.1  christos 
     25   1.2  christos 1.2. transport: Protocol 2 compression algorithm "zlib (a] openssh.com"
     26   1.1  christos 
     27   1.1  christos This transport-layer compression method uses the zlib compression
     28   1.1  christos algorithm (identical to the "zlib" method in rfc4253), but delays the
     29   1.1  christos start of compression until after authentication has completed. This
     30   1.1  christos avoids exposing compression code to attacks from unauthenticated users.
     31   1.1  christos 
     32   1.1  christos The method is documented in:
     33   1.1  christos 
     34   1.1  christos http://www.openssh.com/txt/draft-miller-secsh-compression-delayed-00.txt
     35   1.1  christos 
     36  1.10  christos 1.3. transport: New public key algorithms "ssh-rsa-cert-v01 (a] openssh.com",
     37  1.10  christos      "ssh-dsa-cert-v01 (a] openssh.com",
     38   1.2  christos      "ecdsa-sha2-nistp256-cert-v01 (a] openssh.com",
     39   1.2  christos      "ecdsa-sha2-nistp384-cert-v01 (a] openssh.com" and
     40   1.2  christos      "ecdsa-sha2-nistp521-cert-v01 (a] openssh.com"
     41   1.2  christos 
     42   1.2  christos OpenSSH introduces new public key algorithms to support certificate
     43   1.5  christos authentication for users and host keys. These methods are documented
     44   1.5  christos in the file PROTOCOL.certkeys
     45   1.2  christos 
     46   1.2  christos 1.4. transport: Elliptic Curve cryptography
     47   1.2  christos 
     48   1.2  christos OpenSSH supports ECC key exchange and public key authentication as
     49   1.2  christos specified in RFC5656. Only the ecdsa-sha2-nistp256, ecdsa-sha2-nistp384
     50   1.2  christos and ecdsa-sha2-nistp521 curves over GF(p) are supported. Elliptic
     51   1.2  christos curve points encoded using point compression are NOT accepted or
     52   1.2  christos generated.
     53   1.2  christos 
     54   1.3  christos 1.5 transport: Protocol 2 Encrypt-then-MAC MAC algorithms
     55   1.3  christos 
     56   1.3  christos OpenSSH supports MAC algorithms, whose names contain "-etm", that
     57   1.3  christos perform the calculations in a different order to that defined in RFC
     58   1.3  christos 4253. These variants use the so-called "encrypt then MAC" ordering,
     59   1.3  christos calculating the MAC over the packet ciphertext rather than the
     60   1.3  christos plaintext. This ordering closes a security flaw in the SSH transport
     61   1.3  christos protocol, where decryption of unauthenticated ciphertext provided a
     62   1.3  christos "decryption oracle" that could, in conjunction with cipher flaws, reveal
     63   1.3  christos session plaintext.
     64   1.3  christos 
     65   1.3  christos Specifically, the "-etm" MAC algorithms modify the transport protocol
     66   1.3  christos to calculate the MAC over the packet ciphertext and to send the packet
     67   1.3  christos length unencrypted. This is necessary for the transport to obtain the
     68   1.3  christos length of the packet and location of the MAC tag so that it may be
     69   1.3  christos verified without decrypting unauthenticated data.
     70   1.3  christos 
     71   1.3  christos As such, the MAC covers:
     72   1.3  christos 
     73   1.3  christos       mac = MAC(key, sequence_number || packet_length || encrypted_packet)
     74   1.3  christos 
     75   1.3  christos where "packet_length" is encoded as a uint32 and "encrypted_packet"
     76   1.3  christos contains:
     77   1.3  christos 
     78   1.3  christos       byte      padding_length
     79   1.3  christos       byte[n1]  payload; n1 = packet_length - padding_length - 1
     80   1.3  christos       byte[n2]  random padding; n2 = padding_length
     81   1.3  christos 
     82   1.3  christos 1.6 transport: AES-GCM
     83   1.3  christos 
     84   1.3  christos OpenSSH supports the AES-GCM algorithm as specified in RFC 5647.
     85   1.3  christos Because of problems with the specification of the key exchange
     86   1.3  christos the behaviour of OpenSSH differs from the RFC as follows:
     87   1.3  christos 
     88   1.3  christos AES-GCM is only negotiated as the cipher algorithms
     89   1.3  christos "aes128-gcm (a] openssh.com" or "aes256-gcm (a] openssh.com" and never as
     90   1.3  christos an MAC algorithm. Additionally, if AES-GCM is selected as the cipher
     91   1.3  christos the exchanged MAC algorithms are ignored and there doesn't have to be
     92   1.3  christos a matching MAC.
     93   1.3  christos 
     94   1.4  christos 1.7 transport: chacha20-poly1305 (a] openssh.com authenticated encryption
     95   1.4  christos 
     96   1.4  christos OpenSSH supports authenticated encryption using ChaCha20 and Poly1305
     97   1.4  christos as described in PROTOCOL.chacha20poly1305.
     98   1.4  christos 
     99   1.4  christos 1.8 transport: curve25519-sha256 (a] libssh.org key exchange algorithm
    100   1.4  christos 
    101   1.4  christos OpenSSH supports the use of ECDH in Curve25519 for key exchange as
    102   1.4  christos described at:
    103   1.4  christos http://git.libssh.org/users/aris/libssh.git/plain/doc/curve25519-sha256@libssh.org.txt?h=curve25519
    104   1.4  christos 
    105  1.20  christos This is identical to curve25519-sha256 as later published in RFC8731.
    106  1.20  christos 
    107  1.22  christos 1.9 transport: ping facility
    108  1.22  christos 
    109  1.22  christos OpenSSH implements a transport level ping message SSH2_MSG_PING
    110  1.22  christos and a corresponding SSH2_MSG_PONG reply.
    111  1.22  christos 
    112  1.22  christos #define SSH2_MSG_PING	192
    113  1.22  christos #define SSH2_MSG_PONG	193
    114  1.22  christos 
    115  1.22  christos The ping message is simply:
    116  1.22  christos 
    117  1.22  christos 	byte		SSH_MSG_PING
    118  1.22  christos 	string		data
    119  1.22  christos 
    120  1.22  christos The reply copies the data (which may be the empty string) from the
    121  1.22  christos ping:
    122  1.22  christos 
    123  1.22  christos 	byte		SSH_MSG_PONG
    124  1.22  christos 	string		data
    125  1.22  christos 
    126  1.22  christos Replies are sent in order. They are sent immediately except when rekeying
    127  1.22  christos is in progress, in which case they are queued until rekeying completes.
    128  1.22  christos 
    129  1.22  christos The server advertises support for these messages using the
    130  1.22  christos SSH2_MSG_EXT_INFO mechanism (RFC8308), with the following message:
    131  1.22  christos 
    132  1.22  christos 	string		"ping (a] openssh.com"
    133  1.22  christos 	string		"0" (version)
    134  1.22  christos 
    135  1.22  christos The ping/reply message is implemented at the transport layer rather
    136  1.22  christos than as a named global or channel request to allow pings with very
    137  1.22  christos short packet lengths, which would not be possible with other
    138  1.22  christos approaches.
    139  1.22  christos 
    140   1.2  christos 2. Connection protocol changes
    141   1.2  christos 
    142   1.2  christos 2.1. connection: Channel write close extension "eow (a] openssh.com"
    143   1.1  christos 
    144   1.1  christos The SSH connection protocol (rfc4254) provides the SSH_MSG_CHANNEL_EOF
    145   1.1  christos message to allow an endpoint to signal its peer that it will send no
    146   1.1  christos more data over a channel. Unfortunately, there is no symmetric way for
    147   1.1  christos an endpoint to request that its peer should cease sending data to it
    148   1.1  christos while still keeping the channel open for the endpoint to send data to
    149   1.1  christos the peer.
    150   1.1  christos 
    151   1.1  christos This is desirable, since it saves the transmission of data that would
    152   1.1  christos otherwise need to be discarded and it allows an endpoint to signal local
    153   1.1  christos processes of the condition, e.g. by closing the corresponding file
    154   1.1  christos descriptor.
    155   1.1  christos 
    156   1.1  christos OpenSSH implements a channel extension message to perform this
    157   1.1  christos signalling: "eow (a] openssh.com" (End Of Write). This message is sent by
    158   1.1  christos an endpoint when the local output of a session channel is closed or
    159   1.1  christos experiences a write error. The message is formatted as follows:
    160   1.1  christos 
    161   1.1  christos 	byte		SSH_MSG_CHANNEL_REQUEST
    162   1.1  christos 	uint32		recipient channel
    163   1.1  christos 	string		"eow (a] openssh.com"
    164   1.1  christos 	boolean		FALSE
    165   1.1  christos 
    166   1.1  christos On receiving this message, the peer SHOULD cease sending data of
    167   1.1  christos the channel and MAY signal the process from which the channel data
    168   1.1  christos originates (e.g. by closing its read file descriptor).
    169   1.1  christos 
    170   1.1  christos As with the symmetric SSH_MSG_CHANNEL_EOF message, the channel does
    171   1.1  christos remain open after a "eow (a] openssh.com" has been sent and more data may
    172   1.1  christos still be sent in the other direction. This message does not consume
    173   1.1  christos window space and may be sent even if no window space is available.
    174   1.1  christos 
    175   1.1  christos NB. due to certain broken SSH implementations aborting upon receipt
    176   1.1  christos of this message (in contravention of RFC4254 section 5.4), this
    177   1.1  christos message is only sent to OpenSSH peers (identified by banner).
    178  1.15  christos Other SSH implementations may be listed to receive this message
    179   1.1  christos upon request.
    180   1.1  christos 
    181   1.2  christos 2.2. connection: disallow additional sessions extension
    182   1.2  christos      "no-more-sessions (a] openssh.com"
    183   1.1  christos 
    184   1.1  christos Most SSH connections will only ever request a single session, but a
    185   1.1  christos attacker may abuse a running ssh client to surreptitiously open
    186   1.1  christos additional sessions under their control. OpenSSH provides a global
    187   1.1  christos request "no-more-sessions (a] openssh.com" to mitigate this attack.
    188   1.1  christos 
    189   1.1  christos When an OpenSSH client expects that it will never open another session
    190   1.1  christos (i.e. it has been started with connection multiplexing disabled), it
    191   1.1  christos will send the following global request:
    192   1.1  christos 
    193   1.1  christos 	byte		SSH_MSG_GLOBAL_REQUEST
    194   1.1  christos 	string		"no-more-sessions (a] openssh.com"
    195   1.1  christos 	char		want-reply
    196   1.1  christos 
    197   1.1  christos On receipt of such a message, an OpenSSH server will refuse to open
    198   1.1  christos future channels of type "session" and instead immediately abort the
    199   1.1  christos connection.
    200   1.1  christos 
    201   1.1  christos Note that this is not a general defence against compromised clients
    202   1.1  christos (that is impossible), but it thwarts a simple attack.
    203   1.1  christos 
    204   1.1  christos NB. due to certain broken SSH implementations aborting upon receipt
    205   1.1  christos of this message, the no-more-sessions request is only sent to OpenSSH
    206   1.1  christos servers (identified by banner). Other SSH implementations may be
    207  1.15  christos listed to receive this message upon request.
    208   1.1  christos 
    209   1.2  christos 2.3. connection: Tunnel forward extension "tun (a] openssh.com"
    210   1.1  christos 
    211   1.1  christos OpenSSH supports layer 2 and layer 3 tunnelling via the "tun (a] openssh.com"
    212   1.1  christos channel type. This channel type supports forwarding of network packets
    213   1.6  christos with datagram boundaries intact between endpoints equipped with
    214   1.1  christos interfaces like the BSD tun(4) device. Tunnel forwarding channels are
    215   1.1  christos requested by the client with the following packet:
    216   1.1  christos 
    217   1.1  christos 	byte		SSH_MSG_CHANNEL_OPEN
    218   1.1  christos 	string		"tun (a] openssh.com"
    219   1.1  christos 	uint32		sender channel
    220   1.1  christos 	uint32		initial window size
    221   1.1  christos 	uint32		maximum packet size
    222   1.1  christos 	uint32		tunnel mode
    223   1.1  christos 	uint32		remote unit number
    224   1.1  christos 
    225   1.1  christos The "tunnel mode" parameter specifies whether the tunnel should forward
    226   1.1  christos layer 2 frames or layer 3 packets. It may take one of the following values:
    227   1.1  christos 
    228   1.1  christos 	SSH_TUNMODE_POINTOPOINT  1		/* layer 3 packets */
    229   1.1  christos 	SSH_TUNMODE_ETHERNET     2		/* layer 2 frames */
    230   1.1  christos 
    231   1.1  christos The "tunnel unit number" specifies the remote interface number, or may
    232  1.14  christos be 0x7fffffff to allow the server to automatically choose an interface. A
    233   1.2  christos server that is not willing to open a client-specified unit should refuse
    234   1.2  christos the request with a SSH_MSG_CHANNEL_OPEN_FAILURE error. On successful
    235   1.2  christos open, the server should reply with SSH_MSG_CHANNEL_OPEN_SUCCESS.
    236   1.1  christos 
    237   1.1  christos Once established the client and server may exchange packet or frames
    238   1.1  christos over the tunnel channel by encapsulating them in SSH protocol strings
    239   1.1  christos and sending them as channel data. This ensures that packet boundaries
    240   1.1  christos are kept intact. Specifically, packets are transmitted using normal
    241   1.1  christos SSH_MSG_CHANNEL_DATA packets:
    242   1.1  christos 
    243   1.1  christos 	byte		SSH_MSG_CHANNEL_DATA
    244   1.1  christos 	uint32		recipient channel
    245   1.1  christos 	string		data
    246   1.1  christos 
    247   1.1  christos The contents of the "data" field for layer 3 packets is:
    248   1.1  christos 
    249   1.1  christos 	uint32			packet length
    250   1.1  christos 	uint32			address family
    251   1.1  christos 	byte[packet length - 4]	packet data
    252   1.1  christos 
    253   1.1  christos The "address family" field identifies the type of packet in the message.
    254   1.1  christos It may be one of:
    255   1.1  christos 
    256   1.1  christos 	SSH_TUN_AF_INET		2		/* IPv4 */
    257   1.1  christos 	SSH_TUN_AF_INET6	24		/* IPv6 */
    258   1.1  christos 
    259   1.1  christos The "packet data" field consists of the IPv4/IPv6 datagram itself
    260   1.1  christos without any link layer header.
    261   1.1  christos 
    262   1.2  christos The contents of the "data" field for layer 2 packets is:
    263   1.1  christos 
    264   1.1  christos 	uint32			packet length
    265   1.1  christos 	byte[packet length]	frame
    266   1.1  christos 
    267   1.1  christos The "frame" field contains an IEEE 802.3 Ethernet frame, including
    268   1.1  christos header.
    269   1.1  christos 
    270   1.4  christos 2.4. connection: Unix domain socket forwarding
    271   1.4  christos 
    272   1.4  christos OpenSSH supports local and remote Unix domain socket forwarding
    273   1.4  christos using the "streamlocal" extension.  Forwarding is initiated as per
    274   1.4  christos TCP sockets but with a single path instead of a host and port.
    275   1.4  christos 
    276   1.4  christos Similar to direct-tcpip, direct-streamlocal is sent by the client
    277   1.4  christos to request that the server make a connection to a Unix domain socket.
    278   1.4  christos 
    279   1.4  christos 	byte		SSH_MSG_CHANNEL_OPEN
    280   1.4  christos 	string		"direct-streamlocal (a] openssh.com"
    281   1.4  christos 	uint32		sender channel
    282   1.4  christos 	uint32		initial window size
    283   1.4  christos 	uint32		maximum packet size
    284   1.4  christos 	string		socket path
    285   1.8  christos 	string		reserved
    286   1.8  christos 	uint32		reserved
    287   1.4  christos 
    288   1.4  christos Similar to forwarded-tcpip, forwarded-streamlocal is sent by the
    289   1.4  christos server when the client has previously send the server a streamlocal-forward
    290   1.4  christos GLOBAL_REQUEST.
    291   1.4  christos 
    292   1.4  christos 	byte		SSH_MSG_CHANNEL_OPEN
    293   1.4  christos 	string		"forwarded-streamlocal (a] openssh.com"
    294   1.4  christos 	uint32		sender channel
    295   1.4  christos 	uint32		initial window size
    296   1.4  christos 	uint32		maximum packet size
    297   1.4  christos 	string		socket path
    298   1.4  christos 	string		reserved for future use
    299   1.4  christos 
    300   1.4  christos The reserved field is not currently defined and is ignored on the
    301   1.4  christos remote end.  It is intended to be used in the future to pass
    302   1.4  christos information about the socket file, such as ownership and mode.
    303   1.4  christos The client currently sends the empty string for this field.
    304   1.4  christos 
    305   1.4  christos Similar to tcpip-forward, streamlocal-forward is sent by the client
    306   1.4  christos to request remote forwarding of a Unix domain socket.
    307   1.4  christos 
    308   1.4  christos 	byte		SSH2_MSG_GLOBAL_REQUEST
    309   1.4  christos 	string		"streamlocal-forward (a] openssh.com"
    310   1.4  christos 	boolean		TRUE
    311   1.4  christos 	string		socket path
    312   1.4  christos 
    313   1.4  christos Similar to cancel-tcpip-forward, cancel-streamlocal-forward is sent
    314   1.4  christos by the client cancel the forwarding of a Unix domain socket.
    315   1.4  christos 
    316   1.4  christos 	byte		SSH2_MSG_GLOBAL_REQUEST
    317   1.4  christos 	string		"cancel-streamlocal-forward (a] openssh.com"
    318   1.4  christos 	boolean		FALSE
    319   1.4  christos 	string		socket path
    320   1.4  christos 
    321   1.5  christos 2.5. connection: hostkey update and rotation "hostkeys-00 (a] openssh.com"
    322   1.5  christos and "hostkeys-prove-00 (a] openssh.com"
    323   1.5  christos 
    324   1.5  christos OpenSSH supports a protocol extension allowing a server to inform
    325   1.5  christos a client of all its protocol v.2 host keys after user-authentication
    326   1.5  christos has completed.
    327   1.5  christos 
    328   1.5  christos 	byte		SSH_MSG_GLOBAL_REQUEST
    329   1.5  christos 	string		"hostkeys-00 (a] openssh.com"
    330  1.16  christos 	char		0 /* want-reply */
    331   1.5  christos 	string[]	hostkeys
    332   1.5  christos 
    333   1.5  christos Upon receiving this message, a client should check which of the
    334  1.11  christos supplied host keys are present in known_hosts.
    335  1.11  christos 
    336  1.11  christos Note that the server may send key types that the client does not
    337  1.14  christos support. The client should disregard such keys if they are received.
    338  1.11  christos 
    339  1.11  christos If the client identifies any keys that are not present for the host,
    340  1.11  christos it should send a "hostkeys-prove (a] openssh.com" message to request the
    341  1.11  christos server prove ownership of the private half of the key.
    342   1.5  christos 
    343   1.5  christos 	byte		SSH_MSG_GLOBAL_REQUEST
    344   1.5  christos 	string		"hostkeys-prove-00 (a] openssh.com"
    345   1.5  christos 	char		1 /* want-reply */
    346   1.5  christos 	string[]	hostkeys
    347   1.5  christos 
    348   1.5  christos When a server receives this message, it should generate a signature
    349   1.5  christos using each requested key over the following:
    350   1.5  christos 
    351   1.5  christos 	string		"hostkeys-prove-00 (a] openssh.com"
    352   1.5  christos 	string		session identifier
    353   1.5  christos 	string		hostkey
    354   1.5  christos 
    355   1.5  christos These signatures should be included in the reply, in the order matching
    356   1.5  christos the hostkeys in the request:
    357   1.5  christos 
    358   1.5  christos 	byte		SSH_MSG_REQUEST_SUCCESS
    359   1.5  christos 	string[]	signatures
    360   1.5  christos 
    361   1.5  christos When the client receives this reply (and not a failure), it should
    362   1.5  christos validate the signatures and may update its known_hosts file, adding keys
    363   1.5  christos that it has not seen before and deleting keys for the server host that
    364   1.5  christos are no longer offered.
    365   1.5  christos 
    366   1.5  christos These extensions let a client learn key types that it had not previously
    367   1.5  christos encountered, thereby allowing it to potentially upgrade from weaker
    368   1.5  christos key algorithms to better ones. It also supports graceful key rotation:
    369   1.5  christos a server may offer multiple keys of the same type for a period (to
    370   1.5  christos give clients an opportunity to learn them using this extension) before
    371   1.5  christos removing the deprecated key from those offered.
    372   1.5  christos 
    373  1.13  christos 2.6. connection: SIGINFO support for "signal" channel request
    374  1.13  christos 
    375  1.13  christos The SSH channels protocol (RFC4254 section 6.9) supports sending a
    376  1.13  christos signal to a session attached to a channel. OpenSSH supports one
    377  1.13  christos extension signal "INFO (a] openssh.com" that allows sending SIGINFO on
    378  1.13  christos BSD-derived systems.
    379  1.13  christos 
    380  1.18  christos 3. Authentication protocol changes
    381   1.2  christos 
    382  1.18  christos 3.1. Host-bound public key authentication
    383  1.18  christos 
    384  1.18  christos This is trivial change to the traditional "publickey" authentication
    385  1.18  christos method. The authentication request is identical to the original method
    386  1.18  christos but for the name and one additional field:
    387  1.18  christos 
    388  1.18  christos 	byte		SSH2_MSG_USERAUTH_REQUEST
    389  1.18  christos 	string		username
    390  1.18  christos 	string		"ssh-connection"
    391  1.18  christos 	string		"publickey-hostbound-v00 (a] openssh.com"
    392  1.18  christos 	bool		has_signature
    393  1.18  christos 	string		pkalg
    394  1.18  christos 	string		public key
    395  1.18  christos 	string		server host key
    396  1.18  christos 
    397  1.18  christos Because the entire SSH2_MSG_USERAUTH_REQUEST message is included in
    398  1.18  christos the signed data, this ensures that a binding between the destination
    399  1.18  christos user, the server identity and the session identifier is visible to the
    400  1.18  christos signer. OpenSSH uses this binding via signed data to implement per-key
    401  1.18  christos restrictions in ssh-agent.
    402  1.18  christos 
    403  1.18  christos A server may advertise this method using the SSH2_MSG_EXT_INFO
    404  1.18  christos mechanism (RFC8308), with the following message:
    405  1.18  christos 
    406  1.18  christos 	string		"publickey-hostbound (a] openssh.com"
    407  1.18  christos 	string		"0" (version)
    408  1.18  christos 
    409  1.18  christos Clients should prefer host-bound authentication when advertised by
    410  1.18  christos server.
    411  1.18  christos 
    412  1.18  christos 4. SFTP protocol changes
    413  1.18  christos 
    414  1.18  christos 4.1. sftp: Reversal of arguments to SSH_FXP_SYMLINK
    415   1.1  christos 
    416   1.1  christos When OpenSSH's sftp-server was implemented, the order of the arguments
    417   1.1  christos to the SSH_FXP_SYMLINK method was inadvertently reversed. Unfortunately,
    418   1.1  christos the reversal was not noticed until the server was widely deployed. Since
    419   1.1  christos fixing this to follow the specification would cause incompatibility, the
    420   1.1  christos current order was retained. For correct operation, clients should send
    421   1.1  christos SSH_FXP_SYMLINK as follows:
    422   1.1  christos 
    423   1.1  christos 	uint32		id
    424   1.1  christos 	string		targetpath
    425   1.1  christos 	string		linkpath
    426   1.1  christos 
    427  1.18  christos 4.2. sftp: Server extension announcement in SSH_FXP_VERSION
    428   1.1  christos 
    429   1.1  christos OpenSSH's sftp-server lists the extensions it supports using the
    430   1.1  christos standard extension announcement mechanism in the SSH_FXP_VERSION server
    431   1.1  christos hello packet:
    432   1.1  christos 
    433   1.1  christos 	uint32		3		/* protocol version */
    434   1.1  christos 	string		ext1-name
    435   1.1  christos 	string		ext1-version
    436   1.1  christos 	string		ext2-name
    437   1.1  christos 	string		ext2-version
    438   1.1  christos 	...
    439   1.1  christos 	string		extN-name
    440   1.1  christos 	string		extN-version
    441   1.1  christos 
    442   1.1  christos Each extension reports its integer version number as an ASCII encoded
    443   1.1  christos string, e.g. "1". The version will be incremented if the extension is
    444   1.1  christos ever changed in an incompatible way. The server MAY advertise the same
    445   1.1  christos extension with multiple versions (though this is unlikely). Clients MUST
    446   1.1  christos check the version number before attempting to use the extension.
    447   1.1  christos 
    448  1.18  christos 4.3. sftp: Extension request "posix-rename (a] openssh.com"
    449   1.1  christos 
    450   1.1  christos This operation provides a rename operation with POSIX semantics, which
    451   1.1  christos are different to those provided by the standard SSH_FXP_RENAME in
    452   1.1  christos draft-ietf-secsh-filexfer-02.txt. This request is implemented as a
    453   1.1  christos SSH_FXP_EXTENDED request with the following format:
    454   1.1  christos 
    455   1.1  christos 	uint32		id
    456   1.1  christos 	string		"posix-rename (a] openssh.com"
    457   1.1  christos 	string		oldpath
    458   1.1  christos 	string		newpath
    459   1.1  christos 
    460   1.1  christos On receiving this request the server will perform the POSIX operation
    461   1.1  christos rename(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
    462   1.1  christos This extension is advertised in the SSH_FXP_VERSION hello with version
    463   1.1  christos "1".
    464   1.1  christos 
    465  1.18  christos 4.4. sftp: Extension requests "statvfs (a] openssh.com" and
    466   1.1  christos          "fstatvfs (a] openssh.com"
    467   1.1  christos 
    468   1.1  christos These requests correspond to the statvfs and fstatvfs POSIX system
    469   1.1  christos interfaces. The "statvfs (a] openssh.com" request operates on an explicit
    470   1.1  christos pathname, and is formatted as follows:
    471   1.1  christos 
    472   1.1  christos 	uint32		id
    473   1.1  christos 	string		"statvfs (a] openssh.com"
    474   1.1  christos 	string		path
    475   1.1  christos 
    476   1.1  christos The "fstatvfs (a] openssh.com" operates on an open file handle:
    477   1.1  christos 
    478   1.1  christos 	uint32		id
    479   1.1  christos 	string		"fstatvfs (a] openssh.com"
    480   1.1  christos 	string		handle
    481   1.1  christos 
    482   1.1  christos These requests return a SSH_FXP_STATUS reply on failure. On success they
    483   1.1  christos return the following SSH_FXP_EXTENDED_REPLY reply:
    484   1.1  christos 
    485   1.1  christos 	uint32		id
    486   1.1  christos 	uint64		f_bsize		/* file system block size */
    487   1.1  christos 	uint64		f_frsize	/* fundamental fs block size */
    488   1.1  christos 	uint64		f_blocks	/* number of blocks (unit f_frsize) */
    489   1.1  christos 	uint64		f_bfree		/* free blocks in file system */
    490   1.1  christos 	uint64		f_bavail	/* free blocks for non-root */
    491   1.1  christos 	uint64		f_files		/* total file inodes */
    492   1.1  christos 	uint64		f_ffree		/* free file inodes */
    493   1.1  christos 	uint64		f_favail	/* free file inodes for to non-root */
    494   1.1  christos 	uint64		f_fsid		/* file system id */
    495   1.1  christos 	uint64		f_flag		/* bit mask of f_flag values */
    496   1.1  christos 	uint64		f_namemax	/* maximum filename length */
    497   1.1  christos 
    498   1.1  christos The values of the f_flag bitmask are as follows:
    499   1.1  christos 
    500   1.1  christos 	#define SSH_FXE_STATVFS_ST_RDONLY	0x1	/* read-only */
    501   1.1  christos 	#define SSH_FXE_STATVFS_ST_NOSUID	0x2	/* no setuid */
    502   1.1  christos 
    503   1.1  christos Both the "statvfs (a] openssh.com" and "fstatvfs (a] openssh.com" extensions are
    504   1.1  christos advertised in the SSH_FXP_VERSION hello with version "2".
    505   1.1  christos 
    506  1.18  christos 4.5. sftp: Extension request "hardlink (a] openssh.com"
    507   1.2  christos 
    508   1.2  christos This request is for creating a hard link to a regular file. This
    509   1.2  christos request is implemented as a SSH_FXP_EXTENDED request with the
    510   1.2  christos following format:
    511   1.2  christos 
    512   1.2  christos 	uint32		id
    513   1.2  christos 	string		"hardlink (a] openssh.com"
    514   1.2  christos 	string		oldpath
    515   1.2  christos 	string		newpath
    516   1.2  christos 
    517   1.2  christos On receiving this request the server will perform the operation
    518   1.2  christos link(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
    519   1.2  christos This extension is advertised in the SSH_FXP_VERSION hello with version
    520   1.2  christos "1".
    521   1.2  christos 
    522  1.18  christos 4.6. sftp: Extension request "fsync (a] openssh.com"
    523   1.4  christos 
    524   1.4  christos This request asks the server to call fsync(2) on an open file handle.
    525   1.4  christos 
    526   1.4  christos 	uint32		id
    527   1.4  christos 	string		"fsync (a] openssh.com"
    528   1.4  christos 	string		handle
    529   1.4  christos 
    530  1.19  christos On receiving this request, a server will call fsync(handle_fd) and will
    531   1.4  christos respond with a SSH_FXP_STATUS message.
    532   1.4  christos 
    533   1.4  christos This extension is advertised in the SSH_FXP_VERSION hello with version
    534   1.4  christos "1".
    535   1.4  christos 
    536  1.18  christos 4.7. sftp: Extension request "lsetstat (a] openssh.com"
    537  1.16  christos 
    538  1.16  christos This request is like the "setstat" command, but sets file attributes on
    539  1.16  christos symlinks.  It is implemented as a SSH_FXP_EXTENDED request with the
    540  1.16  christos following format:
    541  1.16  christos 
    542  1.16  christos 	uint32		id
    543  1.16  christos 	string		"lsetstat (a] openssh.com"
    544  1.16  christos 	string		path
    545  1.16  christos 	ATTRS		attrs
    546  1.16  christos 
    547  1.16  christos See the "setstat" command for more details.
    548  1.16  christos 
    549  1.16  christos This extension is advertised in the SSH_FXP_VERSION hello with version
    550  1.16  christos "1".
    551  1.16  christos 
    552  1.18  christos 4.8. sftp: Extension request "limits (a] openssh.com"
    553  1.16  christos 
    554  1.16  christos This request is used to determine various limits the server might impose.
    555  1.16  christos Clients should not attempt to exceed these limits as the server might sever
    556  1.16  christos the connection immediately.
    557  1.16  christos 
    558  1.16  christos 	uint32		id
    559  1.16  christos 	string		"limits (a] openssh.com"
    560  1.16  christos 
    561  1.16  christos The server will respond with a SSH_FXP_EXTENDED_REPLY reply:
    562  1.16  christos 
    563  1.16  christos 	uint32		id
    564  1.16  christos 	uint64		max-packet-length
    565  1.16  christos 	uint64		max-read-length
    566  1.16  christos 	uint64		max-write-length
    567  1.16  christos 	uint64		max-open-handles
    568  1.16  christos 
    569  1.16  christos The 'max-packet-length' applies to the total number of bytes in a
    570  1.16  christos single SFTP packet.  Servers SHOULD set this at least to 34000.
    571  1.16  christos 
    572  1.16  christos The 'max-read-length' is the largest length in a SSH_FXP_READ packet.
    573  1.16  christos Even if the client requests a larger size, servers will usually respond
    574  1.16  christos with a shorter SSH_FXP_DATA packet.  Servers SHOULD set this at least to
    575  1.16  christos 32768.
    576  1.16  christos 
    577  1.16  christos The 'max-write-length' is the largest length in a SSH_FXP_WRITE packet
    578  1.16  christos the server will accept.  Servers SHOULD set this at least to 32768.
    579  1.16  christos 
    580  1.16  christos The 'max-open-handles' is the maximum number of active handles that the
    581  1.16  christos server allows (e.g. handles created by SSH_FXP_OPEN and SSH_FXP_OPENDIR
    582  1.16  christos packets).  Servers MAY count internal file handles against this limit
    583  1.16  christos (e.g. system logging or stdout/stderr), so clients SHOULD NOT expect to
    584  1.16  christos open this many handles in practice.
    585  1.16  christos 
    586  1.16  christos If the server doesn't enforce a specific limit, then the field may be
    587  1.16  christos set to 0.  This implies the server relies on the OS to enforce limits
    588  1.16  christos (e.g. available memory or file handles), and such limits might be
    589  1.16  christos dynamic.  The client SHOULD take care to not try to exceed reasonable
    590  1.16  christos limits.
    591  1.16  christos 
    592  1.16  christos This extension is advertised in the SSH_FXP_VERSION hello with version
    593  1.16  christos "1".
    594  1.16  christos 
    595  1.18  christos 4.9. sftp: Extension request "expand-path (a] openssh.com"
    596  1.17  christos 
    597  1.17  christos This request supports canonicalisation of relative paths and
    598  1.17  christos those that need tilde-expansion, i.e. "~", "~/..." and "~user/..."
    599  1.17  christos These paths are expanded using shell-like rules and the resultant
    600  1.17  christos path is canonicalised similarly to SSH2_FXP_REALPATH.
    601  1.17  christos 
    602  1.17  christos It is implemented as a SSH_FXP_EXTENDED request with the following
    603  1.17  christos format:
    604  1.17  christos 
    605  1.17  christos 	uint32		id
    606  1.17  christos 	string		"expand-path (a] openssh.com"
    607  1.17  christos 	string		path
    608  1.17  christos 
    609  1.17  christos Its reply is the same format as that of SSH2_FXP_REALPATH.
    610  1.17  christos 
    611  1.17  christos This extension is advertised in the SSH_FXP_VERSION hello with version
    612  1.17  christos "1".
    613  1.17  christos 
    614  1.19  christos 4.10. sftp: Extension request "copy-data"
    615  1.19  christos 
    616  1.19  christos This request asks the server to copy data from one open file handle and
    617  1.19  christos write it to a different open file handle.  This avoids needing to transfer
    618  1.19  christos the data across the network twice (a download followed by an upload).
    619  1.19  christos 
    620  1.19  christos 	byte		SSH_FXP_EXTENDED
    621  1.19  christos 	uint32		id
    622  1.19  christos 	string		"copy-data"
    623  1.19  christos 	string		read-from-handle
    624  1.19  christos 	uint64		read-from-offset
    625  1.19  christos 	uint64		read-data-length
    626  1.19  christos 	string		write-to-handle
    627  1.19  christos 	uint64		write-to-offset
    628  1.19  christos 
    629  1.19  christos The server will copy read-data-length bytes starting from
    630  1.19  christos read-from-offset from the read-from-handle and write them to
    631  1.19  christos write-to-handle starting from write-to-offset, and then respond with a
    632  1.19  christos SSH_FXP_STATUS message.
    633  1.19  christos 
    634  1.19  christos It's equivalent to issuing a series of SSH_FXP_READ requests on
    635  1.19  christos read-from-handle and a series of requests of SSH_FXP_WRITE on
    636  1.19  christos write-to-handle.
    637  1.19  christos 
    638  1.19  christos If read-from-handle and write-to-handle are the same, the server will
    639  1.19  christos fail the request and respond with a SSH_FX_INVALID_PARAMETER message.
    640  1.19  christos 
    641  1.19  christos If read-data-length is 0, then the server will read data from the
    642  1.19  christos read-from-handle until EOF is reached.
    643  1.19  christos 
    644  1.19  christos This extension is advertised in the SSH_FXP_VERSION hello with version
    645  1.19  christos "1".
    646  1.19  christos 
    647  1.19  christos This request is identical to the "copy-data" request documented in:
    648  1.19  christos 
    649  1.19  christos https://tools.ietf.org/html/draft-ietf-secsh-filexfer-extensions-00#section-7
    650  1.19  christos 
    651  1.20  christos 4.11. sftp: Extension request "home-directory"
    652  1.20  christos 
    653  1.20  christos This request asks the server to expand the specified user's home directory.
    654  1.20  christos An empty username implies the current user.  This can be used by the client
    655  1.20  christos to expand ~/ type paths locally.
    656  1.20  christos 
    657  1.20  christos 	byte		SSH_FXP_EXTENDED
    658  1.20  christos 	uint32		id
    659  1.20  christos 	string		"home-directory"
    660  1.20  christos 	string		username
    661  1.20  christos 
    662  1.20  christos This extension is advertised in the SSH_FXP_VERSION hello with version
    663  1.20  christos "1".
    664  1.20  christos 
    665  1.20  christos This provides similar information as the "expand-path (a] openssh.com" extension.
    666  1.20  christos 
    667  1.20  christos This request is identical to the "home-directory" request documented in:
    668  1.20  christos 
    669  1.20  christos https://datatracker.ietf.org/doc/html/draft-ietf-secsh-filexfer-extensions-00#section-5
    670  1.20  christos 
    671  1.20  christos 4.12. sftp: Extension request "users-groups-by-id (a] openssh.com"
    672  1.20  christos 
    673  1.21  christos This request asks the server to return user and/or group names that
    674  1.20  christos correspond to one or more IDs (e.g. as returned from a SSH_FXP_STAT
    675  1.20  christos request). This may be used by the client to provide usernames in
    676  1.20  christos directory listings.
    677  1.20  christos 
    678  1.20  christos 	byte		SSH_FXP_EXTENDED
    679  1.20  christos 	uint32		id
    680  1.20  christos 	string		"users-groups-by-id (a] openssh.com"
    681  1.20  christos 	string		uids
    682  1.20  christos 	string		gids
    683  1.20  christos 
    684  1.20  christos Where "uids" and "gids" consists of one or more integer user or group
    685  1.20  christos identifiers:
    686  1.20  christos 
    687  1.20  christos 	uint32		id-0
    688  1.20  christos 	...
    689  1.20  christos 
    690  1.20  christos The server will reply with a SSH_FXP_EXTENDED_REPLY:
    691  1.20  christos 
    692  1.20  christos 	byte		SSH_FXP_EXTENDED_REPLY
    693  1.20  christos 	string		usernames
    694  1.20  christos 	string		groupnames
    695  1.20  christos 
    696  1.20  christos Where "username" and "groupnames" consists of names in identical request
    697  1.20  christos order to "uids" and "gids" respectively:
    698  1.20  christos 
    699  1.20  christos 	string		name-0
    700  1.20  christos 	...
    701  1.20  christos 
    702  1.20  christos If a name cannot be identified for a given user or group ID, an empty
    703  1.20  christos string will be returned in its place.
    704  1.20  christos 
    705  1.20  christos It is acceptable for either "uids" or "gids" to be an empty set, in
    706  1.20  christos which case the respective "usernames" or "groupnames" list will also
    707  1.20  christos be empty.
    708  1.20  christos 
    709  1.20  christos This extension is advertised in the SSH_FXP_VERSION hello with version
    710  1.20  christos "1".
    711  1.20  christos 
    712  1.18  christos 5. Miscellaneous changes
    713  1.12  christos 
    714  1.18  christos 5.1 Public key format
    715  1.12  christos 
    716  1.12  christos OpenSSH public keys, as generated by ssh-keygen(1) and appearing in
    717  1.12  christos authorized_keys files, are formatted as a single line of text consisting
    718  1.12  christos of the public key algorithm name followed by a base64-encoded key blob.
    719  1.12  christos The public key blob (before base64 encoding) is the same format used for
    720  1.12  christos the encoding of public keys sent on the wire: as described in RFC4253
    721  1.12  christos section 6.6 for RSA and DSA keys, RFC5656 section 3.1 for ECDSA keys
    722  1.12  christos and the "New public key formats" section of PROTOCOL.certkeys for the
    723  1.12  christos OpenSSH certificate formats.
    724  1.12  christos 
    725  1.18  christos 5.2 Private key format
    726  1.12  christos 
    727  1.12  christos OpenSSH private keys, as generated by ssh-keygen(1) use the format
    728  1.12  christos described in PROTOCOL.key by default. As a legacy option, PEM format
    729  1.12  christos (RFC7468) private keys are also supported for RSA, DSA and ECDSA keys
    730  1.12  christos and were the default format before OpenSSH 7.8.
    731  1.12  christos 
    732  1.18  christos 5.3 KRL format
    733  1.12  christos 
    734  1.12  christos OpenSSH supports a compact format for Key Revocation Lists (KRLs). This
    735  1.12  christos format is described in the PROTOCOL.krl file.
    736  1.12  christos 
    737  1.18  christos 5.4 Connection multiplexing
    738  1.12  christos 
    739  1.12  christos OpenSSH's connection multiplexing uses messages as described in
    740  1.12  christos PROTOCOL.mux over a Unix domain socket for communications between a
    741  1.12  christos master instance and later clients.
    742  1.12  christos 
    743  1.18  christos 5.5. Agent protocol extensions
    744  1.18  christos 
    745  1.18  christos OpenSSH extends the usual agent protocol. These changes are documented
    746  1.18  christos in the PROTOCOL.agent file.
    747  1.18  christos 
    748  1.21  christos $OpenBSD: PROTOCOL,v 1.48 2022/11/07 01:53:01 dtucker Exp $
    749  1.22  christos $OpenBSD: PROTOCOL,v 1.49 2023/08/28 03:28:43 djm Exp $
    750   1.3  christos $NetBSD: PROTOCOL,v 1.22 2023/10/25 20:19:57 christos Exp $
    751