6 * libcontrac is an implementation of the Apple/Google Contact Tracing API.
8 * See the draft specs: https://www.apple.com/covid19/contacttracing/
12 * If you have autoconf you can install as follows.
15 * autoreconf --install
24 * Include header files.
26 * #include "contrac/contrac.h"
27 * #include "contrac/rpi.h"
28 * #include "contrac/dtk.h"
29 * #include "contrac/rpi_list.h"
30 * #include "contrac/rpi_list.h"
31 * #include "contrac/matches.h"
34 * ### Broadcasting and uploading keys
36 * Most of the functionality is managed through the opaque `Contrac` structure.
38 * Create and initialise the structure as follows. The update call updates the
39 * Daily Tracing Key and Rolling Proximity Identifier based on the current time.
42 * Contrac * contrac = contrac_new();
43 * // Generates a random Tracing Key if one hasn't yet been set
44 * contrac_update_current_time(data);
47 * Get the Rolling Proximity Identifier for broadcast in Bluetooth beacons.
49 * // Returns a buffer containing RPI_SIZE bytes of data
50 * unsigned char const * rpi = contrac_get_proximity_id(contrac);
53 * Get the Daily Tracing Key to upload to a Diagnosis Server in case of a positive
56 * // Returns a buffer containing DTK_SIZE bytes of data
57 * unsigned char const * dtk = contrac_get_daily_key(contrac);
60 * ### Receiving and matching keys
62 * Add RPIs captured via Bluetooth to an RPI list.
64 * RpiList * rpis = rpi_list_new();
65 * // Add bytes captured at a given time to the list
66 * rpi_list_add_beacon(rpis, captured_bytes, time_interval_number);
69 * Construct a list of DTKs using data downloaded from a Diagnosis Server.
71 * DtkList * dtks = dtk_list_new();
72 * // Add data downloaded from a Diagnosis Server to the list
73 * dtk_list_add_diagnosis(dtks, dtk_bytes, day_number);
76 * Having collected these two lists any matches can be tested for as follows.
79 * MatchList * matches = match_list_new();
80 * match_list_find_matches(matches, rpis, dtks);
82 * if (match_list_count(matches) > 0) {
83 * printf("Exposure identified, follow medical advice\n");
91 * match_list_delete(matches);
92 * rpi_list_delete(rpis);
93 * dtk_list_delete(dtks);
94 * contrac_delete(contrac);
99 * @defgroup KeyGeneration Key Generation
100 * @brief Core Contact Tracing functionality
102 * This class provides the core Contact Tracing functionality. It provides an
104 * 1. Generating a random Tracing Key.
105 * 2. Generating a Daily Tracing Key based on the current day number.
106 * 3. Generating a Rolling Proximity Identifier based on the current time
109 * Values can be extracted and set in binary or base64 format.
114 * @defgroup Utils Utilities
115 * @brief Static utility functions
117 * Provides various static utitlity functions. In particular:
119 * base64 encoding and decoding functionality.
120 * Time conversion: from epoch to day numbers and time interval numbers.
125 * @defgroup DailyTracingKey Daily Tracing Key
126 * @brief Daily Tracing Key functionality
128 * This class is used to generate and manage the Daily Tracing Key (DTK). It's
129 * largely internal. The functionality from \ref Contrac should generally be
130 * used in preference to this.
135 * @defgroup RandomProximityIdentifier Random Proximity Identifier
136 * @brief Proximity Identifier functionality
138 * This class is used to generate and manage the Random Proximity Identifier
139 * (RPI). It's largely internal. The functionality from \ref Contrac should
140 * generally be used in preference to this.
145 * @defgroup Containers Containers
146 * @brief Provides containers for managing lists of items
148 * This allows the simplified management of lists of Dtk and Rpi objects. This
149 * is useful when checking DTKs received from a Diagnosis Server with RPIs
150 * captured over Bluetooth. The two can be easily stored and passed into the
151 * \ref match_list_find_matches() function.
156 * @defgroup Matching Matching
157 * @brief Provides a way to match collected RPIs with downloaded DTKs.
159 * This class provides functionality allowing RPIs that have been collected
160 * over Bluetooth to be matched against DTKs downloaded from a Diagnosis
166 * @defgroup Logging Logging
167 * @brief Allows output to be sent to the log
169 * This is a simple set of functions and macros that allows strings to be
170 * recorded in the syslog.