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 like this:
  10
  11 ```
  12 autoreconf --install
  13 ./configure
  14 make
  15 make install
  16 ```
  17
  18 You can also run the unit tests and build the
  19 [documentation](https://www.flypig.co.uk/docs/libcontrac/):
  20 ```
  21 make check
  22 make doxygen
  23 ```
  24
  25 ## Usage
  26
  27 Include header files.
  28 ```
  29 #include "contrac/contrac.h"
  30 #include "contrac/rpi.h"
  31 #include "contrac/dtk.h"
  32 #include "contrac/rpi_list.h"
  33 #include "contrac/rpi_list.h"
  34 #include "contrac/matches.h"
  35 ```
  36
  37 ### Broadcasting and uploading keys
  38
  39 Most of the functionality is managed through the opaque `Contrac` structure.
  40
  41 Create and initialise the structure as follows. The update call updates the
  42 Daily Tracing Key and Rolling Proximity Identifier based on the current time.
  43
  44 ```
  45 Contrac * contrac = contrac_new();
  46 // Generates a random Tracing Key if one hasn't yet been set
  47 contrac_update_current_time(data);
  48 ```
  49
  50 Get the Rolling Proximity Identifier for broadcast in Bluetooth beacons.
  51 ```
  52 // Returns a buffer containing RPI_SIZE bytes of data
  53 unsigned char const * rpi = contrac_get_proximity_id(contrac);
  54 ```
  55
  56 Get the Daily Tracing Key to upload to a Diagnosis Server in case of a positive
  57 test result.
  58 ```
  59 // Returns a buffer containing DTK_SIZE bytes of data
  60 unsigned char const * dtk = contrac_get_daily_key(contrac);
  61 ```
  62
  63 ### Receiving and matching keys
  64
  65 Add RPIs captured via Bluetooth to an RPI list.
  66 ```
  67 RpiList * rpis = rpi_list_new();
  68 // Add bytes captured at a given time to the list
  69 rpi_list_add_beacon(rpis, captured_bytes, time_interval_number);
  70 ```
  71
  72 Construct a list of DTKs using data downloaded from a Diagnosis Server.
  73 ```
  74 DtkList * dtks = dtk_list_new();
  75 // Add data downloaded from a Diagnosis Server to the list
  76 dtk_list_add_diagnosis(dtks, dtk_bytes, day_number);
  77 ```
  78
  79 Having collected these two lists any matches can be tested for as follows.
  80
  81 ```
  82 MatchList * matches = match_list_new();
  83 match_list_find_matches(matches, rpis, dtks);
  84
  85 if (match_list_count(matches) > 0) {
  86         printf("Exposure identified, follow medical advice\n");
  87 }
  88 ```
  89
  90 ### Cleaning up
  91
  92 Finally, clean up.
  93 ```
  94 match_list_delete(matches);
  95 rpi_list_delete(rpis);
  96 dtk_list_delete(dtks);
  97 contrac_delete(contrac);
  98 ```
  99
 100 ## Licence
 101
 102 Copyright (c) David Llewellyn-Jones, 2020
 103
 104 libcontrac is released under the GPL v2 Licence. Read COPYING for information on the license.
 105
 106 ## Contact and Links
 107
 108 Library home page: https://www.flypig.co.uk/contrac
 109
 110 API documentation: https://www.flypig.co.uk/docs/libcontrac/
 111
 112 Source code from git:
 113 ```
 114 git clone git@www.flypig.org.uk:libcontrac
 115 ```
 116
 117 I can be contacted via one of the following.
 118
 119  * My website: https://www.flypig.co.uk
 120  * Email: at david@flypig.co.uk
 121