* Copyright David Llewellyn-Jones, 2020
* Released under the GPLv2.
*
- * @brief Core Contact Tracing functionality
+ * @brief Core Contact Tracing functionality
* @section DESCRIPTION
*
* This class provides the core Contact Tracing functionality. It provides an
// Defines
/**
- * Inernal flag mask.
+ * A mask used internally with the status flags.
*
* When set the flag indicates that the Tracing Key has been correctly
* initialised.
#define STATUS_TK (1 << 0)
/**
- * Inernal flag mask.
+ * A mask used internally with the status flags.
*
* When set the flag indicates that the Daily Tracing Key has been correctly
* initialised.
#define STATUS_DTK (1 << 1)
/**
- * Inernal flag mask.
+ * A mask used internally with the status flags.
*
* When set the flag indicates that the Rolling Proximity Identifier has been
* correctly initialised.
#define STATUS_RPI (1 << 2)
/**
- * Inernal flag mask.
+ * A mask used internally with the status flags.
*
* When all of these flags are set it indicates that the structure is fully
* initialised.
// Function definitions
/**
- * Create a new instance of the class.
+ * Creates a new instance of the class.
*
* @return The newly created object.
*/
}
/**
- * Delete an instance of the class, freeing up the memory allocated to it.
+ * Deletes an instance of the class, freeing up the memory allocated to it.
*
* @param data The instance to free.
*/
}
/**
- * Generate a random Contact Tracing Key.
+ * 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.
}
/**
- * Set the current 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
* The day number is calculated as:
* (Number of Seconds since Epoch) / (60 * 60 * 24)
*
- * Which can be caluclated from the current epoch using the
+ * 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.
*
* @param data The context object to work with.
+ * @param day_number The day number used to generate the DTK.
* @return true if the operation completed successfully, false otherwise.
*/
bool contrac_set_day_number(Contrac * data, uint32_t day_number) {
}
/**
- * Set the current 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
*
* and must fall in the interval [0, 143].
*
- * It can be caluclated from the current epoch using the
+ * 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
}
/**
- * Get whether the internal state has been fully configured or not.
+ * 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
}
/**
- * Set the Tracing Key for the device in binary format.
+ * 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.
+ *
+ * @param data The context object to work with.
+ * @return The day number most recently used to generate the DTK.
+ */
+uint32_t contrac_get_day_number(Contrac * data) {
+ return dtk_get_day_number(data->dtk);
+}
+
+/**
+ * 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.
+ *
+ * @param data The context object to work with.
+ * @return The time interval number most recently used to generate the RPI.
+ */
+uint8_t contrac_get_time_interval_number(Contrac * data) {
+ return rpi_get_time_interval_number(data->rpi);
+}
+
+/**
+ * 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().
* 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.
+ * data.It doen't have to be null terminated.
*
* @param data The context object to work with.
* @param tracing_key The Tracing Key to set in binary format.
}
/**
- * Get the Tracing Key for the device in binary format.
+ * 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
*
* 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.
+ * 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.
*
* @param data The context object to work with.
* @return The Tracing Key in binary format, not null terminated.
}
/**
- * Get the Tracing Key for the device in base64 format.
+ * 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
}
/**
- * Set the Tracing Key for the device in base64 format.
+ * 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().
}
/**
- * Get the Daily Tracing Key for the device in binary format.
+ * 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
*
* 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.
+ * 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.
*
* @param data The context object to work with.
* @return The Daily Tracing Key in binary format, not null terminated.
}
/**
- * Get the Daily Tracing Key for the device in base64 format.
+ * 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
}
/**
- * Get the Rolling Proximity Identifier for the device in binary format.
+ * 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
*
* 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.
+ * 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.
*
* @param data The context object to work with.
* @return The Rolling Proximity Identifier in binary format, not null
}
/**
- * Get the Rolling Proximity Identifier for the device in base64 format.
+ * 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
}
/**
- * Update the Daily Tracing Key and Random Proxmity Identifer.
+ * Updates the Daily Tracing Key and Random Proxmity Identifer.
*
* The Daily Tracing Key changes every day, the Random Proximity Identifier
* changes every 10 minutes.
projects / libcontrac.git / blobdiff