BLE Security

API Reference

group btm_ble_sec_api_functions

Bluetooth LE security API (authorisation, authentication and encryption)

note

General Security APIs are listed in Generic Security API section.

Unnamed Group

void wiced_bt_ble_security_grant(wiced_bt_device_address_t bd_addr, wiced_bt_dev_status_t res)

btm_ble_api_functions

Grant or deny access. Used in response to an BTM_SECURITY_REQUEST_EVT event.

Parameters

  • bd_addr – [in] : peer device bd address.

  • res – [in] : BTM_SUCCESS to grant access; BTM_MODE_UNSUPPORTED, if local device does not allow pairing; BTM_REPEATED_ATTEMPTS otherwise

Returns

None

wiced_bool_t wiced_bt_ble_data_signature(wiced_bt_device_address_t bd_addr, uint8_t *p_text, uint16_t len, wiced_dev_ble_signature_t signature)

Sign the data using AES128 CMAC algorith.

Parameters

  • bd_addr – [in] target device the data to be signed for.

  • p_text – [in] signing data

  • len – [in] length of the signing data

  • signature – [in] output parameter where data signature is going to be stored

Returns

TRUE if signing successful, otherwise FALSE.

wiced_bool_t wiced_bt_ble_verify_signature(wiced_bt_device_address_t bd_addr, uint8_t *p_orig, uint16_t len, uint32_t counter, uint8_t *p_comp)

Verify the data signature.

Parameters

  • bd_addr – [in] target device the data to be signed for.

  • p_orig – [in] original data before signature.

  • len – [in] length of the signing data

  • counter – [in] counter used when doing data signing

  • p_comp – [in] signature to be compared against.

Returns

TRUE if signature verified correctly; otherwise FALSE.

wiced_bool_t wiced_bt_ble_get_security_state(wiced_bt_device_address_t bd_addr, uint8_t *p_le_sec_flags, uint8_t *p_le_key_size)

Get security mode 1 flags and encryption key size for LE peer.

Parameters

  • bd_addr – [in] : peer address

  • p_le_sec_flags – [out] : security flags (see wiced_bt_ble_sec_flags_e)

  • p_le_key_size – [out] : encryption key size

Returns

TRUE if successful

wiced_bt_dev_status_t wiced_bt_ble_set_privacy_mode(wiced_bt_device_address_t remote_bda, wiced_bt_ble_address_type_t rem_bda_type, wiced_bt_ble_privacy_mode_t privacy_mode)

Updates privacy mode if device is already available in controller resolving list.

Parameters

  • remote_bda – [in] -remote device address received during connection up

  • rem_bda_type – [in] -remote device address type received during connection up

  • privacy_mode – [in] - privacy mode (see wiced_bt_ble_privacy_mode_t)

Returns

wiced_bt_dev_status_t WICED_BT_ILLEGAL_VALUE : if paramer is wrong WICED_BT_UNSUPPORTED : if command not supported WICED_BT_UNKNOWN_ADDR : if bd_addr is wrong WICED_BT_ILLEGAL_ACTION : if device not added to resolving list or peer irk is not valid WICED_BT_ERROR : error while processing the command WICED_BT_SUCCESS : if command started

wiced_bt_dev_status_t wiced_bt_ble_read_device_random_address(wiced_bt_device_address_t random_bd_addr)

Get the configured local random device address.

Note : random address depends on below settings in that priority order. 1) Global privacy configuration using rpa_refresh_timeout (see wiced_bt_cfg_settings_t). 2) else configured for static random bd_address while downloading using BT_DEVICE_ADDRESS=random build setting.

Parameters

random_bd_addr – [out] - device random bd address

Returns

wiced_bt_dev_status_t WICED_BT_SUCCESS : if random address is configured. WICED_BT_WRONG_MODE : if random address not configured.

wiced_bool_t wiced_bt_ble_is_ext_adv_supported(void)

Check if the local BT controller supports extended advertising.

Returns

wiced_bool_t

wiced_bool_t wiced_bt_ble_is_periodic_adv_supported(void)

Check if the local BT controller supports periodic advertising.

Returns

wiced_bool_t

wiced_bt_dev_status_t wiced_bt_ble_set_ext_adv_random_address(wiced_bt_ble_ext_adv_handle_t adv_handle, wiced_bt_device_address_t random_addr)

