History: The Simple Blinkenlights Transfer Protokoll (SBTP) Version 0.8 (25. June 2003) The Simple Blinkenlights Transfer Protokoll (SBTP) Version 0.5 (18. Sept. 2002) (This is NOT an internet-standard - unless you install it everywhere you can...) Overview: ========= The SBTP is a simple internet protokoll based loosely on POP3 that will let you (in a simple way) build up a central repository for Blinkenlights- and Arcadefiles. For a better understanding see the file sample.log for a sample session. In further development stages this will also let you convert Blinkenlight- Movies (.blm) into xml-based Arcade-files (.bar) Overall Basics: =============== This test-implementation does not include user-authentification. But to be compatible with future versions you MUST send a USER and PASS command with both USER and PASS set to "anonymous". The server MAY use per-user rights (e.g. only the user who has uploaded a file may delete it). See command-specification below. The server-response always begins with a "+" or "-" to show if the command did or did not work. Further information *must* be supplied to simplify debugging and direct communication User<->Server! All the commands *MUST NOT* be interpreted case-sensitiv, but the command-arguments *MUST* be case-sensitiv! Further, file transmission (as specified below) consists of multiple (single) lines, always terminated by a CR. CRLF *may* be supported but you *should* always use unix-conform line termination! Warning, lines longer then 160 chars (including the termination character) *must* be rejected by the server. TABS (\t) should be converted or rejected as following: 1.) Tabs in commands are not allowed. 2.) Tabs in Movies are to be converted into 4 (four) whitespaces ! Percent-Signs (%) in Strings should not be allowed for security-reasons ! (possible exploits in printf's) and should be converted into spaces. Multi-Line-Transfer begins with a positive feedback answer (e.g. "+OK sending now"), followed by the actual data, ended with a line containing a single "."+CR Due to this design (and the file-transfer is plaintext) the file itself is not allowed to have s line containing a single "." But as this is in the specification of the file-formats itself this is not a bug - it's a feature :-) The protocoll itself uses two modes: authentification mode and file-transfer mode. THE MAXIMUM LENGTH OF A FILENAME IS 30 CHARACTERS! (Note: If the servers supports uploading it *must* check the uploaded files for their correctnes!) Authentification mode (Basics): =============================== First of all, the server send a positive response and a multi-line information about itself. This information *MUST NOT* be parsed, but *should be* displayed to the user. Then the user has to state a helo-command with an optional message which is to be ignored. The server answeres with with a list of possible commands and fileformats. Then, after getting a full authentification (using USER and PASS) the server checks the authentification data and gives a positive or negative response. On negative response the server closes the connection else it enters file-transfer mode. Authentification mode (Commands): ================================= Command: HELO *MUST* -------------------------- Possible Responses: +{Optional Text} -{Optional Text} The HELO may be given only at the begining of the authentification process. Using it twice will result in a negative response and closing of the connection (in this case, it's a single-line response). Followed by a multi-line response giving the possible commands and file-formats like this, every option in one line preceeded by the type. Servers may decide to show a Motto or Ascii-Logo in one or more lines preceeded by LOGO Examples: -> Command: (COMD) COMD LIST -> Filetype: (FILE) FILE BLM -> Anonymous Login (LGIN) LGIN ANON Note: ALL supported commands have to be listed. Also note specific information in the commands-specification that available commands may give in the LGIN-response. Lines that are not understood by clients can be safely ignored. But the client MUST check the availability of features it plans to use! Command: USER *MUST* -------------------------- Possible Responses: +{Optional Text} -{Optional Text} The User *must* be accepted except when USER-Command is already given. This is for security reasons so it is harder to guess a valid username. Example: USER 12345 Command: PASS *MUST* -------------------------- Possible Responses: +{Optional Text} -{Optional Text} A negative response may be given if authentification fails or the USER-command is not given yet. If the error was a missing USER-command the servers waits for it. If there was an authentification error the server quits the connection. A positive respone means the the server has entered file-transfer mode. Command: QUIT *MUST* -------------------------- Possible Responses: +{Optional Text} The Server *must* accept the QUIT-Command in *every* stage in authentification mode, *must* send a positive response and *must* close the connection. Command: HELP *OPTIONAL* -------------------------- Possible Responses: +{Optional Text} -{Optional Text} The HELP-command is optional. If implemented, this is a multi-line response. WARNING: The HELP command must either be ommited completly or implemented in BOTH modes! File-transfer mode: =================== Command: LIST *MUST* -------------------------- Possible responses: +{Optional Text} This is a multiline-response. Each file is listed in a single line. Even if there is no available file the server gives a positive response but send no filename but immediatly end the multi-line transfer in the proper way. Note: the LIST command *MUST NOT* list any Loveletter-files. Command: RETR *MUST* -------------------------- Possible Responses: +{Optional Text} -{Optional Text} If there is an error (negative response) this is a single-line response, otherwise it is a multi-line one. The file is send as plaintext and terminated the usual way. Command: SEND *OPTIONAL* -------------------------- Possible Responses: +{Optional Text} -{Negative Text} If the server allows uploading it will response positive and will await file transfer. A negative response must be given if the server denies uploading (for this user or generally doesn't support it but likes to be compatible with the FULL protocoll) or if the file exists. Overwriting existing files are only allowed if the file-attribute "W" (see INFO) is set. Uploading *must* use the multi-line type described in RETR. After the client ends multi-line transfer with "." + CR the server *SHOULD* check the file-integrity and *MUST* issue another response to show if the file is accepted. Command: DELE *OPTIONAL* -------------------------- Possible Responses: +{Optional Text} -{Negative Text} If deleting files is allowed for this user AND the file exists the file AND the (optional) user-rights of this file are correct the file *MUST* be deleted and the client given a positive response. Every other case produces a negative one. Command: INFO *OPTIONAL* -------------------------- Possible Responses: +{Optional Text} -{Negative Text} Command usually uses the same rights as the RETR-Command This command (if successful) gives the header of the file # Headerline1 # Headerline2 # ... # Headerline(X) Command: HELP *OPTIONAL* -------------------------- Possible Responses: +{Optional Text} -{Optional Text} The HELP-command is optional. If implemented, this is a multi-line response. WARNING: The HELP command must either be ommited completly or implemented in BOTH modes! Command: QUIT *MUST* -------------------------- Possible Responses: +{Optional Text} The Server *must* accept the QUIT-Command in *every* stage in file-transfer mode, *must* send a positive response and *must* close the connection. Command: LOVE *OPTIONAL* -------------------------- Possible Responses: +{Optional Text} -{Negative Text} Yes, this protocoll also works with the famous blinkenlights-Loveletters! Similar to the SEND-Command, but the the files are stored hidden under a unique ID and can only be accessed through the PLAY command with that ID. The LOVE command *MUST NOT* accept a filename, instead the file should be stored under its unique ID, and should only avaiable to the PLAY command and/or any hard- or softwareplayer on this server destined for playing loveletters. The response after the file transfer is either a single-line negative response or a positive multi-line response. If the file is accepted, the first line of the response *MUST* be a STORED following an alphanumerical ID without blanks. An ID that could not easely be guessed is *VERY RECOMMENDED* (like md5sum of the file). If you plan giving access to loveletters through cell-phone the server should issue a 5- to 9 digits pseudo-random number that *MUST* be unique! The server may send more lines containing additional site-specific information, that the client *SHOULD NOT* parse but directly display to the user. The client *SHOULD* parse the first line, but *ONLY* if both server AND client understand the PLAY command! See the file PROTOKOLL_SAMPLE_LOG for an example. Command: PLAY *OPTIONAL* -------------------------- Possible Responses: +{Optional Text} -{Negative Text} If this command is implemented, the LOVE command *MUST* be implemented as well. The purpose of this command is to tell the server to play a loveletter on external hard- or software if available. The PLAY command is used with the ID given by the LOVE-command.