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 2. Connection protocol changes
  95
  96 2.1. connection: Channel write close extension "eow@openssh.com"
  97
  98 The SSH connection protocol (rfc4254) provides the SSH_MSG_CHANNEL_EOF
  99 message to allow an endpoint to signal its peer that it will send no
 100 more data over a channel. Unfortunately, there is no symmetric way for
 101 an endpoint to request that its peer should cease sending data to it
 102 while still keeping the channel open for the endpoint to send data to
 103 the peer.
 104
 105 This is desirable, since it saves the transmission of data that would
 106 otherwise need to be discarded and it allows an endpoint to signal local
 107 processes of the condition, e.g. by closing the corresponding file
 108 descriptor.
 109
 110 OpenSSH implements a channel extension message to perform this
 111 signalling: "eow@openssh.com" (End Of Write). This message is sent by
 112 an endpoint when the local output of a session channel is closed or
 113 experiences a write error. The message is formatted as follows:
 114
 115         byte            SSH_MSG_CHANNEL_REQUEST
 116         uint32          recipient channel
 117         string          "eow@openssh.com"
 118         boolean         FALSE
 119
 120 On receiving this message, the peer SHOULD cease sending data of
 121 the channel and MAY signal the process from which the channel data
 122 originates (e.g. by closing its read file descriptor).
 123
 124 As with the symmetric SSH_MSG_CHANNEL_EOF message, the channel does
 125 remain open after a "eow@openssh.com" has been sent and more data may
 126 still be sent in the other direction. This message does not consume
 127 window space and may be sent even if no window space is available.
 128
 129 NB. due to certain broken SSH implementations aborting upon receipt
 130 of this message (in contravention of RFC4254 section 5.4), this
 131 message is only sent to OpenSSH peers (identified by banner).
 132 Other SSH implementations may be whitelisted to receive this message
 133 upon request.
 134
 135 2.2. connection: disallow additional sessions extension
 136      "no-more-sessions@openssh.com"
 137
 138 Most SSH connections will only ever request a single session, but a
 139 attacker may abuse a running ssh client to surreptitiously open
 140 additional sessions under their control. OpenSSH provides a global
 141 request "no-more-sessions@openssh.com" to mitigate this attack.
 142
 143 When an OpenSSH client expects that it will never open another session
 144 (i.e. it has been started with connection multiplexing disabled), it
 145 will send the following global request:
 146
 147         byte            SSH_MSG_GLOBAL_REQUEST
 148         string          "no-more-sessions@openssh.com"
 149         char            want-reply
 150
 151 On receipt of such a message, an OpenSSH server will refuse to open
 152 future channels of type "session" and instead immediately abort the
 153 connection.
 154
 155 Note that this is not a general defence against compromised clients
 156 (that is impossible), but it thwarts a simple attack.
 157
 158 NB. due to certain broken SSH implementations aborting upon receipt
 159 of this message, the no-more-sessions request is only sent to OpenSSH
 160 servers (identified by banner). Other SSH implementations may be
 161 whitelisted to receive this message upon request.
 162
 163 2.3. connection: Tunnel forward extension "tun@openssh.com"
 164
 165 OpenSSH supports layer 2 and layer 3 tunnelling via the "tun@openssh.com"
 166 channel type. This channel type supports forwarding of network packets
 167 with datagram boundaries intact between endpoints equipped with
 168 interfaces like the BSD tun(4) device. Tunnel forwarding channels are
 169 requested by the client with the following packet:
 170
 171         byte            SSH_MSG_CHANNEL_OPEN
 172         string          "tun@openssh.com"
 173         uint32          sender channel
 174         uint32          initial window size
 175         uint32          maximum packet size
 176         uint32          tunnel mode
 177         uint32          remote unit number
 178
 179 The "tunnel mode" parameter specifies whether the tunnel should forward
 180 layer 2 frames or layer 3 packets. It may take one of the following values:
 181
 182         SSH_TUNMODE_POINTOPOINT  1              /* layer 3 packets */
 183         SSH_TUNMODE_ETHERNET     2              /* layer 2 frames */
 184
 185 The "tunnel unit number" specifies the remote interface number, or may
 186 be 0x7fffffff to allow the server to automatically chose an interface. A
 187 server that is not willing to open a client-specified unit should refuse
 188 the request with a SSH_MSG_CHANNEL_OPEN_FAILURE error. On successful
 189 open, the server should reply with SSH_MSG_CHANNEL_OPEN_SUCCESS.
 190
 191 Once established the client and server may exchange packet or frames
 192 over the tunnel channel by encapsulating them in SSH protocol strings
 193 and sending them as channel data. This ensures that packet boundaries
 194 are kept intact. Specifically, packets are transmitted using normal
 195 SSH_MSG_CHANNEL_DATA packets:
 196
 197         byte            SSH_MSG_CHANNEL_DATA
 198         uint32          recipient channel
 199         string          data
 200
 201 The contents of the "data" field for layer 3 packets is:
 202
 203         uint32                  packet length
 204         uint32                  address family
 205         byte[packet length - 4] packet data
 206
 207 The "address family" field identifies the type of packet in the message.
 208 It may be one of:
 209
 210         SSH_TUN_AF_INET         2               /* IPv4 */
 211         SSH_TUN_AF_INET6        24              /* IPv6 */
 212
 213 The "packet data" field consists of the IPv4/IPv6 datagram itself
 214 without any link layer header.
 215
 216 The contents of the "data" field for layer 2 packets is:
 217
 218         uint32                  packet length
 219         byte[packet length]     frame
 220
 221 The "frame" field contains an IEEE 802.3 Ethernet frame, including
 222 header.
 223
 224 3. SFTP protocol changes
 225
 226 3.1. sftp: Reversal of arguments to SSH_FXP_SYMLINK
 227
 228 When OpenSSH's sftp-server was implemented, the order of the arguments
 229 to the SSH_FXP_SYMLINK method was inadvertently reversed. Unfortunately,
 230 the reversal was not noticed until the server was widely deployed. Since
 231 fixing this to follow the specification would cause incompatibility, the
 232 current order was retained. For correct operation, clients should send
 233 SSH_FXP_SYMLINK as follows:
 234
 235         uint32          id
 236         string          targetpath
 237         string          linkpath
 238
 239 3.2. sftp: Server extension announcement in SSH_FXP_VERSION
 240
 241 OpenSSH's sftp-server lists the extensions it supports using the
 242 standard extension announcement mechanism in the SSH_FXP_VERSION server
 243 hello packet:
 244
 245         uint32          3               /* protocol version */
 246         string          ext1-name
 247         string          ext1-version
 248         string          ext2-name
 249         string          ext2-version
 250         ...
 251         string          extN-name
 252         string          extN-version
 253
 254 Each extension reports its integer version number as an ASCII encoded
 255 string, e.g. "1". The version will be incremented if the extension is
 256 ever changed in an incompatible way. The server MAY advertise the same
 257 extension with multiple versions (though this is unlikely). Clients MUST
 258 check the version number before attempting to use the extension.
 259
 260 3.3. sftp: Extension request "posix-rename@openssh.com"
 261
 262 This operation provides a rename operation with POSIX semantics, which
 263 are different to those provided by the standard SSH_FXP_RENAME in
 264 draft-ietf-secsh-filexfer-02.txt. This request is implemented as a
 265 SSH_FXP_EXTENDED request with the following format:
 266
 267         uint32          id
 268         string          "posix-rename@openssh.com"
 269         string          oldpath
 270         string          newpath
 271
 272 On receiving this request the server will perform the POSIX operation
 273 rename(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
 274 This extension is advertised in the SSH_FXP_VERSION hello with version
 275 "1".
 276
 277 3.4. sftp: Extension requests "statvfs@openssh.com" and
 278          "fstatvfs@openssh.com"
 279
 280 These requests correspond to the statvfs and fstatvfs POSIX system
 281 interfaces. The "statvfs@openssh.com" request operates on an explicit
 282 pathname, and is formatted as follows:
 283
 284         uint32          id
 285         string          "statvfs@openssh.com"
 286         string          path
 287
 288 The "fstatvfs@openssh.com" operates on an open file handle:
 289
 290         uint32          id
 291         string          "fstatvfs@openssh.com"
 292         string          handle
 293
 294 These requests return a SSH_FXP_STATUS reply on failure. On success they
 295 return the following SSH_FXP_EXTENDED_REPLY reply:
 296
 297         uint32          id
 298         uint64          f_bsize         /* file system block size */
 299         uint64          f_frsize        /* fundamental fs block size */
 300         uint64          f_blocks        /* number of blocks (unit f_frsize) */
 301         uint64          f_bfree         /* free blocks in file system */
 302         uint64          f_bavail        /* free blocks for non-root */
 303         uint64          f_files         /* total file inodes */
 304         uint64          f_ffree         /* free file inodes */
 305         uint64          f_favail        /* free file inodes for to non-root */
 306         uint64          f_fsid          /* file system id */
 307         uint64          f_flag          /* bit mask of f_flag values */
 308         uint64          f_namemax       /* maximum filename length */
 309
 310 The values of the f_flag bitmask are as follows:
 311
 312         #define SSH_FXE_STATVFS_ST_RDONLY       0x1     /* read-only */
 313         #define SSH_FXE_STATVFS_ST_NOSUID       0x2     /* no setuid */
 314
 315 Both the "statvfs@openssh.com" and "fstatvfs@openssh.com" extensions are
 316 advertised in the SSH_FXP_VERSION hello with version "2".
 317
 318 10. sftp: Extension request "hardlink@openssh.com"
 319
 320 This request is for creating a hard link to a regular file. This
 321 request is implemented as a SSH_FXP_EXTENDED request with the
 322 following format:
 323
 324         uint32          id
 325         string          "hardlink@openssh.com"
 326         string          oldpath
 327         string          newpath
 328
 329 On receiving this request the server will perform the operation
 330 link(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
 331 This extension is advertised in the SSH_FXP_VERSION hello with version
 332 "1".
 333
 334 $OpenBSD: PROTOCOL,v 1.20 2013/01/08 18:49:04 markus Exp $