README.md

   1 # libcontrac ReadMe
   2
   3 libcontrac is an implementation of the 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 ./configure
  13 make
  14 make check
  15 make install
  16 ```
  17
  18 ## Usage
  19
  20 Include header files.
  21 ```
  22 #include "contrac/contrac.h"
  23 #include "contrac/rpi.h"
  24 #include "contrac/dtk.h"
  25 #include "contrac/rpi_list.h"
  26 #include "contrac/rpi_list.h"
  27 #include "contrac/matches.h"
  28 ```
  29
  30 ### Broadcasting and uploading keys
  31
  32 Most of the functionality revolves around the Conrac structure.
  33
  34 Create and initialise the structure as follows. The day and interval number
  35 should be set appropriately.
  36
  37 ```
  38 Contrac * contrac = contrac_new();
  39 contrac_generate_tracing_key(contrac);
  40 contrac_set_day_number(contrac, 23);
  41 contrac_set_time_interval_number(contrac, 76);
  42 ```
  43
  44 Get the Rolling Proxmity 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 Rpi * rpi = rpi_new();
  63
  64 // Add captured bytes at given time
  65 rpi_assign(rpi, captured_bytes, time_interval_number);
  66 rpi_list_append(rpis, rpi);
  67 ```
  68
  69 Construct a list of DTKs from data downloaded from a Diagnosis Server.
  70 ```
  71 DtkList * dtks = dtk_list_new();
  72 Dtk * dtk = dtk_new();
  73
  74 // Add data downloaded from the server
  75 dtk_assign(dtk, dtk_bytes, day_number);
  76 dtk_list_append(dtks, dtk);
  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 More information can be found at: https://www.flypig.co.uk/contrac
 109
 110 The source code can be obtained from git:
 111
 112 git clone git@www.flypig.org.uk:libcontrac
 113
 114 I can be contacted via one of the following.
 115
 116  * My website: https://www.flypig.co.uk
 117  * Email: at david@flypig.co.uk
 118