- djm@cvs.openbsd.org 2008/05/16 08:30:42
[PROTOCOL]
document our protocol extensions and deviations; ok markus@
- djm@cvs.openbsd.org 2008/05/17 01:31:56
[PROTOCOL]
grammar and correctness fixes from stevesk@
diff --git a/PROTOCOL b/PROTOCOL
new file mode 100644
index 0000000..5a9404e
--- /dev/null
+++ b/PROTOCOL
@@ -0,0 +1,154 @@
+This documents OpenSSH's deviations and extensions to the published SSH
+protocol.
+
+Note that OpenSSH's sftp and sftp-server implement revision 3 of the SSH
+filexfer protocol described in:
+
+http://www.openssh.com/txt/draft-ietf-secsh-filexfer-02.txt
+
+Features from newer versions of the draft are not supported, unless
+explicitly implemented as extensions described below.
+
+1. transport: Protocol 2 MAC algorithm "umac-64@openssh.com"
+
+This is a new transport-layer MAC method using the UMAC algorithm
+(rfc4418). This method is identical to the "umac-64" method documented
+in:
+
+http://www.openssh.com/txt/draft-miller-secsh-umac-01.txt
+
+2. transport: Protocol 2 compression algorithm "zlib@openssh.com"
+
+This transport-layer compression method uses the zlib compression
+algorithm (identical to the "zlib" method in rfc4253), but delays the
+start of compression until after authentication has completed. This
+avoids exposing compression code to attacks from unauthenticated users.
+
+The method is documented in:
+
+http://www.openssh.com/txt/draft-miller-secsh-compression-delayed-00.txt
+
+3. connection: Channel write close extension "eow@openssh.com"
+
+The SSH connection protocol (rfc4254) provides the SSH_MSG_CHANNEL_EOF
+message to allow an endpoint to signal its peer that it will send no
+more data over a channel. Unfortunately, there is no symmetric way for
+an endpoint to request that its peer should cease sending data to it
+while still keeping the channel open for the endpoint to send data to
+the peer.
+
+This is desirable, since it saves the transmission of data that would
+otherwise need to be discarded and it allows an endpoint to signal local
+processes of the condition, e.g. by closing the corresponding file
+descriptor.
+
+OpenSSH implements a channel extension message to perform this
+signalling: "eow@openssh.com" (End Of Write). This message is sent by an
+endpoint when the local output of a channel is closed or experiences a
+write error. The message is formatted as follows:
+
+ byte SSH_MSG_CHANNEL_REQUEST
+ uint32 recipient channel
+ string "eow@openssh.com"
+ boolean FALSE
+
+On receiving this message, the peer SHOULD cease sending data of
+the channel and MAY signal the process from which the channel data
+originates (e.g. by closing its read file descriptor).
+
+As with the symmetric SSH_MSG_CHANNEL_EOF message, the channel does
+remain open after a "eow@openssh.com" has been sent and more data may
+still be sent in the other direction. This message does not consume
+window space and may be sent even if no window space is available.
+
+4. sftp: Reversal of arguments to SSH_FXP_SYMLINK
+
+When OpenSSH's sftp-server was implemented, the order of the arguments
+to the SSH_FXP_SYMLINK method was inadvertendly reversed. Unfortunately,
+the reversal was not noticed until the server was widely deployed. Since
+fixing this to follow the specification would cause incompatibility, the
+current order was retained. For correct operation, clients should send
+SSH_FXP_SYMLINK as follows:
+
+ uint32 id
+ string targetpath
+ string linkpath
+
+5. sftp: Server extension announcement in SSH_FXP_VERSION
+
+OpenSSH's sftp-server lists the extensions it supports using the
+standard extension announcement mechanism in the SSH_FXP_VERSION server
+hello packet:
+
+ uint32 3 /* protocol version */
+ string ext1-name
+ string ext1-version
+ string ext2-name
+ string ext2-version
+ ...
+ string extN-name
+ string extN-version
+
+Each extension reports its integer version number as an ASCII encoded
+string, e.g. "1". The version will be incremented if the extension is
+ever changed in an incompatible way. The server MAY advertise the same
+extension with multiple versions (though this is unlikely). Clients MUST
+check the version number before attemping to use the extension.
+
+6. sftp: Extension request "posix-rename@openssh.com"
+
+This operation provides a rename operation with POSIX semantics, which
+are different to those provided by the standard SSH_FXP_RENAME in
+draft-ietf-secsh-filexfer-02.txt. This request is implemented as a
+SSH_FXP_EXTENDED request with the following format:
+
+ uint32 id
+ string "posix-rename@openssh.com"
+ string oldpath
+ string newpath
+
+On receiving this request the server will perform the POSIX operation
+rename(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
+This extension is advertised in the SSH_FXP_VERSION hello with version
+"1".
+
+7. sftp: Extension requests "statvfs@openssh.com" and
+ "fstatvfs@openssh.com"
+
+These requests correspond to the statvfs and fstatvfs POSIX system
+interfaces. The "statvfs@openssh.com" request operates on an explicit
+pathname, and is formatted as follows:
+
+ uint32 id
+ string "statvfs@openssh.com"
+ string path
+
+The "fstatvfs@openssh.com" operates on an open filehandle:
+
+ uint32 id
+ string "fstatvfs@openssh.com"
+ string handle
+
+These requests return a SSH_FXP_STATUS reply on failure. On success they
+return the following SSH_FXP_EXTENDED_REPLY reply:
+
+ uint32 id
+ uint32 f_bsize /* file system block size */
+ uint32 f_frsize /* fundamental fs block size */
+ uint64 f_blocks /* number of blocks (unit f_frsize) */
+ uint64 f_bfree /* free blocks in file system */
+ uint64 f_bavail /* free blocks for non-root */
+ uint64 f_files /* total file inodes */
+ uint64 f_ffree /* free file inodes */
+ uint64 f_favail /* free file inodes for to non-root */
+ uint32 f_fsid /* file system id */
+ uint32 f_flag /* bit mask of f_flag values */
+ uint32 f_namemax /* maximum filename length */
+
+The values of the f_flag bitmask are as follows:
+
+ #define SSH_FXE_STATVFS_ST_RDONLY 0x1 /* read-only */
+ #define SSH_FXE_STATVFS_ST_NOSUID 0x2 /* no setuid */
+
+$Id: PROTOCOL,v 1.1 2008/05/19 06:11:56 djm Exp $
+