[BACK]Return to PROTOCOL CVS log [TXT][DIR] Up to [local] / src / usr.bin / ssh

Annotation of src/usr.bin/ssh/PROTOCOL, Revision 1.49

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