crypto/openssh/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 2.4. connection: Unix domain socket forwarding
 236
 237 OpenSSH supports local and remote Unix domain socket forwarding
 238 using the "streamlocal" extension.  Forwarding is initiated as per
 239 TCP sockets but with a single path instead of a host and port.
 240
 241 Similar to direct-tcpip, direct-streamlocal is sent by the client
 242 to request that the server make a connection to a Unix domain socket.
 243
 244         byte            SSH_MSG_CHANNEL_OPEN
 245         string          "direct-streamlocal@openssh.com"
 246         uint32          sender channel
 247         uint32          initial window size
 248         uint32          maximum packet size
 249         string          socket path
 250         string          reserved for future use
 251
 252 Similar to forwarded-tcpip, forwarded-streamlocal is sent by the
 253 server when the client has previously send the server a streamlocal-forward
 254 GLOBAL_REQUEST.
 255
 256         byte            SSH_MSG_CHANNEL_OPEN
 257         string          "forwarded-streamlocal@openssh.com"
 258         uint32          sender channel
 259         uint32          initial window size
 260         uint32          maximum packet size
 261         string          socket path
 262         string          reserved for future use
 263
 264 The reserved field is not currently defined and is ignored on the
 265 remote end.  It is intended to be used in the future to pass
 266 information about the socket file, such as ownership and mode.
 267 The client currently sends the empty string for this field.
 268
 269 Similar to tcpip-forward, streamlocal-forward is sent by the client
 270 to request remote forwarding of a Unix domain socket.
 271
 272         byte            SSH2_MSG_GLOBAL_REQUEST
 273         string          "streamlocal-forward@openssh.com"
 274         boolean         TRUE
 275         string          socket path
 276
 277 Similar to cancel-tcpip-forward, cancel-streamlocal-forward is sent
 278 by the client cancel the forwarding of a Unix domain socket.
 279
 280         byte            SSH2_MSG_GLOBAL_REQUEST
 281         string          "cancel-streamlocal-forward@openssh.com"
 282         boolean         FALSE
 283         string          socket path
 284
 285 3. SFTP protocol changes
 286
 287 3.1. sftp: Reversal of arguments to SSH_FXP_SYMLINK
 288
 289 When OpenSSH's sftp-server was implemented, the order of the arguments
 290 to the SSH_FXP_SYMLINK method was inadvertently reversed. Unfortunately,
 291 the reversal was not noticed until the server was widely deployed. Since
 292 fixing this to follow the specification would cause incompatibility, the
 293 current order was retained. For correct operation, clients should send
 294 SSH_FXP_SYMLINK as follows:
 295
 296         uint32          id
 297         string          targetpath
 298         string          linkpath
 299
 300 3.2. sftp: Server extension announcement in SSH_FXP_VERSION
 301
 302 OpenSSH's sftp-server lists the extensions it supports using the
 303 standard extension announcement mechanism in the SSH_FXP_VERSION server
 304 hello packet:
 305
 306         uint32          3               /* protocol version */
 307         string          ext1-name
 308         string          ext1-version
 309         string          ext2-name
 310         string          ext2-version
 311         ...
 312         string          extN-name
 313         string          extN-version
 314
 315 Each extension reports its integer version number as an ASCII encoded
 316 string, e.g. "1". The version will be incremented if the extension is
 317 ever changed in an incompatible way. The server MAY advertise the same
 318 extension with multiple versions (though this is unlikely). Clients MUST
 319 check the version number before attempting to use the extension.
 320
 321 3.3. sftp: Extension request "posix-rename@openssh.com"
 322
 323 This operation provides a rename operation with POSIX semantics, which
 324 are different to those provided by the standard SSH_FXP_RENAME in
 325 draft-ietf-secsh-filexfer-02.txt. This request is implemented as a
 326 SSH_FXP_EXTENDED request with the following format:
 327
 328         uint32          id
 329         string          "posix-rename@openssh.com"
 330         string          oldpath
 331         string          newpath
 332
 333 On receiving this request the server will perform the POSIX operation
 334 rename(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
 335 This extension is advertised in the SSH_FXP_VERSION hello with version
 336 "1".
 337
 338 3.4. sftp: Extension requests "statvfs@openssh.com" and
 339          "fstatvfs@openssh.com"
 340
 341 These requests correspond to the statvfs and fstatvfs POSIX system
 342 interfaces. The "statvfs@openssh.com" request operates on an explicit
 343 pathname, and is formatted as follows:
 344
 345         uint32          id
 346         string          "statvfs@openssh.com"
 347         string          path
 348
 349 The "fstatvfs@openssh.com" operates on an open file handle:
 350
 351         uint32          id
 352         string          "fstatvfs@openssh.com"
 353         string          handle
 354
 355 These requests return a SSH_FXP_STATUS reply on failure. On success they
 356 return the following SSH_FXP_EXTENDED_REPLY reply:
 357
 358         uint32          id
 359         uint64          f_bsize         /* file system block size */
 360         uint64          f_frsize        /* fundamental fs block size */
 361         uint64          f_blocks        /* number of blocks (unit f_frsize) */
 362         uint64          f_bfree         /* free blocks in file system */
 363         uint64          f_bavail        /* free blocks for non-root */
 364         uint64          f_files         /* total file inodes */
 365         uint64          f_ffree         /* free file inodes */
 366         uint64          f_favail        /* free file inodes for to non-root */
 367         uint64          f_fsid          /* file system id */
 368         uint64          f_flag          /* bit mask of f_flag values */
 369         uint64          f_namemax       /* maximum filename length */
 370
 371 The values of the f_flag bitmask are as follows:
 372
 373         #define SSH_FXE_STATVFS_ST_RDONLY       0x1     /* read-only */
 374         #define SSH_FXE_STATVFS_ST_NOSUID       0x2     /* no setuid */
 375
 376 Both the "statvfs@openssh.com" and "fstatvfs@openssh.com" extensions are
 377 advertised in the SSH_FXP_VERSION hello with version "2".
 378
 379 10. sftp: Extension request "hardlink@openssh.com"
 380
 381 This request is for creating a hard link to a regular file. This
 382 request is implemented as a SSH_FXP_EXTENDED request with the
 383 following format:
 384
 385         uint32          id
 386         string          "hardlink@openssh.com"
 387         string          oldpath
 388         string          newpath
 389
 390 On receiving this request the server will perform the operation
 391 link(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
 392 This extension is advertised in the SSH_FXP_VERSION hello with version
 393 "1".
 394
 395 10. sftp: Extension request "fsync@openssh.com"
 396
 397 This request asks the server to call fsync(2) on an open file handle.
 398
 399         uint32          id
 400         string          "fsync@openssh.com"
 401         string          handle
 402
 403 One receiving this request, a server will call fsync(handle_fd) and will
 404 respond with a SSH_FXP_STATUS message.
 405
 406 This extension is advertised in the SSH_FXP_VERSION hello with version
 407 "1".
 408
 409 $OpenBSD: PROTOCOL,v 1.24 2014/07/15 15:54:14 millert Exp $