Security Manager#

sl_bt_sm_io_capability_t#

sl_bt_sm_io_capability_t

These values define the security management related I/O capabilities supported by the device.

sl_bt_sm_configure#

sl_status_t sl_bt_sm_configure (uint8_t flags, uint8_t io_capabilities)

Configure security requirements and I/O capabilities of the system.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_set_minimum_key_size#

sl_status_t sl_bt_sm_set_minimum_key_size (uint8_t minimum_key_size)

Set the minimum allowed key size used for bonding. The default value is 16 bytes.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_set_debug_mode#

sl_status_t sl_bt_sm_set_debug_mode ()

Set Security Manager in debug mode. In this mode, the secure connections bonding uses known debug keys, so that the encrypted packet can be opened by Bluetooth protocol analyzer. To disable the debug mode, restart the device.

Bondings made in debug mode are unsecure.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_store_bonding_configuration#

sl_status_t sl_bt_sm_store_bonding_configuration (uint8_t max_bonding_count, uint8_t policy_flags)

Set the maximum allowed bonding count and bonding policy. The maximum number of bondings that can be supported depends on how much user data is stored in the NVM3 and the NVM3 size. When bond policy value 1 or 2 is selected, the stack will automatically write the new bond, as per the policy, only if the maximum allowed bonding count has been reached. If the stack can't write a new bond for any other reason (e.g., NVM3 is full), an error will be thrown through the bonding_failed event indicating why the bonding was not written. The application has to manually release space from the NVM (e.g., by deleting one of the existing bonds or application data) so that a new bond can be saved. The default value is 13.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_set_bondable_mode#

sl_status_t sl_bt_sm_set_bondable_mode (uint8_t bondable)

Set whether the device should accept new bondings. By default, the device does not accept new bondings.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_set_passkey#

sl_status_t sl_bt_sm_set_passkey (int32_t passkey)

Enter a fixed passkey, which will be used in the sl_bt_evt_sm_passkey_display event.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_increase_security#

sl_status_t sl_bt_sm_increase_security (uint8_t connection)

Enhance the security of a connection to current security requirements. On an unencrypted connection, it will encrypt the connection and will also perform bonding if requested by both devices. On an encrypted connection, it will cause the connection to be re-encrypted.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_bt_evt_connection_parameters - Triggered after increasing security has been completed successfully and indicates the latest security mode of the connection.

• sl_bt_evt_sm_bonded - Triggered if pairing or bonding was performed in this operation and the result is successful.

• sl_bt_evt_sm_bonding_failed - Triggered if pairing or bonding was performed in this operation and the result has failed.

sl_bt_sm_enter_passkey#

sl_status_t sl_bt_sm_enter_passkey (uint8_t connection, int32_t passkey)

Enter a passkey after receiving a passkey request event.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_passkey_confirm#

sl_status_t sl_bt_sm_passkey_confirm (uint8_t connection, uint8_t confirm)

Accept or reject the reported passkey confirm value.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_bonding_confirm#

sl_status_t sl_bt_sm_bonding_confirm (uint8_t connection, uint8_t confirm)

Accept or reject the bonding request.

NOTE! When the bonding handle for the connection is anything other than SL_BT_INVALID_BONDING_HANDLE (0xff), a bonding already exists for this connection. Overwriting the existing bonding is a potential security risk. The bonding handle is included in the sl_bt_evt_sm_confirm_bonding event.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_delete_bonding#

sl_status_t sl_bt_sm_delete_bonding (uint8_t bonding)

Delete the specified bonding. The connection will be closed if the remote device is connected currently.

This commands deletes the information from the persistent bonding database when the built-in bonding database (bluetooth_feature_builtin_bonding_database) is used.

When used with Filter Accept List (bluetooth_feature_accept_list) or Resolving List (bluetooth_feature_resolving_list), this command removes the deleted device from the lists.

This command is unavailable if the external bonding database (bluetooth_feature_external_bonding_database) is used.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_delete_bondings#

sl_status_t sl_bt_sm_delete_bondings ()

Delete all bondings and device local identity resolving key (IRK). All connections to affected devices are closed as well.

This command empties the persistent bonding database when the built-in bonding database (bluetooth_feature_builtin_bonding_database) is used.

When used with Filter Accept List (bluetooth_feature_accept_list) or Resolving List (bluetooth_feature_resolving_list), this command removes the deleted devices from the lists.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_get_bonding_handles#

sl_status_t sl_bt_sm_get_bonding_handles (uint32_t reserved, uint32_t * num_bondings, size_t max_bondings_size, size_t * bondings_len, uint8_t * bondings)

Get number of entries and bitmask of their handles saved in the bonding database.

To get the bonding information and peer device address of a bonding, use the sl_bt_sm_get_bonding_details command. The bonding handle can be calculated from the handle bitmask returned by this command, or alternatively, repeat calling the sl_bt_sm_get_bonding_details command to get the detailed information of all bondings.

This command is unavailable if the external bonding database (bluetooth_feature_external_bonding_database) is used.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_get_bonding_details#

sl_status_t sl_bt_sm_get_bonding_details (uint32_t bonding, bd_addr * address, uint8_t * address_type, uint8_t * security_mode, uint8_t * key_size)

Get the detailed information for a bonding entry. Data includes remote device address and address type as well as security mode for bonding and a used encryption key length.

To get the detailed information of all bondings, repeat calling this command starting from 0 as the bonding handle value until the maximum number of configured bondings are reached. Use 32 as the maximum number if the configured number is unknown.

This command is unavailable if the external bonding database (bluetooth_feature_external_bonding_database) is used.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_find_bonding_by_address#

sl_status_t sl_bt_sm_find_bonding_by_address (bd_addr address, uint32_t * bonding, uint8_t * security_mode, uint8_t * key_size)

Find the bonding entry by using a Bluetooth device address.

This command is unavailable if the external bonding database (bluetooth_feature_external_bonding_database) is used.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_resolve_rpa#

sl_status_t sl_bt_sm_resolve_rpa (bd_addr rpa, bd_addr * address, uint8_t * address_type, uint32_t * bonding)

Find the identity address of bonded device by using resolvable private address (RPA).

The error SL_STATUS_NOT_FOUND is returned if the RPA cannot be resolved.

This command is unavailable if the external bonding database (bluetooth_feature_external_bonding_database) is used.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_set_bonding_key#

SL_BGAPI_DEPRECATED sl_status_t sl_bt_sm_set_bonding_key (uint32_t bonding, uint8_t key_type, aes_key_128 key)

sl_bt_sm_set_legacy_oob#

sl_status_t sl_bt_sm_set_legacy_oob (uint8_t enable, aes_key_128 oob_data)

Set Out-Of-Band (OOB) encryption data for a legacy pairing of a device. OOB data may be, for example, a PIN code exchanged over an alternate path, such as NFC. The device will not allow any other bonding if OOB data is set. OOB data can't be set simultaneously with secure connections OOB data.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_set_oob#

sl_status_t sl_bt_sm_set_oob (uint8_t enable, aes_key_128 * random, aes_key_128 * confirm)

Enable the use of Out-Of-Band (OOB) encryption data for a device for secure connections pairing. Enabling will generate new OOB data and confirm values, which can be sent to the remote device. After enabling the secure connections OOB data, the remote devices OOB data can be set with sl_bt_sm_set_remote_oob. Calling this function will erase any set remote device OOB data and confirm values. The device will not allow any other bonding if OOB data is set. The secure connections OOB data cannot be enabled simultaneously with legacy pairing OOB data.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_set_remote_oob#

sl_status_t sl_bt_sm_set_remote_oob (uint8_t enable, aes_key_128 random, aes_key_128 confirm)

Set Out-Of-Band (OOB) data and confirm values received from the remote device for secure connections pairing. OOB data must be enabled with sl_bt_sm_set_oob before setting the remote device OOB data.

Returns

• SL_STATUS_OK if successful. Error code otherwise.

sl_bt_cmd_sm_configure_id#

#define sl_bt_cmd_sm_configure_id

0x010f0020

sl_bt_cmd_sm_set_minimum_key_size_id#

#define sl_bt_cmd_sm_set_minimum_key_size_id

0x140f0020

sl_bt_cmd_sm_set_debug_mode_id#

#define sl_bt_cmd_sm_set_debug_mode_id

0x0f0f0020

sl_bt_cmd_sm_store_bonding_configuration_id#

#define sl_bt_cmd_sm_store_bonding_configuration_id

0x020f0020

sl_bt_cmd_sm_set_bondable_mode_id#

#define sl_bt_cmd_sm_set_bondable_mode_id

0x000f0020

sl_bt_cmd_sm_set_passkey_id#

#define sl_bt_cmd_sm_set_passkey_id

0x100f0020

sl_bt_cmd_sm_increase_security_id#

#define sl_bt_cmd_sm_increase_security_id

0x040f0020

sl_bt_cmd_sm_enter_passkey_id#

#define sl_bt_cmd_sm_enter_passkey_id

0x080f0020

sl_bt_cmd_sm_passkey_confirm_id#

#define sl_bt_cmd_sm_passkey_confirm_id

0x090f0020

sl_bt_cmd_sm_bonding_confirm_id#

#define sl_bt_cmd_sm_bonding_confirm_id

0x0e0f0020

sl_bt_cmd_sm_delete_bonding_id#

#define sl_bt_cmd_sm_delete_bonding_id

0x060f0020

sl_bt_cmd_sm_delete_bondings_id#

#define sl_bt_cmd_sm_delete_bondings_id

0x070f0020

sl_bt_cmd_sm_get_bonding_handles_id#

#define sl_bt_cmd_sm_get_bonding_handles_id

0x150f0020

sl_bt_cmd_sm_get_bonding_details_id#

#define sl_bt_cmd_sm_get_bonding_details_id

0x160f0020

sl_bt_cmd_sm_find_bonding_by_address_id#

#define sl_bt_cmd_sm_find_bonding_by_address_id

0x170f0020

sl_bt_cmd_sm_resolve_rpa_id#

#define sl_bt_cmd_sm_resolve_rpa_id

0x1d0f0020

sl_bt_cmd_sm_set_bonding_key_id#

#define sl_bt_cmd_sm_set_bonding_key_id

0x180f0020

sl_bt_cmd_sm_set_legacy_oob_id#

#define sl_bt_cmd_sm_set_legacy_oob_id

0x190f0020

sl_bt_cmd_sm_set_oob_id#

#define sl_bt_cmd_sm_set_oob_id

0x1a0f0020

sl_bt_cmd_sm_set_remote_oob_id#

#define sl_bt_cmd_sm_set_remote_oob_id

0x1b0f0020

sl_bt_rsp_sm_configure_id#

#define sl_bt_rsp_sm_configure_id

0x010f0020

sl_bt_rsp_sm_set_minimum_key_size_id#

#define sl_bt_rsp_sm_set_minimum_key_size_id

0x140f0020

sl_bt_rsp_sm_set_debug_mode_id#

#define sl_bt_rsp_sm_set_debug_mode_id

0x0f0f0020

sl_bt_rsp_sm_store_bonding_configuration_id#

#define sl_bt_rsp_sm_store_bonding_configuration_id

0x020f0020

sl_bt_rsp_sm_set_bondable_mode_id#

#define sl_bt_rsp_sm_set_bondable_mode_id

0x000f0020

sl_bt_rsp_sm_set_passkey_id#

#define sl_bt_rsp_sm_set_passkey_id

0x100f0020

sl_bt_rsp_sm_increase_security_id#

#define sl_bt_rsp_sm_increase_security_id

0x040f0020

sl_bt_rsp_sm_enter_passkey_id#

#define sl_bt_rsp_sm_enter_passkey_id

0x080f0020

sl_bt_rsp_sm_passkey_confirm_id#

#define sl_bt_rsp_sm_passkey_confirm_id

0x090f0020

sl_bt_rsp_sm_bonding_confirm_id#

#define sl_bt_rsp_sm_bonding_confirm_id

0x0e0f0020

sl_bt_rsp_sm_delete_bonding_id#

#define sl_bt_rsp_sm_delete_bonding_id

0x060f0020

sl_bt_rsp_sm_delete_bondings_id#

#define sl_bt_rsp_sm_delete_bondings_id

0x070f0020

sl_bt_rsp_sm_get_bonding_handles_id#

#define sl_bt_rsp_sm_get_bonding_handles_id

0x150f0020

sl_bt_rsp_sm_get_bonding_details_id#

#define sl_bt_rsp_sm_get_bonding_details_id

0x160f0020

sl_bt_rsp_sm_find_bonding_by_address_id#

#define sl_bt_rsp_sm_find_bonding_by_address_id

0x170f0020

sl_bt_rsp_sm_resolve_rpa_id#

#define sl_bt_rsp_sm_resolve_rpa_id

0x1d0f0020

sl_bt_rsp_sm_set_bonding_key_id#

#define sl_bt_rsp_sm_set_bonding_key_id

0x180f0020

sl_bt_rsp_sm_set_legacy_oob_id#

#define sl_bt_rsp_sm_set_legacy_oob_id

0x190f0020

sl_bt_rsp_sm_set_oob_id#

#define sl_bt_rsp_sm_set_oob_id

0x1a0f0020

sl_bt_rsp_sm_set_remote_oob_id#

#define sl_bt_rsp_sm_set_remote_oob_id

0x1b0f0020