Peer Manager

Module for managing Bluetooth LE bonding, which includes controlling encryption and pairing procedures as well as persistently storing different pieces of data that must be stored when bonded. More...

Topics
	All versions of Peer IDs.
	The data ID for each iteration of the data formats in non-volatile storage.
	GATT Database Service Structure
	LESC module
	Module for handling LESC related events.
	Peer Manager Standard Event Handlers
	Standard event handlers implementing some best practices for Bluetooth LE security.
	Peer Manager defined security errors

Data Structures
struct	pm_conn_sec_config
	Configuration of a security procedure. More...
struct	pm_peer_data_bonding
	Data associated with a bond to a peer. More...
struct	pm_peer_data_local_gatt_db
	Data on a local GATT database. More...
struct	pm_conn_sec_status
	Security status of a connection. More...
struct	pm_conn_config_req_evt
	Parameters specific to the PM_EVT_CONN_CONFIG_REQ event. More...
struct	pm_conn_sec_start_evt
	Events parameters specific to the PM_EVT_CONN_SEC_START event. More...
struct	pm_conn_secured_evt
	Parameters specific to the PM_EVT_CONN_SEC_SUCCEEDED event. More...
struct	pm_conn_secure_failed_evt
	Parameters specific to the PM_EVT_CONN_SEC_FAILED event. More...
struct	pm_conn_sec_params_req_evt
	Parameters specific to the PM_EVT_CONN_SEC_PARAMS_REQ event. More...
struct	pm_peer_data_update_succeeded_evt
	Parameters specific to the PM_EVT_PEER_DATA_UPDATE_SUCCEEDED event. More...
struct	pm_peer_data_update_failed_evt
	Parameters specific to the PM_EVT_PEER_DATA_UPDATE_FAILED event. More...
struct	pm_failure_evt
	Standard parameters for failure events. More...
struct	pm_evt
	An event from the Peer Manager module. More...

Macros
#define	PM_PEER_ID_INVALID   0xFFFF
	Invalid value for Peer ID.
#define	PM_STORE_TOKEN_INVALID   0
	Invalid value for store token.
#define	PM_PEER_ID_N_AVAILABLE_IDS   256
	The number of available peer IDs.
#define	PM_LOCAL_DB_LEN_OVERHEAD_BYTES   offsetof(struct pm_peer_data_local_gatt_db, data)
	The static-length part of the local GATT data struct.
#define	PM_CONN_SEC_ERROR_BASE   0x1000
	The base for Peer Manager defined errors. See Peer Manager defined security errors.

Typedefs
typedef void(*	pm_evt_handler_t) (const struct pm_evt *pm_evt)
	Event handler for events from the Peer Manager module.

Enumerations
enum	pm_peer_id_list_skip {   PM_PEER_ID_LIST_ALL_ID , PM_PEER_ID_LIST_SKIP_NO_ID_ADDR = 1 << 0 , PM_PEER_ID_LIST_SKIP_NO_IRK = 1 << 1 , PM_PEER_ID_LIST_SKIP_NO_CAR = 1 << 2 ,   PM_PEER_ID_LIST_SKIP_ALL = PM_PEER_ID_LIST_SKIP_NO_IRK | PM_PEER_ID_LIST_SKIP_NO_CAR }
	Peer list filtrations. They determine which peer ID will be added to list. More...
enum	pm_peer_data_id {   PM_PEER_DATA_ID_FIRST = 0 , PM_PEER_DATA_ID_BONDING = 7 , PM_PEER_DATA_ID_SERVICE_CHANGED_PENDING = 1 , PM_PEER_DATA_ID_GATT_LOCAL = 8 ,   PM_PEER_DATA_ID_GATT_REMOTE = 5 , PM_PEER_DATA_ID_PEER_RANK = 6 , PM_PEER_DATA_ID_CENTRAL_ADDR_RES = 9 , PM_PEER_DATA_ID_APPLICATION = 4 ,   PM_PEER_DATA_ID_LAST = 10 , PM_PEER_DATA_ID_INVALID = 0xFF }
	The different types of data associated with a peer. More...