Sends HCI command to set the random address for an adv set.

WICED_BT_SUCCESS : If random addr is set successfully WICED_BT_ILLEGAL_VALUE : If paramer is wrong WICED_BT_UNSUPPORTED : If command not supported WICED_BT_NO_RESOURCES : If no memory to issue the command WICED_BT_PENDING : If command queued to send down

Parameters

  • adv_handle – [in] - handle of the advertising set

  • random_addr – [in] - random address to use for this set

Returns

wiced_bt_dev_status_t

wiced_bt_dev_status_t wiced_bt_ble_set_ext_adv_parameters(wiced_bt_ble_ext_adv_handle_t adv_handle, wiced_bt_ble_ext_adv_event_property_t event_properties, uint32_t primary_adv_int_min, uint32_t primary_adv_int_max, wiced_bt_ble_advert_chnl_map_t primary_adv_channel_map, wiced_bt_ble_address_type_t own_addr_type, wiced_bt_ble_address_type_t peer_addr_type, wiced_bt_device_address_t peer_addr, wiced_bt_ble_advert_filter_policy_t adv_filter_policy, int8_t adv_tx_power, wiced_bt_ble_ext_adv_phy_t primary_adv_phy, uint8_t secondary_adv_max_skip, wiced_bt_ble_ext_adv_phy_t secondary_adv_phy, wiced_bt_ble_ext_adv_sid_t adv_sid, wiced_bt_ble_ext_adv_scan_req_notification_setting_t scan_request_not)

Sends the HCI command to set the parameters for extended advetisement.

WICED_BT_SUCCESS : If all extended adv params are set successfully WICED_BT_ILLEGAL_VALUE : If paramer is wrong WICED_BT_UNSUPPORTED : If command not supported WICED_BT_NO_RESOURCES : If no memory to issue the command WICED_BT_PENDING : If command queued to send down

Parameters

  • adv_handle – [in] Advertisement set handle

  • event_properties – [in] Bit mask to speicify connectable,scannable,low duty,high duty,directed,legacy adv

  • primary_adv_int_min – [in] Range: 0x000020 to 0xFFFFFF (20 ms to 10,485.759375 s)

  • primary_adv_int_max – [in] Range: 0x000020 to 0xFFFFFF(20 ms to 10,485.759375 s)

  • primary_adv_channel_map – [in] BLE advertisement channel map (see wiced_bt_ble_advert_chnl_map_e)

  • own_addr_type – [in] Ignored in case of anonymous adv. See event_properties

  • peer_addr_type – [in] Peer address type

  • peer_addr – [in] peer address

  • adv_filter_policy – [in] Adv filter policy

  • adv_tx_power – [in] -127 to +126. 127 means host has no preference

  • primary_adv_phy – [in] Phy used to transmit ADV packets on Primary ADV channels

  • secondary_adv_max_skip – [in] Valid only in case of extended ADV. Range 0 to FF. Maximum advertising events controller can skip before sending auxiliary adv packets on the secondary adv channel

  • secondary_adv_phy – [in] Phy used to transmit ADV packets on secondary ADV channels. Valid only in case of extended ADV

  • adv_sid – [in] Advertisement set identifier is the value to be transmitted in extended ADV PDUs

  • scan_request_not – [in] scan request received notification enable/disable

Returns

wiced_bt_dev_status_t

wiced_bt_dev_status_t wiced_bt_ble_set_ext_adv_data(wiced_bt_ble_ext_adv_handle_t adv_handle, uint16_t data_len, uint8_t *p_data)

Sends HCI command to write the extended adv data.

Parameters

  • adv_handle – [in] - handle of the advertising set

  • data_len – [in] - length of the adv data to use for this set

  • p_data – [in] - pointer to the adv data to use for this set

Returns

wiced_bt_dev_status_t WICED_BT_SUCCESS : If all extended adv data set successfully WICED_BT_ILLEGAL_VALUE : If paramer is wrong WICED_BT_UNSUPPORTED : If command not supported WICED_BT_NO_RESOURCES : If no memory to issue the command WICED_BT_PENDING : If command queued to send down

