General Description

LE Security API.

Functions
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 More...

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 More...

uint16_t	wiced_bt_dev_get_acl_conn_handle (wiced_bt_device_address_t bdaddr, wiced_bt_transport_t transport)
	get the acl connection handle for bdaddr More...

void	wiced_bt_ble_security_grant (wiced_bt_device_address_t bd_addr, wiced_bt_smp_status_t res)
	Grant or deny access. More...

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 algorithm. More...

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. More...

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. More...

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. More...

wiced_result_t	wiced_ble_private_device_address_resolution (wiced_bt_device_address_t rpa, BT_OCTET16 irk)
	Function wiced_ble_private_device_address_resolution. More...

wiced_result_t	wiced_bt_ble_address_resolution_list_clear_and_disable (void)
	Function wiced_bt_ble_address_resolution_list_clear_and_disable. More...

void	wiced_bt_ble_resolving_list_auto_enable_set (wiced_bool_t enable)
	Function wiced_bt_ble_resolving_list_auto_enable_set. More...

wiced_result_t	wiced_bt_ble_resolving_list_enable (wiced_bool_t enable)
	Function wiced_bt_ble_resolving_list_enable. More...

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)
	Bluetooth LE Security Functions. More...

wiced_result_t	wiced_bt_dev_sec_pair_without_bonding (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)
	Pair with peer device(dont store the keys). More...

wiced_result_t	wiced_bt_dev_sec_bond_cancel (wiced_bt_device_address_t bd_addr)
	Cancel an ongoing bonding process with peer device. More...

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. More...

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) More...

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. More...

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 More...

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. More...

Function Documentation

◆ wiced_bt_ble_security_grant()

void wiced_bt_ble_security_grant	(	wiced_bt_device_address_t	bd_addr,
		wiced_bt_smp_status_t	res
	)

Grant or deny access.

Used in response to an BTM_SECURITY_REQUEST_EVT event.

Parameters

[in]	bd_addr	: peer device bd address.
[in]	res	: To allow pairing set to SMP_SUCCESS, To disallow pairing check wiced_bt_smp_status_t to set specific SMP error code

Returns: None

◆ wiced_bt_dev_sec_bond()

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
	)

Bluetooth LE Security Functions.

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)

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).

Returns

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

◆ wiced_bt_dev_add_device_to_address_resolution_db()

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

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

Returns: wiced_result_t

◆ wiced_bt_dev_remove_device_from_address_resolution_db()

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

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

Returns: wiced_result_t

◆ wiced_bt_dev_get_acl_conn_handle()

uint16_t wiced_bt_dev_get_acl_conn_handle	(	wiced_bt_device_address_t	bdaddr,
		wiced_bt_transport_t	transport
	)

get the acl connection handle for bdaddr

Parameters

[in]	bdaddr	device identity address
[in]	transport	connection transport

Returns: : acl connection handle

◆ wiced_bt_ble_data_signature()

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 algorithm.

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

Returns: TRUE if signing successful, otherwise FALSE.

◆ wiced_bt_ble_verify_signature()

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

[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.

Returns: TRUE if signature verified correctly; otherwise FALSE.

◆ wiced_bt_ble_get_security_state()

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

[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

Returns: TRUE if successful

◆ wiced_bt_ble_set_privacy_mode()

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

[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)

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_ble_private_device_address_resolution()

wiced_result_t wiced_ble_private_device_address_resolution	(	wiced_bt_device_address_t	rpa,
		BT_OCTET16	irk
	)

Function wiced_ble_private_device_address_resolution.

             This API verifies whether given device address is Resolvable Private Address or not

Parameters

rpa	LE Resolvable Private Address
irk	LE IRK

Returns: wiced_result_t WICED_BT_SUCCESS the identity of device address has been resolved. WICED_BT_ERROR otherwise.

◆ wiced_bt_ble_address_resolution_list_clear_and_disable()

wiced_result_t wiced_bt_ble_address_resolution_list_clear_and_disable ( void )

Function wiced_bt_ble_address_resolution_list_clear_and_disable.

This API clears the address resolution list and disables the address resolution feature.

Returns: wiced_result_t WICED_BT_SUCCESS if address resolution list is cleared and adress resolution feature is disabled. WICED_BT_ERROR otherwise.

◆ wiced_bt_ble_resolving_list_auto_enable_set()

void wiced_bt_ble_resolving_list_auto_enable_set ( wiced_bool_t enable )

Function wiced_bt_ble_resolving_list_auto_enable_set.

This API allows applications to enable/disable auto enablement of address resolution feature on update of the resolving list viz, wiced_bt_dev_add_device_to_address_resolution_db wiced_bt_dev_remove_device_from_address_resolution_db

Parameters

[in] enable : Set to 1 to enable auto enabling address resolution

Returns

◆ wiced_bt_ble_resolving_list_enable()

wiced_result_t wiced_bt_ble_resolving_list_enable ( wiced_bool_t enable )

Function wiced_bt_ble_resolving_list_enable.

This API allows applications to enable/disable address resolution feature

Parameters

[in] enable : Set to 1 to enable address resolution, 0 to disable

Note: : In order to add multiple devices to the address resolution db, invoke address resolution APIs in the following order wiced_bt_ble_address_resolution_list_clear_and_disable // to clear and disable the db wiced_bt_ble_resolving_list_auto_enable_set(0) // to disable auto enabling the db

wiced_bt_dev_add_device_to_address_resolution_db(..) .. wiced_bt_dev_add_device_to_address_resolution_db(..) wiced_bt_ble_resolving_list_enable(1) wiced_bt_ble_resolving_list_auto_enable_set(1)

Returns

◆ wiced_bt_dev_sec_pair_without_bonding()

wiced_result_t wiced_bt_dev_sec_pair_without_bonding	(	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
	)

Pair with peer device(dont store the keys).

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)

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).

Returns

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

◆ wiced_bt_dev_sec_bond_cancel()

wiced_result_t wiced_bt_dev_sec_bond_cancel ( wiced_bt_device_address_t bd_addr )

Cancel an ongoing bonding process with peer device.

Parameters

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

Returns

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

◆ wiced_bt_dev_set_encryption()

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.

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

Returns

WICED_BT_SUCCESS : already encrypted
WICED_BT_PENDING : Status is notified using BTM_ENCRYPTION_STATUS_EVT of wiced_bt_management_cback_t.
WICED_BT_WRONG_MODE : connection not up.
WICED_BT_BUSY : security procedures are currently active

◆ wiced_bt_dev_confirm_req_reply()

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

[in]	res	: result of the operation WICED_BT_SUCCESS if success
[in]	bd_addr	: Address of the peer device

Returns: void

◆ wiced_bt_dev_send_key_press_notif()

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_bt_dev_delete_bonded_device()

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

Attention: Stack does not store any bonding information. For applications which use BLE mode invoke wiced_bt_dev_remove_device_from_address_resolution_db to remove the device from the resolving list.

Parameters

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

Returns: Returns WICED_SUCCESS

◆ wiced_bt_dev_get_security_state()

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

[in]	bd_addr	: peer address
[out]	p_sec_flags	: security flags (see wiced_bt_sec_flags_e)

Returns: TRUE if successful