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 contrac_generate_tracing_key(contrac);
  41 contrac_set_day_number(contrac, 23);
  42 contrac_set_time_interval_number(contrac, 76);
  43 ```
  44
  45 Get the Rolling Proximity Identifier for broadcast in Bluetooth beacons.
  46 ```
  47 // Returns a buffer containing RPI_SIZE bytes of data
  48 const unsigned char * rpi = contrac_get_proximity_id(contrac);
  49 ```
  50
  51 Get the Daily Tracing Key to upload to a Diagnosis Server in case of a positive
  52 test result.
  53 ```
  54 // Returns a buffer containing DTK_SIZE bytes of data
  55 const unsigned char * dtk = contrac_get_daily_key(contrac);
  56 ```
  57
  58 ### Receiving and matching keys
  59
  60 Add RPIs captured via Bluetooth to an RPI list.
  61 ```
  62 RpiList * rpis = rpi_list_new();
  63
  64 // Add bytes captured at a given time to the list
  65 Rpi * rpi = rpi_new();
  66 rpi_assign(rpi, captured_bytes, time_interval_number);
  67 rpi_list_append(rpis, rpi);
  68 ```
  69
  70 Construct a list of DTKs from data downloaded from a Diagnosis Server.
  71 ```
  72 DtkList * dtks = dtk_list_new();
  73
  74 // Add data downloaded from the server to the list
  75 Dtk * dtk = dtk_new();
  76 dtk_assign(dtk, dtk_bytes, day_number);
  77 dtk_list_append(dtks, dtk);
  78 ```
  79
  80 Having collected these two lists any matches can be tested for as follows.
  81
  82 ```
  83 MatchList * matches = match_list_new();
  84 match_list_find_matches(matches, rpis, dtks);
  85
  86 if (match_list_count(matches) > 0) {
  87         printf("Exposure identified, follow medical advice\n");
  88 }
  89 ```
  90
  91 ### Cleaning up
  92
  93 Finally, clean up.
  94 ```
  95 match_list_delete(matches);
  96 rpi_list_delete(rpis);
  97 dtk_list_delete(dtks);
  98 contrac_delete(contrac);
  99 ```
 100
 101 ## Licence
 102
 103 Copyright (c) David Llewellyn-Jones, 2020
 104
 105 libcontrac is released under the GPL v2 Licence. Read COPYING for information on the license.
 106
 107 ## Contact and Links
 108
 109 More information can be found at: https://www.flypig.co.uk/contrac
 110
 111 The source code can be obtained from git:
 112 ```
 113 git clone git@www.flypig.org.uk:libcontrac
 114 ```
 115
 116 I can be contacted via one of the following.
 117
 118  * My website: https://www.flypig.co.uk
 119  * Email: at david@flypig.co.uk
 120