User Tools

Site Tools


content:activity:naf5

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
content:activity:naf5 [28/11/2013 20:53]
Andrew Bettison [Technical notes] minor improvements
content:activity:naf5 [01/12/2013 20:20] (current)
Andrew Bettison [Technical notes] refer to N5 from within N6
Line 1: Line 1:
 ====== New America Foundation - Contractor Agreement #32-OTIUSAID2013 “NAF5” ====== ====== New America Foundation - Contractor Agreement #32-OTIUSAID2013 “NAF5” ======
  
-In February 2014, [[:content:about]] commenced a fifth round of work for the [[http://www.newamerica.net/|New America Foundation]]'s [[http://oti.newamerica.net/|Open Technology Institute]] to improve [[:content:tech:Serval DNA]] key management to allow [[:content:tech:Commotion OpenBTS|Commotion OpenBTS]] to assign a [[:content:tech: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.+In September 2013, [[:content:about]] commenced a fifth round of work for the [[http://www.newamerica.net/|New America Foundation]]'s [[http://oti.newamerica.net/|Open Technology Institute]] to improve [[:content:tech:Serval DNA]] key management to allow [[:content:tech:Commotion OpenBTS|Commotion OpenBTS]] to assign a [[:content:tech: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) ===== ===== Section 1: Work to be Performed (Scope of Work) =====
Line 10: Line 10:
   * <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: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: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: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.   * <BOOKMARK:R7>**R7**. Extend test suite to cover the above.
  
Line 19: Line 19:
     * the [[https://github.com/servalproject/serval-dna/blob/21b123212c42c5b2ec94da07ca298b00d3f3d0a9/keyring.c|keyring.c]] code supports many "contexts", each one with its own keyring PIN;     * the [[https://github.com/servalproject/serval-dna/blob/21b123212c42c5b2ec94da07ca298b00d3f3d0a9/keyring.c|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 first "context" is always created, and is for the null (empty) keyring PIN,
-    * the [[https://github.com/servalproject/serval-dna/blob/21b123212c42c5b2ec94da07ca298b00d3f3d0a9/commandline.c|commandline.c]] command-line API only supports a single ''--keyring-pin=PIN'' option, which creates a second "context" if used +    * the [[https://github.com/servalproject/serval-dna/blob/21b123212c42c5b2ec94da07ca298b00d3f3d0a9/commandline.c|commandline.c]] command-line API only supports a single ''<nowiki>--keyring-pin=PIN</nowiki>'' option, which creates a second "context" if used 
-    * the [[https://github.com/servalproject/serval-dna/blob/21b123212c42c5b2ec94da07ca298b00d3f3d0a9/commandline.c|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]]**)+    * the [[https://github.com/servalproject/serval-dna/blob/21b123212c42c5b2ec94da07ca298b00d3f3d0a9/commandline.c|commandline.c]] command-line API already supports many ''<nowiki>--entry-pin=PIN</nowiki>'' 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//.   * <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     * 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
Line 26: Line 26:
     * the daemon chooses the first unlocked, start-up SID as its //main identity//     * 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)     * 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+  * <BOOKMARK:N3>**N3**. The Serval DNA daemon opens its keyring and applies the command-line supplied PINs before starting its routing engine.  This has the following consequences
-    * 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; +    * a daemon cannot perform identity hand-over requests while starting up, in order to gain custody of its initial 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.+    * thus, if two daemons are started with the same initially-unlocked identities in their keyrings, there will be a routing conflict on those identities; 
 +  <BOOKMARK:N4>**N4**. 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. 
 +  * <BOOKMARK:N5>**N5**. The existing [[https://github.com/servalproject/serval-dna/blob/21b123212c42c5b2ec94da07ca298b00d3f3d0a9/keyring.c|keyring.c]] code has a few flaws that were not remedied by this contract: 
 +    - unlocked keyring entries are used as a positive cache to avoid redundant unlocks: 
 +      * when unlocking with an entry PIN, the code first checks whether there are already any unlocked entries with the same PIN, and if so, does not perform an unlock scan through the keyring file 
 +      * however, if a PIN unlocks no entries, then re-trying the same PIN repeats the unlock scan (ie, there is no negative caching of PIN attempts) -- functionally this is of no consequence, its only impact is on CPU use and hence potentially on battery life 
 +    - the running Serval DNA daemon does not re-load keyring entries from the keyring file while running, which leads to "stale cache" types of problems: 
 +      * if another process modifies the keyring file (eg, runs a ''servald keyring add'' command), the running daemon will not be aware of the change until re-started 
 +      * the long-term objective is to re-implement all keyring operations as requests to the daemon process, which will resolve all "stale cache" and race condition bugs in one go 
 +      * however, in the meantime, the current implementation has some functional limitations ("bugs") of which developers must be aware 
 +  * <BOOKMARK:N6>**N6**.  The ''id relinquish sid'' command introduces a new functional flaw into keyring operations that is revealed by the following sequence of operations: 
 +      * one //enter PIN// command unlocks two more identities 
 +      * a //relinquish SID// command then locks one of these identities 
 +      * a subsequent //enter PIN// command will not re-unlock that identity, because the positive caching (see **[[#N5]]**) will detect that there are still identities bearing that PIN 
 +    * hence, in order for //enter PIN// to work as expected, ALL identities already unlocked with that PIN must be relinquished first 
 +    * for this reason, if the //relinquish SID// command is ever used, then for safety every //enter PIN// command should be immediately preceded by a matching //relinquish PIN// command
  
 ===== PROGRESS REPORT ===== ===== PROGRESS REPORT =====
  
-Summary of work performed to date;+Development commenced in September 2013, prior to the date of contract, and finished in mid October 2013.  This report was completed at the start of December 2013, when the contract was submitted for approval as complete. 
 +==== Implementation ====
  
-[[https://github.com/servalproject/serval-dna/commit/73342a9659cc086184418385813e0822eebfca5d|73342a9]] **[[#R1]]**, Announce fake links in the routing table to secondary identities.+**[[#R1]]** -- multi-SID routing (completed 9 October) 
 +  * commit [[https://github.com/servalproject/serval-dna/commit/73342a9659cc086184418385813e0822eebfca5d|73342a9]] announces fake links in the routing table to secondary identities (see **[[#N2]]**
 +  * commit [[https://github.com/servalproject/serval-dna/commit/0c1c767af00fb614689c8e0b953efb7629aa85f5|0c1c767]] automatically claims the route to any identity with an existing route when all possible routes disappear
  
-[[https://github.com/servalproject/serval-dna/commit/ae7e120ed537c07b7231f37b11c1c5ea64846516|ae7e120]] **[[#R2]]**, Pass a pin to servald to unlock an identity from the keyring.+**[[#R2]]** -- **''servald id enter pin <PIN>''** (completed 8 October) 
 +  * commit [[https://github.com/servalproject/serval-dna/commit/ae7e120ed537c07b7231f37b11c1c5ea64846516|ae7e120]] passes an entry PIN (see **[[#N1]]**to the Serval DNA daemon to unlock an identity in the keyring
  
-[[https://github.com/servalproject/serval-dna/commit/ef7351bddc0088f30386efd2c9ebf91ba4ee3fe2|ef7351b]] - **[[#R4]]**, Relinquish identities based on either the entry pin or SID.+**[[#R3]]** -- **''servald id announce <SID>''** (completed 13 October) 
 +  * commit [[https://github.com/servalproject/serval-dna/commit/b8ec5687115579ad468a3eea568283a9e0e37569|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 requestthe daemon locks the SID and responds 
 +    * on receiving the response, the daemon proceeds to unlock the SID and announce it as routable locally
  
-[[https://github.com/servalproject/serval-dna/commit/0c1c767af00fb614689c8e0b953efb7629aa85f5|0c1c767]] **[[#R1]]**, automatically claim the route to an identity with an existing route when all possible routes disappear.+**[[#R4]]** -- **''servald id relinquish pin <PIN|SID>''** (completed 14 October) 
 +  * commit [[https://github.com/servalproject/serval-dna/commit/ef7351bddc0088f30386efd2c9ebf91ba4ee3fe2|ef7351b]] either: 
 +    * relinquishes (locks) a single identity specified by its SID (see **[[#N6]]**)or 
 +    * locks all identities that were unlocked with a given entry PIN (see **[[#N2]]**) 
 +  * commit [[https://github.com/servalproject/serval-dna/commit/d5d5737f1cc74c639782a4111dc158d8b0307b02|d5d5737]] renamed the ''id revoke pin'' command to ''id relinquish pin'' to conform to contract
  
-[[https://github.com/servalproject/serval-dna/commit/b8ec5687115579ad468a3eea568283a9e0e37569|b8ec568]] **[[#R3]]**, When a SID is unlocked, but is a route already exists, automatically trigger a request / challenge / response handshake with the existing instance of this SID so it can be unlocked and routable locally.+**[[#R5]]** -- keyring entry tags (completed 12 November) 
 +  * commit [[https://github.com/servalproject/serval-dna/commit/9680b24f231bb8f8c2dfdfb3c38ef86091318bb6|9680b24]] adds commands to read, write, and search a new key type for storing name/value pairs ("tags"), subject to the limitations described in **[[#N5]]**
 +    * 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)
  
-[[https://github.com/servalproject/serval-dna/commit/c3b4d68|c3b4d68]] - **[[#R5]]**, Read / Write / and search new key type for storing tag name / value pairs. +**[[#R6]]** -- **''servald id list [<tag>|<SID>]''** (completed 12 November) 
- +  * commit [[https://github.com/servalproject/serval-dna/commit/4e543f7|4e543f7]] implements the new ''id list'' command
-[[https://github.com/servalproject/serval-dna/commit/4e543f7|4e543f7]] - **[[#R6]]**, Implement id list command to list identities currently unlocked in the running daemon. Allow filtering by tag name value pairs.+    * lists identities currently unlocked in the running daemon 
 +    * optionally filters by tag name and value 
 +    * does not include tags or DIDs in its output
  
 +**[[#R7]]** -- automated test cases (completed 12 November)
 +  * commit [[https://github.com/servalproject/serval-dna/commit/73342a9659cc086184418385813e0822eebfca5d|73342a9]] added the [[https://github.com/servalproject/serval-dna/blob/73342a9659cc086184418385813e0822eebfca5d/tests/routing|tests/routing]] ''multiple_ids'' test case for **[[#R1]]**
 +  * commit [[https://github.com/servalproject/serval-dna/commit/ae7e120ed537c07b7231f37b11c1c5ea64846516|ae7e120]] added the [[https://github.com/servalproject/serval-dna/blob/ae7e120ed537c07b7231f37b11c1c5ea64846516/tests/keyring|tests/keyring]] ''KeyringEntryPinServer'' test case for **[[#R2]]** (two ''id enter pin'' commands)
 +  * commit [[https://github.com/servalproject/serval-dna/commit/0c1c767af00fb614689c8e0b953efb7629aa85f5|0c1c767]] added the [[https://github.com/servalproject/serval-dna/tree/0c1c767af00fb614689c8e0b953efb7629aa85f5/tests/routing|tests/routing]] ''unlock_ids'' and ''migrate_id'' test cases for **[[#R3]]**
 +  * commit [[https://github.com/servalproject/serval-dna/commit/ef7351bddc0088f30386efd2c9ebf91ba4ee3fe2|ef7351b]] expanded the [[https://github.com/servalproject/serval-dna/blob/ef7351bddc0088f30386efd2c9ebf91ba4ee3fe2/tests/keyring|tests/keyring]] ''KeyringEntryPinServer'' and [[https://github.com/servalproject/serval-dna/tree/b8ec5687115579ad468a3eea568283a9e0e37569/tests/routing|tests/routing]] ''migrate_id'' test cases for **[[#R4]]** (added ''id revoke pin'' commands)
 +  * commit [[https://github.com/servalproject/serval-dna/commit/534b01ba2a5dc010d45e20f82a2c0b37805d9154|534b01b]] added the new [[https://github.com/servalproject/serval-dna/blob/534b01ba2a5dc010d45e20f82a2c0b37805d9154/tests/keyring|tests/keyring]] ''DidName'' test case, to ensure safety prior to refactoring the existing ''keyring set did'' command to use the new tag code
 +  * commit [[https://github.com/servalproject/serval-dna/commit/9680b24f231bb8f8c2dfdfb3c38ef86091318bb6|9680b24]] added the [[https://github.com/servalproject/serval-dna/tree/9680b24f231bb8f8c2dfdfb3c38ef86091318bb6/tests/keyring|tests/keyring]] test case ''SetTag'' for **[[#R5]]** (three ''keyring set tag'' commands)
 +  * commit [[https://github.com/servalproject/serval-dna/commit/0b404b02603ec914788fe2e1afebac12ba8aa7df|0b404b0]] added the [[https://github.com/servalproject/serval-dna/tree/0b404b02603ec914788fe2e1afebac12ba8aa7df/tests/keyring|tests/keyring]] test case ''ListTags'' for **[[#R6]]** (three ''id list'' commands)
content/activity/naf5.1385700806.txt.gz · Last modified: 28/11/2013 20:53 by Andrew Bettison