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.

Return

None

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

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

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.

Return

TRUE if signing successful, otherwise FALSE.

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

  • [in] p_text: signing data

  • [in] len: length of the signing data

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

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.

Return

TRUE if signature verified correctly; otherwise FALSE.

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

  • [in] p_orig: original data before signature.

  • [in] len: length of the signing data

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

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

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.

Return

TRUE if successful

Parameters
  • [in] bd_addr: : peer address

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

  • [out] p_le_key_size: : encryption key size

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.

Return

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

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

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

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

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.

Return

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

Parameters
  • [out] random_bd_addr: - device random bd address

wiced_bool_t wiced_bt_ble_is_ext_adv_supported(void)

Check if the local BT controller supports extended advertising.

Return

wiced_bool_t

wiced_bool_t wiced_bt_ble_is_periodic_adv_supported(void)

Check if the local BT controller supports periodic advertising.

Return

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

Return

wiced_bt_dev_status_t

Parameters
  • [in] adv_handle: - handle of the advertising set

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

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

Return

wiced_bt_dev_status_t

Parameters
  • [in] adv_handle: Advertisement set handle

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

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

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

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

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

  • [in] peer_addr_type: Peer address type

  • [in] peer_addr: peer address

  • [in] adv_filter_policy: Adv filter policy

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

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

  • [in] secondary_adv_max_skip: 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

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

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

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

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.

Return

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

Parameters
  • [in] adv_handle: - handle of the advertising set

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

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

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

Return

wiced_bt_dev_status_t

Parameters
  • [in] adv_handle: - handle of the advertising set

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

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

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

Return

wiced_bt_dev_status_t

Parameters
  • [in] enable: - true to enable, false to disable

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

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

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

Return

wiced_bt_dev_status_t

Parameters
  • [in] adv_handle: - handle to advertisement set

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

Return

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.

Return

uint8_t

uint16_t wiced_bt_ble_read_max_ext_adv_data_len(void)

Read the maximum ADV data length supported by the controller.

Return

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

Return

wiced_bt_dev_status_t

Parameters
  • [in] adv_handle: advertisement set handle

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

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

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

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.

Return

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

Parameters
  • [in] adv_handle: advertisement set handle

  • [in] adv_data_length: periodic data length

  • [in] p_adv_data: pointer to the periodic data

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.

Return

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

Parameters
  • [in] adv_handle: - handle of the advertising set

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

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

Return

wiced_bt_dev_status_t

Parameters
  • [in] p_ext_scan_cfg: - pointer to scan configuration

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.

Return

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

Parameters
  • [in] options: - ref: wiced_bt_ble_adv_sync_options_t

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

  • [in] adv_addr_type: - address type

  • [in] adv_addr: - address value

  • [in] skip:

  • [in] sync_timeout: - timeout value

  • [in] sync_cte_type: - 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

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.

Return

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

Return

wiced_bt_dev_status_t

Parameters
  • [in] sync_handle: - Sync handle received in WICED_BT_BLE_PERIODIC_ADV_SYNC_ESTABLISHED_EVENT.

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.

Return

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

Parameters
  • [in] advertiser_addr_type: : Periodic advertiser addr type

  • [in] advetiser_addr: : Periodic advertiser addr

  • [in] adv_sid: : Periodic advertiser sid

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.

Return

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

Parameters
  • [in] advertiser_addr_type: : Periodic advertiser addr type

  • [in] advetiser_addr: : Periodic advertiser addr

  • [in] adv_sid: : Periodic advertiser sid

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.

Return

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.

Return

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.

Return

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

Parameters
  • [in] p_app_adv_ext_event_cb: - pointer to function to receive extended adv events.

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.

Return

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

Parameters
  • [in] sync_handle: : Sync handle

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

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

Return

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
Return

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

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

  • [in] transport: : BT_TRANSPORT_BR_EDR or BT_TRANSPORT_LE

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

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

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.

Return

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

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

Return

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

  • [in] transport: : BT_TRANSPORT_BR_EDR or BT_TRANSPORT_LE

  • [in] p_ref_data: : Encryption type wiced_bt_ble_sec_action_type_t

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)

Return

void

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

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

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
  • [in] bd_addr: : Address of the peer device

  • [in] type: : 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

Return

wiced_result_t

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

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

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

Return

wiced_result_t

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

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.

Return

TRUE if successful

Parameters

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

Return

wiced_result_t

Parameters
  • [in] bd_addr: : remote bd address

  • [out] p_key_mask: : ble key mask stored

add link key information to internal address resolution db

Return

wiced_result_t

Parameters
  • [in] p_link_keys: : link keys information stored in application side

remove link key information from internal address resolution db

Return

wiced_result_t

Parameters
  • [in] p_link_keys: : link keys information stored in application side