enum	pm_conn_sec_procedure { PM_CONN_SEC_PROCEDURE_ENCRYPTION , PM_CONN_SEC_PROCEDURE_BONDING , PM_CONN_SEC_PROCEDURE_PAIRING }
	Different procedures that can lead to an encrypted link. More...
enum	pm_evt_id {   PM_EVT_BONDED_PEER_CONNECTED , PM_EVT_CONN_CONFIG_REQ , PM_EVT_CONN_SEC_START , PM_EVT_CONN_SEC_SUCCEEDED ,   PM_EVT_CONN_SEC_FAILED , PM_EVT_CONN_SEC_CONFIG_REQ , PM_EVT_CONN_SEC_PARAMS_REQ , PM_EVT_STORAGE_FULL ,   PM_EVT_ERROR_UNEXPECTED , PM_EVT_PEER_DATA_UPDATE_SUCCEEDED , PM_EVT_PEER_DATA_UPDATE_FAILED , PM_EVT_PEER_DELETE_SUCCEEDED ,   PM_EVT_PEER_DELETE_FAILED , PM_EVT_PEERS_DELETE_SUCCEEDED , PM_EVT_PEERS_DELETE_FAILED , PM_EVT_LOCAL_DB_CACHE_APPLIED ,   PM_EVT_LOCAL_DB_CACHE_APPLY_FAILED , PM_EVT_SERVICE_CHANGED_IND_SENT , PM_EVT_SERVICE_CHANGED_IND_CONFIRMED , PM_EVT_PERIPHERAL_SECURITY_REQ ,   PM_EVT_FLASH_GARBAGE_COLLECTED , PM_EVT_FLASH_GARBAGE_COLLECTION_FAILED }
	Types of events that can come from the Peer Manager module. More...
enum	pm_peer_data_op { PM_PEER_DATA_OP_UPDATE , PM_PEER_DATA_OP_DELETE }
	Actions that can be performed to peer data in persistent storage. More...

Functions
uint32_t	pm_init (void)
	Initialize the Peer Manager.
uint32_t	pm_register (pm_evt_handler_t event_handler)
	Register an event handler with the Peer Manager.
uint32_t	pm_sec_params_set (ble_gap_sec_params_t *sec_params)
	Provide pairing and bonding parameters to use for pairing procedures.
uint32_t	pm_conn_secure (uint16_t conn_handle, bool force_repairing)
	Establish encryption on a connection, and optionally establish a bond.
uint32_t	pm_conn_exclude (uint16_t conn_handle, const void *context)
	Exclude a connection from the Bluetooth LE event flow handled inside the Peer Manager.
void	pm_conn_sec_config_reply (uint16_t conn_handle, struct pm_conn_sec_config *conn_sec_config)
	Provide a security configuration for a link.
uint32_t	pm_conn_sec_params_reply (uint16_t conn_handle, ble_gap_sec_params_t *sec_params, const void *context)
	Provide security parameters for a link.
void	pm_local_database_has_changed (void)
	Manually inform that the local database has changed.
uint32_t	pm_conn_sec_status_get (uint16_t conn_handle, struct pm_conn_sec_status *conn_sec_status)
	Get the security status of a connection.
bool	pm_sec_is_sufficient (uint16_t conn_handle, struct pm_conn_sec_status *sec_status_req)
	Compare the security status of a connection against a baseline.
uint32_t	pm_lesc_public_key_set (ble_gap_lesc_p256_pk_t *public_key)
	Specify the public key to use for LESC operations.
uint32_t	pm_allow_list_set (const uint16_t *peers, uint32_t peer_cnt)
	Set or clear the allow list.
uint32_t	pm_allow_list_get (ble_gap_addr_t *addrs, uint32_t *addr_cnt, ble_gap_irk_t *irks, uint32_t *irk_cnt)
	Retrieve the previously set allow list.
uint32_t	pm_device_identities_list_set (const uint16_t *peers, uint32_t peer_cnt)
	Function for setting and clearing the device identities list.
uint32_t	pm_id_addr_set (const ble_gap_addr_t *addr)
	Set the local Bluetooth identity address.
uint32_t	pm_id_addr_get (ble_gap_addr_t *addr)
	Retrieve the local Bluetooth identity address.