wiced_bt_dev_status_t wiced_bt_ble_set_ext_scan_rsp_data(wiced_bt_ble_ext_adv_handle_t adv_handle, uint16_t data_len, uint8_t *p_data)

Sends HCI command to write the extended scan rsp data.

WICED_BT_SUCCESS : If all extended scan response data set successfully WICED_BT_ILLEGAL_VALUE : If paramer is wrong WICED_BT_UNSUPPORTED : If command not supported WICED_BT_NO_RESOURCES : If no memory to issue the command WICED_BT_PENDING : If command queued to send down

Parameters

  • adv_handle – [in] - handle of the advertising set

  • data_len – [in] - length of the scan response data to use for this set

  • p_data – [in] - pointer to the scan response data to use for this set

Returns

wiced_bt_dev_status_t

wiced_bt_dev_status_t wiced_bt_ble_start_ext_adv(uint8_t enable, uint8_t num_sets, wiced_bt_ble_ext_adv_duration_config_t *p_dur)

Sends the HCI command to start/stop extended advertisements.

WICED_BT_ILLEGAL_VALUE : If paramer is wrong WICED_BT_UNSUPPORTED : If command not supported WICED_BT_NO_RESOURCES : If no memory to issue the command WICED_BT_SUCCESS : If successful

Parameters

  • enable – [in] - true to enable, false to disable

  • num_sets – [in] - number of sets to enable, unused if disabling

  • p_dur – [in] - pointer to adv handle(s) and duration configuration

Returns

wiced_bt_dev_status_t

wiced_bt_dev_status_t wiced_bt_ble_remove_adv_set(wiced_bt_ble_ext_adv_handle_t adv_handle)

Sends the HCI command to remove an extended advertisement set (which is currently not advertising)

WICED_BT_ILLEGAL_VALUE : If paramer is wrong WICED_BT_UNSUPPORTED : If command not supported WICED_BT_NO_RESOURCES : If no memory to issue the command WICED_BT_SUCCESS : If successful

Parameters

adv_handle – [in] - handle to advertisement set

Returns

wiced_bt_dev_status_t

wiced_bt_dev_status_t wiced_bt_ble_clear_adv_sets(void)

Sends the HCI command to remove all extended advertisement sets which are currently not advertising.

WICED_BT_UNSUPPORTED : If command not supported WICED_BT_NO_RESOURCES : If no memory to issue the command WICED_BT_SUCCESS : If successfuly

Returns

wiced_bt_dev_status_t

uint8_t wiced_bt_ble_read_num_ext_adv_sets(void)

Read the number of ADV sets supported by the controller.

Returns

uint8_t

uint16_t wiced_bt_ble_read_max_ext_adv_data_len(void)

Read the maximum ADV data length supported by the controller.

Returns

uint16_t

wiced_bt_dev_status_t wiced_bt_ble_set_periodic_adv_params(wiced_bt_ble_ext_adv_handle_t adv_handle, uint16_t periodic_adv_int_min, uint16_t periodic_adv_int_max, wiced_bt_ble_periodic_adv_prop_t periodic_adv_properties)

Sends the HCI command to set the parameters for periodic advertising.

WICED_BT_ILLEGAL_VALUE : If paramer is wrong WICED_BT_UNSUPPORTED : If command not supported WICED_BT_NO_RESOURCES : If no memory to issue the command WICED_BT_SUCCESS : If successful

Parameters

  • adv_handle – [in] advertisement set handle

  • periodic_adv_int_min – [in] Range N: 0x0006 to 0xFFFF, Time = N * 1.25 ms

  • periodic_adv_int_max – [in] Range N: 0x0006 to 0xFFFF, Time = N * 1.25 ms

  • periodic_adv_properties – [in] periodic adv property indicates which field should be include in periodic adv

Returns

wiced_bt_dev_status_t

wiced_bt_dev_status_t wiced_bt_ble_set_periodic_adv_data(wiced_bt_ble_ext_adv_handle_t adv_handle, uint16_t adv_data_length, uint8_t *p_adv_data)

Sends the HCI command to write the periodic adv data.

Parameters

  • adv_handle – [in] advertisement set handle

  • adv_data_length – [in] periodic data length

  • p_adv_data – [in] pointer to the periodic data

Returns

