README.md

   1 # libcontrac ReadMe
   2
   3 libcontrac is an implementation of the Apple/Google Contact Tracing API.
   4
   5 See the draft specs: https://www.apple.com/covid19/contacttracing/
   6
   7 ## Install
   8
   9 If you have autoconf you can install as follows.
  10
  11 ```
  12 autoreconf --install
  13 ./configure
  14 make
  15 make check
  16 make install
  17 ```
  18
  19 ## Usage
  20
  21 Include header files.
  22 ```
  23 #include "contrac/contrac.h"
  24 #include "contrac/rpi.h"
  25 #include "contrac/dtk.h"
  26 #include "contrac/rpi_list.h"
  27 #include "contrac/rpi_list.h"
  28 #include "contrac/matches.h"
  29 ```
  30
  31 ### Broadcasting and uploading keys
  32
  33 Most of the functionality revolves around the opaque `Contrac` structure.
  34
  35 Create and initialise the structure as follows. The day and interval number
  36 should be set appropriately.
  37
  38 ```
  39 Contrac * contrac = contrac_new();
  40 // Generates a random Tracing Key if one hasn't yet been set
  41 contrac_update_current_time(data);
  42 ```
  43
  44 Get the Rolling Proximity Identifier for broadcast in Bluetooth beacons.
  45 ```
  46 // Returns a buffer containing RPI_SIZE bytes of data
  47 const unsigned char * rpi = contrac_get_proximity_id(contrac);
  48 ```
  49
  50 Get the Daily Tracing Key to upload to a Diagnosis Server in case of a positive
  51 test result.
  52 ```
  53 // Returns a buffer containing DTK_SIZE bytes of data
  54 const unsigned char * dtk = contrac_get_daily_key(contrac);
  55 ```
  56
  57 ### Receiving and matching keys
  58
  59 Add RPIs captured via Bluetooth to an RPI list.
  60 ```
  61 RpiList * rpis = rpi_list_new();
  62 // Add bytes captured at a given time to the list
  63 rpi_list_add_beacon(rpis, captured_bytes, time_interval_number);
  64 ```
  65
  66 Construct a list of DTKs from data downloaded from a Diagnosis Server.
  67 ```
  68 DtkList * dtks = dtk_list_new();
  69 // Add data downloaded from the server to the list
  70 dtk_list_add_diagnosis(dtks, dtk_bytes, day_number);
  71 ```
  72
  73 Having collected these two lists any matches can be tested for as follows.
  74
  75 ```
  76 MatchList * matches = match_list_new();
  77 match_list_find_matches(matches, rpis, dtks);
  78
  79 if (match_list_count(matches) > 0) {
  80         printf("Exposure identified, follow medical advice\n");
  81 }
  82 ```
  83
  84 ### Cleaning up
  85
  86 Finally, clean up.
  87 ```
  88 match_list_delete(matches);
  89 rpi_list_delete(rpis);
  90 dtk_list_delete(dtks);
  91 contrac_delete(contrac);
  92 ```
  93
  94 ## Licence
  95
  96 Copyright (c) David Llewellyn-Jones, 2020
  97
  98 libcontrac is released under the GPL v2 Licence. Read COPYING for information on the license.
  99
 100 ## Contact and Links
 101
 102 More information can be found at: https://www.flypig.co.uk/contrac
 103
 104 The source code can be obtained from git:
 105 ```
 106 git clone git@www.flypig.org.uk:libcontrac
 107 ```
 108
 109 I can be contacted via one of the following.
 110
 111  * My website: https://www.flypig.co.uk
 112  * Email: at david@flypig.co.uk
 113