215 lines
6.9 KiB
Markdown
215 lines
6.9 KiB
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`.
|
|
|
|
|
|
### Keepalive ###
|
|
|
|
After the communication between client and server has been established,
|
|
server starts sending keepalive messages to the client at a rate of two
|
|
messages per second.
|
|
The keepalive message, as any other server to client message must be
|
|
acknowledged by the client.
|
|
|
|
Server to client:
|
|
|
|
* `chr(0)`: keepalive message identifier
|
|
|
|
Client to server:
|
|
|
|
* `P\r\n`
|
|
|
|
|
|
### Sending audio signal ###
|
|
|
|
Sending audio signal from client to server is a two-step procedure:
|
|
client must request permission to trasmit to the server and then, if
|
|
server acknowledges, client can start transmitting audio data.
|
|
|
|
Client to server:
|
|
|
|
* `TX0\r\n`
|
|
|
|
Server to client:
|
|
|
|
* `chr(1)chr(hh)chr(ll)`: transmission acknowledged (hh*256+ll is the
|
|
client index in client list)
|
|
|
|
Client to server:
|
|
|
|
* `TX1\r\n` followed by 325 bytes: data following the first line
|
|
contains 10 GSM 6.10 frames (representing 20mS of audio signal each one)
|
|
encoded with WAV#49 variant.
|
|
|
|
Client to server:
|
|
|
|
* `RX0\r\n`: client stops transmitting audio.
|
|
|
|
|
|
### Receiving audio signal ###
|
|
|
|
Server to client:
|
|
|
|
* `chr(2)chr(hh)chr(ll)` followed by 325 bytes: data following the first
|
|
3 bytes contains 10 GSM 6.10 frames (representing 20mS of audio signal
|
|
each one) encoded with WAV#49 variant. hh*256+ll represents the index in
|
|
the client list of the client sending audio.
|
|
|
|
|
|
### Sending text messages ###
|
|
|
|
Client to server:
|
|
|
|
* `TM:<ID>clientId</ID><MS>Message body</MS>\r\n`: Sends "Message body"
|
|
to client having id "clientId". If clientId is an empty string,
|
|
message is sent to all clients on the same network, including the
|
|
message sender.
|
|
|
|
|
|
### Receiving text messages ###
|
|
|
|
Server to client:
|
|
|
|
* `chr(4)` followed by 3-lines message: incoming message first line
|
|
contains the sender ID, second line the message body, third line the
|
|
message type: "A" for network messages or "P" for messages directed to a
|
|
single client.
|
|
|
|
|
|
### Receiving client list ###
|
|
|
|
Server to client:
|
|
|
|
* `chr(3)` followed by a multiline message: each line contains a client
|
|
description in an XML-like format containing the following fields:
|
|
|
|
* **S**: Client status: 0=Available, 1=Not available, 2=Absent
|
|
* **M**: Client mute status: 0=Not muted, 1=Muted
|
|
* **NN**: Same as in authetication procedure
|
|
* **CT**: Same as in authetication procedure
|
|
* **BC**: Same as in authetication procedure
|
|
* **ON**: Same as in authetication procedure
|
|
* **ID**: Client ID (assigned to the client by the system manager
|
|
through the server during the authentication phase)
|
|
* **DS**: Same as in authetication procedure
|
|
|
|
|
|
### Receiving network list ###
|
|
|
|
Server to client:
|
|
|
|
* `chr(5)` followed by a multiline message: each line contains the name
|
|
of a network.
|
|
|
|
|