|
libcontrac
A library for contact tracing
|
Core Contact Tracing functionality. More...
Files | |
| file | contrac.c |
| Core Contact Tracing functionality. | |
| file | dtk_list.c |
| Provides a list of DTKs. | |
| file | rpi_list.c |
| Provides a list of RPIs. | |
| file | contrac.h |
| Core Contact Tracing functionality. | |
| file | contrac_private.h |
| Private header for the Core Contact Tracing functionality. | |
| file | dtk_list.h |
| Provides a list of DTKs. | |
| file | rpi_list.h |
| Provides a list of RPIs. | |
Data Structures | |
| struct | Contrac |
| The core structure for storing Contact Tracing state. More... | |
Macros | |
| #define | STATUS_TK (1 << 0) |
| #define | STATUS_DTK (1 << 1) |
| #define | STATUS_RPI (1 << 2) |
| #define | STATUS_INITIALISED (STATUS_TK | STATUS_DTK | STATUS_RPI) |
| #define | TK_SIZE (32) |
| #define | TK_SIZE_BASE64 (44) |
Functions | |
| Contrac * | contrac_new () |
| void | contrac_delete (Contrac *data) |
| bool | contrac_generate_tracing_key (Contrac *data) |
| bool | contrac_set_day_number (Contrac *data, uint32_t day_number) |
| bool | contrac_set_time_interval_number (Contrac *data, uint8_t time_interval_number) |
| bool | contrac_get_initialised (Contrac const *data) |
| uint32_t | contrac_get_day_number (Contrac *data) |
| uint8_t | contrac_get_time_interval_number (Contrac *data) |
| void | contrac_set_tracing_key (Contrac *data, unsigned char const *tracing_key) |
| unsigned char const * | contrac_get_tracing_key (Contrac const *data) |
| void | contrac_get_tracing_key_base64 (Contrac const *data, char *base64) |
| bool | contrac_set_tracing_key_base64 (Contrac *data, char const *tracing_key) |
| unsigned char const * | contrac_get_daily_key (Contrac const *data) |
| void | contrac_get_daily_key_base64 (Contrac const *data, char *base64) |
| unsigned char const * | contrac_get_proximity_id (Contrac const *data) |
| void | contrac_get_proximity_id_base64 (Contrac const *data, char *base64) |
| bool | contrac_update_current_time (Contrac *data) |
Core Contact Tracing functionality.
This class provides the core Contact Tracing functionality. It provides an interfaces for:
Values can be extracted and set in binary or base64 format.
| #define STATUS_DTK (1 << 1) |
A mask used internally with the status flags.
When set the flag indicates that the Daily Tracing Key has been correctly initialised.
| #define STATUS_INITIALISED (STATUS_TK | STATUS_DTK | STATUS_RPI) |
A mask used internally with the status flags.
When all of these flags are set it indicates that the structure is fully initialised.
| #define STATUS_RPI (1 << 2) |
A mask used internally with the status flags.
When set the flag indicates that the Rolling Proximity Identifier has been correctly initialised.
| #define STATUS_TK (1 << 0) |
A mask used internally with the status flags.
When set the flag indicates that the Tracing Key has been correctly initialised.
| #define TK_SIZE (32) |
The size in bytes of a Tracing Key in binary format
| #define TK_SIZE_BASE64 (44) |
The size in bytes of a Tracing Key in base64 format
| void contrac_delete | ( | Contrac * | data | ) |
Deletes an instance of the class, freeing up the memory allocated to it.
| data | The instance to free. |
| bool contrac_generate_tracing_key | ( | Contrac * | data | ) |
Generates a random Contact Tracing Key.
The operation may fail under certain circumstances, such as there being insufficient entropy in the system to guarantee a random result.
| data | The context object to work with. |
| unsigned char const * contrac_get_daily_key | ( | Contrac const * | data | ) |
Gets the Daily Tracing Key for the device in binary format.
This allows the Daily Tracing Key to be extracted. The Daily Tracing Key should be kept secret (to maintain privacy) until a positive test is confirmed, at which point the user may choose to upload the key to a Diagnosis Server, so that others can be notified.
The buffer returned will contain exactly DTK_SIZE (16) bytes of data in binary format. This may therefore contain null bytes, and the buffer will not necessarily be null terminated. Future operations may cause the data to change, so the caller should make a copy of the buffer rather than keeping the pointer to it.
| data | The context object to work with. |
| void contrac_get_daily_key_base64 | ( | Contrac const * | data, |
| char * | base64 | ||
| ) |
Gets the Daily Tracing Key for the device in base64 format.
This allows the Daily Tracing Key to be extracted. The Daily Tracing Key should be kept secret (to maintain privacy) until a positive test is confirmed, at which point the user may choose to upload the key to a Diagnosis Server, so that others can be notified.
The buffer provided must be at least DTK_SIZE_BASE64 + 1 (25) bytes long and will be filled out with the Tracing Key in base64 format (DTK_SIZE_BASE64 bytes) followed by a null terminator (1 byte).
| data | The context object to work with. |
| base64 | A buffer of at least DTK_SIZE_BASE64 + 1 bytes for the result. |
| uint32_t contrac_get_day_number | ( | Contrac * | data | ) |
Gets the current day number.
Gets the current day number used to generate the most recent DTK.
The day number is calculated as: (Number of Seconds since Epoch) / (60 * 60 * 24)
Which can be caluclated from the current epoch using the epoch_to_day_number() function.
| data | The context object to work with. |
| bool contrac_get_initialised | ( | Contrac const * | data | ) |
Gets whether the internal state has been fully configured or not.
The internal state must be fully configured before a Daily Tracing Key or Rolling Proximity Identifier can be calculated. This function returns whether it is in this state or not.
In order to fully configure the structure, a Tracing Key must either be generated using contrac_generate_tracing_key(), or set using either contrac_set_tracing_key() or contrac_set_tracing_key_base64().
In addition the day number and time interval number must be set using contrac_set_day_number() and contrac_set_time_interval_number() respectively.
Alternatively these can be set automatically based on the current time using contrac_update_current_time().
| data | The context object to work with. |
| unsigned char const * contrac_get_proximity_id | ( | Contrac const * | data | ) |
Gets the Rolling Proximity Identifier for the device in binary format.
This allows the Rolling Proximity Identifier to be extracted. The Rolling Proximity Identifier is for broadcast to other devices using BLE and changes frequently.
The buffer returned will contain exactly RPI_SIZE (16) bytes of data in binary format. This may therefore contain null bytes, and the buffer will not necessarily be null terminated. Future operations may cause the data to change, so the caller should make a copy of the buffer rather than keeping the pointer to it.
| data | The context object to work with. |
| void contrac_get_proximity_id_base64 | ( | Contrac const * | data, |
| char * | base64 | ||
| ) |
Gets the Rolling Proximity Identifier for the device in base64 format.
This allows the Rolling Proximity Identifier to be extracted. The Rolling Proximity Identifier is for broadcast to other devices using BLE and changes frequently.
The buffer provided must be at least RPI_SIZE_BASE64 + 1 (25) bytes long and will be filled out with the Tracing Key in base64 format (RPI_SIZE_BASE64 bytes) followed by a null terminator (1 byte).
| data | The context object to work with. |
| base64 | A buffer of at least RPI_SIZE_BASE64 + 1 bytes for the result. |
| uint8_t contrac_get_time_interval_number | ( | Contrac * | data | ) |
Gets the current time interval number.
Gets the current time interval number used to generate the most recent RPI.
The time interval number is calculated as: (Seconds Since Start of DayNumber) / (60 * 10)
and must fall in the interval [0, 143].
It can be caluclated from the current epoch using the epoch_to_time_interval_number() function.
| data | The context object to work with. |
| unsigned char const * contrac_get_tracing_key | ( | Contrac const * | data | ) |
Gets the Tracing Key for the device in binary format.
This allows the Tracing Key to be extracted. The Tracing Key should be kept secret (to maintain privacy), however it still may need to be extracted, for example so it can be saved in persistent storage between runs.
The buffer returned will contain exactly TK_SIZE (32) bytes of data in binary format. This may therefore contain null bytes, and the buffer will not necessarily be null terminated. Future operations may cause the data to change, so the caller should make a copy of the buffer rather than keeping the pointer to it.
| data | The context object to work with. |
| void contrac_get_tracing_key_base64 | ( | Contrac const * | data, |
| char * | base64 | ||
| ) |
Gets the Tracing Key for the device in base64 format.
This allows the Tracing Key to be extracted. The Tracing Key should be kept secret (to maintain privacy), however it still may need to be extracted, for example so it can be saved in persistent storage between runs.
The buffer provided must be at least TK_SIZE_BAS64 + 1 (45) bytes long and will be filled out with the Tracing Key in base64 format (TK_SIZE_BAS64 bytes) followed by a null terminator (1 byte).
| data | The context object to work with. |
| base64 | A buffer of at least TK_SIZE_BAS64 + 1 bytes for the result. |
| Contrac * contrac_new | ( | ) |
Creates a new instance of the class.
| bool contrac_set_day_number | ( | Contrac * | data, |
| uint32_t | day_number | ||
| ) |
Sets the current day number.
This will result in a new Daily Tracing Key being generated based on the day provided. If neither the Tracing Key nor the day have changed, the DTK will remain the same.
The day number is calculated as: (Number of Seconds since Epoch) / (60 * 60 * 24)
Which can be calculated from the current epoch using the epoch_to_day_number() function.
The operation may fail if a Tracing Key has yet to be configured.
| data | The context object to work with. |
| day_number | The day number used to generate the DTK. |
| bool contrac_set_time_interval_number | ( | Contrac * | data, |
| uint8_t | time_interval_number | ||
| ) |
Sets the current time interval number.
This will result in a new Rolling Proximity Idetifier being generated based on the time interval number. If none of the Tracing Key, day nor time interval have changed, the RPI will stay the same.
The time interval number is calculated as: (Seconds Since Start of DayNumber) / (60 * 10)
and must fall in the interval [0, 143].
It can be calculated from the current epoch using the epoch_to_time_interval_number() function.
The operation may fail if a Tracing Key or Daily Tracing Key have yet to be configured.
| data | The context object to work with. |
| time_interval_number | The time interval number to set. |
| void contrac_set_tracing_key | ( | Contrac * | data, |
| unsigned char const * | tracing_key | ||
| ) |
Sets the Tracing Key for the device in binary format.
When first configuring a system, the Tracing Key must be generated randomly, e.g. using contrac_generate_tracing_key().
However, on future runs it's important that the Tracing Key stays the same. In this case the key can be restored using this function.
The tracing_key buffer passed in must contain exactly TK_SIZE (32) bytes of data.It doen't have to be null terminated.
| data | The context object to work with. |
| tracing_key | The Tracing Key to set in binary format. |
| bool contrac_set_tracing_key_base64 | ( | Contrac * | data, |
| char const * | tracing_key | ||
| ) |
Sets the Tracing Key for the device in base64 format.
When first configuring a system, the Tracing Key must be generated randomly, e.g. using contrac_generate_tracing_key().
However, on future runs it's important that the Tracing Key stays the same. In this case the key can be restored using this function.
The tracing_key buffer passed in must contain exactly TK_SIZE_BASE64 (44) bytes of base64-encoded data. It can be null terminated, but doesn't need to be.
| data | The context object to work with. |
| tracing_key | The Tracing Key to set in base64 format. |
| bool contrac_update_current_time | ( | Contrac * | data | ) |
Updates the Daily Tracing Key and Random Proxmity Identifer.
The Daily Tracing Key changes every day, the Random Proximity Identifier changes every 10 minutes.
Calling this function will update them both based on the current system time.
Note that getting either the DTK or RPI does not cause an update, so if you want to get the correct values based on the time, it makes sense to call this function before getting them.
The operation may fail if the state has not yet been fully initialised (for example if a Tracing Key has not yet been generated or set).
| data | The context object to work with. |
1.8.13