Alexander Haväng        *
													    Tobias Rundström
				Good Secure Transfer Protocol (GSTP)

Status of this Memo
	   This document is work in progress.
	   This is version 2003-02-05.

Abstract
		GSTP is a binary protocol for secure and simple file transfer between
		two IP connected hosts. GSTP is designed to be established on top of a
		TLS connection, but will function on top of any reliable connection
		protocol such as TCP.
		GSTP uses the TLS protocol to establish a secure
		channel between the client and the server, so that no information or
		data is transmitted in clear text.
		GSTP tried to do right, where the File Transfer Protocol (FTP) did wrong,
		especially with issues such as connection and firewall simplicity,
		encryption, virtual hosts and protocol simplicity.

1. Connections
   GTSP uses TCP/10042 for all communication and file transfers.
   A session consist of a series of messages.
   The GSTP client issues command messages to the GSTP server, which
   responds with reply messages.
   The first message sent must be the hello packet, and that is sent before the
   TLS connection is initalized (i.e unencrypted).
   There can be several reply messages issued for one command message,
   and reply messages where the id field is zero is used for reply messages
   that don't apply to a certain command message. This type of reply messages is
   used for status messages from the server.
   Each unique command message id will always be answered with exactly one final
   message with the SUCCESS or FAILURE status code set.
   Unless otherwize specified, all integer fields below are unsigned and in
   in network byte order.
   The GSTP protocol does not care about byte alignment boundaries.
   Work around them.

2. Message description
   <message length : 16 bit> The complete message length, including the length
							 field itself.
   <message id: 16 bit>
   <message data: message length bytes>

   The minimum size for a gstp message is 5 bytes.
   The message id field should not be 0, and it is ok to reuse ids, just be
   careful not to have two different pending commands with the same id.

   The maximum message length is 32k, unless otherwize specified by the client
   issuing a SET command. This also means that all GSTP implementations MUST
   be able to handle message sizes of 32k.

   We're still thinking about UTF-8 or some similar character encoding.. but
   haven't decided yet. Right now, all strings are transmitted as 8 bit clean
   single-byte character encoding.

3. Command message description
   The message data field in the message looks like this:
   <command opcode: 8 bit> This is the command opcode, for possible values
   see (5) below.
	If the last bit in the opcode is set, then the following option field is present.
	   <command options: 16 bit> Used for the command/reply system.
   <command data: message length - 15 or 17 bytes>   

4. Reply message description
   The message data field in the reply message looks like this:
   
   <reply status code: 8 bit>
		  0 - Success
		  1 - Failure
		  2 - Status
		  3 - Result
		  4 - Error

   Iff the status code includes 2 or 4 (i.e either status or error), then the
   following field is present.
      <reply generic status data field: 64 bit> 						
	  Numeric equivalent of the message below. A non-exhaustive list of ids can be
	  found in gstp_reply.h.
	  The first 16 bits should represent the command opcode. The next 16 bits
	  should represent the class of the message. The last 32 bits are individual.

   <reply message: message length - 21 or 13 bytes>

   The reply message for error or status messages should be in english.

   Using the generic status data field, the client should, without reading the
   actual reply message, be able to present a message to the user, telling him
   what the message was about.

5. Command opcodes
   The command opcode is one of the following values.
   A GSTP server must implement this compulsory list of commands,
   and must reply with a failure message to other unsupported opcodes.


	The 16 bit command option can be used for command/reply flags.
	At this time, there is only one option used,
	GSTP_COMMAND_OPTION_NO_SUCCESS_REPLY, which is used when you don't
	want a success message back from the server. This is most useful when
	you are sending a lot of data to the server, e.g the Write command.
	
5.0 Authenticate command
	<authenticate type: 16 bit> 0 for anonymous, 1 for user/password authentication.
	<authenticate user length: 16 bit>
	<authenticate user data: authenticate user length>
	<authenticate password length: 16 bit>
	<authenticate password data: authenticate password length>

	For anonymous access, the type is set to 0, and the rest of the command
	data must be ignored.

5.1 Logout command
	The logout command terminates the connection and closes the connection
	socket. All pending transfers will be terminated.

5.2 Open command
	The open command opens a file on the server side, either for reading
	or writing. The open commands results in a file descriptor described
	as a single integer. This integer does not have to be the actual value
	of the file descriptor on the server, but it could be.
	The file descriptor is kept open until the client disconnects, or
	issues a Close command.
	<open options: 16 bit> Open, close, or append
	<open offset: 64 bit> Fast forward to
	<open file name length: 32 bit>
	<open file name: open file name length>
	
	The reply message:
	<open totalsize: 64 bit> File total size
	<open offset: 64 bit> File offset
	<open fd: 16 bit> File descriptor

5.3 Close command
	<close fd: 16 bit> File descriptor

5.4 Read command
	Request read length bytes from read fd.
	<read fd: 16 bit>
	<read length: 64 bit>

	Reply message:
	<read total length: 64 bit>
	<read message length: 16 bit>
	<read data: read message length>

