esp-ena/components/ena/include/ena-storage.h

// Copyright 2020 Lukas Haubaum
//
// Licensed under the GNU Affero General Public License, Version 3;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at

//     https://www.gnu.org/licenses/agpl-3.0.html
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
/**
 * @file
 * 
 * @brief storage part to store own TEKs and beacons
 * 
 */
#ifndef _ena_STORAGE_H_
#define _ena_STORAGE_H_

#include "ena-crypto.h"

#define ENA_STORAGE_LOG "ESP-ENA-storage"                                                  // TAG for Logging
#define ENA_STORAGE_PARTITION_NAME (CONFIG_ENA_STORAGE_PARTITION_NAME)                     // name of partition to use for storing
#define ENA_STORAGE_START_ADDRESS (CONFIG_ENA_STORAGE_START_ADDRESS)                       // start address of storage
#define ENA_STORAGE_TEK_MAX (CONFIG_ENA_STORAGE_TEK_MAX)                                   // Period of storing TEKs                                                                            // length of a stored beacon -> RPI keysize + AEM size + 4 Bytes for ENIN + 4 Bytes for RSSI
#define ENA_STORAGE_TEMP_BEACONS_MAX (CONFIG_ENA_STORAGE_TEMP_BEACONS_MAX)                 // Maximum number of temporary stored beacons                                                    // length of a stored beacon -> RPI keysize + AEM size + 4 Bytes for ENIN + 4 Bytes for RSSI
#define ENA_STORAGE_EXPOSURE_INFORMATION_MAX (CONFIG_ENA_STORAGE_EXPOSURE_INFORMATION_MAX) // Maximum number of stored exposure information

/**
 * @brief structure for TEK
 */
typedef struct __attribute__((__packed__))
{
    uint8_t key_data[ENA_KEY_LENGTH]; // key data for encryption
    uint32_t enin;                    // ENIN marking start of validity
    uint8_t rolling_period;           // period after validity start to mark key as expired
} ena_tek_t;

/**
 * @brief sturcture for storing a beacons
 */
typedef struct __attribute__((__packed__))
{
    uint8_t rpi[ENA_KEY_LENGTH];          // received RPI of beacon
    uint8_t aem[ENA_AEM_METADATA_LENGTH]; // received AEM of beacon
    uint32_t timestamp_first;             // timestamp of first recognition
    uint32_t timestamp_last;              // timestamp of last recognition
    int rssi;                             // average measured RSSI
} ena_beacon_t;

/**
 * @brief structure for storing a Exposure Information (combined ExposureInformation, ExposureWindow and ScanInstance from Google API >= 1.5)
 */
typedef struct __attribute__((__packed__))
{
    uint32_t day;            // Day of the exposure, using UTC, encapsulated as the time of the beginning of that day.
    int typical_attenuation; // Aggregation of the attenuations of all of a given diagnosis key's beacons received during the scan, in dB.
    int min_attenuation;     // Minimum attenuation of all of a given diagnosis key's beacons received during the scan, in dB.
    int duration_minutes;    // The duration of the exposure in minutes.
    int report_type;         // Type of diagnosis associated with a key.
} ena_exposure_information_t;

/**
 * @brief       read bytes at given address
 * 
 * @param[in]   address     the address to read bytes from
 * @param[out]  data        pointer to write the read data
 * @param[in]   size        how many bytes to read
 */
void ena_storage_read(size_t address, void *data, size_t size);

/**
 * @brief       store bytes at given address
 * 
 * @param[in]   address     the address to write bytes to
 * @param[in]   data        pointer to the data to write
 * @param[in]   size        how many bytes to write
 */
void ena_storage_write(size_t address, void *data, size_t size);

/**
 * @brief       erase storage at given address
 * 
 * @param[in]   address     the address to erase from
 * @param[in]   size        how many bytes to erase
 */
void ena_storage_erase(size_t address, size_t size);

/**
 * @brief       deletes bytes at given address and shift other data back
 * 
 * @param[in] address       the address to delete from
 * @param[in] end_address   the address to mark end of shift
 * @param[in] size          how many bytes to delete
 */
void ena_storage_shift_delete(size_t address, size_t end_address, size_t size);

/**
 * @brief       get timestamp of most recent exposure data
 * 
 * @return 
 *              unix timestamp
 */
uint32_t ena_storage_read_last_exposure_date(void);

/**
 * @brief       set timestamp of most recent exposure data
 * 
 * @param[in] timestamp unix timestamp
 */
void ena_storage_write_last_exposure_date(uint32_t timestamp);

/**
 * @brief       get number of stored TEKs
 * 
 * @return
 *              total number of TEKs stored
 */
uint32_t ena_storage_tek_count(void);

/**
 * @brief       get last stored TEK
 * 
 * @param[out]  tek         pointer to write last TEK to
 * 
 * @return 
 *              total number of TEKs stored
 */
uint32_t ena_storage_read_last_tek(ena_tek_t *tek);