wiced_bt_dev_status_t WICED_BT_ILLEGAL_VALUE : If paramer is wrong WICED_BT_UNSUPPORTED : If command not supported WICED_BT_NO_RESOURCES : If no memory to issue the command WICED_BT_SUCCESS : If successful

wiced_bt_dev_status_t wiced_bt_ble_start_periodic_adv(wiced_bt_ble_ext_adv_handle_t adv_handle, wiced_bool_t enable)

Sends the HCI command to start/stop periodic advertisements.

Parameters

  • adv_handle – [in] - handle of the advertising set

  • enable – [in] - true to enable, false to disable

Returns

wiced_bt_dev_status_t WICED_BT_ILLEGAL_VALUE : If paramer is wrong WICED_BT_UNSUPPORTED : If command not supported WICED_BT_NO_RESOURCES : If no memory to issue the command WICED_BT_SUCCESS : If successful

wiced_bt_dev_status_t wiced_bt_ble_cache_ext_scan_config(wiced_bt_ble_ext_scan_config_t *p_ext_scan_cfg)

Stores extended scan configuration to apply on start ext scan.

WICED_BT_ILLEGAL_VALUE : If paramer is wrong WICED_BT_UNSUPPORTED : If command not supported WICED_BT_NO_RESOURCES : If no memory to issue the command WICED_BT_SUCCESS : If successful

Parameters

p_ext_scan_cfg – [in] - pointer to scan configuration

Returns

wiced_bt_dev_status_t

wiced_bt_dev_status_t wiced_bt_ble_create_sync_to_periodic_adv(wiced_bt_ble_adv_sync_options_t options, wiced_bt_ble_ext_adv_sid_t adv_sid, wiced_bt_ble_address_type_t adv_addr_type, wiced_bt_device_address_t adv_addr, uint16_t skip, uint16_t sync_timeout, uint8_t sync_cte_type)

Sends the HCI command to synchronize with periodic advertising from an advertiser and begin receiving periodic advertising packets.

Parameters

  • options – [in] - ref: wiced_bt_ble_adv_sync_options_t

  • adv_sid – [in] - min SID / max SID

  • adv_addr_type – [in] - address type

  • adv_addr – [in] - address value

  • skip – [in]

  • sync_timeout – [in] - timeout value

  • sync_cte_type – [in] - bit 0 - Do not sync to packets with an AoA Constant Tone Extension 1 - Do not sync to packets with an AoD Constant Tone Extension with 1 μs slots 2 - Do not sync to packets with an AoD Constant Tone Extension with 2 μs slots 3 - Do not sync to packets with a type 3 Constant Tone Extension

Returns

wiced_bt_dev_status_t WICED_BT_ILLEGAL_VALUE : If paramer is wrong WICED_BT_UNSUPPORTED : If command not supported WICED_BT_NO_RESOURCES : If no memory to issue the command WICED_BT_SUCCESS : If successful

wiced_bt_dev_status_t wiced_bt_ble_cancel_sync_to_periodic_adv(void)

Sends HCI command to cancel the create sync command while it is pending.

Returns

wiced_bt_dev_status_t WICED_BT_UNSUPPORTED : If command not supported WICED_BT_NO_RESOURCES : If no memory to issue the command WICED_BT_SUCCESS : If successful

wiced_bt_dev_status_t wiced_bt_ble_terminate_sync_to_periodic_adv(uint16_t sync_handle)

Sends the HCI command to stop reception of periodic advertising identified by the sync_handle.

WICED_BT_UNSUPPORTED : If command not supported WICED_BT_NO_RESOURCES : If no memory to issue the command WICED_BT_PENDING : If command queued to send down WICED_BT_SUCCESS : If successful

Parameters

sync_handle – [in] - Sync handle received in WICED_BT_BLE_PERIODIC_ADV_SYNC_ESTABLISHED_EVENT.

Returns

wiced_bt_dev_status_t

wiced_bt_dev_status_t wiced_bt_ble_add_device_to_periodic_adv_list(wiced_bt_ble_address_type_t advertiser_addr_type, wiced_bt_device_address_t advetiser_addr, wiced_bt_ble_ext_adv_sid_t adv_sid)

Sends the HCI command to add the given advertiser to Periodic Advertiser list.

Note : Caller shall not attempt to add more than max list size Shall not attempt to call this API, while create to periodic sync command is pending.