5.5 Write command
	Write write length bytes to write fd
	<write fd: 16 bit>
	<write total length: 64 bit>
	<write message length: 16 bit>
	<write message data: write message length>

5.6 Remove command
	The remove command removes files or directories.
	<remove options: 32 bit>
	<remove path count: 16 bit>
			<remove path length: 32 bit>
			<remove path data: remove path length>

5.7 Change properties command
	<chprop options: 32 bit>
	<chprop path count: 16 bit>
			<chprop path length: 32 bit>
			<chprop path data: chprop path length>
			<chprop prop count: 16 bit>
					<chprop prop id: 64 bit>
					<chprop prop length bytes: 32 bit>
					<chprop prop data: chprop prop length bytes>

5.8 Create command
	<create type: 16 bit>
	<create options: 32 bit>
	<create path length: 32 bit>
	<create path data: create path length>

	If the create type is 2 (symbolic link) then we add
	<create path source length: 32 bit>
	<create path source data: create path source length>

	create type:
		   0 - Normal file
		   1 - Directory
		   2 - Symbolic link

	create options:
		   None sofar, file permissions should be set with a Change properties
		   command.
	
5.9 List Directory command
	<directory glob length: 32 bit>
	<directory glob data: directory glob length>
	<directory options: 32 bit>
	<path length: 32 bit>
	<path data: path length>

	The server must only reply with the file properties that are 
	available in the directory options part of the command.

	List Directory reply message
	<file count: 64 bit>
		  <file property count: 16 bit>
				<file property id: 16 bit>
				<file property length: 32 bit>
				<file property data: file property length>

5.10 Ping command
	 <ping data: 32 bit>

	 The Ping command will always result in a Pong reply from the server
	 with the exact same ping data. 

5.11 Stat command
	 The stat command is used to check the existance and properties of a file.
	 <stat file length: 32 bit>
	 <stat file data: 32 bit>

	 Reply message:
     <stat file property count: 16 bit> 0 Indicates no such file or directory.
	 	 <stat file property id: 16 bit>
		 <stat file property length: 32 bit>
		 <stat file property data: stat file property length>

5.12 Move command
	 <move options: 32 bit>
	 <move source length: 32 bit>
	 <move source path: move source length>
	 <move destination length: 32 bit>
	 <move destination path: move destination length>

5.13 Checksum command
	 <checksum type: 16 bit>
	 <checksum options: 32 bit>
	 <checksum offset: 64 bit>
	 <checksum length: 64 bit>
	 <checksum path length: 32 bit>
	 <checksum path data: checksum path length>

	 Result reply message:
	 <checksum file length: 64 bit>
	 <checksum data length: 16 bit>
	 <checksum data: checksum data length>

5.16 Capabilities command
	 The capabilities command should describe, in detail, what commands,
	 options and properties	are available at the remote system.

	 The capability command is empty.

	 The reply looks like this:

	 <capabilities count: 16 bit>
	 	 <capabilities id: 16 bit>
		 <capabilities property count: 16 bit>
					   <capabilities property id: 16 bit>
					   <capabilities property value length: 16 bit>
					   <capabilities property value: capabilities property value length>

	 Each capability id in the reply presents what opcodes are available in the
	 server. So, if the open opcode has been disabled, there will be no capability id
	 with id=2. If the open opcode is available, but write access has been disabled, then
	 id=2 will be in the reply, but property id (GSTP_CAPABILITY_OPEN_WRITE) will not be available.
	 The capability id 42 should be used for settings with no applicable opcode.
	 The value part of each property is usually not used, but could be used when some kind of
	 string is the applicable value for a certain property.
	 Capabilities for the AUTH command are pointless, since the capabilites
	 command is issued after the user has logged in.
	 Capabilities for the capability command is, for obvious reasons, also pointless.

5.17 Map command
	 <map id: 16 bit>

	 Result reply message:
	 <map entries: 32 bit>
		  <map entry index: 32 bit>
		  <map entry value length: 16 bit>
		  <map entry value: map entry value length>

     The map command is for receiving server maps. This is most useful for
	 the password and group map, which contains mappings between uid & gid
	 and usernames & groups.

5.18 Locate command
	 <locate options: 32 bit> /* Same as directory options for rdir */
	 <locate criteria: 8 bit> /* Number of criteria for the search */
			 <locate criteria id: 16 bit>
			 <locate criteria length: 16 bit>
			 <locate criteria data: locate criteria length>

	 The reply message looks just like the rdir reply.

5.20 Avail command
     The avail command is used to retrieve file system usage information for a 
     certain directory. This way a user will know whether his upload will fit on the remote system. This should only be used in an informative way, and should not stop the user from uploading too large a file. It is in no way a guarantee that the file will fit, since other users might fill the file system.

     <avail options: 32 bit>
     <avail path length: 32 bit>
     <avail path: avail path length>

     The avail reply:

     <avail total bytes: 64 bit> Total capacity of filesystem in bytes.
     <avail free bytes: 64 bit> Number of free bytes on the filesystem.
     <avail total files: 64 bit> Total capacity of filesystem files.
     <avail free files: 64 bit> Number of free files.

