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  sm_bonding_key_t {
  sm_bonding_key_ltk = 0x1, sm_bonding_key_addr_public = 0x2, sm_bonding_key_addr_static = 0x4, sm_bonding_key_irk = 0x8,
  sm_bonding_key_edivrand = 0x10, sm_bonding_key_csrk = 0x20, sm_bonding_key_masterid = 0x40
}
 Bonding Keys.
 
enum  sm_io_capability_t {
  sm_io_capability_displayonly = 0x0, sm_io_capability_displayyesno = 0x1, sm_io_capability_keyboardonly = 0x2, sm_io_capability_noinputnooutput = 0x3,
  sm_io_capability_keyboarddisplay = 0x4
}
 SMP I/O Capabilities.
 

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_status_t sl_bt_sm_set_oob_data (size_t oob_data_len, const uint8_t *oob_data)
 
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_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_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 ()
 

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:

The following procedure can be used to respond to the bonding initiated by a 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.

Enumerator
sm_bonding_key_ltk 

(0x1) LTK saved in master

sm_bonding_key_addr_public 

(0x2) Public Address

sm_bonding_key_addr_static 

(0x4) Static Address

sm_bonding_key_irk 

(0x8) Identity resolving key for resolvable private addresses

sm_bonding_key_edivrand 

(0x10) EDIV+RAND received from slave

sm_bonding_key_csrk 

(0x20) Connection signature resolving key

sm_bonding_key_masterid 

(0x40) EDIV+RAND sent to master

◆ sm_io_capability_t

enum sm_io_capability_t

SMP I/O Capabilities.

Enumerator
sm_io_capability_displayonly 

(0x0) Display Only

sm_io_capability_displayyesno 

(0x1) Display with Yes/No-buttons

sm_io_capability_keyboardonly 

(0x2) Keyboard Only

sm_io_capability_noinputnooutput 

(0x3) No Input and No Output

sm_io_capability_keyboarddisplay 

(0x4) Display with Keyboard

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 MITM protection
  • 1: Bonding requires MITM 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 to 7: Reserved

Default value: 0x00

[in]io_capabilitiesEnum sm_io_capability_t. I/O Capabilities. The default I/O Capability used by the stack is No Input and No Output. Values:
  • sm_io_capability_displayonly (0x0): Display Only
  • sm_io_capability_displayyesno (0x1): Display with Yes/No-buttons
  • sm_io_capability_keyboardonly (0x2): Keyboard Only
  • sm_io_capability_noinputnooutput (0x3): No Input and No Output
  • 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_sizeMinimum 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 whitelist, which can be enabled with sl_bt_gap_enable_whitelisting.

Parameters
[in]addressAddress of the device added to whitelist
[in]address_typeEnum gap_address_type_t. Address type of the device added to whitelist. Values:
  • gap_public_address (0x0): Public device address
  • gap_static_address (0x1): Static device address
  • gap_random_resolvable_address (0x2): Private resolvable random address
  • gap_random_nonresolvable_address (0x3): Private non-resolvable 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 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
[in]max_bonding_countMaximum 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 existing 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]passkeyPasskey. 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_status_t 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
[in]oob_data_lenArray length
[in]oob_dataOOB data. To set OOB data, send a 16-byte array. 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_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 
)

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]enableEnable OOB with secure connections pairing. Values:
  • 0: disable
  • 1: enable
[in]max_oob_data_sizeSize of output buffer passed in oob_data
[out]oob_data_lenOn return, set to the length of output data written to oob_data
[out]oob_dataOOB data. 32-byte array. The first 16-bytes contain randomly-generated OOB data and the last 16-bytes confirm value.
Returns
SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_sm_set_sc_remote_oob_data()

sl_status_t 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
[in]oob_data_lenArray length
[in]oob_dataRemote 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. 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]connectionConnection 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]connectionConnection handle
[in]passkeyPasskey. 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]connectionConnection handle
[in]confirmAcceptance. 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]connectionConnection handle
[in]confirmAcceptance. Values:
  • 0: Reject
  • 1: Accept bonding request
Returns
SL_STATUS_OK if successful. Error code otherwise.

◆ sl_bt_sm_list_all_bondings()

sl_status_t 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_sm_delete_bonding()

sl_status_t sl_bt_sm_delete_bonding ( uint8_t  bonding)

Delete specified bonding information or whitelist from the persistent store.

Parameters
[in]bondingBonding 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 whitelist from the persistent store.

Returns
SL_STATUS_OK if successful. Error code otherwise.