Parameters

  • advertiser_addr_type – [in] : Periodic advertiser addr type

  • advetiser_addr – [in] : Periodic advertiser addr

  • adv_sid – [in] : Periodic advertiser sid

Returns

wiced_bt_dev_status_t WICED_BT_ILLEGAL_VALUE : If paramer is wrong WICED_BT_UNSUPPORTED : If command not supported WICED_BT_NO_RESOURCES : If no memory to issue the command WICED_BT_PENDING : If command queued to send down WICED_BT_SUCCESS : If successful

wiced_bt_dev_status_t wiced_bt_ble_remove_device_from_periodic_adv_list(wiced_bt_ble_address_type_t advertiser_addr_type, wiced_bt_device_address_t advetiser_addr, wiced_bt_ble_ext_adv_sid_t adv_sid)

Sends the HCI command to remove the given advertiser from Periodic Advertiser list.

Note : Shall not attempt to call this API, while create to periodic sync command is pending.

Parameters

  • advertiser_addr_type – [in] : Periodic advertiser addr type

  • advetiser_addr – [in] : Periodic advertiser addr

  • adv_sid – [in] : Periodic advertiser sid

Returns

wiced_bt_dev_status_t WICED_BT_ILLEGAL_VALUE : If paramer is wrong WICED_BT_UNSUPPORTED : If command not supported WICED_BT_NO_RESOURCES : If no memory to issue the command WICED_BT_PENDING : If command queued to send down WICED_BT_SUCCESS : If successful

wiced_bt_dev_status_t wiced_bt_ble_clear_periodic_adv_list(void)

Sends the HCI command to remove to remove all devices from the the Periodic Advertisers list.

Note : Shall not attempt to call this API, while create to periodic sync command is pending.

Returns

wiced_bt_dev_status_t WICED_BT_UNSUPPORTED : If command not supported WICED_BT_NO_RESOURCES : If no memory to issue the command WICED_BT_PENDING : If command queued to send down WICED_BT_SUCCESS : If successful

uint8_t wiced_bt_ble_read_periodic_adv_list_size(void)

Read the Periodic Advertisers list size.

Returns

uint8_t : list size

void wiced_bt_ble_register_adv_ext_cback(wiced_bt_ble_adv_ext_event_cb_fp_t p_app_adv_ext_event_cb)

Register an application callback function to receive extended advertising events.

Parameters

p_app_adv_ext_event_cb – [in] - pointer to function to receive extended adv events.

Returns

wiced_bt_dev_status_t WICED_BT_UNSUPPORTED : If command not supported WICED_BT_NO_RESOURCES : If no memory to issue the command WICED_BT_PENDING : If command queued to send down WICED_BT_SUCCESS : If successful

wiced_bt_dev_status_t wiced_bt_ble_set_periodic_adv_rcv_enable(wiced_bt_ble_periodic_adv_sync_handle_t sync_handle, wiced_bool_t enable)

Sends the HCI command enable or disable receiving periodic ADV data for a sync handle.

Parameters

  • sync_handle – [in] : Sync handle

  • enable – [in] : Boolean for enable/disable.

Returns

wiced_bt_dev_status_t WICED_BT_UNSUPPORTED : If command not supported WICED_BT_NO_RESOURCES : If no memory to issue the command WICED_BT_SUCCESS : If command queued to send down

Functions

wiced_result_t wiced_bt_dev_get_ble_keys(wiced_bt_device_address_t bd_addr, wiced_bt_dev_le_key_type_t *p_key_mask)

get le key mask from stored key information of nv ram

Parameters

  • bd_addr – [in] : remote bd address

  • p_key_mask – [out] : ble key mask stored

Returns

wiced_result_t

wiced_result_t wiced_bt_dev_add_device_to_address_resolution_db(wiced_bt_device_link_keys_t *p_link_keys)

add link key information to internal address resolution db

Parameters

p_link_keys – [in] : link keys information stored in application side

Returns

wiced_result_t

wiced_result_t wiced_bt_dev_remove_device_from_address_resolution_db(wiced_bt_device_link_keys_t *p_link_keys)

remove link key information from internal address resolution db

Parameters

p_link_keys – [in] : link keys information stored in application side

Returns

wiced_result_t