This is an old revision of the document!

New America Foundation - Contractor Agreement #32-OTIUSAID2013 “NAF5”

In February 2014, The Serval Project commenced a fifth round of work for the New America Foundation's Open Technology Institute to improve Serval DNA key management to allow Commotion OpenBTS to assign a Serval Identity (SID) to each GSM handset and migrate the identity from node to node to follow the GSM handset. This involves adding multi-key support for node addressing, allowing each node to announce multiple keys, and enabling multiple identities for each node.

Section 1: Work to be Performed (Scope of Work)

  • <BOOKMARK:R1>R1. Complete multi-SID support to serval routing engine and network layer.
  • <BOOKMARK:R2>R2. Implement servald id enter pin <PIN> which unlocks any SID identities protected by that PIN. If the SID already has a remote route, then the SID is not announced, but if no remote route exists, then the SID is announced as routable to this node. Returns the list of identities unlocked by that pin, and whether each is announced or already has a remote route.
  • <BOOKMARK:R3>R3. Implement SID roaming handshake procedure with servald id announce <SID>.
  • <BOOKMARK:R4>R4. Implement servald id relinquish pin <PIN|SID>, which releases the specified identities, and removes those identities from the local routing table.
  • <BOOKMARK:R5>R5. Add ability to store tags (which could be IEMI/IMSIs) in keyring entries.
  • <BOOKMARK:R6>R6. Implement servald id list [<TAG|SID>] that lists all unlocked identities, or only those unlocked identities with a supplied SID or tag (which could be the IEMI/IMSI).
  • <BOOKMARK:R7>R7. Extend test suite to cover the above.

Technical notes

The following implementation decisions were made during the course of the contract.

  • <BOOKMARK:N1>N1. The R2 and R4 keyring PIN enter and relinquish commands only affect entry PINS not keyring PINs. A running daemon can have at most one keyring PIN, which is set by the command-line option when started and cannot be relinquished while running.
    • the keyring.c code supports many “contexts”, each one with its own keyring PIN;
    • the first “context” is always created, and is for the null (empty) keyring PIN,
    • the commandline.c command-line API only supports a single --keyring-pin=PIN option, which creates a second “context” if used
    • the commandline.c command-line API already supports many --entry-pin=PIN options, however these should not be used for identities that are intended to be dynamically unlocked and locked (see N3)
  • <BOOKMARK:N2>N2. The daemon uses one SID as its main identity for its entire lifetime. All other SIDs are treated as secondary identities.
    • the daemon automatically unlocks all PIN-less identities it can find in the keyring on start-up, as well as any whose PINs are supplied on the command line
    • if there are none, the daemon creates a PIN-less one automatically and stores it in the keyring (for re-use in future sessions)
    • the daemon chooses the first unlocked, start-up SID as its main identity
    • the daemon does not allow its main identity to be relinquished (locked)
  • <BOOKMARK:N3>N3. Identity hand-over is only performed when a running daemon is requested to unlock an identity, and on no other occasions. In particular:
    • identity hand-over is not performed when a daemon starts up, to try to gain custody of its initial identities, so if two daemons are started with shared unlocked identities in their keyrings, there will be a routing conflict on those identities;
    • identity hand-over is not performed opportunistically (eg, at regular intervals), so a network merge between subnets which each had the same identity present will produce a routing conflict on that identity.



R1 – multi-SID routing

  • commit 73342a9 announces fake links in the routing table to secondary identities (see N2)
  • commit 0c1c767 automatically claims the route to any identity with an existing route when all possible routes disappear

R2servald id enter pin <PIN>

  • commit ae7e120 passes an entry PIN (see N1) to the Serval DNA daemon to unlock an identity in the keyring

R3servald id announce <SID>

  • commit b8ec568 implements the announce command:
    • if a route to that SID already exists, then sends a challenge/response request to the existing instance of this SID,
    • on receiving the request, the daemon locks the SID and responds
    • on receiving the response, the daemon proceeds to unlock the SID and announce it as routable locally

R4servald id relinquish pin <PIN|SID>

  • commit ef7351b either:
    • relinquishes (locks) a single identity specified by its SID (see N4), or
    • locks all identities that were unlocked with a given entry PIN (see N2)

R5 – keyring entry tags

  • commit c3b4d68 adds commands to read, write, and search a new key type for storing name/value pairs (“tags”):
    • the new keyring set tag <SID> <tag> <value> command sets the value of a given tag on a given identity (which must be unlocked by the supplied PIN options)
    • the keyring set did command and the new keyring set tag command both list all DIDs and tags of the affected identity (after applying the modification)
    • the keyring dump command now includes tags in its output
    • the keyring list command does NOT include tags in its output (for backward compatibility reasons)

R6servald id list [<tag>|<SID>]

  • commit 4e543f7 implements the new id list command:
    • lists identities currently unlocked in the running daemon
    • optionally filters by tag name and value
    • does not include tags or DIDs in its output
content/activity/naf5.1385704443.txt.gz · Last modified: 28/11/2013 21:54 by Andrew Bettison