gnuradionetwork/docs/protocols.markdown

The FreeRadioNetwork protocol
=============================

This document describes the results of reverse-engeneering the official
set of [FreeRadioNetwork](http//freeradionetwork.eu) programs through
network traffic sniffing and software decompilation.


System components
-----------------

The FreeRadioNetwork system is composed of three programs:

* client
* server
* system manager

Client and server executables are freely available, while the system
manager is not. The role of the system manager is account management,
including password generation and credentials checking, keeping track
of active servers and connected users.

The client talks to the system manager only to get the list of active
servers and to request the creation of a new account/password: any other
communication from the client goes to the server.

Server listens for clients connection on TCP port 10024 (by default, but
can be changed through the server GUI), while the system manager listen
for server connections and client queries on TCP port 10025. In both the
client and the server, the system manager address is hard coded as
`frn.no-ip.info`.


Client - server protocol
------------------------

The client sends requests to the server in the form of CR+LF terminated
ascii text lines. Response to commands and unsolicited events from the
server (i.e. incoming text messages), excluding authentication procedure
and voice packets, starts with a byte indicating the message type
followed by one CR+LF terminated ascii line containing the decimal count
of lines following and then the lines composing the message body.


### Authentication ###

As soon as the TCP connection is established, the client sends a line
containing user's info and authentication credential formatted enclosing
fields between html-like tags, for example:

    CT:<VX>2010002</VX><EA>user@example.com</EA><PW>XYZJKWXY</PW><ON>CALLSIGN, Name</ON><BC>PC Only</BC><DS></DS><NN>Country</NN><CT>City - Locator</CT><NT>Network</NT>

The line is, as usual, followed by the CR and LF chars (ascii 13 an 10).
The meaning of the fields is the following:

* **VX**: Client version (four digits for the year and three digits for
the release number)
* **EA**: User's email address
* **PW**: The password assigned by the system manager to the user
* **ON**: Operator's name, usually in the form CALLSIGN, RealName
* **BC**: Indicates the client type:
 * `PC Only`
 * `Parrot`
 * `Crosslink`
 * *BBB* `Ch`*CCC* *MM* `CTC`*TT* where **BBB** is the band (3 digits:
 433, 446, 027,...), **CCC** is the channel number (3 digits), **MM**
 is the modulation (AM or FM), **TT** is the subtone number (2 digits)
* **DS**: Description, only used for gateways, empty for other client
types
* **NN**: Country
* **CT**: Client's location in the form of City - Locator
* **NT**: Network (channel, room) to join on login

In response to the authentication request, the server sends two lines of
text (CR+LF terminated):

    2010002
    <MT></MT><SV>2009005</SV><AL>OK</AL><BN>backup.server.org</BN><BP>10024</BP><KP>327119</KP>

The first line contains the latest client version available.
The second one contains authentication results and server info:

* **MT**: Unknown meaning, always empty
* **SV**: Server version
* **AL**: Authentication result:
 * `OK`: Success, unprivileged user
 * `ADMIN`: Success, user has administration privileges
 * `OWNER`: Success, user is the server owner
 * `NOK`: Failed, invalid client version
 * `WRONG`: Failed, invalid credentials
 * `BLOCK`: Failed, user already logged in
* **BN**: Backup server
* **BP**: Backup server port
* **KP**: Six digits code used for second phase

At this point, if authentication succeeds, server versions greater than
2009004 needs one more line from the client before considering the
connection fully established. The line is a five digits number computed
as follows:

1. Split the KP code in two-digits numbers: `AABBCC`
2. Let `X` be the result of: `(AA+2)*(BB+1)+(CC+4)*(CC+7)`
3. Extend `X` to be 5 digits long, padding to the left with zeroes as
needed and let's call the resulting digits `DEFGH` respectively
4. The authentication code is composed by rearranging the digits as
`GDFHE`

For example, let's KP be `327119`. AA would be 32, BB=71 and CC=19.

    X = (32+2)*(71+1)+(19+4)*(19+7) = 3046

Padding to five digits we would get `03046`, so D=0, E=3, F=0, G=4, H=6
so the auth code wold be `40063`.