uint32_t	pm_privacy_set (const ble_gap_privacy_params_t *privacy_params)
	Configure privacy settings.
uint32_t	pm_privacy_get (ble_gap_privacy_params_t *privacy_params)
	Retrieve privacy settings.
bool	pm_address_resolve (const ble_gap_addr_t *addr, const ble_gap_irk_t *irk)
	Resolve a resolvable address with an identity resolution key (IRK).
uint32_t	pm_conn_handle_get (uint16_t peer_id, uint16_t *conn_handle)
	Get the connection handle of the connection with a bonded peer.
uint32_t	pm_peer_id_get (uint16_t conn_handle, uint16_t *peer_id)
	Retrieve the ID of a peer, given its connection handle.
uint32_t	pm_peer_id_list (uint16_t *peer_list, uint32_t *const list_size, uint16_t first_peer_id, enum pm_peer_id_list_skip skip_id)
	Retrieve a filtered list of peer IDs.
uint16_t	pm_next_peer_id_get (uint16_t prev_peer_id)
	Get the next peer ID in the sequence of all used peer IDs.
uint32_t	pm_peer_count (void)
	Query the number of valid peer IDs that are available.

Functions (Peer Data)
Functions for manipulating peer data.
uint32_t	pm_peer_data_load (uint16_t peer_id, enum pm_peer_data_id data_id, void *data, uint32_t *len)
	Retrieve the stored data of a peer.
uint32_t	pm_peer_data_bonding_load (uint16_t peer_id, struct pm_peer_data_bonding *data)
	Read a peer's bonding data (PM_PEER_DATA_ID_BONDING).
uint32_t	pm_peer_data_remote_db_load (uint16_t peer_id, struct ble_gatt_db_srv *data, uint32_t *len)
	Read a peer's remote DB values. (PM_PEER_DATA_ID_GATT_REMOTE).
uint32_t	pm_peer_data_app_data_load (uint16_t peer_id, void *data, uint32_t *len)
	Read a peer's application data. (PM_PEER_DATA_ID_APPLICATION).
uint32_t	pm_peer_data_store (uint16_t peer_id, enum pm_peer_data_id data_id, const void *data, uint32_t len, uint32_t *token)
	Set or update stored data of a peer.
uint32_t	pm_peer_data_bonding_store (uint16_t peer_id, const struct pm_peer_data_bonding *data, uint32_t *token)
	Set or update a peer's bonding data (PM_PEER_DATA_ID_BONDING).
uint32_t	pm_peer_data_remote_db_store (uint16_t peer_id, const struct ble_gatt_db_srv *data, uint32_t len, uint32_t *token)
	Set or update a peer's remote DB values. (PM_PEER_DATA_ID_GATT_REMOTE).
uint32_t	pm_peer_data_app_data_store (uint16_t peer_id, const void *data, uint32_t len, uint32_t *token)
	Set or update a peer's application data. (PM_PEER_DATA_ID_APPLICATION).
uint32_t	pm_peer_data_delete (uint16_t peer_id, enum pm_peer_data_id data_id)
	Delete specific data stored for a peer.
uint32_t	pm_peer_new (uint16_t *new_peer_id, struct pm_peer_data_bonding *bonding_data, uint32_t *token)
	Manually add a peer to the non-volatile storage.
uint32_t	pm_peer_delete (uint16_t peer_id)
	Delete all data stored for a peer and free the peer ID.
uint32_t	pm_peers_delete (void)
	Delete all data stored for all peers.
uint32_t	pm_peer_ranks_get (uint16_t *highest_ranked_peer, uint32_t *highest_rank, uint16_t *lowest_ranked_peer, uint32_t *lowest_rank)
	Find the highest and lowest ranked peers.
uint32_t	pm_peer_rank_highest (uint16_t peer_id)
	Update the rank of a peer to be the highest among all stored peers.

Detailed Description

Module for managing Bluetooth LE bonding, which includes controlling encryption and pairing procedures as well as persistently storing different pieces of data that must be stored when bonded.

The API consists of functions for configuring the pairing and encryption behavior of the device and functions for manipulating the stored data.

This module uses ZMS to interface with persistent storage. It uses a Devicetree storage partition exclusive to the Peer Manager.