Text 347, 703 rader
Skriven 2005-05-30 21:40:27 av Michiel Broek (2:280/2802)
Ärende: FSP-1018 rev 2 part 1
=============================
**********************************************************************
FTSC FIDONET TECHNICAL STANDARDS COMMITTEE
**********************************************************************
Publication: FSP-1018
Revision: 2
Title: Binkp/1.0 Protocol specification
Authors: Michiel Broek
Stas Degteff
Issue Date: xx Jan 2004
Review Date: xx Jan 2006
----------------------------------------------------------------------
Contents:
1. Background
1. Motivation for a new protocol
2. Definitions
3. Protocol Overview
4. Frame Format
1. Notation
2. Examples
5. Protocol Commands and Their Arguments
1. Classification
2. Escaping method for illegal characters in Command Argument
3. Non-ASCII Characters in Command Argument Symbol String
4. File Name Issues
5. Binkp Commands
6. Example of Frame Exchange in a Simple binkp Session
6. Protocol States
1. Session Setup Stage
1. Originating Side
2. Answering Side
2. File Transfer Stage
3. Session Termination
7. Protocol Identification String
8. Protocol Extensions
1. Recommended Protocol Extensions.
9. Binkp license
10. Glossary
11. References
A. History
----------------------------------------------------------------------
Status of this document
-----------------------
This document is a Fidonet Standard Proposal (FSP), issued by the
FTSC for the benefit of the Fidonet community.
This document specifies an optional Fidonet standard protocol for
the Fidonet community, and requests discussion and suggestions for
improvements.
This document is based on the FSP-1011 proposal by Dima Maloff
(maloff@corbina.net), Maxim Masiutin (max@ritlabs.com) and
Nick Soveiko (nsoveiko@doe.carleton.ca).
This document is released to the public domain, and may be used,
copied or modified for any purpose whatever.
Abstract
--------
This specification defines binkp/1.0 - a protocol to handle a
session between two Fidonet Technology systems over a reliable
connection.
Assumption that the connection is reliable makes possible to
eliminate error-checking and unnecessary synchronization steps,
achieving both ease of implementation and major performance
improvement over connections with large unpredictable delays (e.g.
Internet using TCP).
Etymology of term "binkp" is: "binkd protocol". This protocol
was originally developed for the TCP-FTN mailer binkd by Dima
Maloff.
New implementations are advised to implement binkp/1.1 described
in another document. Mailers using a later protocol version MUST
always be backwards compatible with this binkp/1.0 protocol, and
thus be able to fallback to this binkp/1.0 protocol if needed.
1. Background
-------------
1.1 Motivation for a new protocol
---------------------------------
Existing Fidonet Technical Standards and Fidonet Reference Library
documents [FTS-0001], [FTS-0006], [EMSI] specify both session
handshake procedures and transmission capabilities that imply:
* non-reliable communication channel between mailers
* low round-trip times in the communication channel between
mailers.
This was commonplace a few years ago, when Fidonet systems were not
using transport other than direct dial-up on a visible basis.
Things have changed today, when other communication media becomes
widely available on a day-to-day basis. This communication media
typically provides implementation of Physical, Data Link, Network
and Transport layers of the ISO/OSI Reference Model and facilitates
relieving Session layer of inappropriate functions, such as error
control, flow control, call management and data transparency
[Halsall95]. Examples of such communication media are TCP/IP socket
connection X25 connection and HDLC family protocol connection.
New communication media can be generally characterized by the
reliable transmission service offered by it to the Session layer
protocol. Reliable transmission implies that:
* Data link and/or Transport layer protocols are responsible for
error control and delivery of frames in correct sequence
* Session layer and higher layer protocols are operating on top
of connection-oriented mode
* Quality of Service provisions (if any) result in unspecified
delays between transmitter and receiver
* connections are rarely aborted.
Combination of these factors imposed the following requirements for
the new Fidonet protocol:
* error control can be eliminated throughout the session layer
protocol for both handshake and default file transfer method
* session setup procedure should minimize number of
synchronization points for fast handshake
* protocol should be insensitive to delays and robust with
respect to timeouts
* application flow control should be moved to file level;
individual data frames do not need to be error checked nor
acknowledged
* protocol should be independent from both higher and lower layer
protocols
* protocol should be reasonably easy to implement and allow
future extensions.
2. Definitions
--------------
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
in this document are to be interpreted as described in [FTA-1006].
However, for readability, these words may sometimes not appear in
all uppercase letters in this specification. Although it should not
impact minimal realization of binkp protocol, it must be noted that
Protocol Extensions may override, update or obsolete requirement
levels indicated by the above keywords in chapters from 3 to 6
inclusive.
Calling party in this document is referred to as the Originating
side and called party is referred to as the Answering side.
Originating side here is the party that initiates the connection
between two systems.
Mailer in this document is a software that implements the protocol.
Words "frame", "packet", and "block" when used in this document
refer to binkp's Frames, unless explicitly stated otherwise.
Other definitions that are not local to this document can be found
in the Glossary.
This document is organized as following:
Frames section defines binkp's frames. Binkp commands and their
arguments section provides detailed description of all defined
protocol commands together with recommendations for their usage.
Actual binkp implementation may match it's own diagrams provided
that such implementation remains fully compatible with current
specification. Protocol states section gives rigorous state
diagrams for the minimum realization of binkp. All mailers MUST
support this minimum realization. The License, Glossary and
References sections can be found at the end of this document.
3. Protocol Overview
--------------------
Binkp is a Fidonet session layer protocol intended for use over
data transparent bi-directional channels with reliable
transmission. There are no other requirements for the service
provided by the underlying protocol suite. Presentation and
application layer protocols are not discussed here. Whenever TCP/IP
socket is used, IANA (Internet Assigned Numbers Authority)
registered port number for binkp 24554 SHOULD be used on the
answering side as default. (The sysop may specify another port
number in the nodelist | or by another method of publication if
the default port is unavailable).
Functionality of the minimum protocol realization makes provision
for:
* password protected sessions
* 5D addressing for Fidonet and technology compatible networks
* exchange of netmail packets and arcmail bundles in both
directions, including poll and mail pickup, as well as transfer
of any binary or ASCII files
* ensuring integrity of transmitted mail and files
* simultaneous bi-directional transmission
* maximizing performance over packet switched data networks
Binkp uses only one synchronization point during session startup,
that is password exchange. This feature facilitates fast session
startup for high latency links. Sliding window flow control is
incorporated on the file level. This ensures that a batch of small
files is transmitted with the same efficiency as a one large file.
The binkp 1.0 protocol does not define file requests, however
there are implementations that support Wazoo file requests.
Therefore most systems running a binkp 1.0 implementation should
not carry any request flags in the nodelist.
4. Frame Format
---------------
Binkp is defined in terms of sending and receiving specifically
formatted data blocks. We call them frames.
Command frames carry protocol commands and may change protocol
state. Data frames are usually appended to files being received by
mailers or may be discarded, depending on the protocol state: file
receiving in progress or not.
The particular way of mapping an octet stream or a datagram stream
of the transport layer into binkp frames may depend on the
underlying protocol suite. At this time, we define such mapping for
TCP/IP socket connection which can also be used for similar
transports as well.
The socket stream is being split into binkp frames in the following
manner (big endian systems representation):
7 6543210 76543210
+-+-------+--------+--- ................ ---+
|T| SIZE | DATA |
+-+-------+--------+--- ................ ---+
|<- 2 octets ->|<- up to 32767 octets ->|
(frame header) (frame data)
The first bit (named "T") specifies the frame type:
* 0 indicates a data frame;
* 1 indicates a command frame.
Next 15 bits marked SIZE carry the size of the DATA part of the
frame in octets (with the bit marked 0 being the least
significant). That is, the actual length of a binkp frame is
SIZE+2.
The size of the DATA part MUST vary between 0 and 32767 octets, but
size is 0 (empty frame data) is obsolete and SHOULD NOT be used in
future implementations. Upon receiving of a packet header with the
SIZE field set to 0, the total length of the incoming packet must
be treated as 2, this packet must be silent dropped.
Some old implementations do send empty frames as the last frame.
The first octet of a command frame data is the command ID. The ID
must be between 0 and 127 inclusive.
Other octets carry command arguments. Command arguments are an
arbitrary symbol string that may be null-terminated or not.
Treating of a null character in the middle of a command depends on
realization (with the options being "treat as whitespace" or
"treat as end-of-line"). The terminating null character (if any)
is either stripped or used by mailers internally as an end-of-line
marker.
4.1 Notation
------------
As stated before, command ID is a number between 0 and 127. Every
binkp command defined in this document has a symbolic name in the
form M_XXX. Symbolic names are defined in binkp commands section.
We will use symbolic names and not numeric command IDs to refer to
commands everywhere in this document.
The following notation is used to describe binkp's command frames:
M_XXX "Data string"
The actual numeric command ID for the command with the symbolic
name of M_XXX should be written into the first octet of the DATA
area of a binkp frame. "Data string" is a string to be copied into
DATA area starting at second octet. SIZE should be set to the total
length of "Data string" plus one for the octet to store the command
number. T bit should be set to 1.
4.2 Examples
------------
M_OK "":
7 6543210 76543210 76543210
+-+-------+--------+--------+
|1| 0 1| 4|
+-+-------+--------+--------+
| | +----- command ID (no arguments)
| +-------- frame length
+- command frame flag
M_NUL "TEST":
+-+-------+--------+--------+-------+--------+--------+--------+
|1| 0 5| 0| T E S T |
+-+-------+--------+--------+-------+--------+--------+--------+
5. Protocol Commands and Their Arguments
----------------------------------------
5.1 Classification
------------------
Protocol commands may be classified by protocol stage:
1. Session setup stage: M_ADR (MUST be sent by both sides), M_PWD
(MUST NOT be sent by the Answering side), M_OK (MUST NOT be sent
by the Originating side).
These commands MUST NOT be sent during the file transfer stage.
2. File transfer stage: M_FILE, M_GOT, M_GET, M_SKIP, M_EOB.
These commands MUST NOT be sent during session setup stage.
3. Any stage: M_NUL, M_ERR, M_BSY. These commands MAY be sent any
time during the session.
5.2 Escaping method for illegal characters in Command Argument
--------------------------------------------------------------
In some cases there is a need to send illegal characters in
the command argument (usually the file name). These characters
SHOULD be escaped using form of 4th symbols sequence: "\", "x"
and two hexadecimal digits (digits "a".."f" may be any case).
Examples:
whitespace (" ") excaped as "\x20"; pipe ("|") escaped as "\x7c".
If escaping may be used in some command argument, mailer MUST
allways escape character '\' for prevent uncertainty.
In FSP-1011.003 the escape method is specified as two hexadecimal
digits preceded with a backslash (e.g. a whitespace is
transmitted as "\20"). Some mailers have implemented that method.
It is advised to have a setting for specific nodes to sent escaped
characters using the incorrect method.
Any mailer SHOULD decode "\20" into space in file names for
compatibility purposes.
5.3 Non-ASCII Characters in Command Argument Symbol String
----------------------------------------------------------
Generally, mailer SHOULD use only characters from the ASCII range
[32...126] in the symbol strings for command arguments.
Other characters MAY be used only in M_NUL command argument in
plain form.
Implementation recommendation: use isprint() function (ISO C).
5.4 File Name Issues
--------------------
In binkp commands that contain a file name, the file name MUST NOT
include a whitespace (ASCII value 20 hex). If name of file to send
contents space, it MUST be escaped. The file name SHOULD NOT
include symbols other than alphanumeric (A-Z,a-z,0-9) and safe
characters as defined below in BNF. All other symbols are to be
considered unsafe and SHOULD be escaped. Space and backslash (\)
MUST be escaped.
For example: file name "abcd e.0f@" must be transmitted in form
"abcd\x20e.0f@".
filename= *pchar
pchar = plain | escaped
plain = alpha | digit | safe
safe = "!" | """ | "#" | "$" | "%" | "&" | "'" | "(" | ")" |
"*" | "+" | "," | "-" | "." | "/" | ":" | ";" | "<" |
"=" | ">" | "?" | "@" | "[" | "]" | "^" | "_" | "`" |
"{" | "|" | "}" | "~"
alpha = "A" | "B" | ... | "Z" | "a" | "b" | ... | "z"
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
escaped = "\x" HEX HEX
HEX = digit | "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b" |
"c" | "d" | "e" | "f"
Note: some characters are illegal for file names in some OS such as
DOS or Windows. The protocol do not impose limitations for these
characters in file names and if mailer receives OS incompatible
file name then it's reaction determine on a implementation: mailer
may be destructive skip file, save file with some legal name or
other.
The protocol does not impose limitations on the file name length
other than those arising from the finite length of the binkp frame
itself. Really file name length can't exceed 32751 bytes.
5.5 Binkp Commands
------------------
Format: symbolic_command_name command_ID
M_NUL 0
Command arguments MAY contain human-readable information,
such as nodelist info, sysop name, etc. This frame also can
be used at setup stage to show the other side the supported
protocol extensions. Mailer MAY ignore and/or log arguments
of M_NUL (if presented options not supported).
E.g. "ZYZ Dima Maloff"
The following format of M_NUL argument is recommended for
compatibility purposes:
* M_NUL "OPT protocol options list"
here 'protocol options list' is a space separated list
of binkp options and extensions supported by the
mailer.
this command may be repeated many times for different
options.
* M_NUL "SYS system_name"
* M_NUL "ZYZ sysop's_name"
* M_NUL "LOC system_location"
* M_NUL "NDL system_capabilities"
* M_NUL "TIME date_time"
to inform remote about current time;
date_time format is described in [RFC822].
Example of valid date_time is:
Sun, 06 Nov 1994 08:49:37 GMT
* M_NUL "VER mailer_version protocol_version";
** mailer_version may contents any printable
characters (spaces and other).
** binkp 1.0 mailers MAY send "binkp/1.0" string
for protocol_version. Some old mailers don't send
the M_NUL "VER" frame.
* M_NUL "TRF netmail_bytes arcmail_bytes"
traffic prognosis (in bytes) for the netmail
(netmail_bytes) and arcmail + files (arcmail_bytes),
both are decimal ASCII strings
Another M_NUL arguments used by some mailers:
* M_NUL "PHN string"
phone number, IP address, etc.
* M_NUL "OPM string"
string is a message for the system operator that may
require manual attention
* M_NUL "FREQ"
indicate file request
Any other M_NUL arguments may be used.
M_ADR 1
List of 5D FTN addresses (space separated).
e.g. M_ADR "2:5047/13.1@fidonet 2:5047/0@fidonet"
If the "point" part of address is 0 the string ".0" may be
omitted.
Extension: 4D, 3D and 2D addresses use.
If mailer support 5D addresses and it receive 4D address:
for compatibility purposes mailer MAY append default domain
into received address ("fidonet" or other default domain).
Also 3D address MAY be appended by zero point number and
default domain and 2D address MAY be appended by default
zone number, zero point number and default domain.
However, it is strongly recommended that all
implementations send 5d addresses to avoid ambiguities.
M_PWD 2
Session password, case sensitive. Only Originating side
MUST send this message. After successful password
authentication of the remote, Answering side may proceed
to the file transfer stage. This command MUST never be sent
by the Answering side. If no password is available for the
remote, M_PWD "-" must be sent to indicate that there is no
password.
e.g. M_PWD "pAsSwOrD"
M_OK 4
Acknowledgement for a correct password. Upon receiving of
this command, originating side goes to file transfer stage.
This command MUST NOT be sent by the Originating side.
Arguments may be ignored or logged.
e.g. ""
The following format of M_OK argument is recommended for
compatibility purposes:
* M_OK "non-secure"
report to remote about normal password unprotected
session; usually used for empty password;
* M_OK "secure"
report to remote about normal password protected session
M_FILE 3
Space separated list of parameters for the next file to be
transmitted: filename; size in bytes; unixtime; file
transmission offset.
Synopsis:
M_FILE "<filename> <file_size> <unixtime> <file_offset>"
File_size, unixtime and file_offset are decimal integers.
Implementation note: mailer MUST check received string to
prevent number overflow and skip file if overflow.
In the basic implementation: size, unixtime and offset
MUST be positive numbers or zero.
Until the next M_FILE command is received, all data frames
must carry data from this file in consecutive manner. There
is no end of file identifier as the file size is known
beforehand. If there are "extra" data frames, Mailer MAY
append this data to the file or skip it. If a M_FILE frame
is received before all data of the file is received, the
already received part of the file MUST be saved as
unfinished and a new file receiving process MUST be
started.
By default, transmission of each file SHOULD be started
from offset 0. M_GET command sent by the remote MUST force
the mailer to start transmission from the specified offset.
e.g. M_FILE "config.sys 125 2476327846 0"
or, answering to M_GET with offset 100:
M_FILE "config.sys 125 2476327846 100"
M_EOB 5
End-of-Batch. M_EOB command must be transmitted after all
the files have been sent.
Arguments of the command MUST be ignored in the basic
implementation.
e.g. ""
M_GOT 6
File acknowledgement, that MUST be transmitted upon
receiving of the last data frame for current file.
Synopsis:
M_GOT "<filename> <size> <unixtime>"
Argument values for this command shall be the same as for
the M_FILE sent by remote. (In other words arguments are:
"filename", "size in bytes" and "unixtime" of successfully
received file. These values MUST be decimal integers).
M_GOT can also be transmitted while receiving a file,
in which case transmitting party may interpret it as a
destructive file skip: after receive M_GOT mailer SHOULD
stop sending data of the specified file.
e.g. M_GOT "config.sys 125 2476327846"
M_ERR 7
This command indicates a fatal error. A party sending M_ERR
SHOULD abort the session. Argument SHOULD contain an error
explanation and may be logged by the remote. Mailer sends
M_ERR in response for an incorrect password. Mailer MUST
NOT abort a session without sending a M_ERR or a M_BSY
frame (though state machine tables, for simplicity, may
not include "transmit M_ERR" instructions).
e.g. M_ERR "Incorrect password"
The following list of M_ERR argument is recommended for
compatibility purposes (but other messages are possible):
* "Bad address"
remote mailer passed bad (restricted) address;
* "Incorrect password"
remote side send incorrect password;
* "<command>: cannot parse args"
illegal argument string for binkp command;
Implementation note: after receive M_ERR and session drops
mailer should wait some time before next poll to that link
to prevent continuous poll.
M_BSY 8
M_BSY command is transmitted when the system encounters a
non-fatal error typically due to temporary lack of
resources to proceed with the session. (E.g. incoming
session limit exceed.)
The argument SHOULD contain an explanation of the situation
and may be logged by remote. M_BSY may be sent at any time
during the session (including session setup stage), not
only the stages explicitly indicated in the finite state
machine.
The side, which have sent M_BSY, is in legal position to
abort the session. Mailer MUST be able to accept M_BSY at
any time. Though state machine tables, for simplicity, may
not include handling of M_BSY command, Mailer MUST NOT be
confused by reception of M_BSY command.
E.g. M_BSY "Too many servers"
Implementation note: after receive M_BSY and session drops
mailer should wait some time before next poll to that link
to prevent continuous poll.
Recommended extension:
if a mailer wishes to suggest the remote a time interval
before the next session attempt, it MAY choose to transmit
it in the following format:
M_BSY "RETRY NNNN: <explanation>"
M_BSY "RETRY NNNN"
where NNNN is interval in seconds (decimal string, any
positive number) and <explanation> is an arbitrary string
containing the explanation of the matter (optional).
M_GET 9
M_GET command is a request to (re)send files. MUST be send
only after receive M_FILE command.
Argument is a space separated list of parameters for the
file which we'd like to receive from the remote: filename;
size in bytes; unixtime; file transmission offset. These
arguments are the same as for the M_FILE command.
E.g. M_GET "config.sys 125 2476327846 100"
(complement for M_FILE example)
If previous session is aborted and file receiving isn't
complete mailer MUST send M_GET to continue receiving
this file. Implementation note: if the remote doesn't send
this file before the session is complete, the received
part of the incomplete file should be removed. (Can be
an arcmail bundle that is updated between two sessions).
Mailer reacts to this command as follows: according to the
first three arguments (filename, file size and unixtime),
it determines whether the M_GET argument is the current
file being transmitted to the remote (or a file that have
been transmitted, but we are still waiting an M_GOT
acknowledge for it). If this is the case, it should
* discard transmission of requested file in progress
as soon as possible (don't transmit next data frame);
* perform seek() to the specified offset;
* proceed with transmission of the file requested
starting with an appropriate M_FILE.
For the example above, corresponding M_FILE will have the
following arguments: "config.sys 125 2476327846 100"
When the mailer is finished with transmitting data of the
requested file it may proceed with transmission of other
files it has for the remote.
Note: this algorithm is sensitive for bugs on fast
communication links. If the transmitter sends a transmit
of a file and starts with the next file before the receive
of the M_GET for first file.
The Implementation MUST detect this situation and the
mailer MUST NOT be confused by this.
In addition: this situation increase network traffic.
M_SKIP 10
Non destructive skip. Parameter is a space separated list
of filename, size and unixtime. This command indicates that
the remote should postpone sending the file until next
session.
Greetings, Michiel Broek
Email: mbse@mbse.dds.nl
Fidonet: Michiel Broek at 2:280/2802
... You shall know the truth, and it shall make you freak.
--- MBSE BBS v0.71.2 (GNU/Linux-i386)
* Origin: MBSE Linux BBS. Made in the Netherlands (2:280/2802)
|