/**
 * @brief       get stored TEK at given index
 * 
 * @param[in]   index       the index of the TEK to read
 * @param[out]  tek         pointer to write TEK to
 * 
 */
void ena_storage_get_tek(uint32_t index, ena_tek_t *tek);

/**
 * @brief       store given TEK
 * 
 * This will store the given TEK as new TEK.
 * 
 * @param[in]   tek         the tek to store
 */
void ena_storage_write_tek(ena_tek_t *tek);

/**
 * @brief       get number of stored exposure information
 * 
 * @return
 *              total number of exposure information stored
 */
uint32_t ena_storage_exposure_information_count(void);

/**
 * @brief       get exposure information at given index
 * 
 * @param[in]   index       the index of the exposure information to read
 * @param[out]  exposure_info   pointer to exposure information to write to
 */
void ena_storage_get_exposure_information(uint32_t index, ena_exposure_information_t *exposure_info);

/**
 * @brief       store exposure information
 * 
 * @param[in]   exposure_info   new exposure information to store 
 */
void ena_storage_add_exposure_information(ena_exposure_information_t *exposure_info);

/**
 * @brief       get number of stored temporary beacons
 * 
 * @return
 *              total number of temporary beacons stored
 */
uint32_t ena_storage_temp_beacons_count(void);

/**
 * @brief       get temporary beacon at given index
 * 
 * @param[in]   index       the index of the temporary beacon to read
 * @param[out]  beacon   pointer to temporary beacon to write to
 */
void ena_storage_get_temp_beacon(uint32_t index, ena_beacon_t *beacon);

/**
 * @brief       store temporary beacon
 * 
 * @param[in]   beacon   new temporary beacon to store 
 * 
 * @return 
 *              index of new stored beacon
 */
uint32_t ena_storage_add_temp_beacon(ena_beacon_t *beacon);

/**
 * @brief       store temporary beacon at given index
 * 
 * @param[in]   index       the index of the temporary beacon to overwrite
 * @param[in]   beacon   temporary beacon to store 
 */
void ena_storage_set_temp_beacon(uint32_t index, ena_beacon_t *beacon);

/**
 * @brief       remove temporary beacon at given index
 * 
 * @param[in]   index       the index of the temporary beacon to remove
 */
void ena_storage_remove_temp_beacon(uint32_t index);

/**
 * @brief       get number of permanently stored beacons
 * 
 * @return
 *              total number of beacons stored
 */
uint32_t ena_storage_beacons_count(void);

/**
 * @brief       get permanently stored beacon at given index
 * 
 * @param[in]   index       the index of the beacon to read
 * @param[out] beacon    pointer to to write to
 */
void ena_storage_get_beacon(uint32_t index, ena_beacon_t *beacon);

/**
 * @brief       permanently store beacon
 * 
 * @param[in]   beacon   new beacon to permanently store 
 */
void ena_storage_add_beacon(ena_beacon_t *beacon);

/**
 * @brief       remove beacon at given index
 * 
 * @param[in]   index       the index of the beacon to remove
 */
void ena_storage_remove_beacon(uint32_t index);

/**
 * @brief       erase the storage
 * 
 * This function completely deletes all stored data and resets the counters 
 * of TEKs, temporary beacon and beacon to zero.
 */
void ena_storage_erase_all(void);

/**
 * @brief       erase all stored TEKs
 * 
 * This function deletes all stored TEKs and resets counter to zero.
 */
void ena_storage_erase_tek(void);

/**
 * @brief       erase all stored exposure information
 * 
 * This function deletes all stored exposure information and resets counter to zero.
 */
void ena_storage_erase_exposure_information(void);

/**
 * @brief       erase all stored temporary beacons
 * 
 * This function deletes all stored temporary beacons and resets counter to zero.
 */
void ena_storage_erase_temporary_beacon(void);

/**
 * @brief       erase all permanently stored beacons
 * 
 * This function deletes all stored beacons and resets counter to zero.
 */
void ena_storage_erase_beacon(void);

/**
 * @brief       helper to dump a byte array as hash
 */
void ena_storage_dump_hash_array(uint8_t *data, size_t size);

/**
 * @brief       dump all stored TEKs to serial output
 * 
 * This function prints all stored TEKs to serial output in
 * the following CSV format: #,enin,tek
 */
void ena_storage_dump_teks(void);

/**
 * @brief       dump all stored exposure information to serial output
 * 
 * This function prints all stored exposure information to serial output in
 * the following CSV format: #,day,typical_attenuation,min_attenuation,duration_minutes,report_type
 */
void ena_storage_dump_exposure_information(void);

/**
 * @brief       dump all stored temporary beacons to serial output
 * 
 * This function prints all stored temporary beacons to serial output in
 * the following CSV format: #,timestamp_first,timestamp_last,rpi,aem,rssi
 */
void ena_storage_dump_temp_beacons(void);

/**
 * @brief       dump all stored beacons to serial output
 * 
 * This function prints all stored beacons to serial output in
 * the following CSV format: #,timestamp,rpi,aem,rssi
 */
void ena_storage_dump_beacons(void);

#endif