Lancaster University fork of the Nordic nrf51-SDK repository, which actually lives on github: https://github.com/lancaster-university/nrf51-sdk
ID Manager
[Peer_manager]
An internal module of Peer_manager. More...
Typedefs | |
typedef void(* | im_evt_handler_t )(im_evt_t const *p_event) |
Event handler for events from the ID Manager module. | |
Enumerations | |
enum | im_evt_id_t { IM_EVT_DUPLICATE_ID, IM_EVT_BONDED_PEER_CONNECTED } |
Events that can come from the ID Manager module. More... | |
Functions | |
ret_code_t | im_register (im_evt_handler_t evt_handler) |
Function for registering for events from the ID Manager module. | |
void | im_ble_evt_handler (ble_evt_t *p_ble_evt) |
Function for dispatching SoftDevice events to the ID Manager module. | |
pm_peer_id_t | im_peer_id_get_by_conn_handle (uint16_t conn_handle) |
Function for getting the corresponding peer ID from a connection handle. | |
pm_peer_id_t | im_peer_id_get_by_master_id (ble_gap_master_id_t *p_master_id) |
Function for getting the corresponding peer ID from a master ID (EDIV and rand). | |
pm_peer_id_t | im_peer_id_get_by_irk_match_idx (uint8_t irk_match_idx) |
Function for getting the corresponding peer ID from an IRK match index, see ble_gap_evt_connected_t. | |
uint16_t | im_conn_handle_get (pm_peer_id_t peer_id) |
Function for getting the corresponding connection handle from a peer ID. | |
ret_code_t | im_ble_addr_get (uint16_t conn_handle, ble_gap_addr_t *p_ble_addr) |
Function for getting the BLE address used by the peer when connecting. | |
bool | im_master_id_is_valid (ble_gap_master_id_t const *p_master_id) |
Function for checking whether a master ID is valid or invalid. | |
void | im_new_peer_id (uint16_t conn_handle, pm_peer_id_t peer_id) |
Function for reporting that a new peer ID has been allocated for a specified connection. | |
ret_code_t | im_wlist_set (ble_gap_whitelist_t *p_whitelist) |
Function for informing this module of what whitelist will be used. | |
ret_code_t | im_wlist_create (pm_peer_id_t *p_peer_ids, uint8_t n_peer_ids, ble_gap_whitelist_t *p_whitelist) |
Function for constructing a whitelist for use when advertising. | |
bool | im_address_resolve (ble_gap_addr_t const *p_addr, ble_gap_irk_t const *p_irk) |
Function for resolving a resolvable address with an identity resolution key (IRK). | |
void | ah (uint8_t const *p_k, uint8_t const *p_r, uint8_t *p_local_hash) |
Function for calculating the ah() hash function described in Bluetooth core specification 4.2 section 3.H.2.2.2. |
Detailed Description
An internal module of Peer_manager.
A module for keeping track of peer identities (IRK and peer address).
Typedef Documentation
typedef void(* im_evt_handler_t)(im_evt_t const *p_event) |
Event handler for events from the ID Manager module.
- Parameters:
-
[in] p_event The event that has happened.
Definition at line 80 of file id_manager.h.
Enumeration Type Documentation
enum im_evt_id_t |
Events that can come from the ID Manager module.
- Enumerator:
Definition at line 54 of file id_manager.h.
Function Documentation
void ah | ( | uint8_t const * | p_k, |
uint8_t const * | p_r, | ||
uint8_t * | p_local_hash | ||
) |
Function for calculating the ah() hash function described in Bluetooth core specification 4.2 section 3.H.2.2.2.
BLE uses a hash function to calculate the first half of a resolvable address from the second half of the address and an irk. This function will use the ECB periferal to hash these data acording to the Bluetooth core specification.
- Note:
- The ECB expect little endian input and output. This function expect big endian and will reverse the data as necessary.
- Parameters:
-
[in] p_k The key used in the hash function. For address resolution this is should be the irk. The array must have a length of 16. [in] p_r The rand used in the hash function. For generating a new address this would be a random number. For resolving a resolvable address this would be the last half of the address being resolved. The array must have a length of 3. [out] p_local_hash The result of the hash operation. For address resolution this will match the first half of the address being resolved if and only if the irk used in the hash function is the same one used to generate the address. The array must have a length of 16.
- Note:
- ====IMPORTANT==== This is a special modification to the original nRF51 SDK required by the mbed BLE API to be able to generate BLE private resolvable addresses. This function is used by the BLE API implementation for nRF5xSecurityManager::getAddressFromBondTable() in the ble-nrf51822 yotta module. =================
BLE uses a hash function to calculate the first half of a resolvable address from the second half of the address and an irk. This function will use the ECB periferal to hash these data acording to the Bluetooth core specification.
- Note:
- The ECB expect little endian input and output. This function expect big endian and will reverse the data as necessary.
- Parameters:
-
[in] p_k The key used in the hash function. For address resolution this is should be the irk. The array must have a length of 16. [in] p_r The rand used in the hash function. For generating a new address this would be a random number. For resolving a resolvable address this would be the last half of the address being resolved. The array must have a length of 3. [out] p_local_hash The result of the hash operation. For address resolution this will match the first half of the address being resolved if and only if the irk used in the hash function is the same one used to generate the address. The array must have a length of 16.
Definition at line 714 of file id_manager.c.
bool im_address_resolve | ( | ble_gap_addr_t const * | p_addr, |
ble_gap_irk_t const * | p_irk | ||
) |
Function for resolving a resolvable address with an identity resolution key (IRK).
This function will use the ECB peripheral to resolve a resolvable address. This can be used to resolve the identity of a device distributing a random resolvable address based on any IRKs you have received earlier. If an address is resolved by an IRK, the device disributing the address must also know the IRK.
- Parameters:
-
[in] p_addr A random resolvable address. [in] p_irk An identity resolution key (IRK).
- Return values:
-
true The irk used matched the one used to create the address. false The irk used did not match the one used to create the address, or an argument was NULL.
Definition at line 737 of file id_manager.c.
ret_code_t im_ble_addr_get | ( | uint16_t | conn_handle, |
ble_gap_addr_t * | p_ble_addr | ||
) |
Function for getting the BLE address used by the peer when connecting.
- Parameters:
-
[in] conn_handle The connection handle. [out] p_ble_addr The BLE address used by the peer when the connection specified by conn_handle was established.
- Return values:
-
NRF_SUCCESS The address was found and copied. NRF_ERROR_INVALID_STATE Module not initialized. BLE_ERROR_CONN_HANDLE_INVALID conn_handle does not refer to an active connection. NRF_ERROR_NULL p_ble_addr was NULL.
Definition at line 452 of file id_manager.c.
void im_ble_evt_handler | ( | ble_evt_t * | p_ble_evt ) |
Function for dispatching SoftDevice events to the ID Manager module.
- Parameters:
-
[in] p_ble_evt The SoftDevice event.
Definition at line 249 of file id_manager.c.
uint16_t im_conn_handle_get | ( | pm_peer_id_t | peer_id ) |
Function for getting the corresponding connection handle from a peer ID.
- Parameters:
-
[in] peer_id The peer ID.
- Returns:
- The corresponding connection handle, or BLE_CONN_HANDLE_INVALID if none could be resolved.
Definition at line 538 of file id_manager.c.
bool im_master_id_is_valid | ( | ble_gap_master_id_t const * | p_master_id ) |
Function for checking whether a master ID is valid or invalid.
- Parameters:
-
[in] p_master_id The master ID.
- Return values:
-
true The master id is valid. true The master id is invalid (i.e. all zeros).
Definition at line 551 of file id_manager.c.
void im_new_peer_id | ( | uint16_t | conn_handle, |
pm_peer_id_t | peer_id | ||
) |
Function for reporting that a new peer ID has been allocated for a specified connection.
- Parameters:
-
[in] conn_handle The connection. [in] peer_id The new peer ID.
Definition at line 569 of file id_manager.c.
pm_peer_id_t im_peer_id_get_by_conn_handle | ( | uint16_t | conn_handle ) |
Function for getting the corresponding peer ID from a connection handle.
- Parameters:
-
[in] conn_handle The connection handle.
- Returns:
- The corresponding peer ID, or PM_PEER_ID_INVALID if none could be resolved.
Definition at line 439 of file id_manager.c.
pm_peer_id_t im_peer_id_get_by_irk_match_idx | ( | uint8_t | irk_match_idx ) |
Function for getting the corresponding peer ID from an IRK match index, see ble_gap_evt_connected_t.
- Parameters:
-
[in] irk_match_idx The IRK match index.
- Returns:
- The corresponding peer ID, or PM_PEER_ID_INVALID if none could be resolved.
Definition at line 522 of file id_manager.c.
pm_peer_id_t im_peer_id_get_by_master_id | ( | ble_gap_master_id_t * | p_master_id ) |
Function for getting the corresponding peer ID from a master ID (EDIV and rand).
- Parameters:
-
[in] p_master_id The master ID.
- Returns:
- The corresponding peer ID, or PM_PEER_ID_INVALID if none could be resolved.
Definition at line 491 of file id_manager.c.
ret_code_t im_register | ( | im_evt_handler_t | evt_handler ) |
Function for registering for events from the ID Manager module.
- Note:
- This will also initialize the module if needed.
- Parameters:
-
[in] evt_handler Callback for events from the ID Manager module.
- Return values:
-
NRF_SUCCESS Registration was successful. NRF_ERROR_NO_MEM No more registrations possible. NRF_ERROR_NULL evt_handler was NULL.
Definition at line 406 of file id_manager.c.
ret_code_t im_wlist_create | ( | pm_peer_id_t * | p_peer_ids, |
uint8_t | n_peer_ids, | ||
ble_gap_whitelist_t * | p_whitelist | ||
) |
Function for constructing a whitelist for use when advertising.
- Note:
- When advertising with whitelist, always use the whitelist created/set by the most recent call to this function or to im_wlist_set, whichever happened most recently.
- Do not call this function while advertising with another whitelist.
- Parameters:
-
[in] p_peer_ids The ids of the peers to be added to the whitelist. [in] n_peer_ids The number of peer ids in p_peer_ids. [in,out] p_whitelist The constructed whitelist. Note that p_adv_whitelist->pp_addrs must be NULL or point to an array with size BLE_GAP_WHITELIST_ADDR_MAX_COUNT and p_adv_whitelist->pp_irks must be NULL or point to an array with size BLE_GAP_WHITELIST_IRK_MAX_COUNT.
- Return values:
-
NRF_SUCCESS Whitelist successfully created. NRF_ERROR_NULL p_whitelist was NULL.
Definition at line 579 of file id_manager.c.
ret_code_t im_wlist_set | ( | ble_gap_whitelist_t * | p_whitelist ) |
Function for informing this module of what whitelist will be used.
This function is meant to be used when the app wants to use a custom whitelist. When using peer manager, this function must be used if a custom whitelist is used.
- Note:
- When using a whitelist, always use the whitelist created/set by the most recent call to im_wlist_create or to this function, whichever happened most recently.
- Do not call this function while scanning with another whitelist.
- Do not add any irks to the whitelist that are not present in the bonding data of a peer in the peer database.
- Parameters:
-
[in] p_whitelist The whitelist.
- Return values:
-
NRF_SUCCESS Whitelist successfully set. NRF_ERROR_NULL p_whitelist was NULL. NRF_ERROR_NOT_FOUND One or more of the whitelists irks was not found in the peer_database.
Definition at line 645 of file id_manager.c.
Generated on Tue Jul 12 2022 15:07:15 by 1.7.2