New America Foundation - Contractor Agreement #33-OTIUSAID2013 “NAF6”
Section 1: Work to be Performed (Scope of Work)
Milestone 1: Implement MSP
Milestone 2: Implement authenticated TCP→MSP & MSP→TCP port forwarding
<BOOKMARK:R4>R4. Implement TCP to MSP port forwarding.
<BOOKMARK:R5>R5. Implement MSP to TCP port forwarding.
. Implement IP & SID based blacklists and white lists to provide access control. (See N2
<BOOKMARK:R7>R7. Extend the serval test framework to provide coverage of the above.
. Update serval and commotion wikis to document the use of the port forwarding functions. (See N4
Milestone 3: Integrated SOCKS proxy with auto-discovery of proxy servers on mesh
. Implement a service probe extension for DNA that asks if any nodes on the network are offering SOCKS proxy services, caches the result, and updates the port forwarding rules using the TCP to MSP port forwarding library. The service discovery probe will be made general purpose to allow mesh nodes to announce arbitrary services. (See N5
<BOOKMARK:R10>R10. Add an “Use SOCKS proxy” option to the “Connect” Activity or other appropriate place in the Serval Mesh application that is enabled only if an MSP-enabled SOCKS proxy is detectable on the mesh. This option will give instructions on how to configure proxy settings on the phone.
. Add an “Offer SOCKS proxy access to the internet (can cost you money)” option to the “Connect” Activity of the Serval Mesh application that is enabled only when cellular data is enabled or equivalent functionality. When selected, this launches the “Select peers to allow to use your SOCKS proxy” activity that allows manipulation of a list of SIDs who are allowed to use the SOCKS proxy, or an equivalent mechanism. (See N6
<BOOKMARK:R12>R12. Extend the serval test framework to cover as much of this functionality as possible, and write and execute test plans for those parts not coverable by the test framework (Android user interface and live network tests).
<BOOKMARK:R13>R13. Update serval and commotion wikis to document the above.
. Commit an updated version of the Serval Mesh app that includes the above functionality. (See N7
<BOOKMARK:N1>N1. The MSP congestion control algorithm is quite simplistic and conservative. It should work without flooding the network over low latency links with minimal packet loss. There is plenty of scope for further R&D to improve throughput in situations with high packet loss and latency.
. The new MDP packet filtering rules only match SID
and MDP port number
because the IP addresses of forwarded TCP connections are unknown to the Serval DNA
daemon. The only suitable point in the connection chain for IP black/whitelisting would be the run-time configuration of the SOCKS proxy server implemented for R11
, to only allow certain devices to access the SOCKS proxy.
. The new MDP packet filtering rules are specified in an ASCII
text file whose path is set in the Serval DNA
. Typically this text file would be in the same directory as the
file, in which case the path can be relative. The syntax is shown by the following example:
The effect of this file is:
the first line allows all packets to and from the PING port of all remote nodes, effectively allowing this node to ping other nodes
the second line blocks all packets from any remote node sent to the local TRACE port, preventing this node from participating in route tracing
the third line allows all packets received from and sent to the given SID
the last line disallows all other packets
The rules are tried in order from first to last on each incoming and outgoing packet until a rule is found that matches. If that rule is
drop then the packet is blocked. If no rule matches then the packet is allowed. So in the example above, TRACE packets will not be received from the node with the given SID because rule 2 matches before rule 3.
The filter rules only affect incoming packets which are addressed to the local node and outgoing packets generated by the local node. They do not apply to packets for other nodes that are forwarded. This is because, in general, packets for other nodes are encrypted, so the port numbers are unknown.
Even if a rule prevents a broadcast packet from being processed by this node, that packet will still be forwarded to other nodes.
technical document contains a more comprehensive (and up to date) description of the packet rules file.
. The Tunnelling.md
technical document describes the TCP-over-MSP tunnelling commands in detail.
. Instead of attempting to overload DNS
, which suffers from security issues and a strict hierarchical delegation model unsuited to a dynamically changing network topology with no infrastructure, the opportunity was taken to invent a new service discovery protocol completly native to the Serval Mesh, taking advantage of the inherent security provided by Serval Identity (SID)
addressing and Mesh Datagram Protocol (MDP)
packet encryption. The new protocol was later named Cooee
. The Cooee.md
technical document describes the new protocol, which will be extended as needed in future to encompass more kinds of service.
<BOOKMARK:N6>N6. As well as a SOCKS proxy, an HTTP proxy was implemented to assist with testing, since most Android browsers do not support SOCKS but do support HTTP proxies. This makes the grant much more practical, since most uses of the TCP-over-Mesh tunnelling would have the objective of providing Web access.
. In practical terms, the SOCKS/HTTP proxy feature that this grant adds to the Serval Mesh
app for Android is of very limited use, and is suitable mainly for demonstration and proof-of-concept, because:
an Android device can only act as a useful proxy service if it has Internet access via either Wi-Fi or a Mobile Data Plan
if an Android device is connected to the internet via Wi-Fi, then it cannot put Wi-Fi in Ad Hoc mode or run as a Personal Hotspot, so it can only connect with other Android devices that are associated to the same Access Point, in which case they also have Internet access, and have no need of the Serval Mesh proxy
if a Mobile Data Plan is available on a proxy Android device, then it can easily share this with nearby devices using Android's Personal Hotspot function, so the Serval Mesh proxy is superfluous
All development, testing and documentation work for Milestone 1 was carried out by modifying the Serval DNA software component. The results of the work are freely available as source code from Serval DNA GitHub repository, so most links below refer to this repository.
Example usage, server side:
1$ servald msp listen 512
- Listening on port 512
- New connection from SID2:268
- Sending EOF to SID2:512
- Received EOF from SID2:512
- Connection with SID2:512 closed
Example usage, corresponding client side:
2$ servald msp connect SID1 512
- Connecting to SID1:512
- Connected to SID1:512
- Received EOF from SID1:512
- Sending EOF to SID1:512
- Connection with SID1:512 closed
R1 – Implement MSP
added new servald commands to exercise the new MSP client-side library and MSP protocol:
servald msp listen PORT
servald msp connect SID PORT
Both of these commands redirect standard I/O across the MSP stream.
improved MSP failure handling
implemented a sliding window protocol to handle large volumes of data (see N1
implemented MSP connection timeouts and keep-alive packets, to ensure that an MSP connection fails if the other end ceases responding
revamped the MSP API
to make it more usable and extensible
R2 – Test MSP
created a new test suite tests/msp
, initially containing a single test case performing essentially the commands shown above with a short data transfers in each direction
improved the first test case to assert that transmitted data arrives intact
added two more test cases, for one-way transfers of large (64 KiB) data
added two more test cases, one for keep-alive of a quiescent connection, and one for connection failure when no end-point is listening
R3 – Document MSP
As with Milestone 1, all development, testing and documentation work for Milestone 2 was carried out by modifying the Serval DNA software component. The results of the work are freely available as source code from Serval DNA GitHub repository, so most links below refer to this repository.
Example usage, assuming telnetd is listening on localhost:23:
1$ servald msp listen --forward=23 512
- Forwarding from port 512 to AF_INET:127.0.0.1:23
2$ servald msp connect --forward=4096 SID1 512
- Forwarding from AF_INET:127.0.0.1:4096 to SID1:512
2$ telnet localhost 4096
Connected to localhost.
Escape character is '^]'.
Ubuntu Saucy Salamander (development branch)
$ cat /dev/urandom | hexdump -C
Connection closed by foreign host.
R4 – Implement TCP → MSP forwarding (client side)
R5 – Implement MSP → TCP forwarding (server side)
R6 – Implement MDP black/whitelist
implemented a new configuration option
which names an ASCII
text file that contains a list of filter rules for all incoming and outgoing MDP packets
the same commit created a new test suite tests/mdp
, containing two test cases for packet filtering rules
improved the filter rules syntax to make it possible to write a single rule matching inbound and outbound packets from a single SID
for a discussion of the filter rules design, and N3
for examples of the filter rules file syntax
R7 – Test MSP-TCP forwarding and MDP black/whitelist
added another test case, for forwarding a TCP connection via MSP connection (client end)
added another test case, for forwarding an MSP connection to a TCP port (server end), thereby creating a TCP tunnel through MSP
improved diagnostic logging for the test cases
R8 – Document MSP-TCP forwarding and MDP black/whitelist
All development, testing and documentation work for Milestone 3 was carried out by modifying the Serval DNA software component and the Serval Mesh app for Android (a.k.a. Batphone). The results of the work are freely available as source code from Serval DNA GitHub repository and Batphone GitHub repository, so most links below refer to this repository.
R9 – Service discovery
Serval DNA commit 672104b
) for the MSP-TCP forwarding service, adding the
option to the MSP listen
Serval DNA commit d811978
created the Cooee.md
technical document to describe the new Serval Mesh service discovery protocol
R10 – SOCKS proxy client in Batphone
Batphone commit b3d8735
added a new Android service to Batphone to start the Serval DNA MSP connect
process, and added a new Android activity (screen) to discover a SOCKS server using Cooee
and allow the user to select one
Batphone commit 017cefe
replaced the Serval Mesh
home-screen “Maps” icon with a blank icon (awaiting an icon design) labelled “Proxy” that opens the new activity
R11 – SOCKS proxy server in Batphone
Batphone commit 65bb8cf
imported the Srelay source code as a Git submodule
and added it to the Batphone build
Srelay commits a785b1e
added an Android makefile and made small changes to port to Android
Batphone commit b3d8735
added a new Android service to Batphone to start the SOCKS server process and the Serval DNA MSP listen
process, and added a new Android activity (screen) to start and stop the SOCKS server
Batphone commit 21c385e
added a new Android activity (screen) to Batphone for managing the whitelist of SIDs
authorised to use the SOCKS server
R12 – Testing
The following automated Serval DNA tests were added:
new test cases were added to tests/jni
to test the new Cooee
service discovery protocol via the new Java classes that implemented its client API
An HTTP proxy server was added to Batphone in addition to the SOCKS proxy (see N6
) to facilitate testing:
by Dave Vandervies, publicly licensed under the ISC License
, was chosen for its simplicity, small size and compatible license
Batphone commit b3d8735
included code to start Tiny Inetd and Micro Proxy as well as the SOCKS proxy server
The tunnelling proxy function was manually tested using the HTTP proxy, since the stock Android browser supports HTTP proxies but not SOCKS
R13 – Update wikis
R14 – Commit Batphone with SOCKS