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.

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

ret_code_t	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_eid_config_get (uint8_t slot_no, es_eid_config_t *p_config)
	Function for fetching the EID configuration. More...

ret_code_t	es_security_ecdh_pair_preserve (void)
	Function for preserving an ECDH key pair by writing it to flash. 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.

Detailed Description

Types and functions for dealing with security of Eddystone beacons.

Enumeration Type Documentation

enum es_security_msg_t

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

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

Parameters

[in] slot_no The index of the slot.

Returns: 32-bit clock value.

ret_code_t es_security_ecdh_pair_preserve ( void )

Function for preserving an ECDH key pair by writing it to flash.

Returns: See es_flash_access_ecdh_key_pair for possible return values.

void es_security_eid_config_get	(	uint8_t	slot_no ,
		es_eid_config_t *	p_config
	)

Function for fetching the EID configuration.

Parameters

[in]	slot_no	The index of the slot for which to load the configuration.
[out]	p_config	Pointer to the EID configuration.

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

Parameters

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

Parameters

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

Parameters

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

Parameters

[in] msg_cb Callback 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_key Pointer 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_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.

Parameters

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

Parameters

[out] p_rand_chlg_buff Pointer 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_no The 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_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.

Returns: Number of seconds passed since the last invocation.

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

Parameters

[in] p_challenge Pointer 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_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.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation