External Bonding Database#

External Bonding Database.

Receive and respond to requests related to managing an external bonding database. When the application uses the bluetooth_feature_external_bonding_database feature, the Bluetooth stack and the application use the commands and events in this class to store and retrieve data from the persistent bonding storage.

When this feature is used, the built-in bonding database (bluetooth_feature_builtin_bonding_database) and the address resolving in the Bluetooth stack are excluded. The user application and external bonding database are responsible for the following functionalities:

  • The external bonding database must be able to reliably and permanently store the bonding data and type tuples that are provided by the stack in the sl_bt_evt_external_bondingdb_data_request event. Data types sl_bt_external_bondingdb_data_remote_address and sl_bt_external_bondingdb_data_remote_address_type can be used by the application to identify the device, but they are not used by the stack and hence the stack will not ask for their values. Other data types in sl_bt_external_bondingdb_data_t are needed by the Bluetooth Security Manager or GATT Server. The Long Term Keys (LTK) and Identity Resolving Keys (IRK) must be stored securely. When the database is on a separate host device, they must be securely transmitted between the host and target over the NCP transport. The application also needs to manage the bondings in the storage, e.g., delete a bonding when requested by the business logic.

  • Manage a local RAM-based bookkeeping to keep track of open connections. At a minimum, the remote Bluetooth address address and address type must be stored in the bookkeeping when a sl_bt_evt_connection_opened event is received. If the remote Bluetooth device address is a resolvable private random (RPA) address, the application may perform address resolving using the IRK keys of the remote devices stored in the bonding database. Address resolving is required for identifying a connected device using an RPA address. When the scanner or periodic advertising synchronization feature is used, RPA addresses in advertisement report or sync events may need to be resolved if required by the business requirements.

  • When the Bluetooth stack requires bonding data, it will send an sl_bt_evt_external_bondingdb_data_request event. The application must respond to the request by sending the data value using the sl_bt_external_bondingdb_set_data command. The GATT server will pend the requests from the remote GATT client and encryption or bonding is not possible until all requested bonding data has been sent to the stack. The stack will send sl_bt_evt_external_bondingdb_data_ready when it has received all the necessary bonding data from the application.

In this configuration, the value of bonding parameter in sl_bt_evt_advertiser_scan_request, sl_bt_evt_connection_opened, sl_bt_evt_sm_bonded, sl_bt_evt_scanner_scan_report, sl_bt_evt_scanner_legacy_advertisement_report, sl_bt_evt_scanner_extended_advertisement_report, sl_bt_evt_sync_opened, and sl_bt_evt_sync_transfer_received is always SL_BT_INVALID_BONDING_HANDLE (0xff). Resolving the bonding handle is the responsibility of the external bonding database. Additionally, the following BGAPI commands are not available and will return the SL_STATUS_NOT_AVAILABLE error:

Modules#

sl_bt_evt_external_bondingdb_data_request

sl_bt_evt_external_bondingdb_data

sl_bt_evt_external_bondingdb_data_ready

Enumerations#

enum
sl_bt_external_bondingdb_data_remote_address = 0x0
sl_bt_external_bondingdb_data_remote_address_type = 0x1
sl_bt_external_bondingdb_data_remote_ltk = 0x2
sl_bt_external_bondingdb_data_local_ltk = 0x3
sl_bt_external_bondingdb_data_remote_central_inf = 0x4
sl_bt_external_bondingdb_data_local_central_inf = 0x5
sl_bt_external_bondingdb_data_irk = 0x6
sl_bt_external_bondingdb_data_meta = 0x7
sl_bt_external_bondingdb_data_gatt_client_config = 0x8
sl_bt_external_bondingdb_data_gatt_client_features = 0x9
sl_bt_external_bondingdb_data_gatt_db_hash = 0xa
}

These values define the bonding data types, which are stored in the persistent store.

Functions#

sl_status_t
sl_bt_external_bondingdb_set_data(uint8_t connection, uint8_t type, size_t data_len, const uint8_t *data)

Enumeration Documentation#

sl_bt_external_bondingdb_data_t#

sl_bt_external_bondingdb_data_t

These values define the bonding data types, which are stored in the persistent store.

Enumerator
sl_bt_external_bondingdb_data_remote_address

