.. index::
double: TRANSPORT; subsystem
.. _TRANSPORT-Subsystem-Dev:
TRANSPORT
=========
.. _Address-validation-protocol:
Address validation protocol
---------------------------
This section documents how the GNUnet transport service validates
connections with other peers. It is a high-level description of the
protocol necessary to understand the details of the implementation. It
should be noted that when we talk about PING and PONG messages in this
section, we refer to transport-level PING and PONG messages, which are
different from core-level PING and PONG messages (both in implementation
and function).
The goal of transport-level address validation is to minimize the
chances of a successful man-in-the-middle attack against GNUnet peers on
the transport level. Such an attack would not allow the adversary to
decrypt the P2P transmissions, but a successful attacker could at least
measure traffic volumes and latencies (raising the adversaries
capabilities by those of a global passive adversary in the worst case).
The scenarios we are concerned about is an attacker, Mallory, giving a
``HELLO`` to Alice that claims to be for Bob, but contains Mallory's IP
address instead of Bobs (for some transport). Mallory would then forward
the traffic to Bob (by initiating a connection to Bob and claiming to be
Alice). As a further complication, the scheme has to work even if say
Alice is behind a NAT without traversal support and hence has no address
of her own (and thus Alice must always initiate the connection to Bob).
An additional constraint is that ``HELLO`` messages do not contain a
cryptographic signature since other peers must be able to edit (i.e.
remove) addresses from the ``HELLO`` at any time (this was not true in
GNUnet 0.8.x). A basic **assumption** is that each peer knows the set of
possible network addresses that it **might** be reachable under (so for
example, the external IP address of the NAT plus the LAN address(es)
with the respective ports).
The solution is the following. If Alice wants to validate that a given
address for Bob is valid (i.e. is actually established **directly** with
the intended target), she sends a PING message over that connection to
Bob. Note that in this case, Alice initiated the connection so only
Alice knows which address was used for sure (Alice may be behind NAT, so
whatever address Bob sees may not be an address Alice knows she has).
Bob checks that the address given in the ``PING`` is actually one of
Bob's addresses (ie: does not belong to Mallory), and if it is, sends
back a ``PONG`` (with a signature that says that Bob owns/uses the
address from the ``PING``). Alice checks the signature and is happy if
it is valid and the address in the ``PONG`` is the address Alice used.
This is similar to the 0.8.x protocol where the ``HELLO`` contained a
signature from Bob for each address used by Bob. Here, the purpose code
for the signature is ``GNUNET_SIGNATURE_PURPOSE_TRANSPORT_PONG_OWN``.
After this, Alice will remember Bob's address and consider the address
valid for a while (12h in the current implementation). Note that after
this exchange, Alice only considers Bob's address to be valid, the
connection itself is not considered 'established'. In particular, Alice
may have many addresses for Bob that Alice considers valid.
The ``PONG`` message is protected with a nonce/challenge against replay
attacks (`replay <http://en.wikipedia.org/wiki/Replay_attack>`__) and
uses an expiration time for the signature (but those are almost
implementation details).
NAT library
.. _NAT-library:
NAT library
-----------
The goal of the GNUnet NAT library is to provide a general-purpose API
for NAT traversal **without** third-party support. So protocols that
involve contacting a third peer to help establish a connection between
two peers are outside of the scope of this API. That does not mean that
GNUnet doesn't support involving a third peer (we can do this with the
distance-vector transport or using application-level protocols), it just
means that the NAT API is not concerned with this possibility. The API
is written so that it will work for IPv6-NAT in the future as well as
current IPv4-NAT. Furthermore, the NAT API is always used, even for
peers that are not behind NAT --- in that case, the mapping provided is
simply the identity.
NAT traversal is initiated by calling ``GNUNET_NAT_register``. Given a
set of addresses that the peer has locally bound to (TCP or UDP), the
NAT library will return (via callback) a (possibly longer) list of
addresses the peer **might** be reachable under. Internally, depending
on the configuration, the NAT library will try to punch a hole (using
UPnP) or just \"know\" that the NAT was manually punched and generate
the respective external IP address (the one that should be globally
visible) based on the given information.
The NAT library also supports ICMP-based NAT traversal. Here, the other
peer can request connection-reversal by this peer (in this special case,
the peer is even allowed to configure a port number of zero). If the NAT
library detects a connection-reversal request, it returns the respective
target address to the client as well. It should be noted that
connection-reversal is currently only intended for TCP, so other plugins
**must** pass ``NULL`` for the reversal callback. Naturally, the NAT
library also supports requesting connection reversal from a remote peer
(``GNUNET_NAT_run_client``).
Once initialized, the NAT handle can be used to test if a given address
is possibly a valid address for this peer (``GNUNET_NAT_test_address``).
This is used for validating our addresses when generating PONGs.
Finally, the NAT library contains an API to test if our NAT
configuration is correct. Using ``GNUNET_NAT_test_start`` **before**
binding to the respective port, the NAT library can be used to test if
the configuration works. The test function act as a local client,
initialize the NAT traversal and then contact a ``gnunet-nat-server``
(running by default on ``gnunet.org``) and ask for a connection to be
established. This way, it is easy to test if the current NAT
configuration is valid.
.. _Distance_002dVector-plugin:
Distance-Vector plugin
----------------------
The Distance Vector (DV) transport is a transport mechanism that allows
peers to act as relays for each other, thereby connecting peers that
would otherwise be unable to connect. This gives a larger connection set
to applications that may work better with more peers to choose from (for
example, File Sharing and/or DHT).
The Distance Vector transport essentially has two functions. The first
is \"gossiping\" connection information about more distant peers to
directly connected peers. The second is taking messages intended for
non-directly connected peers and encapsulating them in a DV wrapper that
contains the required information for routing the message through
forwarding peers. Via gossiping, optimal routes through the known DV
neighborhood are discovered and utilized and the message encapsulation
provides some benefits in addition to simply getting the message from
the correct source to the proper destination.
The gossiping function of DV provides an up to date routing table of
peers that are available up to some number of hops. We call this a
fisheye view of the network (like a fish, nearby objects are known while
more distant ones unknown). Gossip messages are sent only to directly
connected peers, but they are sent about other knowns peers within the
\"fisheye distance\". Whenever two peers connect, they immediately
gossip to each other about their appropriate other neighbors. They also
gossip about the newly connected peer to previously connected neighbors.
In order to keep the routing tables up to date, disconnect notifications
are propagated as gossip as well (because disconnects may not be
sent/received, timeouts are also used remove stagnant routing table
entries).
Routing of messages via DV is straightforward. When the DV transport is
notified of a message destined for a non-direct neighbor, the
appropriate forwarding peer is selected, and the base message is
encapsulated in a DV message which contains information about the
initial peer and the intended recipient. At each forwarding hop, the
initial peer is validated (the forwarding peer ensures that it has the
initial peer in its neighborhood, otherwise the message is dropped).
Next the base message is re-encapsulated in a new DV message for the
next hop in the forwarding chain (or delivered to the current peer, if
it has arrived at the destination).
Assume a three peer network with peers Alice, Bob and Carol. Assume that
::
Alice <-> Bob and Bob <-> Carol
are direct (e.g. over TCP or UDP transports) connections, but that Alice
cannot directly connect to Carol. This may be the case due to NAT or
firewall restrictions, or perhaps based on one of the peers respective
configurations. If the Distance Vector transport is enabled on all three
peers, it will automatically discover (from the gossip protocol) that
Alice and Carol can connect via Bob and provide a \"virtual\" Alice <->
Carol connection. Routing between Alice and Carol happens as follows;
Alice creates a message destined for Carol and notifies the DV transport
about it. The DV transport at Alice looks up Carol in the routing table
and finds that the message must be sent through Bob for Carol. The
message is encapsulated setting Alice as the initiator and Carol as the
destination and sent to Bob. Bob receives the messages, verifies that
both Alice and Carol are known to Bob, and re-wraps the message in a new
DV message for Carol. The DV transport at Carol receives this message,
unwraps the original message, and delivers it to Carol as though it came
directly from Alice.
SMTP plugin
.. _SMTP-plugin:
SMTP plugin
-----------
.. todo:: Update?
This section describes the new SMTP transport plugin for GNUnet as it
exists in the 0.7.x and 0.8.x branch. SMTP support is currently not
available in GNUnet 0.9.x. This page also describes the transport layer
abstraction (as it existed in 0.7.x and 0.8.x) in more detail and gives
some benchmarking results. The performance results presented are quite
old and maybe outdated at this point. For the readers in the year 2019,
you will notice by the mention of version 0.7, 0.8, and 0.9 that this
section has to be taken with your usual grain of salt and be updated
eventually.
- Why use SMTP for a peer-to-peer transport?
- SMTPHow does it work?
- How do I configure my peer?
- How do I test if it works?
- How fast is it?
- Is there any additional documentation?
.. _Why-use-SMTP-for-a-peer_002dto_002dpeer-transport_003f:
Why use SMTP for a peer-to-peer transport?
------------------------------------------
There are many reasons why one would not want to use SMTP:
- SMTP is using more bandwidth than TCP, UDP or HTTP
- SMTP has a much higher latency.
- SMTP requires significantly more computation (encoding and decoding
time) for the peers.
- SMTP is significantly more complicated to configure.
- SMTP may be abused by tricking GNUnet into sending mail
to non-participating third parties.
So why would anybody want to use SMTP?
- SMTP can be used to contact peers behind NAT boxes (in virtual
private networks).
- SMTP can be used to circumvent policies that limit or prohibit
peer-to-peer traffic by masking as \"legitimate\" traffic.
- SMTP uses E-mail addresses which are independent of a specific IP,
which can be useful to address peers that use dynamic IP addresses.
- SMTP can be used to initiate a connection (e.g. initial address
exchange) and peers can then negotiate the use of a more efficient
protocol (e.g. TCP) for the actual communication.
In summary, SMTP can for example be used to send a message to a peer
behind a NAT box that has a dynamic IP to tell the peer to establish a
TCP connection to a peer outside of the private network. Even an
extraordinary overhead for this first message would be irrelevant in
this type of situation.
.. _How-does-it-work_003f:
How does it work?
-----------------
When a GNUnet peer needs to send a message to another GNUnet peer that
has advertised (only) an SMTP transport address, GNUnet base64-encodes
the message and sends it in an E-mail to the advertised address. The
advertisement contains a filter which is placed in the E-mail header,
such that the receiving host can filter the tagged E-mails and forward
it to the GNUnet peer process. The filter can be specified individually
by each peer and be changed over time. This makes it impossible to
censor GNUnet E-mail messages by searching for a generic filter.
.. _How-do-I-configure-my-peer_003f:
How do I configure my peer?
---------------------------
First, you need to configure ``procmail`` to filter your inbound E-mail
for GNUnet traffic. The GNUnet messages must be delivered into a pipe,
for example ``/tmp/gnunet.smtp``. You also need to define a filter that
is used by ``procmail`` to detect GNUnet messages. You are free to
choose whichever filter you like, but you should make sure that it does
not occur in your other E-mail. In our example, we will use
``X-mailer: GNUnet``. The ``~/.procmailrc`` configuration file then
looks like this:
::
:0:
* ^X-mailer: GNUnet
/tmp/gnunet.smtp
# where do you want your other e-mail delivered to
# (default: /var/spool/mail/)
:0: /var/spool/mail/
After adding this file, first make sure that your regular E-mail still
works (e.g. by sending an E-mail to yourself). Then edit the GNUnet
configuration. In the section ``SMTP`` you need to specify your E-mail
address under ``EMAIL``, your mail server (for outgoing mail) under
``SERVER``, the filter (X-mailer: GNUnet in the example) under
``FILTER`` and the name of the pipe under ``PIPE``. The completed
section could then look like this:
.. code-block:: text
EMAIL = me@mail.gnu.org MTU = 65000 SERVER = mail.gnu.org:25 FILTER =
"X-mailer: GNUnet" PIPE = /tmp/gnunet.smtp
.. todo:: set highlighting for this code block properly.
Finally, you need to add ``smtp`` to the list of ``TRANSPORTS`` in the
``GNUNETD`` section. GNUnet peers will use the E-mail address that you
specified to contact your peer until the advertisement times out. Thus,
if you are not sure if everything works properly or if you are not
planning to be online for a long time, you may want to configure this
timeout to be short, e.g. just one hour. For this, set ``HELLOEXPIRES``
to ``1`` in the ``GNUNETD`` section.
This should be it, but you may probably want to test it first.
.. _How-do-I-test-if-it-works_003f:
How do I test if it works?
--------------------------
Any transport can be subjected to some rudimentary tests using the
``gnunet-transport-check`` tool. The tool sends a message to the local
node via the transport and checks that a valid message is received.
While this test does not involve other peers and can not check if
firewalls or other network obstacles prohibit proper operation, this is
a great testcase for the SMTP transport since it tests pretty much
nearly all of the functionality.
``gnunet-transport-check`` should only be used without running
``gnunetd`` at the same time. By default, ``gnunet-transport-check``
tests all transports that are specified in the configuration file. But
you can specifically test SMTP by giving the option
``--transport=smtp``.
Note that this test always checks if a transport can receive and send.
While you can configure most transports to only receive or only send
messages, this test will only work if you have configured the transport
to send and receive messages.
.. _How-fast-is-it_003f:
How fast is it?
---------------
We have measured the performance of the UDP, TCP and SMTP transport
layer directly and when used from an application using the GNUnet core.
Measuring just the transport layer gives the better view of the actual
overhead of the protocol, whereas evaluating the transport from the
application puts the overhead into perspective from a practical point of
view.
The loopback measurements of the SMTP transport were performed on three
different machines spanning a range of modern SMTP configurations. We
used a PIII-800 running RedHat 7.3 with the Purdue Computer Science
configuration which includes filters for spam. We also used a Xenon 2
GHZ with a vanilla RedHat 8.0 sendmail configuration. Furthermore, we
used qmail on a PIII-1000 running Sorcerer GNU Linux (SGL). The numbers
for UDP and TCP are provided using the SGL configuration. The qmail
benchmark uses qmail's internal filtering whereas the sendmail
benchmarks relies on procmail to filter and deliver the mail. We used
the transport layer to send a message of b bytes (excluding transport
protocol headers) directly to the local machine. This way, network
latency and packet loss on the wire have no impact on the timings. n
messages were sent sequentially over the transport layer, sending
message i+1 after the i-th message was received. All messages were sent
over the same connection and the time to establish the connection was
not taken into account since this overhead is minuscule in practice ---
as long as a connection is used for a significant number of messages.
+--------------+----------+----------+----------+----------+----------+
| Transport | UDP | TCP | SMTP | SMTP (RH | SMTP |
| | | | (Purdue | 8.0) | (SGL |
| | | | s | | qmail) |
| | | | endmail) | | |
+==============+==========+==========+==========+==========+==========+
| 11 bytes | 31 ms | 55 ms | 781 s | 77 s | 24 s |
+--------------+----------+----------+----------+----------+----------+
| 407 bytes | 37 ms | 62 ms | 789 s | 78 s | 25 s |
+--------------+----------+----------+----------+----------+----------+
| 1,221 bytes | 46 ms | 73 ms | 804 s | 78 s | 25 s |
+--------------+----------+----------+----------+----------+----------+
The benchmarks show that UDP and TCP are, as expected, both
significantly faster compared with any of the SMTP services. Among the
SMTP implementations, there can be significant differences depending on
the SMTP configuration. Filtering with an external tool like procmail
that needs to re-parse its configuration for each mail can be very
expensive. Applying spam filters can also significantly impact the
performance of the underlying SMTP implementation. The microbenchmark
shows that SMTP can be a viable solution for initiating peer-to-peer
sessions: a couple of seconds to connect to a peer are probably not even
going to be noticed by users. The next benchmark measures the possible
throughput for a transport. Throughput can be measured by sending
multiple messages in parallel and measuring packet loss. Note that not
only UDP but also the TCP transport can actually loose messages since
the TCP implementation drops messages if the ``write`` to the socket
would block. While the SMTP protocol never drops messages itself, it is
often so slow that only a fraction of the messages can be sent and
received in the given time-bounds. For this benchmark we report the
message loss after allowing t time for sending m messages. If messages
were not sent (or received) after an overall timeout of t, they were
considered lost. The benchmark was performed using two Xeon 2 GHZ
machines running RedHat 8.0 with sendmail. The machines were connected
with a direct 100 MBit Ethernet connection. Figures udp1200, tcp1200 and
smtp-MTUs show that the throughput for messages of size 1,200 octets is
2,343 kbps, 3,310 kbps and 6 kbps for UDP, TCP and SMTP respectively.
The high per-message overhead of SMTP can be improved by increasing the
MTU, for example, an MTU of 12,000 octets improves the throughput to 13
kbps as figure smtp-MTUs shows. Our research paper [Transport2014]_ has
some more details on the benchmarking results.
Bluetooth plugin
.. _Bluetooth-plugin:
Bluetooth plugin
----------------
This page describes the new Bluetooth transport plugin for GNUnet. The
plugin is still in the testing stage so don't expect it to work
perfectly. If you have any questions or problems just post them here or
ask on the IRC channel.
- What do I need to use the Bluetooth plugin transport?
- BluetoothHow does it work?
- What possible errors should I be aware of?
- How do I configure my peer?
- How can I test it?
.. _What-do-I-need-to-use-the-Bluetooth-plugin-transport_003f:
What do I need to use the Bluetooth plugin transport?
-----------------------------------------------------
If you are a GNU/Linux user and you want to use the Bluetooth transport
plugin you should install the ``BlueZ`` development libraries (if they
aren't already installed). For instructions about how to install the
libraries you should check out the BlueZ site
(`http://www.bluez.org <http://www.bluez.org/>`__). If you don't know if
you have the necessary libraries, don't worry, just run the GNUnet
configure script and you will be able to see a notification at the end
which will warn you if you don't have the necessary libraries.
.. _How-does-it-work2_003f:
.. todo:: Change to unique title?
How does it work2?
------------------
The Bluetooth transport plugin uses virtually the same code as the WLAN
plugin and only the helper binary is different. The helper takes a
single argument, which represents the interface name and is specified in
the configuration file. Here are the basic steps that are followed by
the helper binary used on GNU/Linux:
- it verifies if the name corresponds to a Bluetooth interface name
- it verifies if the interface is up (if it is not, it tries to bring
it up)
- it tries to enable the page and inquiry scan in order to make the
device discoverable and to accept incoming connection requests *The
above operations require root access so you should start the
transport plugin with root privileges.*
- it finds an available port number and registers a SDP service which
will be used to find out on which port number is the server listening
on and switch the socket in listening mode
- it sends a HELLO message with its address
- finally it forwards traffic from the reading sockets to the STDOUT
and from the STDIN to the writing socket
Once in a while the device will make an inquiry scan to discover the
nearby devices and it will send them randomly HELLO messages for peer
discovery.
.. _What-possible-errors-should-I-be-aware-of_003f:
What possible errors should I be aware of?
------------------------------------------
*This section is dedicated for GNU/Linux users*
Well there are many ways in which things could go wrong but I will try
to present some tools that you could use to debug and some scenarios.
- ``bluetoothd -n -d`` : use this command to enable logging in the
foreground and to print the logging messages
- ``hciconfig``: can be used to configure the Bluetooth devices. If you
run it without any arguments it will print information about the
state of the interfaces. So if you receive an error that the device
couldn't be brought up you should try to bring it manually and to see
if it works (use ``hciconfig -a hciX up``). If you can't and the
Bluetooth address has the form 00:00:00:00:00:00 it means that there
is something wrong with the D-Bus daemon or with the Bluetooth
daemon. Use ``bluetoothd`` tool to see the logs
- ``sdptool`` can be used to control and interrogate SDP servers. If
you encounter problems regarding the SDP server (like the SDP server
is down) you should check out if the D-Bus daemon is running
correctly and to see if the Bluetooth daemon started correctly(use
``bluetoothd`` tool). Also, sometimes the SDP service could work but
somehow the device couldn't register its service. Use
``sdptool browse [dev-address]`` to see if the service is registered.
There should be a service with the name of the interface and GNUnet
as provider.
- ``hcitool`` : another useful tool which can be used to configure the
device and to send some particular commands to it.
- ``hcidump`` : could be used for low level debugging
.. _How-do-I-configure-my-peer2_003f:
.. todo:: Fix name/referencing now that we're using Sphinx.
How do I configure my peer2?
----------------------------
On GNU/Linux, you just have to be sure that the interface name
corresponds to the one that you want to use. Use the ``hciconfig`` tool
to check that. By default it is set to hci0 but you can change it.
A basic configuration looks like this:
::
[transport-bluetooth]
# Name of the interface (typically hciX)
INTERFACE = hci0
# Real hardware, no testing
TESTMODE = 0 TESTING_IGNORE_KEYS = ACCEPT_FROM;
In order to use the Bluetooth transport plugin when the transport
service is started, you must add the plugin name to the default
transport service plugins list. For example:
::
[transport] ... PLUGINS = dns bluetooth ...
If you want to use only the Bluetooth plugin set *PLUGINS = bluetooth*
On Windows, you cannot specify which device to use. The only thing that
you should do is to add *bluetooth* on the plugins list of the transport
service.
.. _How-can-I-test-it_003f:
How can I test it?
------------------
If you have two Bluetooth devices on the same machine and you are using
GNU/Linux you must:
- create two different file configuration (one which will use the first
interface (*hci0*) and the other which will use the second interface
(*hci1*)). Let's name them *peer1.conf* and *peer2.conf*.
- run *gnunet-core -c peerX.conf -i* in order to generate the peers
private keys. The **X** must be replace with 1 or 2.
- run *gnunet-arm -c peerX.conf -s -i=transport* in order to start the
transport service. (Make sure that you have \"bluetooth\" on the
transport plugins list if the Bluetooth transport service doesn't
start.)
- run *gnunet-core -c peer1.conf -i* to get the first peer's ID. If
you already know your peer ID (you saved it from the first command),
this can be skipped.
- run *gnunet-transport -c peer2.conf -p=PEER1_ID -s* to start sending
data for benchmarking to the other peer.
This scenario will try to connect the second peer to the first one and
then start sending data for benchmarking.
If you have two different machines and your configuration files are good
you can use the same scenario presented on the beginning of this
section.
Another way to test the plugin functionality is to create your own
application which will use the GNUnet framework with the Bluetooth
transport service.
.. _The-implementation-of-the-Bluetooth-transport-plugin:
The implementation of the Bluetooth transport plugin
----------------------------------------------------
This page describes the implementation of the Bluetooth transport
plugin.
First I want to remind you that the Bluetooth transport plugin uses
virtually the same code as the WLAN plugin and only the helper binary is
different. Also the scope of the helper binary from the Bluetooth
transport plugin is the same as the one used for the WLAN transport
plugin: it accesses the interface and then it forwards traffic in both
directions between the Bluetooth interface and stdin/stdout of the
process involved.
The Bluetooth plugin transport could be used both on GNU/Linux and
Windows platforms.
- Linux functionality
- Pending Features
.. _Linux-functionality:
Linux functionality
^^^^^^^^^^^^^^^^^^^
In order to implement the plugin functionality on GNU/Linux I used the
BlueZ stack. For the communication with the other devices I used the
RFCOMM protocol. Also I used the HCI protocol to gain some control over
the device. The helper binary takes a single argument (the name of the
Bluetooth interface) and is separated in two stages:
.. _THE-INITIALIZATION:
.. todo:: 'THE INITIALIZATION' should be in bigger letters or stand out, not
starting a new section?
THE INITIALIZATION
^^^^^^^^^^^^^^^^^^
- first, it checks if we have root privileges (*Remember that we need
to have root privileges in order to be able to bring the interface up
if it is down or to change its state.*).
- second, it verifies if the interface with the given name exists.
**If the interface with that name exists and it is a Bluetooth
interface:**
- it creates a RFCOMM socket which will be used for listening and call
the *open_device* method
On the *open_device* method:
- creates a HCI socket used to send control events to the device
- searches for the device ID using the interface name
- saves the device MAC address
- checks if the interface is down and tries to bring it UP
- checks if the interface is in discoverable mode and tries to make
it discoverable
- closes the HCI socket and binds the RFCOMM one
- switches the RFCOMM socket in listening mode
- registers the SDP service (the service will be used by the other
devices to get the port on which this device is listening on)
- drops the root privileges
**If the interface is not a Bluetooth interface the helper exits with
a suitable error**
.. _THE-LOOP:
THE LOOP
^^^^^^^^
The helper binary uses a list where it saves all the connected neighbour
devices (*neighbours.devices*) and two buffers (*write_pout* and
*write_std*). The first message which is send is a control message with
the device's MAC address in order to announce the peer presence to the
neighbours. Here are a short description of what happens in the main
loop:
- Every time when it receives something from the STDIN it processes the
data and saves the message in the first buffer (*write_pout*). When
it has something in the buffer, it gets the destination address from
the buffer, searches the destination address in the list (if there is
no connection with that device, it creates a new one and saves it to
the list) and sends the message.
- Every time when it receives something on the listening socket it
accepts the connection and saves the socket on a list with the
reading sockets.
- Every time when it receives something from a reading socket it parses
the message, verifies the CRC and saves it in the *write_std* buffer
in order to be sent later to the STDOUT.
So in the main loop we use the select function to wait until one of the
file descriptor saved in one of the two file descriptors sets used is
ready to use. The first set (*rfds*) represents the reading set and it
could contain the list with the reading sockets, the STDIN file
descriptor or the listening socket. The second set (*wfds*) is the
writing set and it could contain the sending socket or the STDOUT file
descriptor. After the select function returns, we check which file
descriptor is ready to use and we do what is supposed to do on that kind
of event. *For example:* if it is the listening socket then we accept a
new connection and save the socket in the reading list; if it is the
STDOUT file descriptor, then we write to STDOUT the message from the
*write_std* buffer.
To find out on which port a device is listening on we connect to the
local SDP server and search the registered service for that device.
*You should be aware of the fact that if the device fails to connect to
another one when trying to send a message it will attempt one more time.
If it fails again, then it skips the message.* *Also you should know
that the transport Bluetooth plugin has support for*\ **broadcast
messages**\ *.*
.. _Details-about-the-broadcast-implementation:
Details about the broadcast implementation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
First I want to point out that the broadcast functionality for the
CONTROL messages is not implemented in a conventional way. Since the
inquiry scan time is too big and it will take some time to send a
message to all the discoverable devices I decided to tackle the problem
in a different way. Here is how I did it:
- If it is the first time when I have to broadcast a message I make an
inquiry scan and save all the devices' addresses to a vector.
- After the inquiry scan ends I take the first address from the list
and I try to connect to it. If it fails, I try to connect to the next
one. If it succeeds, I save the socket to a list and send the message
to the device.
- When I have to broadcast another message, first I search on the list
for a new device which I'm not connected to. If there is no new
device on the list I go to the beginning of the list and send the
message to the old devices. After 5 cycles I make a new inquiry scan
to check out if there are new discoverable devices and save them to
the list. If there are no new discoverable devices I reset the
cycling counter and go again through the old list and send messages
to the devices saved in it.
**Therefore**:
- every time when I have a broadcast message I look up on the list for
a new device and send the message to it
- if I reached the end of the list for 5 times and I'm connected to all
the devices from the list I make a new inquiry scan. *The number of
the list's cycles after an inquiry scan could be increased by
redefining the MAX_LOOPS variable*
- when there are no new devices I send messages to the old ones.
Doing so, the broadcast control messages will reach the devices but with
delay.
*NOTICE:* When I have to send a message to a certain device first I
check on the broadcast list to see if we are connected to that device.
If not we try to connect to it and in case of success we save the
address and the socket on the list. If we are already connected to that
device we simply use the socket.
.. _Pending-features:
Pending features
^^^^^^^^^^^^^^^^
- Implement a testcase for the helper :Â *The testcase consists of a
program which emulates the plugin and uses the helper. It will
simulate connections, disconnections and data transfers.*
If you have a new idea about a feature of the plugin or suggestions
about how I could improve the implementation you are welcome to comment
or to contact me.
.. _WLAN-plugin:
WLAN plugin
-----------
This section documents how the wlan transport plugin works. Parts which
are not implemented yet or could be better implemented are described at
the end.
.. [Transport2014] https://bib.gnunet.org/date.html#paper_5fshort2014