**********************************************************************
FTSC FIDONET TECHNICAL STANDARDS COMMITTEE
**********************************************************************
Publication: FSP-1016
Revision: 1
Title: Automatic configuration of Points in FidoNet
Author: Christian von Busse, on behalf of all Points and Nodes
who took part in the development of this document.
Revision Date: 17 July 2000
Expire Date: 17 July 2002
Status of this document
-----------------------
This document is a Fidonet Standards Proposal (FSP).
This document specifies an optional Fidonet standard protocol for
the Fidonet community and requests discussion and suggestions for
improvements.
This document is released to the public domain and may be used,
copied or modified for any purpose whatever.
Contents
--------
1. Introduction
2. Definitions
3. Description of the communication between CDP and CDN
3.1 Files to be transfered
3.1.1 From CDP to CDN
3.1.2 From CDN to CDP
3.1.2.1 In case of an accepted automatic application
3.1.2.1.1 PPPPZZZZ.CDN
3.1.2.1.2 ECHOZZZZ.ZIP
3.1.2.1.3 NODEZZZZ.ZIP
3.1.2.2 In case of a rejected automatic application
3.2 How the files are transfered
3.2.1 An address for the CDP
3.2.2 Transmitting the application data
4. Procedure after the first session
4.1 Determining the passwords to be used
4.2 Other recommendations
5. Appendix: Example piece of source code to calculate CRC16
6. Acknowledgements
1. Introduction
---------------
This document proposes a protocol which will enable new Points,
without any specific knowledge about FidoNet and its technicalities,
to quickly and easily establish a link to FidoNet.
The purpose is to make it as easy for everybody to participate in
FidoNet as it is to access the InterNet.
This protocol was designed to be usable, or at least to be able to
be made usable, with common FidoNet Node and Point software. The
effort for Nodes to accept new Points this way and the effort
for developers (or users) to make their Point software compliant
with this protocol has been kept as low as possible.
2. Definitions
--------------
CDP: The new Point.
CDN: A Node accepting new Points in accordance with the proposed
protocol. A CDN Node carries the user-defined flag CDP in the
nodelist.
Function Request: (Also called Service Request). This type of
file request can be used to request a dummy filename from a
Node system. This file request causes an external programme to
be started during the current session. Certain files may be
transfered back to the requesting user in the same session.
Text File: A file containing only ASCII characters between 32 and
126, but including CR (13) and LF (10).
PPPP: Whenever this is used, it stands for the temporary Point
number with which the CDP makes his/her first poll to the CDN.
(See para 3.2.1). The Point number is specified by four
hexadecimal digits. Leading zeros must be added if necessary.
ZZZZ: Stands for the Zone for which the CDP's application shall
be valid. Normally, this is the CDN's FidoNet Zone but it may
differ if the CDN has multiple addresses in multiple Zones.
The Zone number is specified by four hexadecimal digits.
Leading zeros must be added if necessary.
3. Description of the communication between CDP and CDN
-------------------------------------------------------
3.1 Files to be Transfered
--------------------------
All files to be transfered are text files.
They contain either comments or data.
Comment lines start with a ';' or a '#'.
Data lines have the format:
KEY_WORD=VALUE
... and a length of 255 characters at maximum, including the line
termination character(s) CR, LF or CR/LF.
Key words are not case sensitive and can contain spaces in
non-escaped form.
There must not be spaces before or after the =.
By way of exeption ascii characters > 126 may be used in the fields
which will not be used for configuring either the point software or
the node software, and thus not cause any problems: These fields
are:
- In PPPPZZZZ.CDP: RESIDENCE
- In PPPPZZZZ.CDN: EMAIL_ADDR, VOICE
3.1.1 From CDP to CDN
---------------------
The CDP transmits his application to the Node in a text file.
The text file is named PPPPZZZZ.CDP.
PPPPZZZZ.CDP must contain the following keywords:
POINTNAME
The name of the point operator as used in field 5 of a nodelist,
but in the format: First_name Last_name
RESIDENCE
The place where the Point lives, format: zip_code city
The use of zip_code is recommended, city is mandatory.
Please remember, that a zip code is not necessarily composed of
5 numeric characters and that it also can contain alphanumeric
characters.
PNTLST_RES
Again, the place where the Point lives. This field contains
abbrevations typically used in the Pointlist for cities,
format: City
It is recommended not to allow the Point to fill out this entry
but to have the setup automatically generate this value from
RESIDENCE.
VOICEPHONE
The voice phone number of the Point, in international (ISO)
standard, but spaces replaced by dashes, as in the nodelist:
+<country_code>-<area_code>-<phone_number>
An area_code must only be supplied, if it is used in the point's
country.
TEMPAKA
The temporary AKA with which the Point calls the Node during the
application poll.
RESULT
For faster processing on the Node system, this value contains
the filename of the PPPPZZZZ.CDN file that is sent back to the
CDP, should his/her application be successful.
PW_USABLE
The value transmitted here specifies how many different passwords
the point software can make use of. The value ranges from 1 to 4.
The numbers have the following meanings:
1 = The Point software can make use of only one password as
session password, areafix password, file ticker password and
PKT password.
2 = The Point software can make use of one password as session
password and PKT password and can make use of a second one as
areafix and file ticker password.
3 = The Point software can make use of one password as session and
PKT password, can make use of a second one as areafix password
and can make use of a third one as file ticker password.
4 = The Point software can be configured to make use of four
different passwords for the session, areafix, the transmitted
PKTs and the file ticker.
3.1.2 From CDN to CDP
---------------------
Depending on whether the CDN accepts the application or not, the CDP
gets a different text file as an answer.
3.1.2.1 In the case of an accepted automatic application
----------------------------------------------------
If the application is accepted, the CDN transmits three files to the
CDP.
3.1.2.1.1 PPPPZZZZ.CDN
----------------------
This file must contain the following keywords:
POINTNUMBER
The Point number (not the complete AKA) assigned to the CDP.
The CDN's AKA is taken from the nodelist entry carrying the CDP
flag.
PASSWORD
A password for the CDP, to be used at least as session password.
Which passwords will really be used will be defined later on.
AREAFIXPW
A password which can be used as areafix password.
TICKERPW
A password to be used as password for the file ticker.
PKTPW
A password to be used as PKT password.
AREAFIX_NAME
The name to which areafix messages should be addressed.
TICKER_NAME
The name under which the file ticker expects to receive messages.
NL_FREQ
The filename under which the current nodelist can be requested
from the CDN.
NL_DIFF
The name of the nodelist difference files, without extension.
EMAIL_ADDR
An e-Mail address of the Node, which can be used by the Point
in case of questions or difficulties.
Every Node should at least be able to transmit his fidonet.org
address here:
[email protected]<NodeNr>.n<NetNr>.z<Zone>.fidonet.org
VOICE
The CDN's voice phone number, which can be used by the CDP in
case of questions or difficulties.
The CDN can specify a one-line text here of at most 255
characters, which is displayed to the CDP later on. So the CDN
could also tell the CDP that he is not available for voice calls.
WAIT
A non-committal time in minutes, after which, the Node system
should have completely processed the CDP's application. The CDP's
first call with his/her real Point data should not be made before
this time has passed since his/her initial call.
WAIT passes the time to wait as a signed integer. The valid values
range from 0 to 32767.
In case the CDN system should not support all four possible
passwords, the CDN will transmit identical passwords in the
different fields, according to its needs. Otherwise, all four fields
will be filled with different passwords.
PW_USABLE from the PPPPZZZZ.CDP will not be evaluated for this entry
in order to save time during the established connection. It will onl
be evaluated later on, when the CDN configures the CDP on his
system.
All passwords must be 5 to 8 characters long. Passwords have to be
in upper case.
3.1.2.1.2 ECHOZZZZ.ZIP
----------------------
The CDN transfers a list of the echomail areas available to the
Point. This list is a text file named ECHOZZZZ.LST. It has the
format compliant with the *.NA lists:
AREATAG description
AREATAG description
[...]
The description is optional. If it is given, there has to be at
least one space between the AREATAG and the description. A line may
be at max 80 characters long. If a description is longer than that,
it has to be continued in the next line. Lines containing only a
continued description have to start with at least one space.
3.1.2.1.3 NODEZZZZ.ZIP
----------------------
Finally, the CDN transmits a current nodelist to the CDP.
NODEZZZZ.ZIP contains a 3D nodelist with at least the CDN's home
region. The name of that nodelist is the name commonly used for
nodelists in zone ZZZZ.
e.g. in FidoNet Zone 2 this would be NODELIST.<day_of_year>
3.1.2.2 In case of a refused automatic application
-------------------------------------------------------
If the CDN does not accept the application, for whatever reason, the
Point will receive a text file named NOPOINT.CDN.
This text file should contain an explanation as to why the entry was
rejected but it may also be empty.
3.2 How the files are transfered
--------------------------------
All these files are transmitted within an unsecure established
session between the CDN's and the CDP's FidoNet mailer.
3.2.1 An address for the CDP
----------------------------
Two CDPs must be prevented from calling the CDN at the same time
with the same AKA. To achieve this, a temporary AKA is needed for
the application call.
This temporary AKA is formed according to the following scheme:
Zone
The CDN's home Zone
Net
The CDN's Net
Node
Node number 9999
Pointnumber
The Point number is created as a CRC16 (upside-down-CRC16
as used for Z-Modem and the nodelist - start polynom 11021H, start
value 0 without modulation, shifting to the left) checksum created
with POINTNAME, RESIDENCE and VOICEPHONE from PPPPZZZZ.CDP. The
values will be concatenated directly without inserting any spaces.
The checksum has then to be built modulo 32768 in order to prevent
Point numbers exceeding 32767. The Point number is, as all numbers
in the address, specified in decimal format.
Code examples for the most commonly used programming languages
can be found in para.5 below.
3.2.2 Transmitting the application data
---------------------------------------
The CDP transmits the PPPPZZZZ.CDP. In addition, he/she
file-requests the following three "MAGIC" files:
1. CDPOINT, password protected: CDP-PW
2. ECHOLIST
3. NODEZZZZ
The file request of CDPOINT initiates the creation process of
PPPPZZZZ.CDN on the CDN's system. The CDNs system will pick a free
Point number and randomly create the necessary password via a
function file-request, if the mailer cannot react directly to
received files matching a certain filemask.
The file-request of CDPOINT is password protected to minimize the
chance of accidentally initiating this process.
In order to minimize the online time for the CDP, the CDP is not
configured online after he has delivered his data but only after
the session has terminated.
The file-request of ECHOLIST causes ECHOZZZZ.ZIP to be transmitted
to the CDP.
The file-request of NODEZZZZ causes NODEZZZZ.ZIP to be transmitted
to the CDP.
4. Procedure after the first session
------------------------------------
4.1 Determining the passwords to be used
----------------------------------------
The CDN can decide how many different passwords will be used by
entering the same password into mulitple password fields in the
file PPPPZZZZ.CDN (See para. 3.1.2.1)
The Point software transmits its capabilities via the keyword
PW_USABLE in the file PPPPZZZZ.CDP (See para. 3.1.1)
When configuring the passwords, both parties can decide exactly
which password will be used by combining the PW_USABLE entry
with the transmitted passwords.
The following table will make it clear which passwords will be used:
+-------------------------------------------------+
| These passwords will be configured with the |
| value of the field... |
+-----------|------------+-----------+------------+-----------|
| PW_USABLE | Session-PW | PKT-PW | Areafix-PW | Ticker-PW |
+-----------+------------+-----------+------------+-----------|
| 1 | PASSWORD | PASSWORD | PASSWORD | PASSWORD |
| 2 | PASSWORD | PASSWORD | AREAFIXPW | AREAFIXPW |
| 3 | PASSWORD | PASSWORD | AREAFIXPW | TICKERPW |
| 4 | PASSWORD | PKTPW | AREAFIXPW | TICKERPW |
+-----------+------------+-----------+------------+-----------+
4.2 Other recommendations
-------------------------
After the initial session has terminated, the automatic
configuration of the CDP should to be initiated as quickly as
possible.
The new Point should be told by his/her software that his/her
application is being processed now, which will take about WAIT (See
para. 3.1.2.1.1) minutes.
The Point can make use of this time by reading documents about
FidoNet, which the Point software should offer to him/her.
5. Appendix: Example pieces of source code to calculate CRC16
-------------------------------------------------------------
Function crc16_string(InString: String): Word;
{ calculate CRC16 of a string, string is passed }
Var
CRC : Word; { CRC16 }
i : Integer; { Index variable for loop }
Index : Byte; { Index variable for CRC calculation }
Begin
CRC := 0; { initialize CRC }
{ calculate CRC for every character }
For i := 1 to Length(InString) Do
Begin
CRC := (CRC xor (Ord(InString[i]) SHL 8));
For Index := 1 to 8 Do
If ((CRC and $8000) <> 0)
Then CRC := ((CRC SHL 1) xor $1021)
Else CRC := (CRC SHL 1)
End;
crc16_string := (CRC and $FFFF) { return calculated CRC16 }
End; { crc16_string }
[...]
Writeln('CRC16 modulo 32768 (values between 0 and 32767):');
checksum := checksum mod 32768;
Writeln(angStr:12, ' HEX-CRC/16: ', numb2hex(checksum));
Writeln(angStr:12, ' DEZ-CRC/16: ', checksum);
A. Author contact data
----------------------
Christian von Busse
Fidonet: 2:240/2188
B. Acknowledgements
-------------------
The following people (without laying claim to completeness) have
participated in developing this document:
Norbert Bilek, 2:2468/9929
Christian von Busse, 2:240/2188
Werner Dworak, 2:2480/9504
Markus Engmann, 2:2483/21
Michael Haase, 2:2457/265.15
Daniel Hahler, 2:2432/337
Wolfgang Huebner, 2:2490/1906.9
Denny Mleinek, 2:248/7310
Dirk Pokorny, 2:240/5401.7
Herbert Rosenau, 2:2476/493
Tim Schattkowsky, 2:2437/70.29
Siggi Schoenicke, 2:2426/1210
Henning Schroeer, 2:2457/265
Ulrich Schroeter, 2:244/1120
Monika Steinhaeuser, 2:249/3110
C. History
------------
Rev.1, 20000717 First release.