(0x0) Identity address of the remote device, which a resolvable random address can be resolved to

sl_bt_external_bondingdb_data_remote_address_type

(0x1) Type of the remote device identity address. Value 0 is public device address and 1 is static device address

sl_bt_external_bondingdb_data_remote_ltk

(0x2) Long Term Key (LTK) used as central device. The value of this type must be stored securely.

sl_bt_external_bondingdb_data_local_ltk

(0x3) Long Term Key (LTK) used as peripheral device. The value of this type must be stored securely.

sl_bt_external_bondingdb_data_remote_central_inf

(0x4) Identification info used as a central device

sl_bt_external_bondingdb_data_local_central_inf

(0x5) Identification info used as a central device

sl_bt_external_bondingdb_data_irk

(0x6) Identity Resolving Key (IRK) of the remote device that is used for resolving its RPA addresses when the device is in privacy mode. The value of this type must be stored securely.

sl_bt_external_bondingdb_data_meta

(0x7) Metadata about the bonding

sl_bt_external_bondingdb_data_gatt_client_config

(0x8) The remote GATT client characteristic configurations

sl_bt_external_bondingdb_data_gatt_client_features

(0x9) The remote GATT client supported features

sl_bt_external_bondingdb_data_gatt_db_hash

(0xa) Latest local GATT database hash value that the remote client has seen for GATT robust caching feature


Definition at line 11594 of file /mnt/raid/workspaces/ws.iUTchugV0/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

Function Documentation#

sl_bt_external_bondingdb_set_data#

sl_status_t sl_bt_external_bondingdb_set_data (uint8_t connection, uint8_t type, size_t data_len, const uint8_t * data)
Parameters
[in]connection

Connection handle

[in]type

Enum sl_bt_external_bondingdb_data_t. Bonding data type. Values:

  • sl_bt_external_bondingdb_data_remote_address (0x0): Identity address of the remote device, which a resolvable random address can be resolved to

  • sl_bt_external_bondingdb_data_remote_address_type (0x1): Type of the remote device identity address. Value 0 is public device address and 1 is static device address

  • sl_bt_external_bondingdb_data_remote_ltk (0x2): Long Term Key (LTK) used as central device. The value of this type must be stored securely.

  • sl_bt_external_bondingdb_data_local_ltk (0x3): Long Term Key (LTK) used as peripheral device. The value of this type must be stored securely.

  • sl_bt_external_bondingdb_data_remote_central_inf (0x4): Identification info used as a central device

  • sl_bt_external_bondingdb_data_local_central_inf (0x5): Identification info used as a central device

  • sl_bt_external_bondingdb_data_irk (0x6): Identity Resolving Key (IRK) of the remote device that is used for resolving its RPA addresses when the device is in privacy mode. The value of this type must be stored securely.

  • sl_bt_external_bondingdb_data_meta (0x7): Metadata about the bonding

  • sl_bt_external_bondingdb_data_gatt_client_config (0x8): The remote GATT client characteristic configurations

  • sl_bt_external_bondingdb_data_gatt_client_features (0x9): The remote GATT client supported features

  • sl_bt_external_bondingdb_data_gatt_db_hash (0xa): Latest local GATT database hash value that the remote client has seen for GATT robust caching feature

[in]data_len

Length of data in data

[in]data

Bonding data

Set bonding data of a connection from the external bonding database. When the Bluetooth stack needs bonding data, it will send the request to user application with a sl_bt_evt_external_bondingdb_data_request event that contains the requested data type. The application must respond to the request by sending data using this command.

Send 0 length data to the stack with this command if the requested data is not available in the external bonding database.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 11880 of file /mnt/raid/workspaces/ws.iUTchugV0/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

Macro Definition Documentation#

sl_bt_cmd_external_bondingdb_set_data_id#

#define sl_bt_cmd_external_bondingdb_set_data_id
Value:
0x005c0020

Definition at line 11587 of file /mnt/raid/workspaces/ws.iUTchugV0/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_external_bondingdb_set_data_id#

#define sl_bt_rsp_external_bondingdb_set_data_id
Value:
0x005c0020

Definition at line 11588 of file /mnt/raid/workspaces/ws.iUTchugV0/overlay/gsdk/protocol/bluetooth/build_release/bt_api/sw/bgapi/inc/sl_bt_api.h