Security Manager#

Security Manager.

  sl_bt_sm_io_capability_keyboarddisplay = 0x4

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

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.

Use the following procedure to bond with a remote device:

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

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

• Use the 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.

Use the following procedure to respond to the bonding initiated by a remote device:

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

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

• Use the command sl_bt_advertiser_start to start connectable advertising.

• 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#

◆sl_bt_sm_io_capability_t#

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

Function Documentation#

◆sl_bt_sm_configure()#

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

Parameters

• 1: Bonding requires authentication (Man-in-the-Middle protection)

Bit 1:* 0: Allow encryption without bonding

• 1: Encryption requires bonding. Note that this setting will also enable bonding.

Bit 2:* 0: Allow bonding with legacy pairing

• 1: Secure connections only

Bit 3:* 0: Bonding request does not need to be confirmed

• 1: Bonding requests need to be confirmed. Received bonding requests are notified by sl_bt_evt_sm_confirm_bonding

Bit 4:* 0: Allow all connections

• 1: Allow connections only from bonded devices

Bit 5:* 0: Prefer just works pairing when both options are possible based on the settings.

• 1: Prefer authenticated pairing when both options are possible based on the settings.

Bit 6:* 0: Allow secure connections OOB pairing with OOB data from only one device.

• 1: Require secure connections OOB data from both devices.

Bit 7: Reserved Default value: 0x00 | | [in] | io_capabilities | Enum sl_bt_sm_io_capability_t. I/O Capabilities. The default I/O Capability used by the stack is No Input and No Output. Values:* sl_bt_sm_io_capability_displayonly (0x0): Display Only

• sl_bt_sm_io_capability_displayyesno (0x1): Display with Yes/No-buttons

• sl_bt_sm_io_capability_keyboardonly (0x2): Keyboard Only

• sl_bt_sm_io_capability_noinputnooutput (0x3): No Input and No Output

• sl_bt_sm_io_capability_keyboarddisplay (0x4): Display with Keyboard |

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_sm_set_minimum_key_size()#

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

Parameters

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

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_sm_add_to_whitelist()#

Add device to accept list, which can be enabled with sl_bt_gap_enable_whitelisting.

When using external bonding database, the accept list size must be set before adding devices to the list using sl_bt_sm_store_bonding_configuration.

Parameters

• sl_bt_gap_static_address (0x1): Static device address

• sl_bt_gap_random_resolvable_address (0x2): Resolvable private random address

• sl_bt_gap_random_nonresolvable_address (0x3): Non-resolvable private random address |

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_sm_store_bonding_configuration()#

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 can't write a new bond for any other reason (e.g., NVM 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.

When using external bonding database with accept list filtering, this command must be called before adding devices to the accept list to define the list size. Calling this function empties the existing accept list.

Parameters

• 1: New bonding will overwrite the oldest existing bonding

• 2: New bonding will overwrite the bonding that was used the longest time ago

Default: 0 With external bonding database the parameter is ignored. |

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_sm_set_bondable_mode()#

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

Parameters

• 1: Bondings allowed

Default value: 0 |

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_sm_set_passkey()#

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

Parameters

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_sm_increase_security()#

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

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

Enter a passkey after receiving a passkey request event.

Parameters

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_sm_passkey_confirm()#

Accept or reject the reported passkey confirm value.

Parameters

• 1: Accept confirm value |

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_sm_bonding_confirm()#

Accept or reject the bonding request.

Parameters

• 1: Accept bonding request |

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_sm_delete_bonding()#

Delete the specified bonding or accept list filtering. 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.

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

Parameters

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_sm_delete_bondings()#

Delete all bondings, accept list filtering 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.

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_sm_get_bonding_handles()#

Get number of entries and bitmask of their handles saved in the bonding database. The entry in the bonding database can be either bonding or accept list filtering device.

To get the bonding type 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.

Parameters

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_sm_get_bonding_details()#

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.

Parameters

• sl_bt_gap_static_address (0x1): Static device address | | [out] | security_mode | Enum sl_bt_connection_security_t. Connection security mode. Accept list filtering entry has security mode as no security. Values:* sl_bt_connection_mode1_level1 (0x0): No security

• sl_bt_connection_mode1_level2 (0x1): Unauthenticated pairing with encryption

• sl_bt_connection_mode1_level3 (0x2): Authenticated pairing with encryption

• sl_bt_connection_mode1_level4 (0x3): Authenticated Secure Connections pairing with encryption using a 128-bit strength encryption key | | [out] | key_size | Key length in bytes, 0 for accept list filtering entry |

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_sm_find_bonding_by_address()#

Find the bonding or accept list filtering entry by using a Bluetooth device address.

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

Parameters

• sl_bt_connection_mode1_level2 (0x1): Unauthenticated pairing with encryption

• sl_bt_connection_mode1_level3 (0x2): Authenticated pairing with encryption

• sl_bt_connection_mode1_level4 (0x3): Authenticated Secure Connections pairing with encryption using a 128-bit strength encryption key | | [out] | key_size | Key length in bytes, 0 for accept list filtering entry |

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_sm_set_legacy_oob()#

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.

Parameters

• 1: enable | | [in] | oob_data | 16-byte legacy pairing OOB data in little endian format. |

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_sm_set_oob()#

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.

Parameters

• 1: enable | | [out] | random | 16-byte randomly-generated secure connections OOB data in little endian format. | | [out] | confirm | 16-byte confirm value for the OOB random value in little endian format. |

ReturnsSL_STATUS_OK if successful. Error code otherwise.

◆sl_bt_sm_set_remote_oob()#

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.

Parameters

• 1: enable | | [in] | random | 16-byte remote device secure connections OOB data in little endian format. | | [in] | confirm | 16-byte remote device confirm value for the OOB random value in little endian format. |

ReturnsSL_STATUS_OK if successful. Error code otherwise.