Zanka Software Axel Andersson Request for Comments: 1 March 2004 Wired Protocol 1.0 Status of this Memo This memo provides information for the Internet community. It describes an Internet protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) Axel Andersson 2003-2004. All Rights Reserved. Abstract The Wired protocol is an application-level protocol for real time chat, messaging and file transfers. It is based on the client-server model, with many clients connected to one and the same server, allowing both public and private messaging. The main design principles are standardization and the unification of messaging and file transfer systems. Table of Contents 1 Introduction ...................................................3 1.1 Purpose ......................................................3 1.2 Terminology ..................................................3 1.3 Overall Operation ............................................4 1.4 Access Authentication ........................................4 2 Protocol Parameters ............................................4 2.1 Identification Numbers .......................................4 2.2 Control Characters ...........................................5 2.3 Strings ......................................................5 2.4 Booleans .....................................................5 2.5 Version Strings ..............................................5 2.6 Addresses ....................................................6 2.7 Date & Time Format ...........................................6 2.8 Privilege Specifications .....................................6 3 Sequences ......................................................7 3.1 Login Sequence ...............................................7 3.2 Private Chat Sequence ........................................8 4 Files ..........................................................9 4.1 File Listings ................................................9 4.2 Transfers ....................................................9 5 Accounts .......................................................10 6 Commands .......................................................11 6.1 Command Format ................................................11 6.2 Command Listing ...............................................11 6.2.1 BAN .......................................................11 6.2.2 BROADCAST .................................................11 6.2.3 CLEARNEWS .................................................11 6.2.4 CLIENT ....................................................12 6.2.5 CREATEUSER ................................................12 6.2.6 CREATEGROUP ...............................................13 6.2.7 DECLINE ...................................................12 6.2.8 DELETE ....................................................12 6.2.9 DELETEUSER ................................................12 6.2.10 DELETEGROUP ...............................................12 6.2.11 EDITUSER ..................................................12 6.2.12 EDITGROUP .................................................13 6.2.13 FOLDER ....................................................13 6.2.14 GET .......................................................13 6.2.15 GROUPS ....................................................13 6.2.16 HELLO .....................................................13 6.2.17 ICON ......................................................13 6.2.18 INFO ......................................................14 6.2.19 INVITE ....................................................14 6.2.20 JOIN ......................................................14 6.2.21 KICK ......................................................14 6.2.22 LEAVE .....................................................14 6.2.23 LIST ......................................................14 6.2.24 ME ........................................................15 6.2.25 MOVE ......................................................15 6.2.26 MSG .......................................................15 6.2.27 NEWS ......................................................15 6.2.28 NICK ......................................................15 6.2.29 PASS ......................................................15 6.2.30 PING ......................................................15 6.2.31 POST ......................................................15 6.2.32 PRIVCHAT ..................................................16 6.2.33 PRIVILEGES ................................................16 6.2.34 PUT .......................................................16 6.2.35 READUSER ..................................................16 6.2.36 READGROUP .................................................16 6.2.37 SAY .......................................................16 6.2.38 SEARCH ....................................................17 6.2.39 STAT ......................................................17 6.2.40 TRANSFER ..................................................17 6.2.41 USER ......................................................17 6.2.42 USERS .....................................................17 6.2.43 WHO .......................................................17 7 Messages .......................................................17 7.1 Message Format ................................................17 7.2 200 Class Messages ............................................18 7.2.1 200 Server Information ....................................18 7.2.2 201 Login Succeeded .......................................18 7.2.3 202 Ping Reply ............................................18 7.3 300 Class Messages ............................................18 7.3.1 300 Chat ..................................................18 7.3.2 301 Action Chat ...........................................19 7.3.3 302 Client Join ...........................................19 7.3.4 303 Client Leave ..........................................19 7.3.5 304 Status Change .........................................19 7.3.6 305 Private Message .......................................20 7.3.7 306 Client Kicked .........................................20 7.3.8 307 Client Banned .........................................20 7.3.9 308 Client Information ....................................20 7.3.10 309 Broadcast Message .....................................21 7.3.11 310 User List .............................................21 7.3.12 311 User List Done ........................................21 7.3.13 320 News ..................................................22 7.3.14 321 News Done .............................................22 7.3.15 322 News Posted ...........................................22 7.3.16 330 Private Chat Created ..................................22 7.3.17 331 Private Chat Invitiation ..............................22 7.3.18 332 Private Chat Declined .................................23 7.4 400 Class Messages ............................................23 7.4.1 400 Transfer Ready ........................................23 7.4.2 401 Transfer Queued .......................................23 7.4.3 402 File Information ......................................23 7.4.4 410 File Listing ..........................................24 7.4.5 411 File Listing Done .....................................24 7.4.6 420 Search Listing ........................................24 7.4.7 421 Search Listing Done ...................................24 7.5 500 Class Messages ............................................25 7.5.1 500 Command Failed ........................................25 7.5.2 501 Command Not Recognized ................................25 7.5.3 502 Command Not Implemented ...............................25 7.5.4 503 Syntax Error ..........................................25 7.5.5 510 Login Failed ..........................................25 7.5.6 511 Banned ................................................25 7.5.7 512 Client Not Found ......................................25 7.5.8 513 Account Not Found .....................................25 7.5.9 514 Account Exists ........................................25 7.5.10 515 Cannot Be Disconnected ................................26 7.5.11 516 Permission Denied .....................................26 7.5.12 520 File or Directory Not Found ...........................26 7.5.13 521 File or Directory Exists ..............................26 7.5.14 522 Checksum Mismatch .....................................26 7.6 600 Class Messages ............................................26 7.6.1 600 User Specification ....................................26 7.6.2 601 Group Specification ...................................26 7.6.3 602 Privileges Specification ..............................27 7.6.4 610 User Listing ..........................................27 7.6.5 611 User Listing Done .....................................27 7.6.6 620 Group Listing .........................................27 7.6.7 621 Group Listing Done ....................................27 8 References .....................................................28 9 Author's Address ...............................................28 10 Full Copyright Statement .......................................28 1 Introduction 1.1 Purpose The Wired protocol is an application-level protocol for file transfers and user interaction. It is intended to fill a gap among Internet class protocols that either provide transfer services or chat services, usually mutually exclusively. Wired joins these two types together to provide a complete user experience. 1.2 Terminology client A program that establishes connections for the purpose of sending commands and interpreting messages. command A command sent from a client to a server, as defined in section 6. identifier A unique 3-digit number that describes the type of message. field A part of a command or a message that conveys a particular pre-defined type of information. message A message sent from a server to a client, as defined in section 7. server A program that accepts connections in order to service commands by sending back messages. 1.3 Overall Operation The Wired protocol is a textual command/message protocol. A client sends a command in a specific format to the server, and the server interprets this command, and if needed, sends back a message with requested information. Some messages are sent asynchronously, meaning they are sent without having first received a command. These messages can be sent at any given time, and a client should be prepared to handle these as they come. A single connection ("control connection") is used to send these commands and messages back and forth. A separate connection is used for transfers, in order to maintain the control connection while a transfer is running. Wired communication takes place over a TCP/IP connection using TLS [1]. The default port is TCP 2000, but other ports can be used. The transfer port is the default port incremented by one, or 2001 by default. 1.4 Access Authentication Wired requires all clients to provide authentication in order to log in to a server. This authentication consists of a login name and an optional password. Servers wishing to provide anonymous logins should provide a "guest" user with no password. Clients should use this login pair as the default. Passwords are SHA-1 [2] checksums of the actual passwords. No cleartext should be sent over the connection. See section 5 for more information on accounts. 2 Protocol Parameters 2.1 Identification Numbers The protocol uses identification numbers for a number of object types. These are unsigned integers. ID = 1*DIGIT An identification number is assigned to each connected user, starting with 1 and incremented for each new user. In certain situations, the server software itself may participate in communications. When thus, the server assumes the user id 0. An id number is also assigned to each new chat created. Unlike user ids however, these should be assigned randomly from the integer range used. The server should also take care to verify that each client communicating with a certain chat, is actually present on that chat, to prevent unauthorized eavesdropping. The public chat is the chat available to everyone and the chat that is automatically joined upon logging in. The public chat is assigned the chat id 1. 2.2 Control Characters The following control characters from the US-ASCII [7] table are used: EOT = FS = GS = RS = SP = 2.3 Strings All string contents are sent in Unicode [3], UTF-8 encoding [4]. There is no way to select a character set. Clients must be UTF-8 aware if they wish to participate in communications: STRING = 2.4 Booleans When a value can be considered as an on/off switch, a boolean value is used: BOOLEAN = "0" | "1" 2.5 Version Strings Version strings are used to convey the version of either the protocol or the applications involved. The protocol version string uses a fixed format: protocol-version = 1*DIGIT "." 1*DIGIT The application version string has a different format: app-version = name "/" 1*DIGIT "." 1*DIGIT ["." 1*DIGIT] SP "(" os ")" [ SP "(" lib-version [";" SP lib-version] ")" ] name = STRING os = os-release ";" SP os-version ";" SP arch os-release = STRING os-version = STRING arch = STRING lib-version = STRING That is, the application version must always be followed by the operating system version, and optionally, by the versions of additional software used. For example: Wired/1.0 (Darwin; 7.2.0; powerpc) (OpenSSL 0.9.7b 10 Apr 2003) Note that there is no particular format defined for the operation system version strings. 2.6 Addresses IP addresses are sent in textual representation, in the formats described in RFC 790 [8] and RFC 1884 [9]: IP = STRING 2.7 Date & Time Format Date are sent in the ISO 8601 [5] full "date-time" format, as per RFC 3339 [6]: date-fullyear = 4DIGIT date-month = 2DIGIT ; 01-12 date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 time-hour = 2DIGIT ; 00-23 time-minute = 2DIGIT ; 00-59 time-second = 2DIGIT ; 00-58, 00-59, 00-60 time-secfrac = "." 1*DIGIT time-numoffset = ("+" / "-") time-hour ":" time-minute time-offset = "Z" / time-numoffset partial-time = time-hour ":" time-minute ":" time-second [time-secfrac] full-date = date-fullyear "-" date-month "-" date-mday full-time = partial-time time-offset date-time = full-date "T" full-time An example of such a date is: 1996-12-19T16:39:57-08:00 This represents 39 minutes and 57 seconds after the 16th hour of December 19th, 1996 with an offset of -08:00 from UTC. 2.8 Privilege Specifications Privilege specifications are sent in the following format: privileges = get-user-info FS broadcast FS post-news FS clear-news FS download FS upload FS upload-anywhere FS create-folders FS move-files FS delete-files FS view-dropboxes FS create-accounts FS edit-accounts FS delete-accounts FS elevate-privileges FS kick-users FS ban-users FS cannot-be-kicked FS download-speed FS upload-speed get-user-info = BOOLEAN broadcast = BOOLEAN post-news = BOOLEAN clear-news = BOOLEAN download = BOOLEAN upload = BOOLEAN upload-anywhere = BOOLEAN create-folders = BOOLEAN move-files = BOOLEAN delete-files = BOOLEAN view-dropboxes = BOOLEAN create-accounts = BOOLEAN edit-accounts = BOOLEAN delete-accounts = BOOLEAN elevate-privileges = BOOLEAN kick-users = BOOLEAN ban-users = BOOLEAN cannot-be-kicked = BOOLEAN download-speed = 1*DIGIT upload-speed = 1*DIGIT This is a series of boolean values, indicating whether a user can or cannot perform certain commands. See section 5 for more information on accounts. See section 4 for more information on the file related privileges. 3 Sequences 3.1 Login Sequence The login sequence takes place directly after the client has established a connection with the server. 1. The client initiates the sequence by sending the "HELLO" command. 2. The server responds with the 200 Server Information or 511 Banned message. 3. The client sends the "NICK", "ICON" and "CLIENT" commands to set values before becoming visible to other clients. Of these, "NICK" is required, "CLIENT" is optional but highly recommended, and "ICON" is optional. 4. The clients sends the "USER" command with the login name. "guest" should be used as the default login name. 5. The client sends the "PASS" command with the checksum of the actual password. If the password is empty, no check-summing should be performed. 6. The server responds with the 201 Login Succeeded or 510 Login Failed messages. 7. The client requests the user list using "WHO", with a value of "1" for the public user list. 8. The server responds with the 310 User List and 311 User List Done messages. 9. Optionally, the client requests the active privileges mask using "PRIVILEGES". 10. The server responds with the 602 Privileges message. 11. Optionally, the client requests the news using "NEWS". 12. The server responds with the 320 News and 321 News Done messages. 3.2 Private Chat Sequence The private chat sequence takes place when a user requests a private chat audience with another user. 1. Client A initiates the sequence by sending the "PRIVCHAT" command. 2. The server creates a private chat and responds with the 330 Private Chat Created message. Client A is added to the private chat. 3. Client A invites client B to the private chat by sending the "INVITE" message, with the chat id of the new chat and the user id of client B. 4. The server sends the 331 Private Chat Invitation message to client B, with the chat id of the new chat and the user id of client A. 5. Client B sends a "JOIN" or "DECLINE" command with the chat id of the new chat. Following the "JOIN" command, client B sends a "WHO" command, requesting the user list of the private chat. 6. In case of "JOIN", the server adds client B to the new chat and sends out 302 Client Join messages to the user list of the private chat. The server also replies to "WHO" and sends the user list of the private chat to client B. Client A and client B can now communicate in a closed private chat. Other clients can be added by sending out new "INVITE" commands. In case of "DECLINE", the server sends out 332 Private Chat Declined messages to the user list of the private chat. 7. When done, client A and client B send the "LEAVE" command to leave the private chat. 8. The server sends out 303 Client Leave messages to the user list of the private chat. 4 Files 4.1 File Listings The following parameters are sent in file related messages: file-type = 1*DIGIT ; 0-3 The file type is mapped by the server as follows: 0 File 1 Directory 2 Uploads Directory 3 Drop Box Directory Note that for the directory types, the server should send the count of enclosed object as "size" in the listing messages. Uploads directories and drop boxes are special directories that tie in with the permissions listed in section 5. Uploads and drop box directories can be uploaded into by accounts with the "upload" privilege; the "upload-anywhere" privilege is required to upload into a regular directory. Having uploads privileges should also enable "create-folders", but only in the directories where the client can upload. Drop box directories can only be viewed by accounts with the "view-dropboxes" privilege; for others, the directory should appear with an empty listing. Of special consideration is the directory "WIRED", contained within any subdirectory. This directory may contain meta data undefined in this document, and should be removed from file listings. Files contained within the "WIRED" directories can, however, successfully be used in transfers. 4.2 Transfers Because servers should supporting queueing and resuming transfers, these sequences are a bit more complicated than usual. Of note is the so-called Wired checksum. These should be SHA-1 [2] checksums of the first megabyte (1048576 octets) of the file. This is defined to allow check-summing of very large files in real time, and to allow checksums of partially transferred files to match, provided that they exceed 1 MB in size. Sequence, for downloads: 1. The client decides to download a file. If the file has been partially downloaded already, the client should issue a "STAT" command to get the Wired checksum of the file, and compare that to the Wired checksum of the local file. If the match is successful, the "GET" command should be issued with the appropriate offset. 2. The server retains the download request, and may issue 401 Transfer Queued messages until a transfer slot is found. When found, the server issues 400 Transfer Ready, with a unique random textual key string to identify the transfer. 3. The client retains the key received in the 400 messages, connects to the server's transfer port, and sends the "TRANSFER" command with the key to identify which transfer. 4. If the key matches the queued transfer, the server begins sending the file; otherwise, the connection is closed. And, for uploads: 1. The client decides to upload a file, and sends the "PUT" command with the appropriate Wired checksum and file size. 2. The server checks if a partially transferred file exists at the location the client specified. If so, compares the Wired checksum of that file to the one given by the client. If a fully transferred file exists at that path, a 521 File or Directory Exists should be issued. If the transfer is to be accepted, the server may begin sending out 401 Transfer Queued messages until a slot is found. Then, the 400 Transfer Ready is issued, with a unique key. 3. Just as for downloads, the client connects to the transfer port, sends the "TRANSFER" command, and begins sending the file. 5 Accounts There are two principal types of Wired accounts, users and groups. User accounts are the primary authentication mechanism, with login and password pairs, just like most systems. When the client has authenticated, it is assigned a privilege mask by the server, which consists of all the values defined in section in 2.8. A client should retain this mask by sending the "PRIVILEGES" command and save the resulting message. A client should not attempt to perform actions that it knows it cannot complete. The server needs to keep track of the mask, and update it accordingly for logged in clients when, for example, an edit accounts request completes. As mentioned in section 1.4 and elsewhere, the default account "guest" should be provided when server administrators wish to provide an anonymous account. User accounts can be assigned to group accounts. Group accounts are similar to user accounts, but lack the "group" and "password" fields, for obvious reasons. Assigning a user account to a group is just a matter of specifying the group's name for the "group" field. If the "group" field is empty, the user account belongs to no group. When a user account is assigned to a group, the user account's privileges are ignored, and the group account's are used instead. Thus, if user A has no limits on either download or upload rates, but group 1 has limits in place, assigning user A to group 1 will result in all logins for user A to have limits. 6 Commands 6.1 Command Format A command from a client to a server includes a unique command, optionally followed by a single space and arguments. The command is terminated with EOT. command = name [SP argument] EOT name = "BAN" | "BROADCAST" | "CLEARNEWS" | "CLIENT" | "CREATEUSER" | "CREATEGROUP" | "DECLINE" | "DELETE" | "DELETEUSER" | "DELETEGROUP" | "EDITUSER" | "EDITGROUP" | "FOLDER" | "GET" | "GROUPS" | "HELLO" | "ICON" | "INFO" | "INVITE" | "JOIN" | "KICK" | "LEAVE" | "LIST" | "ME" | "MOVE" | "MSG" | "NEWS" | "NICK" | "PASS" | "PING" "POST" | "PRIVCHAT" | "PRIVILEGES" | "PUT" | "READUSER" | "READGROUP" | "SAY" | "SEARCH" | "STAT" | "TRANSFER" | "USER" | "USERS" | "WHO" 6.2 Command Listing 6.2.1 BAN "BAN" SP user FS message EOT user = ID message = STRING Ban the client "user" with the message "message". Performs the same action as "KICK", but also installs a temporary ban on "user". The duration of the time is user-defined. Subject to the privilege "ban-users". 6.2.2 BROADCAST "BROADCAST" SP message EOT message = STRING Send the broadcast message "message" to all connected users. Subject to the privilege "broadcast". 6.2.3 CLEARNEWS "CLEARNEWS" EOT Empty the news. Subject to the privilege "clear-news". 6.2.4 CLIENT "CLIENT" SP app-version EOT See section 2.5 for a specification of "app-version". Send the client version information. See section 3.1 for more information on the login sequence. 6.2.5 CREATEUSER "CREATEUSER" SP name FS password FS group FS privileges EOT name = STRING password = STRING group = STRING Create the user account "name", as a member of "group", which can be empty. See section 2.8 for a specification of "privileges". Subject to the privilege "create-accounts". 6.2.6 CREATEGROUP "CREATEGROUP" SP name FS privileges EOT name = STRING Create the group account "name". See section 2.8 for a specification of "privileges". Subject to the privilege "create-accounts". 6.2.7 DECLINE "DECLINE" SP chat EOT chat = ID Decline a chat invitation to "chat". 6.2.8 DELETE "DELETE" SP path EOT path = STRING Delete the file or folder at "path". All deletes are recursive. Subject to the privilege "delete-files". 6.2.9 DELETEUSER "DELETEUSER" SP name EOT name = STRING Delete the user account "name". Subject to the privilege "delete-accounts". 6.2.10 DELETEGROUP "DELETEGROUP" SP name EOT name = STRING Delete the group account "name". Subject to the privilege "delete-accounts". 6.2.11 EDITUSER "EDITUSER" SP name FS password FS group FS privileges EOT name = STRING password = STRING Modify the user account "name", setting new values or privileges. A user account cannot be renamed, so "name" must already exist. The group membership can be changed by editing "group", which can be empty. See section 2.8 for a specification of "privileges". Subject to the privilege "edit-accounts". 6.2.12 EDITGROUP "EDITGROUP" SP name FS privileges EOT name = STRING Modify the group account "name", setting new privileges. A group account cannot be renamed, so "name" must already exist. See section 2.8 for a specification of "privileges". Subject to the privilege "edit-accounts". 6.2.13 FOLDER "FOLDER" SP path EOT path = STRING Create a new folder at "path". Subject to the privilege "create-folders". 6.2.14 GET "GET" SP path FS offset EOT path = STRING offset = 1*DIGIT Request a download of the file or folder "path", starting from byte offset "offset". See section 4 for more details on transfers. Subject to the privilege "download". 6.2.15 GROUPS "GROUPS" EOT Get a listing of all the group accounts on the server. Subject to the privilege "edit-accounts". 6.2.16 HELLO "HELLO" EOT Start a conversation with a server. See section 3.1 for more information on the login sequence. 6.2.17 ICON Format: "ICON" SP icon EOT icon = 1*DIGIT Change the icon to "icon". 6.2.18 INFO "INFO" SP user EOT user = ID Request client information for "user". Subject to the privilege "get-user-info". 6.2.19 INVITE "INVITE" SP user FS chat EOT user = ID chat = ID Invite the client "user" to the chat "chat". See section 3.2 for more information on private chat sequences. 6.2.20 JOIN "JOIN" SP chat EOT chat = ID Join the chat "chat". See section 3.2 for more information on private chat sequences. 6.2.21 KICK "KICK" SP user FS message EOT user = ID message = STRING Kick the client "user" with the message "message". Subject to the privilege "kick-users". 6.2.22 LEAVE "LEAVE" SP chat EOT chat = ID Leave the chat "chat". See section 3.2 for more information on private chat sequences. 6.2.23 LIST "LIST" SP path EOT path = STRING List the file contents at "path". 6.2.24 ME "ME" SP chat FS message EOT chat = ID message = STRING Send the action chat "message" to "chat". 6.2.25 MOVE "MOVE" SP from FS to EOT from = STRING to = STRING Move the file or folder at "from" to "to". Subject to the privilege "move-files". 6.2.26 MSG Format: "MSG" SP user FS message EOT user = ID message = STRING Send the private message "message" to the user "user". 6.2.27 NEWS "NEWS" EOT Request the news. 6.2.28 NICK "NICK" SP nick EOT nick = STRING Change nick to "nick". 6.2.29 PASS "PASS" SP password EOT password = STRING Send password. See section 3.1 for more information on the login sequence. 6.2.30 PING "PING" EOT Ping the server and let it return a 202 message. Should not affect the idle time. 6.2.31 POST "POST" SP message EOT message = STRING Post "message" to the news. Subject to the privilege "post-news". 6.2.32 PRIVCHAT "PRIVCHAT" EOT Create a new chat on the server. 6.2.33 PRIVILEGES "PRIVILEGES" EOT Request the current privilege mask. See section 3.1 for more information on the login sequence. 6.2.34 PUT "PUT" SP path FS size FS checksum EOT path = STRING size = 1*DIGIT checksum = STRING Request an upload of the file to be located at the remote path "path", with size "size" and the checksum "checksum". See section 4 for more details on transfers. Subject to the privilege "upload". 6.2.35 READUSER "READUSER" SP name EOT name = STRING Get the account specification for the user "name". Subject to the privilege "edit-accounts". 6.2.36 READGROUP "READGROUP" SP name EOT name = STRING Get the account specification for the group "name". Subject to the privilege "edit-accounts". 6.2.37 SAY "SAY" SP chat FS message EOT chat = ID message = STRING Send the chat "message" to "chat". 6.2.38 SEARCH "SEARCH" SP query EOT query = STRING Search the files for filenames containing "query". 6.2.39 STAT "STAT" SP path EOT Get the file information for the file or folder "path". 6.2.40 TRANSFER "TRANSFER" SP hash EOT hash = STRING Identify the transfer requested. See section 4 for more information on files. 6.2.41 USER "USER" SP login EOT login = STRING Send login name. See section 3.1 for more information on the login sequence. 6.2.42 USERS "USERS" EOT Get a listing of all the user accounts on the server. Subject to the privilege "edit-accounts". 6.2.43 WHO "WHO" SP chat EOT chat = ID Get the user list for "chat". 7 Server Messages 7.1 Message Format A message from a server to a client includes a unique three-digit number, followed by a space, then optional fields, and a terminator. message = identifier [SP argument] EOT identifier = "200" | "201" | "202" "300" | "301" | "302" | "303" | "304" | "305" | "306" | "307" | "308" | "309" | "310" | "311" | "320" | "321" | "322" | "330" | "331" | "332" | "400" | "401" | "402" | "410" | "411" | "420" | "421" | "500" | "501" | "502" | "503" | "510" | "511" "512" | "513" | "514" | "515" | "516" | "520" | "521" | "522" "600" | "601" | "610" | "611" | "620" | "621" The first digit of the identifier defines the class of response. The last two digits do not have any categorization role. There are five values for the first digit: 2xx Information 3xx Chat, news, messaging 4xx Files, transfers 5xx Errors 6xx Administrative 7.2 200 Class Messages 7.2.1 200 Server Information "200" SP app-version FS protocol-version FS server-name FS server-description FS start-time server-name = STRING server-description = STRING start-time = date-time Basic information about the server. See section 2.5 for a specification of "app-version" and "protocol-version". In response to "HELLO". 7.2.2 201 Login Succeeded "201" SP user EOT user = ID Login succeeded, client was assigned user id "user". In response to "PASS". 7.2.3 202 Ping Reply "202" SP "Pong" EOT In response to "PING". 7.3 300 Class Messages 7.3.1 300 Chat "300" SP chat FS user FS message EOT chat = ID user = ID message = STRING Standard chat message from "user" on "chat". The chat message is contained within "message ". user ":" SP message 7.3.2 301 Action Chat "301" SP chat FS user FS message EOT chat = ID user = ID message = STRING Action chat message from "user" on "chat". The chat message is contained within "message". Typical output format: "***" SP user SP message 7.3.3 302 Client Join "302" SP chat FS user FS idle FS admin FS icon FS nick FS login FS ip FS host EOT chat = ID user = ID idle = BOOLEAN admin = BOOLEAN icon = 1*DIGIT nick = STRING login = STRING ip = IP host = STRING The client "user" joined "chat". If "chat" is the public chat, the client has joined the server. The rest of the fields are basic information on the client. 7.3.4 303 Client Leave 303 SP chat FS user EOT chat = ID user = ID The client "user" left "chat". If "chat" is the public chat, the client has left the server. 7.3.5 304 Status Change "304" SP user FS idle FS admin FS icon FS nick EOT user = ID idle = BOOLEAN admin = BOOLEAN icon = 1*DIGIT nick = STRING The client "user" changed status. Any number of the given fields have changed. 7.3.6 305 Private Message "305" SP user FS message EOT user = ID message = STRING The client "user" sent the receiver a private message. The actual message is contained within "message". 7.3.7 306 Client Kicked "306" SP victim FS killer FS message EOT victim = ID killer = ID message = STRING The client "victim" was kicked by "killer", who commented with "message". 7.3.8 307 Client Banned "307" SP victim FS killer FS message EOT victim = ID killer = ID message = STRING The client "victim" was banned by "killer", who commented with "message". 7.3.9 308 Client Information "308" SP user FS idle FS admin FS icon FS nick FS login FS ip FS host FS client-version FS cipher-name FS cipher-bits FS login-time FS idle-time FS downloads FS uploads EOT user = ID idle = BOOLEAN admin = BOOLEAN icon = 1*DIGIT nick = STRING login = STRING ip = IP host = STRING client-version = [application-version] cipher-name = [STRING] cipher-bits = 1*DIGIT login-time = date-time idle-time = date-time downloads = *(transfer [GS]) uploads = *(transfer [GS]) transfer = path RS transferred RS size RS speed path = STRING transferred = 1*DIGIT size = 1*DIGIT speed = 1*DIGIT Extended client information for "user". "cipher-name" and "cipher-bits" describe the name of the encryption cipher the client connected using, and the strength in bits of said cipher. These fields may be empty or zero, respectively. "login-time" and "idle-time" respectively describe when the client joined the server, and when the client was last active. "downloads" and "uploads" are optional fields that contain any number of "transfer", inter-spaced with RS. These fields may be empty. In response to "INFO". 7.3.10 309 Broadcast Message "309" SP user FS message EOT user = ID message = STRING A server-wide broadcast message received from "user". The actual message is contained within "message". 7.3.11 310 User List "310" SP chat FS user FS idle FS admin FS icon FS nick FS login FS ip FS host EOT chat = ID user = ID idle = BOOLEAN admin = BOOLEAN icon = 1*DIGIT nick = STRING login = STRING ip = IP host = STRING A client in the user list. Same message format as 302. The user list comes sorted by the time each client joined, descending. In response to "WHO". 7.3.12 311 User List Done "311" SP chat EOT chat = ID End of user list for "chat". In response to "WHO". 7.3.13 320 News "320" SP nick FS post-time FS post EOT nick = STRING post-time = date-time post = STRING A news post, by "nick", posted at "post-time". The actual post is contained within "post". The news comes sorted by the time it was posted, ascending. In response to "NEWS". 7.3.14 321 News Done "321" SP "Done" EOT End of news transfer. In response to "NEWS". 7.3.15 322 News Posted "322" SP nick FS post-time FS post EOT nick = STRING post-time = date-time post = STRING A new news post. Same message format as 320. 7.3.16 330 Private Chat Created "330" SP chat EOT chat = ID A new private chat has been created on the server, and the received has been added to it. See section 3.2 for more information on private chat sequences. In response to "PRIVCHAT". 7.3.17 331 Private Chat Invitiation "331" SP chat FS user EOT chat = ID user = ID The client "user" has invited the received to the private chat "chat". See section 3.2 for more information on private chat sequences. 7.3.18 332 Private Chat Declined "332" SP chat FS user EOT chat = ID user = ID The client "user" declined the invitation to the chat "chat". See section 3.2 for more information on private chat sequences. 7.4 400 Class Messages 7.4.1 400 Transfer Ready "400" SP path FS offset FS hash EOT path = STRING offset = 1*DIGIT hash = STRING The transfer of "path" is ready to begin. "hash" is a unique identifier for this particular transfer. See section 4 for more information on files. In response to "GET" and "PUT". 7.4.2 401 Transfer Queued "401" SP path FS position EOT path = STRING position = 1*DIGIT The transfer of "path" has been queued in line at "position". If "position" is greater than 1, additional 401 messages will be sent until the position reaches 0, at which point a 400 message will be sent. See section 4 for more information on files. In response to "GET" and "PUT". 7.4.3 402 File Information "402" SP path FS type FS size FS created FS modified FS checksum EOT path = STRING type = file-type size = 1*DIGIT created = date-time modified = date-time checksum = STRING Extended file information for "path". See section 4 for more information on files. In response to "STAT". 7.4.4 410 File Listing "410" SP path FS type FS size EOT path = STRING type = file-type size = 1*DIGIT A file in the file listing. The file listing comes sorted by filename, descending. See section 4 for more information on files. In response to "LIST". 7.4.5 411 File Listing Done "411" SP path FS free EOT path = STRING free = 1*DIGIT End of file listing for "path". "free" contains the number of octets available in the file system that "path" resides on. This number should only be sent for paths where the receiver has uploads privileges, otherwise a value of zero should be sent. It is up to the client to determine whether this zero means a full file system or a lack of privileges. In response to "LIST". 7.4.6 420 Search Listing "420" SP path FS type FS size EOT path = STRING type = file-type size = 1*DIGIT A file in the search listing. Same message format as 410. The sorting of the search listing is undefined. See section 4 for more information on files. In response to "SEARCH". 7.4.7 421 Search Listing Done "421" SP "Done" EOT End of search listing. In response to "SEARCH". 7.5 500 Class Messages 7.5.1 500 Command Failed "500" SP "Command Failed" EOT An undefined internal error prevented the command from completing. 7.5.2 501 Command Not Recognized "501" SP "Command Not Recognized" EOT The command was not recognized. 7.5.3 502 Command Not Implemented "502" SP "Command Not Implemented" EOT The command has not been implemented by the server. 7.5.4 503 Syntax Error "503" SP "Syntax Error" EOT There was a syntax error in the command. 7.5.5 510 Login Failed "510" SP "Login Failed" EOT The login could not complete, the login and/or password provided did not match a valid entry. 7.5.6 511 Banned "511" SP "Banned" EOT The login could not complete, the user is banned. 7.5.7 512 Client Not Found "512" SP "Client Not Found" EOT The server could not find the client referred to. 7.5.8 513 Account Not Found "513" SP "Account Not Found" EOT The server could not find the account referred to. 7.5.9 514 Account Exists "514" SP "Account Exists" EOT The account referred to already exists. 7.5.10 515 Cannot Be Disconnected "515" SP "Cannot Be Disconnected" EOT The user attempted to kick or ban another user that has the privilege "cannot-be-disconnected". 7.5.11 516 Permission Denied "516" SP "Permission Denied" EOT The command could not complete, the client lacks sufficient privileges. 7.5.12 520 File or Directory Not Found "520" SP "File or Directory Not Found" EOT The file or directory referred to could not be found. 7.5.13 521 File or Directory Exists "521" SP "File or Directory Exists" EOT There already exists a file or directory at the path referred to. 7.5.14 522 Checksum Mismatch "522" SP "Checksum Mismatch" EOT The two checksums do not match. 7.6 600 Class Messages 7.6.1 600 User Specification "600" SP name FS password FS group FS privileges EOT name = STRING group = STRING password = STRING A specification of a user account. See section 2.8 for a specification of "privileges". See section 5 for more information on accounts. In response to "READUSER". 7.6.2 601 Group Specification "601" SP name FS privileges EOT name = STRING A specification of a group account. See section 2.8 for a specification of "privileges". See section 5 for more information on accounts. In response to "READGROUP". 7.6.3 602 Privileges Specification "602" SP privileges EOT The privileges mask for the receiver. See section 2.8 for a specification of "privileges". See section 5 for more information on accounts. In response to "PRIVILEGES". 7.6.4 610 User Listing "610" SP name EOT name = STRING A user account in the user accounts listing. The sorting of the user accounts listing is undefined. See section 5 for more information on accounts. In response to "USERS". 7.6.5 611 User Listing Done "611" SP "Done" EOT End of user listing. In response to "USERS". 7.6.6 620 Group Listing "620" SP name EOT name = STRING A group account in the group accounts listing. The sorting of the group accounts listing is undefined. See section 5 for more information on accounts. In response to "GROUPS". 7.6.7 621 Group Listing Done "621" SP "Done" EOT End of group listing. In response to "GROUPS". 8 References [1] Dierks, D. and Allen, C., "The TLS Protocol Version 1.0", RFC 2246, January 1999. [2] Eastlake, D., "US Secure Hash Algorithm 1 (SHA1)", RFC 3174, September 2001. [3] "Information Technology - Universal Multiple- Octet Coded Character Set (UCS) - Part 1: Architecture and Basic Multilingual Plane", ISO/IEC 10646-1:1993. [4] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC 2279, January 1998. [5] "Data elements and interchange formats - Information interchange - Representation of dates and times", ISO 8601:1988(E), International Organization for Standardization, June, 1988. [6] Newman, C., "Date and Time on the Internet: Timestamps", RFC 3339, July 2002. [7] "Coded Character Set - 7-Bit American Standard Code for Information Interchange", Standard ANSI X3.4-1986, ANSI, 1986. [8] Postel, J., "Assigned Numbers", RFC 790, September 1981. [9] Hinden, R. and Deering, S., "IP Version 6 Addressing Architecture", RFC 1884, December 1995. 9 Author's Address Axel Andersson, axel@zankasoftware.com 10 Full Copyright Statement Copyright (C) Axel Andersson 2003-2004. All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice, this paragraph and the following disclaimer are included on all such copies and derivative works. THIS DOCUMENT AND THE INFORMATION CONTAINED HEREIN IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.