LE Security

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_dev_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 algorith. 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...
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_dev_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	: WICED_BT_SUCCESS to grant access; WICED_BT_UNSUPPORTED , if local device does not allow pairing; WICED_BT_REPEATED_ATTEMPTS otherwise

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

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_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