From a3cdf3c942e2715986a45c9176167bf6c409b9eb Mon Sep 17 00:00:00 2001 From: Andrew Bettison Date: Mon, 29 Oct 2012 16:42:39 +1030 Subject: [PATCH] Add README.md and INSTALL.md Also capture some documentation of Serval Infrastructure services. --- INSTALL.md | 76 +++++++++++++++++++++++ README.md | 115 +++++++++++++++++++++++++++++++++++ doc/Serval-Infrastructure.md | 38 ++++++++++++ 3 files changed, 229 insertions(+) create mode 100644 INSTALL.md create mode 100644 README.md create mode 100644 doc/Serval-Infrastructure.md diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000..2cb375ed --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,76 @@ +Serval DNA Build and Test +========================= + +To build +-------- + + autoconf + ./configure + make + +Supported Targets +----------------- + +The Serval DNA code successfully builds for the following platforms: + + * Debian Linux, ix86 and x86\_64, kernels 2.6.x and 3.x, [gcc 4.4][] to [gcc 4.7][] + * [Android 2.2 “Froyo”][], Arm, Linux kernels 2.6.x and 3.x, [gcc 4.4][] supplied as + part of [Android NDK][] Revision 7b + * Mac OS X 10.7 “Lion”, x86\_64, [gcc 4.2][] available in [Xcode 4][] 3.2.6 + * Oracle SunOs 5.10 (Solaris), Sparc, [gcc 4.4][] + +Built artefacts +--------------- + +* **servald** is the main executable. + +* **libservald.so** is a shared library built only for Android, which is linked + into the [batphone][] Java executable at run time to provide the [JNI][] + entry points to servald. + +* **directory_service** is the executable for the Serval Infrastructure daemon. + +* **libmonitorclient.a** and **libmonitorclient.so** are libraries implementing + the client end of the monitor interface with the servald daemon. They are + linked into the [batphone][] Java executable at run time and contain [JNI][] + entry points to functions for managing the client end of a monitor connection + with the servald daemon. + +Testing +------- + +The scripts in the [tests](./tests/) directory require [Bash][] version 3.2.48 +or later. To run the tests, build the `servald` executable natively using [GNU +make][], then invoke them manually: + + ./tests/config + ./tests/directory_service + ./tests/dnahelper + ./tests/dnaprotocol + ./tests/jni + ./tests/rhizomeops + ./tests/rhizomeprotocol + ./tests/rhizomestress + ./tests/routing + ./tests/server + +There are options to run tests concurrently for faster results, and to select +subsets of test cases within each script. To see the options, give the +`--help` option to any script: + + ./tests/server --help + +The logs of the most recent test runs are under the [testlog](./testlog/) +directory. + + +[batphone]: https://github.com/servalproject/batphone +[Android 2.2 “Froyo”]: http://developer.android.com/about/versions/android-2.2-highlights.html +[Android NDK]: http://developer.android.com/tools/sdk/ndk/index.html +[gcc 4.2]: http://gcc.gnu.org/gcc-4.2/ +[Xcode 4]: https://developer.apple.com/xcode/ +[gcc 4.4]: http://gcc.gnu.org/gcc-4.4/ +[gcc 4.7]: http://gcc.gnu.org/gcc-4.7/ +[JNI]: http://en.wikipedia.org/wiki/Java_Native_Interface +[Bash]: http://en.wikipedia.org/wiki/Bash_(Unix_shell) +[GNU make]: http://www.gnu.org/software/make/ diff --git a/README.md b/README.md new file mode 100644 index 00000000..1304a256 --- /dev/null +++ b/README.md @@ -0,0 +1,115 @@ +Serval DNA +========== + +This repository contains the source code for the “core” Serval components +implemented in [GNU C][]: + + * The **Distributed Numbering Architecture** (DNA) is the key innovation that + makes mesh telephony viable in the absence of any infrastructure, eg, in the + aftermath of a natural disaster or in remote locations. It is a protocol + carried over MDP (see below) that allows any device to ask its neighboring + devices for a phone number (DID). Such a request will propagate through the + mesh, and any device may respond with the identity (SID) of a subscriber who + has “claimed” that DID. + + * The **Serval Keyring** is a flat file containing all the user identities on + a single device. Each identity is a set of elliptic curve secret + cryptographic keys that belong to a single “mesh subscriber”, indexed by the + subscriber's 256-bit public key, called a SID. Each identity in the keyring is + locked by its own user-chosen password (called a PIN in the code and + documentation), using elliptic curve cryptography to protect locked entries + from theft or tampering, and steganography to allow the user to plausibly + deny the existence of any locked identity. + + * The **Mesh Datagram Protocol** (MDP) is Serval's own layer 3 protocol + designed for secure mesh networking. It is completely independent of + Internet protocols such as IP and UDP, but for the time being is implemented + as an “overlay” network based on UDP/IP because that is the interface that + Linux and other operating systems provide for sending data over WiFi. + However, MDP could easily be implemented directly over a layer 2 data link + such as WiFi or Ethernet MAC. MDP uses subscribers' public keys (SID) as + source and destination addresses, and has a 32-bit port number analogous to + the 16-bit port number used in TCP/IP. + + * The **Rhizome** content distribution service is a storage engine implemented + using SQLite and a content-exchange protocol based on MDP and HTTP for the + pervasive dissemination of content like images, videos, documents, software + upgrades, etc. Each piece of content in Rhizome is called a “bundle”, which + has two parts: a *manifest* that describes the content, and the *payload*, + which is the content itself. Each bundle has its own unique cryptographic + identifier that allows any recipient to verify that it has not been tampered + with. + + * The **MeshMS** messaging service is implemented using Rhizome as its + transport, with each thread represented as a pair of bundles, one for each + direction. At present, the MeshMS logic is implemented in Java within the + [Serval Mesh][batphone] Android app, but is planned to be re-implemented in + C as part of Serval DNA (see [issue #28][]). + + * **Serval Infrastructure** services may optionally be deployed on any devices + in the mesh to expose external services to mesh subscribers and vice versa + (eg, VoIP gateways, SMS satellite links, packetised web), and to overcome + scalability limitations of a perfectly decentralised mesh (eg, central + telephone directory). + +Most of these services are performed by a [daemon][] process called +**servald**. Serval Infrastructure is implemented by a separate daemon called +**directory_service**. + +Copyright and licensing +----------------------- + +Serval DNA is [free software][] produced by the [Serval Project][] and many +[contributors][]. It is licensed to the public under the [GNU General Public +License version 2][GPL2]. All source code is freely available from the Serval +Project's [serval-dna][] Git repository on [GitHub][]. + +The copyright in most of the source code in Serval DNA is held by Serval +Project Inc., an organisation incorporated in the state of South Australia in +the Commonwealth of Australia for the purpose of developing the Serval mesh +software. + +The [Serval Project][] will accept contributions from individual developers who +have agreed to the [Serval Project Developer Agreement - Individual][individ], +and from organisations that have agreed to the [Serval Project Developer +Agreement - Entity][entity]. + +servald +------- + +The **servald** executable is a multi-purpose program designed to be invoked +directly from the command line and also via [JNI][] from within a Java program. +The following command will print a summary of all the operations that servald +offers: + + servald help + +Some operations are self-contained, some start and stop the servald daemon +process, some communicate with the servald daemon as an MDP client, and others +via a two-way [pipe][] called the monitor interface. + +For more detail on the purpose and usage of the servald command-line, see the +[doc](/servalproject/serval-dna/tree/master/doc/) directory. + +Build and test +-------------- + +Instructions for building and testing Serval DNA are in +[INSTALL.md][./INSTALL.md]. (If that link is does not work, try +[INSTALL.md](/servalproject/serval-dna/blob/master/INSTALL.md).) + + +[Serval Project]: http://www.servalproject.org/ +[serval-dna]: https://github.com/servalproject/serval-dna +[batphone]: https://github.com/servalproject/batphone +[issue #28]: https://github.com/servalproject/serval-dna/issues/28 +[GNU C]: http://gcc.gnu.org/ +[daemon]: http://en.wikipedia.org/wiki/Daemon_(computing) +[free software]: http://www.gnu.org/philosophy/free-sw.html +[contributors]: /servalproject/serval-dna/blob/master/CONTRIBUTORS.md +[GitHub]: https://github.com/servalproject +[GPL2]: http://www.gnu.org/licenses/gpl-2.0.html +[individ]: http://developer.servalproject.org/dokuwiki/lib/exe/fetch.php?media=content:software:developeragreements:serval_project_inc-individual.pdf +[entity]: http://developer.servalproject.org/dokuwiki/lib/exe/fetch.php?media=content:software:developeragreements:serval_project_inc-entity.pdf +[JNI]: http://en.wikipedia.org/wiki/Java_Native_Interface +[pipe]: http://www.kernel.org/doc/man-pages/online/pages/man2/pipe.2.html diff --git a/doc/Serval-Infrastructure.md b/doc/Serval-Infrastructure.md new file mode 100644 index 00000000..1eb0d85b --- /dev/null +++ b/doc/Serval-Infrastructure.md @@ -0,0 +1,38 @@ +Serval Infrastructure +===================== + +Based on design discussions between Andrew Bettison and Jeremy Lakeman in +September, 2012. + +In practice, these three services are built into a single daemon that can be +deployed into a mesh at many points. + +Serval Directory Service (SDS) +------------------------------ + +SDS is a registry that associates subscriber names and phone numbers (DID) with +subscriber identities (SID). Any subscriber may potentially register its +details with an SDS, and an SDS may also have its own source of registry +entries, such as an associated Asterisk exchange. SDS allows the decentralised +DNA Lookup architecture to be supplemented with infrastructure, ie, mesh nodes +offering persistent services or bridges out of the mesh. + +* Maps DID or Name → SID +* Responds to DNA Lookup requests +* Keeps registry of DNA entries (SID-DID-name) +* Accepts registrations and renewals of DNA entries +* Collects and caches DNA responses from local networks + +Serval Internet Location Service (SILS) +--------------------------------------- + +* Maps SID → IP address + port number (`sockaddr_in`) +* Keeps a SIR (Subscriber Internet Registry) +* Accepts registrations (signed) +* Responds to location requests + +Serval Internet Routing Service (SIRS) +-------------------------------------- + +* Forwards MDP packets to MDP nodes listening on IP addresses/ports +* Uses SILS to resolve destination IP addresses/ports