nRF5 SDK v13.0.0
Data Structures | Typedefs | Enumerations | Functions

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_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.
 

Detailed Description

Types and functions for dealing with security of Eddystone beacons.

Enumeration Type Documentation

Security events.

Enumerator
ES_SECURITY_MSG_UNLOCKED 

Beacon is unlocked.

ES_SECURITY_MSG_EID 

EID has been generated.

ES_SECURITY_MSG_IK 

IK has been generated.

ES_SECURITY_MSG_ECDH 

Public ECDH has been generated.

ES_SECURITY_MSG_STORE_TIME 

EID slot time must be stored.

Function Documentation

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.

Parameters
[in]slot_noThe index of the slot whose public ECDH key is retrieved.
[in]p_pub_ecdhPointer to the public ECDH.
[in]scaler_kK rotation scaler.
uint32_t es_security_clock_get ( uint8_t  slot_no)

Function for returning the beacon clock value (in little endian).

Parameters
[in]slot_noThe index of the slot.
Returns
32-bit clock value.
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.

Parameters
[in]slot_noThe index of the slot whose EID is retrieved.
[out]p_eid_bufferPointer 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.

Parameters
[in]slot_noThe 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.

Parameters
[in]slot_noThe index of the slot to restore.
[in]k_scalerK rotation scaler.
[in]time_counterEID slot time counter value (in seconds).
[in]p_ikPointer 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.

Parameters
[in]slot_noThe index of the EID slot whose encrypted IK is retrieved.
[out]p_key_bufferBuffer for the key.
ret_code_t es_security_init ( es_security_msg_cb_t  msg_cb)

Function for initializing the security module.

Parameters
[in]msg_cbCallback function.
Returns
See app_timer_start for possible return values.
ret_code_t es_security_lock_code_update ( uint8_t *  p_encrypted_key)

Function for updating the lock code and storing it to flash.

Parameters
[in]p_encrypted_keyPointer to the new lock code.
Returns
See es_flash_access_lock_key for possible return values.
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.

Parameters
[in]slot_noThe index of the EID slot whose IK is retrieved.
[out]p_key_bufferBuffer 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.

Parameters
[in]slot_noThe index of the slot whose public ECDH key is retrieved.
[out]p_edch_bufferPointer 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.

Parameters
[out]p_rand_chlg_buffPointer to a buffer to which the random challenge is copied.
Returns
See sd_rand_application_vector_get for possible return values.
uint8_t es_security_scaler_get ( uint8_t  slot_no)

Function for returning the rotation exponent scaler value.

Parameters
[in]slot_noThe index of the slot.
Returns
K rotation scaler.
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.

Parameters
[in]slot_noThe index of the slot whose public ECDH key is retrieved.
[in]p_encrypted_ikPointer to the received IK.
[in]scaler_kK rotation scaler.
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.

Parameters
[in]ik_slot_noThe index of the EID slot whose IK is paired with the eTLM.
[in]p_tlmPointer to the TLM frame buffer.
[out]p_etlmPointer 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.

Parameters
[in]p_challengePointer to the challenge buffer.
Returns
See sd_ecb_block_encrypt for possible return values.
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.

Parameters
[in]p_unlock_tokenThe 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.

Returns
Number of seconds passed since the last invocation.

Documentation feedback | Developer Zone | Subscribe | Updated