Security Manager
Security Manager.
Modules | |
sl_bt_evt_sm_passkey_display | |
Indicates a request to display the passkey to the user. | |
sl_bt_evt_sm_passkey_request | |
Indicates a request for the passkey prompt displayed on the remote device. | |
sl_bt_evt_sm_confirm_passkey | |
Indicates a request for passkey display and confirmation by the user. | |
sl_bt_evt_sm_bonded | |
Triggered after the pairing or bonding procedure is successfully completed. | |
sl_bt_evt_sm_bonding_failed | |
This event is triggered if the pairing or bonding procedure fails. | |
sl_bt_evt_sm_confirm_bonding | |
Indicates a user request to display that the new bonding request is received and for the user to confirm the request. | |
sl_bt_evt_sm_list_bonding_entry | |
Triggered by the command sl_bt_sm_list_all_bondings if bondings exist in the local database. | |
sl_bt_evt_sm_list_all_bondings_complete | |
Triggered by the sl_bt_sm_list_all_bondings and follows sl_bt_evt_sm_list_bonding_entry events. | |
Enumerations | |
enum | sl_bt_sm_io_capability_t { sl_bt_sm_io_capability_displayonly = 0x0, sl_bt_sm_io_capability_displayyesno = 0x1, sl_bt_sm_io_capability_keyboardonly = 0x2, sl_bt_sm_io_capability_noinputnooutput = 0x3, sl_bt_sm_io_capability_keyboarddisplay = 0x4 } |
These values define the security management related I/O capabilities supported by the device. | |
Functions | |
sl_status_t | sl_bt_sm_configure (uint8_t flags, uint8_t io_capabilities) |
sl_status_t | sl_bt_sm_set_minimum_key_size (uint8_t minimum_key_size) |
sl_status_t | sl_bt_sm_set_debug_mode () |
sl_status_t | sl_bt_sm_add_to_whitelist (bd_addr address, uint8_t address_type) |
sl_status_t | sl_bt_sm_store_bonding_configuration (uint8_t max_bonding_count, uint8_t policy_flags) |
sl_status_t | sl_bt_sm_set_bondable_mode (uint8_t bondable) |
sl_status_t | sl_bt_sm_set_passkey (int32_t passkey) |
SL_BGAPI_DEPRECATED sl_status_t | sl_bt_sm_set_oob_data (size_t oob_data_len, const uint8_t *oob_data) |
SL_BGAPI_DEPRECATED sl_status_t | sl_bt_sm_use_sc_oob (uint8_t enable, size_t max_oob_data_size, size_t *oob_data_len, uint8_t *oob_data) |
SL_BGAPI_DEPRECATED sl_status_t | sl_bt_sm_set_sc_remote_oob_data (size_t oob_data_len, const uint8_t *oob_data) |
sl_status_t | sl_bt_sm_increase_security (uint8_t connection) |
sl_status_t | sl_bt_sm_enter_passkey (uint8_t connection, int32_t passkey) |
sl_status_t | sl_bt_sm_passkey_confirm (uint8_t connection, uint8_t confirm) |
sl_status_t | sl_bt_sm_bonding_confirm (uint8_t connection, uint8_t confirm) |
SL_BGAPI_DEPRECATED sl_status_t | sl_bt_sm_list_all_bondings () |
sl_status_t | sl_bt_sm_delete_bonding (uint8_t bonding) |
sl_status_t | sl_bt_sm_delete_bondings () |
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) |
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) |
sl_status_t | sl_bt_sm_find_bonding_by_address (bd_addr address, uint32_t *bonding, uint8_t *security_mode, uint8_t *key_size) |
sl_status_t | sl_bt_sm_set_legacy_oob (uint8_t enable, aes_key_128 oob_data) |
sl_status_t | sl_bt_sm_set_oob (uint8_t enable, aes_key_128 *random, aes_key_128 *confirm) |
sl_status_t | sl_bt_sm_set_remote_oob (uint8_t enable, aes_key_128 random, aes_key_128 confirm) |
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 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
◆ 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()
sl_status_t sl_bt_sm_configure | ( | uint8_t | flags, |
uint8_t | io_capabilities |
||
) |
Configure security requirements and I/O capabilities of the system.
- Parameters
-
[in] flags
Security requirement bitmask.
Bit 0:
- 0: Allow bonding without authentication
- 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 to 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
- 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.
- Parameters
-
[in] minimum_key_size
Minimum allowed key size for bonding. Range: 7 to 16
- 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_add_to_whitelist()
sl_status_t sl_bt_sm_add_to_whitelist | ( | bd_addr | address, |
uint8_t | address_type |
||
) |
Add device to accept list, which can be enabled with sl_bt_gap_enable_whitelisting.
- Parameters
-
[in] address
Address of the device added to accept list [in] address_type
Enum sl_bt_gap_address_type_t. Address type of the device added to accept list. Values: - sl_bt_gap_public_address (0x0): Public device address
- 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
- 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 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.
- Parameters
-
[in] max_bonding_count
Maximum allowed bonding count. Range: 1 to 32 [in] policy_flags
Bonding policy. Values:
- 0: If database is full, new bonding attempts will fail
- 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
- 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.
- Parameters
-
[in] bondable
Bondable mode. Values:
- 0: New bondings not accepted
- 1: Bondings allowed
Default value: 0
- 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.
- Parameters
-
[in] passkey
Passkey. Valid range: 0-999999. Set -1 to disable and start using random passkeys.
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
◆ sl_bt_sm_set_oob_data()
SL_BGAPI_DEPRECATED sl_status_t sl_bt_sm_set_oob_data | ( | size_t | oob_data_len, |
const uint8_t * | oob_data |
||
) |
Deprecated and replaced by sl_bt_sm_set_legacy_oob command.
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
-
[in] oob_data_len
Length of data in oob_data
[in] oob_data
OOB data. To set OOB data, send a 16-byte array. Values are in little endian format. To clear OOB data, send a zero-length array.
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
◆ sl_bt_sm_use_sc_oob()
SL_BGAPI_DEPRECATED sl_status_t sl_bt_sm_use_sc_oob | ( | uint8_t | enable, |
size_t | max_oob_data_size, |
||
size_t * | oob_data_len, |
||
uint8_t * | oob_data |
||
) |
Deprecated and replaced by sl_bt_sm_set_oob command.
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
-
[in] enable
Enable OOB with secure connections pairing. Values: - 0: disable
- 1: enable
[in] max_oob_data_size
Size of output buffer passed in oob_data
[out] oob_data_len
On return, set to the length of output data written to oob_data
[out] oob_data
OOB data. 32-byte array. The first 16-bytes contain randomly-generated OOB data and the last 16-bytes confirm value. Values are in little endian format.
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
◆ sl_bt_sm_set_sc_remote_oob_data()
SL_BGAPI_DEPRECATED sl_status_t sl_bt_sm_set_sc_remote_oob_data | ( | size_t | oob_data_len, |
const uint8_t * | oob_data |
||
) |
Deprecated and replaced by sl_bt_sm_set_remote_oob command.
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
-
[in] oob_data_len
Length of data in oob_data
[in] oob_data
Remote device OOB data and confirm values. To set OOB data, send a 32-byte array. First 16-bytes is OOB data and last 16-bytes the confirm value. Values are in little endian format. To clear OOB data, send a zero-length array.
- 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.
- Parameters
-
[in] connection
Connection handle
- 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.
- Parameters
-
[in] connection
Connection handle [in] passkey
Passkey. Valid range: 0-999999. Set -1 to cancel pairing.
- 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.
- Parameters
-
[in] connection
Connection handle [in] confirm
Acceptance. Values: - 0: Reject
- 1: Accept 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.
- Parameters
-
[in] connection
Connection handle [in] confirm
Acceptance. Values: - 0: Reject
- 1: Accept bonding request
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
◆ sl_bt_sm_list_all_bondings()
SL_BGAPI_DEPRECATED sl_status_t sl_bt_sm_list_all_bondings | ( |
| ) |
Deprecated and replaced by sl_bt_sm_get_bonding_handles and sl_bt_sm_get_bonding_details commands.
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_sm_delete_bonding()
sl_status_t sl_bt_sm_delete_bonding | ( | uint8_t | bonding | ) |
Delete specified bonding information or accept list filtering from the persistent store.
- Parameters
-
[in] bonding
Bonding handle
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
◆ sl_bt_sm_delete_bondings()
sl_status_t sl_bt_sm_delete_bondings | ( |
| ) |
Delete all bonding information and accept list filtering from the persistent store. This will also delete device local identity resolving key (IRK).
- 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. The entry in the bonding database can be either bonding or accept list filtering device. Use sl_bt_sm_get_bonding_details to find the type of bonding entry and the device's address.
- Parameters
-
[in] reserved
Use the value 0 on this reserved field. Do not use none-zero values because they are reserved for future use. [out] num_bondings
Total number of bondings and accept list filtering devices stored in bonding database. [in] max_bondings_size
Size of output buffer passed in bondings
[out] bondings_len
On return, set to the length of output data written to bondings
[out] bondings
4 byte bit field of used bonding handles in little endian format. Bit 0 of first byte is bonding handle 0, bit 0 of second byte is bonding handle 8 etc. If the bit is 1 that bonding handle exists in the bonding database.
- 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.
- Parameters
-
[in] bonding
Bonding handle [out] address
Bluetooth address of the remote device [out] address_type
Enum sl_bt_gap_address_type_t. Address type. Values: - sl_bt_gap_public_address (0x0): Public device address
- 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
- 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 or accept list filtering entry by using a Bluetooth device address.
- Parameters
-
[in] address
The Bluetooth device address [out] bonding
The bonding handle [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
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
◆ 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.
- Parameters
-
[in] enable
Enable OOB with legacy pairing. Values: - 0: disable
- 1: enable
[in] oob_data
16-byte legacy pairing OOB data in little endian format.
- 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.
- Parameters
-
[in] enable
Enable OOB with secure connections pairing. Values: - 0: disable
- 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.
- 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.
- Parameters
-
[in] enable
Enable remote device OOB data with secure connections pairing. Values: - 0: disable
- 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.
- Returns
- SL_STATUS_OK if successful. Error code otherwise.