Address Resolving List#

Address Resolving List.

Provides support for adding and removing devices from the Resolving List in controller-based privacy.

Adding a peer device to the Resolving List allows the Bluetooth controller to resolve the address when the peer device is using privacy and is transmitting with a Resolvable Private Address (RPA). When the controller has resolved an address in a received Bluetooth packet such as an advertisement, the corresponding event will report the peer device's identity address even if a Resolvable Private Address was used over the air.

When the application has added a peer device to the Resolving List, the application may use the peer device's identity address in commands such as sl_bt_connection_open or sl_bt_sync_scanner_open even if the peer device is using privacy and is using a Resolvable Private Address over the air.

When a device is added to the Resolving List, the stack automatically sets the local Identity Resolving Key (IRK) of the entry based on the current local privacy state. If local privacy is active, the real local IRK is used, which causes the controller to use Resolvable Private Addresses for the local device's address. If local privacy is not active, an all-zero local IRK is used, which allows the controller to use the local device's identity address and to accept directed advertising packets addressed to the identity address.

Because the local IRK is set at the time the device is added, the application should remove all devices from the Resolving List and re-add them after changing the local privacy mode. Existing Resolving List entries are not automatically updated when the local privacy mode changes.

Enumerations#

enum

sl_bt_resolving_list_privacy_mode_t {

sl_bt_resolving_list_privacy_mode_network = 0x0

sl_bt_resolving_list_privacy_mode_device = 0x1

}

Specifies the Privacy Mode used for a peer device in the Resolving List. The privacy mode controls how the Bluetooth controller handles packets from the peer device.

Functions#

sl_status_t

sl_bt_resolving_list_add_device_by_bonding(uint32_t bonding, uint8_t privacy_mode)

sl_status_t

sl_bt_resolving_list_add_device_by_address(bd_addr address, uint8_t address_type, aes_key_128 key, uint8_t privacy_mode)

sl_status_t

sl_bt_resolving_list_remove_device_by_bonding(uint32_t bonding)

sl_status_t

sl_bt_resolving_list_remove_device_by_address(bd_addr address, uint8_t address_type)

sl_status_t

sl_bt_resolving_list_remove_all_devices(void)

sl_status_t

sl_bt_resolving_list_read_peer_resolvable_address(bd_addr address, uint8_t address_type, bd_addr *address_out)

Macros#

#define

sl_bt_cmd_resolving_list_add_device_by_bonding_id 0x005d0020

#define

sl_bt_cmd_resolving_list_add_device_by_address_id 0x015d0020

#define

sl_bt_cmd_resolving_list_remove_device_by_bonding_id 0x025d0020

#define

sl_bt_cmd_resolving_list_remove_device_by_address_id 0x035d0020

#define

sl_bt_cmd_resolving_list_remove_all_devices_id 0x045d0020

#define

sl_bt_cmd_resolving_list_read_peer_resolvable_address_id 0x055d0020

#define

sl_bt_rsp_resolving_list_add_device_by_bonding_id 0x005d0020

#define

sl_bt_rsp_resolving_list_add_device_by_address_id 0x015d0020

#define

sl_bt_rsp_resolving_list_remove_device_by_bonding_id 0x025d0020

#define

sl_bt_rsp_resolving_list_remove_device_by_address_id 0x035d0020

#define

sl_bt_rsp_resolving_list_remove_all_devices_id 0x045d0020

#define

sl_bt_rsp_resolving_list_read_peer_resolvable_address_id 0x055d0020

Enumeration Documentation#

sl_bt_resolving_list_privacy_mode_t#

sl_bt_resolving_list_privacy_mode_t

Specifies the Privacy Mode used for a peer device in the Resolving List. The privacy mode controls how the Bluetooth controller handles packets from the peer device.

Enumerator
sl_bt_resolving_list_privacy_mode_network	(0x0) Use Network Privacy Mode for the peer device. The controller will only accept Resolvable Private Addresses from the peer device. If the peer device has a non-zero IRK in the Resolving List and sends a packet using its identity address, the controller will reject the packet. This is the default and stricter mode that enforces the use of privacy by the peer device.
sl_bt_resolving_list_privacy_mode_device	(0x1) Use Device Privacy Mode for the peer device. The controller will accept both Resolvable Private Addresses and the identity address from the peer device. This is a more permissive mode that allows the peer device to use its identity address even when it has distributed its IRK. Note that using this mode means the peer device's network privacy is not enforced by the local controller.

Function Documentation#

sl_bt_resolving_list_add_device_by_bonding#

sl_status_t sl_bt_resolving_list_add_device_by_bonding (uint32_t bonding, uint8_t privacy_mode)

Parameters

Type Direction Argument Name Description

uint32_t

[in]

bonding

The bonding handle

uint8_t

[in]

privacy_mode

Enum sl_bt_resolving_list_privacy_mode_t. The Privacy Mode to use for the peer device. Values:

sl_bt_resolving_list_privacy_mode_network (0x0): Use Network Privacy Mode for the peer device. The controller will only accept Resolvable Private Addresses from the peer device. If the peer device has a non-zero IRK in the Resolving List and sends a packet using its identity address, the controller will reject the packet. This is the default and stricter mode that enforces the use of privacy by the peer device.
sl_bt_resolving_list_privacy_mode_device (0x1): Use Device Privacy Mode for the peer device. The controller will accept both Resolvable Private Addresses and the identity address from the peer device. This is a more permissive mode that allows the peer device to use its identity address even when it has distributed its IRK. Note that using this mode means the peer device's network privacy is not enforced by the local controller.

