Security Manager#

Security Manager.

Modules#

sl_bt_evt_sm_passkey_display

sl_bt_evt_sm_passkey_request

sl_bt_evt_sm_confirm_passkey

sl_bt_evt_sm_bonded

sl_bt_evt_sm_bonding_failed

sl_bt_evt_sm_confirm_bonding

sl_bt_evt_sm_list_bonding_entry

sl_bt_evt_sm_list_all_bondings_complete

Enumerations#

Functions#

Detailed Description#

Security Manager.

The commands in this class manage Bluetooth security, including commands for starting and stopping encryption and commands for management of all bonding operations.

The following procedure is used to bond with a remote device:

• Use command sl_bt_sm_configure to configure security requirements and I/O capabilities of this device.

• Use command sl_bt_sm_set_bondable_mode to set this device into bondable mode.

• Use command sl_bt_connection_open to open a connection to the remote device.

• After the connection is open, use command sl_bt_sm_increase_security to encrypt the connection. This will also start the bonding process.

The following procedure can be used to respond to the bonding initiated by a remote device:

• Use command sl_bt_sm_configure to configure security requirements and I/O capabilities of this device.

• Use command sl_bt_sm_set_bondable_mode to set this device into bondable mode.

• Use command sl_bt_advertiser_start to set this device into advertising and connectable mode.

• Open a connection to this device from the remote device.

• After the connection is open, start the bonding process on the remote device.

If MITM is required, the application needs to display or ask the user to enter a passkey during the process. See events sl_bt_evt_sm_passkey_display and sl_bt_evt_sm_passkey_request for more information.

Enumeration Type Documentation#

sm_bonding_key_t#

enum sm_bonding_key_t

Bonding Keys.

sm_io_capability_t#

enum sm_io_capability_t

SMP I/O Capabilities.

Function Documentation#

sl_bt_sm_configure()#

(
	 uint8_t 	 flags, 
	 uint8_t 	 io_capabilities 
)

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

Parameters

Returns

 SL_STATUS_OK if successful. Error code otherwise.

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.

Parameters

Returns

 SL_STATUS_OK if successful. Error code otherwise.

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_add_to_whitelist()#

Add device to whitelist, which can be enabled with sl_bt_gap_enable_whitelisting.

Parameters

Returns

 SL_STATUS_OK if successful. Error code otherwise.

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 NVM and the NVM 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 is not able to write a new bond for any other reason (e.g. nvm full) then an error will be thrown through the bonding_failed event indicating why the bonding could not be written. It is left up to the application 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.

Parameters

Returns

 SL_STATUS_OK if successful. Error code otherwise.

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.

Parameters

Returns

 SL_STATUS_OK if successful. Error code otherwise.

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.

Parameters

Returns

 SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_set_oob_data()#

(
	 size_t 	 oob_data_len 
	 const uint8_t * 	 oob_data 
)

Set OOB data (out-of-band encryption data) for legacy pairing for 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.

Parameters

Returns

 SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_use_sc_oob()#

(
	 uint8_t 	 enable 
	 size_t 	 max_oob_data_size 
	 size_t * 	 oob_data_len 
	 uint8_t * 	 oob_data 
)

Enable the use of OOB data (out-of-band 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_sc_remote_oob_data. 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.

Parameters

Returns

 SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_set_sc_remote_oob_data()#

(
	 size_t 	 oob_data_len 
	 const uint8_t * 	 oob_data 
)

Set OOB data and confirm values (out-of-band encryption) received from the remote device for secure connections pairing. OOB data must be enabled with sl_bt_sm_use_sc_oob before setting the remote device OOB data.

Parameters

Returns

 SL_STATUS_OK if successful. Error code otherwise.

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.

Parameters

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

(
	 uint8_t 	 connection 
	 int32_t 	 passkey 
)

Enter a passkey after receiving a passkey request event.

Parameters

Returns

 SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_passkey_confirm()#

(
	 uint8_t 	 connection 
	 uint8_t 	 confirm 
)

Accept or reject the reported passkey confirm value.

Parameters

Returns

 SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_bonding_confirm()#

(
	 uint8_t 	 connection 
	 uint8_t 	 confirm 
)

Accept or reject the bonding request.

Parameters

Returns

 SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_list_all_bondings()#

(	)

List all bondings stored in the bonding database. Bondings are reported by the sl_bt_evt_sm_list_bonding_entry event for each bonding and the report is ended with sl_bt_evt_sm_list_all_bondings_complete event. Use only for debugging purposes because reading from the persistent store is relatively slow.

Returns

 SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_bt_evt_sm_list_bonding_entry

• sl_bt_evt_sm_list_all_bondings_complete

sl_bt_sm_delete_bonding()#

(
	 uint8_t 	 bonding
)

Delete specified bonding information or whitelist from the persistent store.

Parameters

Returns

 SL_STATUS_OK if successful. Error code otherwise.

sl_bt_sm_delete_bondings()#

(	)

Delete all bonding information and whitelist from the persistent store.

Returns

 SL_STATUS_OK if successful. Error code otherwise.