Types and functions for dealing with security of Eddystone beacons. More...
Data Structures | |
struct | es_eid_config_t |
EID configuration. More... | |
Typedefs | |
typedef void(* | es_security_msg_cb_t )(uint8_t slot_no, es_security_msg_t msg_type) |
typedef nrf_ble_escs_lock_state_read_t | es_security_lock_state_t |
Eddystone beacon lock state. | |
typedef uint8_t | es_stopwatch_id_t |
Enumerations | |
enum | es_security_msg_t { ES_SECURITY_MSG_UNLOCKED, ES_SECURITY_MSG_EID, ES_SECURITY_MSG_IK, ES_SECURITY_MSG_ECDH, ES_SECURITY_MSG_STORE_TIME } |
Security events. More... | |
Functions | |
ret_code_t | es_security_init (es_security_msg_cb_t msg_cb) |
Function for initializing the security module. More... | |
ret_code_t | es_security_lock_code_update (uint8_t *p_encrypted_key) |
Function for updating the lock code and storing it to flash. More... | |
void | es_security_unlock_prepare (uint8_t *p_challenge) |
Function for reading the challenge and encrypting it with AES_ECB. More... | |
void | es_security_unlock_verify (uint8_t *p_unlock_token) |
Function for unlocking the beacon. More... | |
ret_code_t | es_security_random_challenge_generate (uint8_t *p_rand_chlg_buff) |
Function for generating a random challenge for the unlock characteristic. More... | |
void | es_security_client_pub_ecdh_receive (uint8_t slot_no, uint8_t *p_pub_ecdh, uint8_t scaler_k) |
Function for storing the public ECDH key from the client in the beacon registration process. More... | |
void | es_security_shared_ik_receive (uint8_t slot_no, uint8_t *p_encrypted_ik, uint8_t scaler_k) |
Function for storing the shared IK from the client in the beacon registration process. More... | |
void | es_security_pub_ecdh_get (uint8_t slot_no, uint8_t *p_edch_buffer) |
Function for copying the 32-byte ECDH key into the provided buffer. More... | |
uint32_t | es_security_clock_get (uint8_t slot_no) |
Function for returning the beacon clock value (in little endian). More... | |
void | es_security_update_time (void) |
Function for updating the beacon time counter. More... | |
uint8_t | es_security_scaler_get (uint8_t slot_no) |
Function for returning the rotation exponent scaler value. More... | |
void | es_security_eid_get (uint8_t slot_no, uint8_t *p_eid_buffer) |
Function for copying the 8-byte EID into the provided buffer. More... | |
void | es_security_eid_slots_restore (uint8_t slot_no, uint8_t k_scaler, uint32_t time_counter, const uint8_t *p_ik) |
Function for restoring an EID slot. More... | |
void | es_security_eid_slot_destroy (uint8_t slot_no) |
Function for destroying stored EID states. More... | |
void | es_security_plain_eid_id_key_get (uint8_t slot_no, uint8_t *p_key_buffer) |
Function for copying the 16-byte EID ID key into the provided buffer. More... | |
void | es_security_encrypted_eid_id_key_get (uint8_t slot_no, uint8_t *p_key_buffer) |
Function for copying the 16-byte LK encrypted EID ID key into the provided buffer. More... | |
void | es_security_tlm_to_etlm (uint8_t ik_slot_no, es_tlm_frame_t *p_tlm, es_etlm_frame_t *p_etlm) |
Function for converting a TLM frame into an eTLM frame using the EIK of the specified slot. More... | |
uint32_t | es_security_timing_seconds_passed (void) |
Function for getting the number of seconds passed since the last invocation. More... | |
void | es_security_timing_init (void) |
Function for initializing the security timing module. | |
uint32_t | es_stopwatch_check (es_stopwatch_id_t id) |
Function for getting the number of seconds passed since the last invocation. More... | |
ret_code_t | es_stopwatch_create (es_stopwatch_id_t *p_sw_id, uint32_t ticks_wrap) |
void | es_stopwatch_init (void) |
Function for initializing the security timing module. | |
Types and functions for dealing with security of Eddystone beacons.
enum es_security_msg_t |
void es_security_client_pub_ecdh_receive | ( | uint8_t | slot_no, |
uint8_t * | p_pub_ecdh, | ||
uint8_t | scaler_k | ||
) |
Function for storing the public ECDH key from the client in the beacon registration process.
This function starts a series of cryptographic activities, including the generation of temporary keys and EIDs.
[in] | slot_no | The index of the slot whose public ECDH key is retrieved. |
[in] | p_pub_ecdh | Pointer to the public ECDH. |
[in] | scaler_k | K rotation scaler. |
uint32_t es_security_clock_get | ( | uint8_t | slot_no | ) |
Function for returning the beacon clock value (in little endian).
[in] | slot_no | The index of the slot. |
void es_security_eid_get | ( | uint8_t | slot_no, |
uint8_t * | p_eid_buffer | ||
) |
Function for copying the 8-byte EID into the provided buffer.
[in] | slot_no | The index of the slot whose EID is retrieved. |
[out] | p_eid_buffer | Pointer to the buffer. |
void es_security_eid_slot_destroy | ( | uint8_t | slot_no | ) |
Function for destroying stored EID states.
This function should be called when the slot is either overwritten as another slot or cleared by writing an empty byte or a single 0.
[in] | slot_no | The index of the slot to destroy. |
void es_security_eid_slots_restore | ( | uint8_t | slot_no, |
uint8_t | k_scaler, | ||
uint32_t | time_counter, | ||
const uint8_t * | p_ik | ||
) |
Function for restoring an EID slot.
[in] | slot_no | The index of the slot to restore. |
[in] | k_scaler | K rotation scaler. |
[in] | time_counter | EID slot time counter value (in seconds). |
[in] | p_ik | Pointer to the identity key of the specified slot. |
void es_security_encrypted_eid_id_key_get | ( | uint8_t | slot_no, |
uint8_t * | p_key_buffer | ||
) |
Function for copying the 16-byte LK encrypted EID ID key into the provided buffer.
[in] | slot_no | The index of the EID slot whose encrypted IK is retrieved. |
[out] | p_key_buffer | Buffer for the key. |
ret_code_t es_security_init | ( | es_security_msg_cb_t | msg_cb | ) |
Function for initializing the security module.
[in] | msg_cb | Callback function. |
ret_code_t es_security_lock_code_update | ( | uint8_t * | p_encrypted_key | ) |
Function for updating the lock code and storing it to flash.
[in] | p_encrypted_key | Pointer to the new lock code. |
void es_security_plain_eid_id_key_get | ( | uint8_t | slot_no, |
uint8_t * | p_key_buffer | ||
) |
Function for copying the 16-byte EID ID key into the provided buffer.
[in] | slot_no | The index of the EID slot whose IK is retrieved. |
[out] | p_key_buffer | Buffer for the key. |
void es_security_pub_ecdh_get | ( | uint8_t | slot_no, |
uint8_t * | p_edch_buffer | ||
) |
Function for copying the 32-byte ECDH key into the provided buffer.
[in] | slot_no | The index of the slot whose public ECDH key is retrieved. |
[out] | p_edch_buffer | Pointer to the buffer. |
ret_code_t es_security_random_challenge_generate | ( | uint8_t * | p_rand_chlg_buff | ) |
Function for generating a random challenge for the unlock characteristic.
[out] | p_rand_chlg_buff | Pointer to a buffer to which the random challenge is copied. |
uint8_t es_security_scaler_get | ( | uint8_t | slot_no | ) |
Function for returning the rotation exponent scaler value.
[in] | slot_no | The index of the slot. |
void es_security_shared_ik_receive | ( | uint8_t | slot_no, |
uint8_t * | p_encrypted_ik, | ||
uint8_t | scaler_k | ||
) |
Function for storing the shared IK from the client in the beacon registration process.
This function starts a series of cryptographic activities, including the generation of temporary keys and EIDs.
[in] | slot_no | The index of the slot whose public ECDH key is retrieved. |
[in] | p_encrypted_ik | Pointer to the received IK. |
[in] | scaler_k | K rotation scaler. |
uint32_t es_security_timing_seconds_passed | ( | void | ) |
Function for getting the number of seconds passed since the last invocation.
If the function returns zero, the 'last time called' state is not updated. If a non-zero value is returned, the 'last time called' state will point to the last whole second.
void es_security_tlm_to_etlm | ( | uint8_t | ik_slot_no, |
es_tlm_frame_t * | p_tlm, | ||
es_etlm_frame_t * | p_etlm | ||
) |
Function for converting a TLM frame into an eTLM frame using the EIK of the specified slot.
[in] | ik_slot_no | The index of the EID slot whose IK is paired with the eTLM. |
[in] | p_tlm | Pointer to the TLM frame buffer. |
[out] | p_etlm | Pointer to the eTLM frame buffer. |
void es_security_unlock_prepare | ( | uint8_t * | p_challenge | ) |
Function for reading the challenge and encrypting it with AES_ECB.
The result of the encryption is compared with the provided unlock token in es_security_unlock_verify.
[in] | p_challenge | Pointer to the challenge buffer. |
void es_security_unlock_verify | ( | uint8_t * | p_unlock_token | ) |
Function for unlocking the beacon.
This function compares the result from es_security_unlock_prepare to the input unlock token and unlocks the beacon if matching.
[in] | p_unlock_token | The unlock token written by the client. |
void es_security_update_time | ( | void | ) |
Function for updating the beacon time counter.
This function checks how much time has passed since the last invocation and, if required, updates the EID, the temporary key, or both. The function generates an ES_SECURITY_MSG_STORE_TIME event for each active security slot every 24 hours.
uint32_t es_stopwatch_check | ( | es_stopwatch_id_t | id | ) |
Function for getting the number of seconds passed since the last invocation.
If the function returns zero, the 'last time called' state is not updated. If a non-zero value is returned, the 'last time called' state will point to the last whole second.