Default: sl_bt_resolving_list_privacy_mode_network (Use Network Privacy Mode for the peer device)

Add a device to the Resolving List based on its bonding handle.

This command is not available if the application uses the external bonding database provided by the component bluetooth_feature_external_bonding_database. In that configuration the application can use the command sl_bt_resolving_list_add_device_by_address and provide the peer's identity address and its Identity Resolving Key (IRK).

The local IRK for the Resolving List entry is set automatically based on whether local privacy is currently active. If local privacy is not active, an all-zero local IRK is used so that the local device uses its identity address.

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_resolving_list_add_device_by_address#

sl_status_t sl_bt_resolving_list_add_device_by_address (bd_addr address, uint8_t address_type, aes_key_128 key, uint8_t privacy_mode)

Parameters

Type	Direction	Argument Name	Description
bd_addr	[in]	address	Bluetooth address of the peer device
uint8_t	[in]	address_type	Enum sl_bt_gap_address_type_t. The peer device address type. Values: sl_bt_gap_public_address (0x0): Public device address sl_bt_gap_static_address (0x1): Static device address
aes_key_128	[in]	key	Identity Resolving Key (IRK) of the peer device in little endian format.
uint8_t	[in]	privacy_mode	Enum sl_bt_resolving_list_privacy_mode_t. The Privacy Mode to use for the peer device. Values: sl_bt_resolving_list_privacy_mode_network (0x0): Use Network Privacy Mode for the peer device. The controller will only accept Resolvable Private Addresses from the peer device. If the peer device has a non-zero IRK in the Resolving List and sends a packet using its identity address, the controller will reject the packet. This is the default and stricter mode that enforces the use of privacy by the peer device. sl_bt_resolving_list_privacy_mode_device (0x1): Use Device Privacy Mode for the peer device. The controller will accept both Resolvable Private Addresses and the identity address from the peer device. This is a more permissive mode that allows the peer device to use its identity address even when it has distributed its IRK. Note that using this mode means the peer device's network privacy is not enforced by the local controller. Default: sl_bt_resolving_list_privacy_mode_network (Use Network Privacy Mode for the peer device)

Add a device to the Resolving List based on its identity address and its Identity Resolving Key (IRK).

This command is typically only needed when the application uses the external bonding database provided by the component bluetooth_feature_external_bonding_database. When the application uses the built-in bonding database, the command sl_bt_resolving_list_add_device_by_bonding is more convenient.

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_resolving_list_remove_device_by_bonding#

sl_status_t sl_bt_resolving_list_remove_device_by_bonding (uint32_t bonding)

Parameters

Type	Direction	Argument Name	Description
uint32_t	[in]	bonding	The bonding handle

Remove a device from the Resolving List based on its bonding handle.

This command is not available if the application uses the external bonding database provided by the component bluetooth_feature_external_bonding_database. In that configuration the application can use the command sl_bt_resolving_list_remove_device_by_address and provide the peer's identity address.

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_resolving_list_remove_device_by_address#

sl_status_t sl_bt_resolving_list_remove_device_by_address (bd_addr address, uint8_t address_type)

Parameters

Type Direction Argument Name Description

bd_addr

[in]

address

Bluetooth address of the peer device

uint8_t

[in]

address_type

Enum sl_bt_gap_address_type_t. The peer device address type. Values:

sl_bt_gap_public_address (0x0): Public device address
sl_bt_gap_static_address (0x1): Static device address

Remove a device from the Resolving List based on its identity address.

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_resolving_list_remove_all_devices#

sl_status_t sl_bt_resolving_list_remove_all_devices (void )

Parameters

Type	Direction	Argument Name	Description
void	N/A

Remove all devices from the Resolving List.

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_resolving_list_read_peer_resolvable_address#

sl_status_t sl_bt_resolving_list_read_peer_resolvable_address (bd_addr address, uint8_t address_type, bd_addr * address_out)

Parameters

Type Direction Argument Name Description

Type	Direction	Argument Name	Description
bd_addr	[in]	address	Bluetooth identity address of the peer device
uint8_t	[in]	address_type	Enum sl_bt_gap_address_type_t. The peer identity address type. Values: sl_bt_gap_public_address (0x0): Public device address sl_bt_gap_static_address (0x1): Static device address
bd_addr *	[out]	address_out	The peer's current resolvable private address tracked by the controller.

bd_addr

[in]

address

Bluetooth identity address of the peer device

uint8_t

[in]

address_type

Enum sl_bt_gap_address_type_t. The peer identity address type. Values:

sl_bt_gap_public_address (0x0): Public device address
sl_bt_gap_static_address (0x1): Static device address

bd_addr *

[out]

address_out

The peer's current resolvable private address tracked by the controller.

Read the peer's current Resolvable Private Address (RPA) from the controller Resolving List.

The peer must already exist in the Resolving List. The command identifies the peer by its identity address. The controller returns the current peer RPA that it is tracking for that Resolving List entry.

Use this command when the application needs to inspect the peer's current over-the-air RPA after the peer has been resolved to its identity address by the controller.

Returns

SL_STATUS_OK if successful. Error code otherwise.