document our protocol extensions and deviations; ok markus@

1 files changed, 154 insertions, 0 deletions

diff --git a/usr.bin/ssh/PROTOCOL b/usr.bin/ssh/PROTOCOL
new file mode 100644
index 00000000000..b2c917be0a7
--- /dev/null
+++ b/usr.bin/ssh/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 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
+avoid 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 the 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		"statvfs@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/16 08:30:42 djm Exp $
+