BLE Security

group btm_ble_sec_api_functions

BLE Security API.

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

Unnamed Group

void wiced_bt_dev_configure_secure_connections_only_mode(void)

Bluetooth BLE Security Functions.

Configure device to allow connections only with secure connections supported devices

note

API must be called only once after BTM_ENABLED_EVT event received, before starting bluetooth activity

Returns

void

wiced_result_t wiced_bt_dev_sec_bond(wiced_bt_device_address_t bd_addr, wiced_bt_ble_address_type_t bd_addr_type, wiced_bt_transport_t transport, uint8_t pin_len, uint8_t *p_pin)

Bond with peer device.

If the connection is already up, but not secure, pairing is attempted.

note

PIN parameters are only needed when bonding with legacy devices (pre-2.1 Core Spec)

WICED_BT_PENDING : if successfully initiated, WICED_BT_SUCCESS : if already paired to the device, else error code

Parameters
  • bd_addr[in] : Peer device bd address to pair with.

  • bd_addr_type[in] : BLE_ADDR_PUBLIC or BLE_ADDR_RANDOM (applies to LE devices only)

  • transport[in] : BT_TRANSPORT_BR_EDR or BT_TRANSPORT_LE

  • pin_len[in] : Length of input parameter p_pin (0 if not used).

  • p_pin[in] : Pointer to Pin Code to use (NULL if not used).

Returns

wiced_result_t wiced_bt_dev_sec_bond_cancel(wiced_bt_device_address_t bd_addr)

Cancel an ongoing bonding process with peer device.

WICED_BT_PENDING : if cancel initiated, WICED_BT_SUCCESS : if cancel has completed already, else error code.

Parameters

bd_addr[in] : Peer device bd address to pair with.

Returns

wiced_result_t wiced_bt_dev_set_encryption(wiced_bt_device_address_t bd_addr, wiced_bt_transport_t transport, void *p_ref_data)

Encrypt the specified connection.

Status is notified using BTM_ENCRYPTION_STATUS_EVT of wiced_bt_management_cback_t.

WICED_BT_SUCCESS : already encrypted WICED_BT_PENDING : command will be returned in the callback WICED_BT_WRONG_MODE : connection not up. WICED_BT_BUSY : security procedures are currently active

Parameters
  • bd_addr[in] : Address of peer device

  • transport[in] : BT_TRANSPORT_BR_EDR or BT_TRANSPORT_LE

  • p_ref_data[in] : Encryption type wiced_bt_ble_sec_action_type_t

Returns

void wiced_bt_dev_confirm_req_reply(wiced_result_t res, wiced_bt_device_address_t bd_addr)

Confirm the numeric value for pairing (in response to BTM_USER_CONFIRMATION_REQUEST_EVT of wiced_bt_management_cback_t)

Parameters
  • res[in] : result of the operation WICED_BT_SUCCESS if success

  • bd_addr[in] : Address of the peer device

Returns

void

void wiced_bt_dev_send_key_press_notif(wiced_bt_device_address_t bd_addr, wiced_bt_dev_passkey_entry_type_t type)

Inform remote device of keypress during pairing.

Used during the passkey entry by a device with KeyboardOnly IO capabilities (typically a HID keyboard device).

Parameters
  • bd_addr[in] : Address of the peer device

  • type[in] : notification type

wiced_result_t wiced_bt_dev_get_bonded_devices(wiced_bt_dev_bonded_device_info_t *p_paired_device_list, uint16_t *p_num_devices)

get bonded device list

Parameters
  • p_paired_device_list[out] : array for getting bd address of bonded devices

  • p_num_devices[in] : list size of p_pared_device_list total number of bonded devices stored

Returns

wiced_result_t

wiced_result_t wiced_bt_dev_delete_bonded_device(wiced_bt_device_address_t bd_addr)

remove bonding with remote device with assigned bd_addr Note: This API cannot be used while being connected to the remote bd_addr

Parameters

bd_addr[in] : bd_addr of remote device to be removed from bonding list

Returns

wiced_result_t

wiced_bool_t wiced_bt_dev_get_security_state(wiced_bt_device_address_t bd_addr, uint8_t *p_sec_flags)

Get security flags for the device.

Parameters
Returns

TRUE if successful

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

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

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