PROTOCOL

   1 This documents OpenSSH's deviations and extensions to the published SSH
   2 protocol.
   3
   4 Note that OpenSSH's sftp and sftp-server implement revision 3 of the SSH
   5 filexfer protocol described in:
   6
   7 http://www.openssh.com/txt/draft-ietf-secsh-filexfer-02.txt
   8
   9 Newer versions of the draft will not be supported, though some features
  10 are individually implemented as extensions described below.
  11
  12 The protocol used by OpenSSH's ssh-agent is described in the file
  13 PROTOCOL.agent
  14
  15 1. Transport protocol changes
  16
  17 1.1. transport: Protocol 2 MAC algorithm "umac-64@openssh.com"
  18
  19 This is a new transport-layer MAC method using the UMAC algorithm
  20 (rfc4418). This method is identical to the "umac-64" method documented
  21 in:
  22
  23 http://www.openssh.com/txt/draft-miller-secsh-umac-01.txt
  24
  25 1.2. transport: Protocol 2 compression algorithm "zlib@openssh.com"
  26
  27 This transport-layer compression method uses the zlib compression
  28 algorithm (identical to the "zlib" method in rfc4253), but delays the
  29 start of compression until after authentication has completed. This
  30 avoids exposing compression code to attacks from unauthenticated users.
  31
  32 The method is documented in:
  33
  34 http://www.openssh.com/txt/draft-miller-secsh-compression-delayed-00.txt
  35
  36 1.3. transport: New public key algorithms "ssh-rsa-cert-v00@openssh.com",
  37      "ssh-dsa-cert-v00@openssh.com",
  38      "ecdsa-sha2-nistp256-cert-v01@openssh.com",
  39      "ecdsa-sha2-nistp384-cert-v01@openssh.com" and
  40      "ecdsa-sha2-nistp521-cert-v01@openssh.com"
  41
  42 OpenSSH introduces new public key algorithms to support certificate
  43 authentication for users and hostkeys. These methods are documented in
  44 the file PROTOCOL.certkeys
  45
  46 1.4. transport: Elliptic Curve cryptography
  47
  48 OpenSSH supports ECC key exchange and public key authentication as
  49 specified in RFC5656. Only the ecdsa-sha2-nistp256, ecdsa-sha2-nistp384
  50 and ecdsa-sha2-nistp521 curves over GF(p) are supported. Elliptic
  51 curve points encoded using point compression are NOT accepted or
  52 generated.
  53
  54 1.5 transport: Protocol 2 Encrypt-then-MAC MAC algorithms
  55
  56 OpenSSH supports MAC algorithms, whose names contain "-etm", that
  57 perform the calculations in a different order to that defined in RFC
  58 4253. These variants use the so-called "encrypt then MAC" ordering,
  59 calculating the MAC over the packet ciphertext rather than the
  60 plaintext. This ordering closes a security flaw in the SSH transport
  61 protocol, where decryption of unauthenticated ciphertext provided a
  62 "decryption oracle" that could, in conjunction with cipher flaws, reveal
  63 session plaintext.
  64
  65 Specifically, the "-etm" MAC algorithms modify the transport protocol
  66 to calculate the MAC over the packet ciphertext and to send the packet
  67 length unencrypted. This is necessary for the transport to obtain the
  68 length of the packet and location of the MAC tag so that it may be
  69 verified without decrypting unauthenticated data.
  70
  71 As such, the MAC covers:
  72
  73       mac = MAC(key, sequence_number || packet_length || encrypted_packet)
  74
  75 where "packet_length" is encoded as a uint32 and "encrypted_packet"
  76 contains:
  77
  78       byte      padding_length
  79       byte[n1]  payload; n1 = packet_length - padding_length - 1
  80       byte[n2]  random padding; n2 = padding_length
  81
  82 1.6 transport: AES-GCM
  83
  84 OpenSSH supports the AES-GCM algorithm as specified in RFC 5647.
  85 Because of problems with the specification of the key exchange
  86 the behaviour of OpenSSH differs from the RFC as follows:
  87
  88 AES-GCM is only negotiated as the cipher algorithms
  89 "aes128-gcm@openssh.com" or "aes256-gcm@openssh.com" and never as
  90 an MAC algorithm. Additionally, if AES-GCM is selected as the cipher
  91 the exchanged MAC algorithms are ignored and there doesn't have to be
  92 a matching MAC.
  93
  94 1.7 transport: chacha20-poly1305@openssh.com authenticated encryption
  95
  96 OpenSSH supports authenticated encryption using ChaCha20 and Poly1305
  97 as described in PROTOCOL.chacha20poly1305.
  98
  99 1.8 transport: curve25519-sha256@libssh.org key exchange algorithm
 100
 101 OpenSSH supports the use of ECDH in Curve25519 for key exchange as
 102 described at:
 103 http://git.libssh.org/users/aris/libssh.git/plain/doc/curve25519-sha256@libssh.org.txt?h=curve25519
 104
 105 2. Connection protocol changes
 106
 107 2.1. connection: Channel write close extension "eow@openssh.com"
 108
 109 The SSH connection protocol (rfc4254) provides the SSH_MSG_CHANNEL_EOF
 110 message to allow an endpoint to signal its peer that it will send no
 111 more data over a channel. Unfortunately, there is no symmetric way for
 112 an endpoint to request that its peer should cease sending data to it
 113 while still keeping the channel open for the endpoint to send data to
 114 the peer.
 115
 116 This is desirable, since it saves the transmission of data that would
 117 otherwise need to be discarded and it allows an endpoint to signal local
 118 processes of the condition, e.g. by closing the corresponding file
 119 descriptor.
 120
 121 OpenSSH implements a channel extension message to perform this
 122 signalling: "eow@openssh.com" (End Of Write). This message is sent by
 123 an endpoint when the local output of a session channel is closed or
 124 experiences a write error. The message is formatted as follows:
 125
 126         byte            SSH_MSG_CHANNEL_REQUEST
 127         uint32          recipient channel
 128         string          "eow@openssh.com"
 129         boolean         FALSE
 130
 131 On receiving this message, the peer SHOULD cease sending data of
 132 the channel and MAY signal the process from which the channel data
 133 originates (e.g. by closing its read file descriptor).
 134
 135 As with the symmetric SSH_MSG_CHANNEL_EOF message, the channel does
 136 remain open after a "eow@openssh.com" has been sent and more data may
 137 still be sent in the other direction. This message does not consume
 138 window space and may be sent even if no window space is available.
 139
 140 NB. due to certain broken SSH implementations aborting upon receipt
 141 of this message (in contravention of RFC4254 section 5.4), this
 142 message is only sent to OpenSSH peers (identified by banner).
 143 Other SSH implementations may be whitelisted to receive this message
 144 upon request.
 145
 146 2.2. connection: disallow additional sessions extension
 147      "no-more-sessions@openssh.com"
 148
 149 Most SSH connections will only ever request a single session, but a
 150 attacker may abuse a running ssh client to surreptitiously open
 151 additional sessions under their control. OpenSSH provides a global
 152 request "no-more-sessions@openssh.com" to mitigate this attack.
 153
 154 When an OpenSSH client expects that it will never open another session
 155 (i.e. it has been started with connection multiplexing disabled), it
 156 will send the following global request:
 157
 158         byte            SSH_MSG_GLOBAL_REQUEST
 159         string          "no-more-sessions@openssh.com"
 160         char            want-reply
 161
 162 On receipt of such a message, an OpenSSH server will refuse to open
 163 future channels of type "session" and instead immediately abort the
 164 connection.
 165
 166 Note that this is not a general defence against compromised clients
 167 (that is impossible), but it thwarts a simple attack.
 168
 169 NB. due to certain broken SSH implementations aborting upon receipt
 170 of this message, the no-more-sessions request is only sent to OpenSSH
 171 servers (identified by banner). Other SSH implementations may be
 172 whitelisted to receive this message upon request.
 173
 174 2.3. connection: Tunnel forward extension "tun@openssh.com"
 175
 176 OpenSSH supports layer 2 and layer 3 tunnelling via the "tun@openssh.com"
 177 channel type. This channel type supports forwarding of network packets
 178 with datagram boundaries intact between endpoints equipped with
 179 interfaces like the BSD tun(4) device. Tunnel forwarding channels are
 180 requested by the client with the following packet:
 181
 182         byte            SSH_MSG_CHANNEL_OPEN
 183         string          "tun@openssh.com"
 184         uint32          sender channel
 185         uint32          initial window size
 186         uint32          maximum packet size
 187         uint32          tunnel mode
 188         uint32          remote unit number
 189
 190 The "tunnel mode" parameter specifies whether the tunnel should forward
 191 layer 2 frames or layer 3 packets. It may take one of the following values:
 192
 193         SSH_TUNMODE_POINTOPOINT  1              /* layer 3 packets */
 194         SSH_TUNMODE_ETHERNET     2              /* layer 2 frames */
 195
 196 The "tunnel unit number" specifies the remote interface number, or may
 197 be 0x7fffffff to allow the server to automatically chose an interface. A
 198 server that is not willing to open a client-specified unit should refuse
 199 the request with a SSH_MSG_CHANNEL_OPEN_FAILURE error. On successful
 200 open, the server should reply with SSH_MSG_CHANNEL_OPEN_SUCCESS.
 201
 202 Once established the client and server may exchange packet or frames
 203 over the tunnel channel by encapsulating them in SSH protocol strings
 204 and sending them as channel data. This ensures that packet boundaries
 205 are kept intact. Specifically, packets are transmitted using normal
 206 SSH_MSG_CHANNEL_DATA packets:
 207
 208         byte            SSH_MSG_CHANNEL_DATA
 209         uint32          recipient channel
 210         string          data
 211
 212 The contents of the "data" field for layer 3 packets is:
 213
 214         uint32                  packet length
 215         uint32                  address family
 216         byte[packet length - 4] packet data
 217
 218 The "address family" field identifies the type of packet in the message.
 219 It may be one of:
 220
 221         SSH_TUN_AF_INET         2               /* IPv4 */
 222         SSH_TUN_AF_INET6        24              /* IPv6 */
 223
 224 The "packet data" field consists of the IPv4/IPv6 datagram itself
 225 without any link layer header.
 226
 227 The contents of the "data" field for layer 2 packets is:
 228
 229         uint32                  packet length
 230         byte[packet length]     frame
 231
 232 The "frame" field contains an IEEE 802.3 Ethernet frame, including
 233 header.
 234
 235 3. SFTP protocol changes
 236
 237 3.1. sftp: Reversal of arguments to SSH_FXP_SYMLINK
 238
 239 When OpenSSH's sftp-server was implemented, the order of the arguments
 240 to the SSH_FXP_SYMLINK method was inadvertently reversed. Unfortunately,
 241 the reversal was not noticed until the server was widely deployed. Since
 242 fixing this to follow the specification would cause incompatibility, the
 243 current order was retained. For correct operation, clients should send
 244 SSH_FXP_SYMLINK as follows:
 245
 246         uint32          id
 247         string          targetpath
 248         string          linkpath
 249
 250 3.2. sftp: Server extension announcement in SSH_FXP_VERSION
 251
 252 OpenSSH's sftp-server lists the extensions it supports using the
 253 standard extension announcement mechanism in the SSH_FXP_VERSION server
 254 hello packet:
 255
 256         uint32          3               /* protocol version */
 257         string          ext1-name
 258         string          ext1-version
 259         string          ext2-name
 260         string          ext2-version
 261         ...
 262         string          extN-name
 263         string          extN-version
 264
 265 Each extension reports its integer version number as an ASCII encoded
 266 string, e.g. "1". The version will be incremented if the extension is
 267 ever changed in an incompatible way. The server MAY advertise the same
 268 extension with multiple versions (though this is unlikely). Clients MUST
 269 check the version number before attempting to use the extension.
 270
 271 3.3. sftp: Extension request "posix-rename@openssh.com"
 272
 273 This operation provides a rename operation with POSIX semantics, which
 274 are different to those provided by the standard SSH_FXP_RENAME in
 275 draft-ietf-secsh-filexfer-02.txt. This request is implemented as a
 276 SSH_FXP_EXTENDED request with the following format:
 277
 278         uint32          id
 279         string          "posix-rename@openssh.com"
 280         string          oldpath
 281         string          newpath
 282
 283 On receiving this request the server will perform the POSIX operation
 284 rename(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
 285 This extension is advertised in the SSH_FXP_VERSION hello with version
 286 "1".
 287
 288 3.4. sftp: Extension requests "statvfs@openssh.com" and
 289          "fstatvfs@openssh.com"
 290
 291 These requests correspond to the statvfs and fstatvfs POSIX system
 292 interfaces. The "statvfs@openssh.com" request operates on an explicit
 293 pathname, and is formatted as follows:
 294
 295         uint32          id
 296         string          "statvfs@openssh.com"
 297         string          path
 298
 299 The "fstatvfs@openssh.com" operates on an open file handle:
 300
 301         uint32          id
 302         string          "fstatvfs@openssh.com"
 303         string          handle
 304
 305 These requests return a SSH_FXP_STATUS reply on failure. On success they
 306 return the following SSH_FXP_EXTENDED_REPLY reply:
 307
 308         uint32          id
 309         uint64          f_bsize         /* file system block size */
 310         uint64          f_frsize        /* fundamental fs block size */
 311         uint64          f_blocks        /* number of blocks (unit f_frsize) */
 312         uint64          f_bfree         /* free blocks in file system */
 313         uint64          f_bavail        /* free blocks for non-root */
 314         uint64          f_files         /* total file inodes */
 315         uint64          f_ffree         /* free file inodes */
 316         uint64          f_favail        /* free file inodes for to non-root */
 317         uint64          f_fsid          /* file system id */
 318         uint64          f_flag          /* bit mask of f_flag values */
 319         uint64          f_namemax       /* maximum filename length */
 320
 321 The values of the f_flag bitmask are as follows:
 322
 323         #define SSH_FXE_STATVFS_ST_RDONLY       0x1     /* read-only */
 324         #define SSH_FXE_STATVFS_ST_NOSUID       0x2     /* no setuid */
 325
 326 Both the "statvfs@openssh.com" and "fstatvfs@openssh.com" extensions are
 327 advertised in the SSH_FXP_VERSION hello with version "2".
 328
 329 10. sftp: Extension request "hardlink@openssh.com"
 330
 331 This request is for creating a hard link to a regular file. This
 332 request is implemented as a SSH_FXP_EXTENDED request with the
 333 following format:
 334
 335         uint32          id
 336         string          "hardlink@openssh.com"
 337         string          oldpath
 338         string          newpath
 339
 340 On receiving this request the server will perform the operation
 341 link(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
 342 This extension is advertised in the SSH_FXP_VERSION hello with version
 343 "1".
 344
 345 10. sftp: Extension request "fsync@openssh.com"
 346
 347 This request asks the server to call fsync(2) on an open file handle.
 348
 349         uint32          id
 350         string          "fsync@openssh.com"
 351         string          handle
 352
 353 One receiving this request, a server will call fsync(handle_fd) and will
 354 respond with a SSH_FXP_STATUS message.
 355
 356 This extension is advertised in the SSH_FXP_VERSION hello with version
 357 "1".
 358
 359 $OpenBSD: PROTOCOL,v 1.23 2013/12/01 23:19:05 djm Exp $