Annotation of src/usr.bin/ssh/PROTOCOL, Revision 1.1
1.1 ! djm 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 the
! 5: SSH filexfer protocol described in:
! 6:
! 7: http://www.openssh.com/txt/draft-ietf-secsh-filexfer-02.txt
! 8:
! 9: Features from newer versions of the draft are not supported, unless
! 10: explicitly implemented as extensions described below.
! 11:
! 12: 1. transport: Protocol 2 MAC algorithm "umac-64@openssh.com"
! 13:
! 14: This is a new transport-layer MAC method using the UMAC algorithm
! 15: (rfc4418). This method is identical to the "umac-64" method documented
! 16: in:
! 17:
! 18: http://www.openssh.com/txt/draft-miller-secsh-umac-01.txt
! 19:
! 20: 2. transport: Protocol 2 compression algorithm "zlib@openssh.com"
! 21:
! 22: This transport-layer compression method uses the zlib compression
! 23: algorithm (identical to the "zlib" method in rfc4253), but delays the
! 24: start of compression until after authentication has completed. This
! 25: avoid exposing compression code to attacks from unauthenticated users.
! 26:
! 27: The method is documented in:
! 28:
! 29: http://www.openssh.com/txt/draft-miller-secsh-compression-delayed-00.txt
! 30:
! 31: 3. connection: Channel write close extension "eow@openssh.com"
! 32:
! 33: The SSH connection protocol (rfc4254) provides the SSH_MSG_CHANNEL_EOF
! 34: message to allow an endpoint to signal its peer that it will send no
! 35: more data over a channel. Unfortunately, there is no symmetric way for
! 36: an endpoint to request that its peer should cease sending data to it
! 37: while still keeping the channel open for the endpoint to send data to
! 38: the peer.
! 39:
! 40: This is desirable, since it saves the transmission of data the would
! 41: otherwise need to be discarded and it allows an endpoint to signal local
! 42: processes of the condition, e.g. by closing the corresponding file
! 43: descriptor.
! 44:
! 45: OpenSSH implements a channel extension message to perform this
! 46: signalling: "eow@openssh.com" (End Of Write). This message is sent by an
! 47: endpoint when the local output of a channel is closed or experiences a
! 48: write error. The message is formatted as follows:
! 49:
! 50: byte SSH_MSG_CHANNEL_REQUEST
! 51: uint32 recipient channel
! 52: string "eow@openssh.com"
! 53: boolean FALSE
! 54:
! 55: On receiving this message, the peer SHOULD cease sending data of
! 56: the channel and MAY signal the process from which the channel data
! 57: originates (e.g. by closing its read file descriptor).
! 58:
! 59: As with the symmetric SSH_MSG_CHANNEL_EOF message, the channel does
! 60: remain open after a "eow@openssh.com" has been sent and more data may
! 61: still be sent in the other direction. This message does not consume
! 62: window space and may be sent even if no window space is available.
! 63:
! 64: 4. sftp: Reversal of arguments to SSH_FXP_SYMLINK
! 65:
! 66: When OpenSSH's sftp-server was implemented, the order of the arguments
! 67: to the SSH_FXP_SYMLINK method was inadvertendly reversed. Unfortunately,
! 68: the reversal was not noticed until the server was widely deployed. Since
! 69: fixing this to follow the specification would cause incompatibility, the
! 70: current order was retained. For correct operation, clients should send
! 71: SSH_FXP_SYMLINK as follows:
! 72:
! 73: uint32 id
! 74: string targetpath
! 75: string linkpath
! 76:
! 77: 5. sftp: Server extension announcement in SSH_FXP_VERSION
! 78:
! 79: OpenSSH's sftp-server lists the extensions it supports using the
! 80: standard extension announcement mechanism in the SSH_FXP_VERSION server
! 81: hello packet:
! 82:
! 83: uint32 3 /* protocol version */
! 84: string ext1-name
! 85: string ext1-version
! 86: string ext2-name
! 87: string ext2-version
! 88: ...
! 89: string extN-name
! 90: string extN-version
! 91:
! 92: Each extension reports its integer version number as an ASCII encoded
! 93: string, e.g. "1". The version will be incremented if the extension is
! 94: ever changed in an incompatible way. The server MAY advertise the same
! 95: extension with multiple versions (though this is unlikely). Clients MUST
! 96: check the version number before attemping to use the extension.
! 97:
! 98: 6. sftp: Extension request "posix-rename@openssh.com"
! 99:
! 100: This operation provides a rename operation with POSIX semantics, which
! 101: are different to those provided by the standard SSH_FXP_RENAME in
! 102: draft-ietf-secsh-filexfer-02.txt. This request is implemented as a
! 103: SSH_FXP_EXTENDED request with the following format:
! 104:
! 105: uint32 id
! 106: string "posix-rename@openssh.com"
! 107: string oldpath
! 108: string newpath
! 109:
! 110: On receiving this request the server will perform the POSIX operation
! 111: rename(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
! 112: This extension is advertised in the SSH_FXP_VERSION hello with version
! 113: "1".
! 114:
! 115: 7. sftp: Extension requests "statvfs@openssh.com" and
! 116: "fstatvfs@openssh.com"
! 117:
! 118: These requests correspond to the statvfs and fstatvfs POSIX system
! 119: interfaces. The "statvfs@openssh.com" request operates on an explicit
! 120: pathname, and is formatted as follows:
! 121:
! 122: uint32 id
! 123: string "statvfs@openssh.com"
! 124: string path
! 125:
! 126: The "fstatvfs@openssh.com" operates on an open filehandle:
! 127:
! 128: uint32 id
! 129: string "statvfs@openssh.com"
! 130: string handle
! 131:
! 132: These requests return a SSH_FXP_STATUS reply on failure. On success they
! 133: return the following SSH_FXP_EXTENDED_REPLY reply:
! 134:
! 135: uint32 id
! 136: uint32 f_bsize /* file system block size */
! 137: uint32 f_frsize /* fundamental fs block size */
! 138: uint64 f_blocks /* number of blocks (unit f_frsize) */
! 139: uint64 f_bfree /* free blocks in file system */
! 140: uint64 f_bavail /* free blocks for non-root */
! 141: uint64 f_files /* total file inodes */
! 142: uint64 f_ffree /* free file inodes */
! 143: uint64 f_favail /* free file inodes for to non-root */
! 144: uint32 f_fsid /* file system id */
! 145: uint32 f_flag /* bit mask of f_flag values */
! 146: uint32 f_namemax /* maximum filename length */
! 147:
! 148: The values of the f_flag bitmask are as follows:
! 149:
! 150: #define SSH_FXE_STATVFS_ST_RDONLY 0x1 /* read-only */
! 151: #define SSH_FXE_STATVFS_ST_NOSUID 0x2 /* no setuid */
! 152:
! 153: $Id$
! 154: