src/main.dox

   1 /**
   2  * @mainpage
   3  *
   4  * @version $(VERSION)
   5  *
   6  * libcontrac is an implementation of the Apple/Google Contact Tracing API.
   7  *
   8  * See the draft specs: https://www.apple.com/covid19/contacttracing/
   9  *
  10  * ## Install
  11  *
  12  * If you have autoconf you can install as follows.
  13  *
  14  * ```
  15  * autoreconf --install
  16  * ./configure
  17  * make
  18  * make check
  19  * make install
  20  * ```
  21  *
  22  * ## Usage
  23  *
  24  * Include header files.
  25  * ```
  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"
  32  * ```
  33  *
  34  * ### Broadcasting and uploading keys
  35  *
  36  * Most of the functionality is managed through the opaque `Contrac` structure.
  37  *
  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.
  40  *
  41  * ```
  42  * Contrac * contrac = contrac_new();
  43  * // Generates a random Tracing Key if one hasn't yet been set
  44  * contrac_update_current_time(data);
  45  * ```
  46  *
  47  * Get the Rolling Proximity Identifier for broadcast in Bluetooth beacons.
  48  * ```
  49  * // Returns a buffer containing RPI_SIZE bytes of data
  50  * unsigned char const * rpi = contrac_get_proximity_id(contrac);
  51  * ```
  52  *
  53  * Get the Daily Tracing Key to upload to a Diagnosis Server in case of a positive
  54  * test result.
  55  * ```
  56  * // Returns a buffer containing DTK_SIZE bytes of data
  57  * unsigned char const * dtk = contrac_get_daily_key(contrac);
  58  * ```
  59  *
  60  * ### Receiving and matching keys
  61  *
  62  * Add RPIs captured via Bluetooth to an RPI list.
  63  * ```
  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);
  67  * ```
  68  *
  69  * Construct a list of DTKs using data downloaded from a Diagnosis Server.
  70  * ```
  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);
  74  * ```
  75  *
  76  * Having collected these two lists any matches can be tested for as follows.
  77  *
  78  * ```
  79  * MatchList * matches = match_list_new();
  80  * match_list_find_matches(matches, rpis, dtks);
  81  *
  82  * if (match_list_count(matches) > 0) {
  83  *      printf("Exposure identified, follow medical advice\n");
  84  * }
  85  * ```
  86  *
  87  * ### Cleaning up
  88  *
  89  * Finally, clean up.
  90  * ```
  91  * match_list_delete(matches);
  92  * rpi_list_delete(rpis);
  93  * dtk_list_delete(dtks);
  94  * contrac_delete(contrac);
  95  * ```
  96  */
  97
  98 /**
  99  * @defgroup KeyGeneration Key Generation
 100  * @brief Core Contact Tracing functionality
 101  *
 102  * This class provides the core Contact Tracing functionality. It provides an
 103  * interfaces for:
 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
 107  *    interval number.
 108  *
 109  * Values can be extracted and set in binary or base64 format.
 110  *
 111  */
 112
 113 /**
 114  * @defgroup Utils Utilities
 115  * @brief Static utility functions
 116  *
 117  * Provides various static utitlity functions. In particular:
 118  *
 119  * base64 encoding and decoding functionality.
 120  * Time conversion: from epoch to day numbers and time interval numbers.
 121  *
 122  */
 123
 124 /**
 125  * @defgroup DailyTracingKey Daily Tracing Key
 126  * @brief Daily Tracing Key functionality
 127  *
 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.
 131  *
 132  */
 133
 134 /**
 135  * @defgroup RandomProximityIdentifier Random Proximity Identifier
 136  * @brief Proximity Identifier functionality
 137  *
 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.
 141  *
 142  */
 143
 144 /**
 145  * @defgroup Containers Containers
 146  * @brief Provides containers for managing lists of items
 147  *
 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.
 152  *
 153  */
 154
 155 /**
 156  * @defgroup Matching Matching
 157  * @brief Provides a way to match collected RPIs with downloaded DTKs.
 158  *
 159  * This class provides functionality allowing RPIs that have been collected
 160  * over Bluetooth to be matched against DTKs downloaded from a Diagnosis
 161  * Server.
 162  *
 163  */
 164
 165 /**
 166  * @defgroup Logging Logging
 167  * @brief Allows output to be sent to the log
 168  *
 169  * This is a simple set of functions and macros that allows strings to be
 170  * recorded in the syslog.
 171  *
 172  */
 173
 174