5.42 Hello command
	 <protocol version: 16 bit>
	 <protocol options: 32 bit>
	 <protocol software id: 32 bit>
	 <protocol software string length: 16 bit>
	 <protocol software : protocol software string length>
	 <protocol host length: 16 bit>
	 <protocol host: protocol host length>

	 The hello result reply looks like this:
	 <protocol version: 16 bit>
	 <protocol options: 32 bit>
	 <protocol software id: 32 bit>
	 <protocol software length: 16 bit>
	 <protocol software : protocol software length>

	 The server must return a FAILURE reply if the client version
	 is incompatible with the server software.
	 This means that if the hello succeeds, then the client is allowed to
	 use the indicated version even if it differs from the server version.

	 However, the client must not use any protocol options indicated in the
	 client hello command unless the same options are available in the server
	 hello reply.

	 Also, the server must not use any protocol options not available in the
	 client hello command.

	 The protocol options should only affect low level communication options,
	 and not command specific options. For the latter, see the capabilities
	 command.

	 The software id:s should be unique for each version of each GSTP software
	 implementation, so that workarounds can be easily implemented.
	 

6.0 Table of numeric values
6.1 Command opcodes
 GSTP_COMMAND_AUTH 0
 GSTP_COMMAND_LOGOUT 1
 GSTP_COMMAND_OPEN 2
 GSTP_COMMAND_CLOSE 3
 GSTP_COMMAND_READ 4
 GSTP_COMMAND_WRITE 5
 GSTP_COMMAND_REMOVE 6
 GSTP_COMMAND_CHPROP 7
 GSTP_COMMAND_CREATE 8
 GSTP_COMMAND_RDIR 9
 GSTP_COMMAND_PING 10
 GSTP_COMMAND_STAT 11
 GSTP_COMMAND_CHECKSUM 12
 GSTP_COMMAND_MOVE 13
 GSTP_COMMAND_SET 14
 GSTP_COMMAND_SEEK 15
 GSTP_COMMAND_CAPABILITIES 16
 GSTP_COMMAND_MAP 17
 GSTP_COMMAND_LOCATE 18
 GSTP_COMMAND_LOCK 19
 GSTP_COMMAND_AVAIL 20

 GSTP_COMMAND_HELLO 42

6.2 Command options
 GSTP_COMMAND_OPTION_NO_REPLY_SUCCESS 1 << 0

6.3 Reply status code
 GSTP_REPLY_SUCCESS 0
 GSTP_REPLY_FAILURE 1
 GSTP_REPLY_STATUS 2
 GSTP_REPLY_RESULT 3
 GSTP_REPLY_ERROR 4

6.4 Reply status id
6.5 Open options
 GSTP_FILE_OPEN_READ 1
 GSTP_FILE_OPEN_WRITE 2
 GSTP_FILE_OPEN_APPEND 3

6.5 Remove options
6.6 Change properties options
6.7 Change properties id
 GSTP_FILE_CHPROP_TYPE_POSIX_CHMOD 0
6.8 Create type
 GSTP_FILE_CREATE_FILE 0
 GSTP_FILE_CREATE_DIR 1
6.9 Create options
6.10 List directory options
 GSTP_DIRECTORY_OPTION_REVERSE 1 << 0
6.11 
 GSTP_DIRECTORY_NODE_PROP_NAME 1
 GSTP_DIRECTORY_NODE_PROP_MODE 2
 GSTP_DIRECTORY_NODE_PROP_LINKS 3
 GSTP_DIRECTORY_NODE_PROP_UID 4
 GSTP_DIRECTORY_NODE_PROP_GID 5
 GSTP_DIRECTORY_NODE_PROP_SIZE 6
 GSTP_DIRECTORY_NODE_PROP_ATIME 7
 GSTP_DIRECTORY_NODE_PROP_MTIME 8
 GSTP_DIRECTORY_NODE_PROP_CTIME 9
 GSTP_DIRECTORY_NODE_PROP_TYPE 10
6.12 List directory node prop type values
 GSTP_DIRECTORY_NODE_PROP_TYPE_REGULAR 1
 GSTP_DIRECTORY_NODE_PROP_TYPE_DIR 2
 GSTP_DIRECTORY_NODE_PROP_TYPE_LINK 3
6.12 Move options
6.13 Checksum type
6.14 Checksum options
6.15 Hello options
 Flags for the protocol options:
 GSTP_HELLO_OPTION_USE_SSL 1 /* Whether to use SSL/TLS */
6.16 Map ids
	 GSTP_MAP_ID_USERS 1
	 GSTP_MAP_ID_GROUPS 2