New America Foundation - First Contractor Agreement “NAF1”

In December 2011, The Serval Project commenced work for the New America Foundation's Open Technology Institute to develop wireless mesh security mechanisms and an OpenBTS dialplan for the Commotion Wireless Project.

This Agreement was followed by a Second Agreement.

SCHEDULE A Milestones

SCHEDULE A Deliverables

Wireless mesh security mechanisms

Wireless mesh networks present unique security challenges that prevent the use of many existing hub-and-spoke security models. The addition of a secure generalizable transport layer, improved verification of users and data sources, and reasonable anonymity is critical to the success of the Project.

Completion indicators
  1. Delivery of scripts, Makefiles and procedural documentation needed to add a secure generalizable transport layer, user and data source verification, to Commotion.
  2. Upstream contribution of all necessary patches to any parent open-source projects (eg, OSLRd)
  3. Delivery of updated Commotion documentation. Documentation shall include an updated README for the Commotion source tree and detailed procedural build documentation for the project wiki.

Development of an OpenBTS Dialplan

OpenBTS forms the basis of GSM cell phone integration in the Commotion Wireless Project. OpenBTS currently lacks a mechanism for user-specified phone numbers – a significant usability feature that will affect software adoption.

Completion indicators
  1. Delivery of the scripts, Makefiles, and procedural documentation needed to add dialplan functionality to OpenBTS.
  2. Upstream contribution of all necessary patches to OpenBTS.
  3. Delivery of updated Commotion documentation. Documentation should include an README for the Commotion source tree and detailed procedural build documentation for the project wiki.


The work was completed in September 2012, and a report submitted in October 2012. The following text is taken directly from the report, edited to link to other relevant material and edited to remove redundant information.

Milestone 1. Integration of NaCl crypto library into DNA

The source code of the NaCl crypto library version 2011/02/21 was copied into the source code tree of the Serval DNA component and made to compile on Linux i686, Mac OS X x86_64, Solaris Sparc and Android Arm. The Serval overlay network (milestone 3) and security architecture (milestone 5) were designed and prototyped around the NaCl library crypto_box and crypto_sign components.

Milestone 2. Create Rhizome directory structure for store-and-forward mesh SMS service

The first prototype of Serval's Rhizome file distribution system had been implemented in Java as part of Serval's “Batphone” Android app (now called “Serval Mesh”). It had been successfully trialled by New Zealand Red Cross in a field exercise in March, 2012. However, in that trial, Mesh SMS messages were not carried via Rhizome, but via a direct-connection protocol that has now been superseded.

In fulfilment of this milestone, the Java prototype of Rhizome was re-implemented in C in the Serval DNA component, and the prototype Java code removed. A command-line oriented API was designed around the Serval DNA component, with a JNI wrapper for direct invocation from within Java. Automated test cases were then developed in Bash (shell script) to formalise many of the Rhizome API contracts and facilitate further development without risk of regression. These tests now play a central role in the Serval team's daily work, and some development is now performed in a test-driven fashion.

The Mesh SMS (called MeshMS) Java code was rewritten to use the new Rhizome API as its transport, and was demonstrated with moderate success at a Shuttleworth Foundation summit in Berlin in June 2012. A single, automated MeshMS test case has been developed, which runs on two Android phones connected to the developer's laptop using USB. However, testing of MeshMS is still a slow process subject to many external dependencies, and is largely manual.

The MeshMS Java code was developed as part of the "Batphone" app for Android, so is unavailable on the OpenBTS platform, which only contains the Serval DNA component. The integrated Serval/OpenBTS platform will forward MeshMS messages between other Serval nodes (by supporting Rhizome), but it cannot inject or extract MeshMS messages in order to provide a GSM SMS/MeshMS gateway.

Some remedial work contemplated for a second or subsequent Agreement would be to re-implement MeshMS in C as part of the Serval DNA component and deprecate the Java code, so that MeshMS became a “core” Serval service defined and guaranteed by a suite of automated tests. A secure Commotion SMS service could then be developed to complement secure Commotion voice calls.

Milestone 3. Mesh Datagram Protocol (MDP)

Mesh Datagram Protocol (MDP) was designed using a 256-bit Serval Identity (SID) as the fundamental network address. The SID is a cryptographic NaCl public key for which only one Mesh user possesses the secret key.

MDP is designed as a OSI Layer 3 ("Network") protocol, and could be implemented directly over a WiFi MAC layer or Ethernet switching fabric. However, MDP was implemented for this contract as an IP Overlay network, using the host's native IP routing to detect and reach neighbouring nodes within Wi-Fi range. This was sufficient to support Rhizome and single-hop voice calls (see milestone 4 below), but does not support multi-hop voice calls or multi-hop Distributed Numbering Architechure (DNA) queries.

MDP Overlay frames could be routed to distant nodes using a mesh routing protocol such as OLSR or B.A.T.M.A.N.. As some final activity, Serval DNA was extended to route using OLSRd and tested on very simple mesh topologies. Some remedial work suggested for the Second Agreement would be to progress Serval's OLSR integration to improve peer discovery and resolve issues arising from larger mesh topologies.

As part of the development of MDP, a new Serval mesh routing protocol based loosely on B.A.T.M.A.N. was built into Serval DNA, so that Serval multi-hop voice calls and number resolution will work in a Serval-only mesh network. This new protocol will serve as a vehicle for future research into scalable and practical mesh networking, but is not within the scope of this Agreement, has not been proven, and is mentioned here for interest only.

Milestone 4. Voice calls via Mesh Datagram Protocol

Serval's own Voice over Mesh Protocol (VoMP) was designed and implemented in Serval DNA, using Mesh Datagram Protocol (MDP) as its transport, to supplant the SIP/SSIP and RTP/zRTP suite of protocols that are conventionally used for VoIP and were used in earlier releases of the Serval Mesh (app for Android).

The Serval DNA implementation of Voice over Mesh Protocol (VoMP) was tested manually under different conditions. It suffers from buffer inflation and echo, which could be remedied under the Second Agreement.

Milestone 5. Integration of security into all features of Serval

The Serval security design was developed and is described in the Security Framework.

The design is pending finalisation and review by experienced security practitioners and cryptographers, and this task is the focus of the Second Agreement work item 5, Resolution of pending NaCl issues.

Milestone 6. Integration of OpenBTS dial plan with DNA backend

The Serval DNA component was ported to the OpenBTS platform and integrated with the OpenBTS software. This work involved two main components:

Two sample configurations, one simple and one advanced for OpenBTS, were developed, containing the Asterisk dial plan. A Python AGI script was developed to allow the dial plan to perform DNA queries. A Python DNA Helper script was developed to allow DNA queries to discover GSM phones in other cells.

The concept of operation, download and build instructions, and configuration are all documented in the following technical documents:

Calls were successfully placed in the laboratory between a laptop running Serval DNA and a single Serval/OpenBTS unit configured with the advanced sample dial plan, communicating over a single hop. SIP clients were used at both ends, as local spectrum regulations prevented the use of the GSM transponder.

Milestone 7. Addition of SIP:MSIP and MSIP:SIP gateways for efficient GSM/VOIP handoff

Much of this milestone was achieved in milestone 6, by the VoMP channel driver for Asterisk. In Asterisk, every call goes through two channel drivers, one for each end point. In the case of calls to and from an external VoIP service, another Asterisk channel driver performs the necessary SIP/RTP conversion.

Tests using SIP clients showed that the SIP-VoMP gateway functions work in Asterisk.