- 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@

1 files changed, 154 insertions, 0 deletions

diff --git a/PROTOCOL b/PROTOCOL
new file mode 100644
index 000000000..5a9404e9e
--- /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 $
+