Security Manager (sm)

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:

If MITM is required, the application needs to display or ask the user to enter a passkey during the process. See events sm_passkey_display and sm_passkey_request for more information. 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 sm_passkey_display and sm_passkey_request for more information.

sm commands

sm_add_to_whitelist

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

C API

/* Function */
struct gecko_msg_sm_add_to_whitelist_rsp_t *gecko_cmd_sm_add_to_whitelist(bd_addr address, uint8 address_type);

/* Response id */
gecko_rsp_sm_add_to_whitelist_id

/* Response structure */
struct gecko_msg_sm_add_to_whitelist_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
bd_addr address Address of the device added to whitelist
uint8 address_type Address type of the device added to whitelist

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

sm_bonding_confirm

Accept or reject the bonding request.

C API

/* Function */
struct gecko_msg_sm_bonding_confirm_rsp_t *gecko_cmd_sm_bonding_confirm(uint8 connection, uint8 confirm);

/* Response id */
gecko_rsp_sm_bonding_confirm_id

/* Response structure */
struct gecko_msg_sm_bonding_confirm_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 connection Connection handle
uint8 confirm Acceptance. Values:
  • 0: Reject
  • 1: Accept bonding request

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

sm_configure

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

C API

/* Function */
struct gecko_msg_sm_configure_rsp_t *gecko_cmd_sm_configure(uint8 flags, uint8 io_capabilities);

/* Response id */
gecko_rsp_sm_configure_id

/* Response structure */
struct gecko_msg_sm_configure_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 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 sm_confirm_bonding events.

Bit 4:

  • 0: Allow all connections
  • 1: Allow connections only from bonded devices

Bit 5 to 7: Reserved

Default value: 0x00

uint8 io_capabilities I/O Capabilities. See link.

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

sm_delete_bonding

Delete specified bonding information or whitelist from the persistent store.

C API

/* Function */
struct gecko_msg_sm_delete_bonding_rsp_t *gecko_cmd_sm_delete_bonding(uint8 bonding);

/* Response id */
gecko_rsp_sm_delete_bonding_id

/* Response structure */
struct gecko_msg_sm_delete_bonding_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 bonding Bonding handle

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

sm_delete_bondings

Delete all bonding information and whitelist from the persistent store.

C API

/* Function */
struct gecko_msg_sm_delete_bondings_rsp_t *gecko_cmd_sm_delete_bondings();

/* Response id */
gecko_rsp_sm_delete_bondings_id

/* Response structure */
struct gecko_msg_sm_delete_bondings_rsp_t
{
  uint16 result;
}

Command does not have parameters (for BGAPI headers refer to link)

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

sm_enter_passkey

Enter a passkey after receiving a passkey request event.

C API

/* Function */
struct gecko_msg_sm_enter_passkey_rsp_t *gecko_cmd_sm_enter_passkey(uint8 connection, int32 passkey);

/* Response id */
gecko_rsp_sm_enter_passkey_id

/* Response structure */
struct gecko_msg_sm_enter_passkey_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 connection Connection handle
int32 passkey Passkey. Valid range: 0-999999. Set -1 to cancel pairing.

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

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.

C API

/* Function */
struct gecko_msg_sm_increase_security_rsp_t *gecko_cmd_sm_increase_security(uint8 connection);

/* Response id */
gecko_rsp_sm_increase_security_id

/* Response structure */
struct gecko_msg_sm_increase_security_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 connection Connection handle

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

Events generated

Event Description
le_connection_parameters Triggered after increasing security has been completed successfully and indicates the latest security mode of the connection.
sm_bonded Triggered if pairing or bonding was performed in this operation and the result is successful.
sm_bonding_failed Triggered if pairing or bonding was performed in this operation and the result has failed.

sm_list_all_bondings

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

C API

/* Function */
struct gecko_msg_sm_list_all_bondings_rsp_t *gecko_cmd_sm_list_all_bondings();

/* Response id */
gecko_rsp_sm_list_all_bondings_id

/* Response structure */
struct gecko_msg_sm_list_all_bondings_rsp_t
{
  uint16 result;
}

Command does not have parameters (for BGAPI headers refer to link)

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

Events generated

Event Description
sm_list_bonding_entry
sm_list_all_bondings_complete

sm_passkey_confirm

Accept or reject the reported passkey confirm value.

C API

/* Function */
struct gecko_msg_sm_passkey_confirm_rsp_t *gecko_cmd_sm_passkey_confirm(uint8 connection, uint8 confirm);

/* Response id */
gecko_rsp_sm_passkey_confirm_id

/* Response structure */
struct gecko_msg_sm_passkey_confirm_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 connection Connection handle
uint8 confirm Acceptance. Values:
  • 0: Reject
  • 1: Accept confirm value

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

sm_set_bondable_mode

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

C API

/* Function */
struct gecko_msg_sm_set_bondable_mode_rsp_t *gecko_cmd_sm_set_bondable_mode(uint8 bondable);

/* Response id */
gecko_rsp_sm_set_bondable_mode_id

/* Response structure */
struct gecko_msg_sm_set_bondable_mode_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 bondable Bondable mode. Values:
  • 0: New bondings not accepted
  • 1: Bondings allowed

Default value: 0

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

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.

C API

/* Function */
struct gecko_msg_sm_set_debug_mode_rsp_t *gecko_cmd_sm_set_debug_mode();

/* Response id */
gecko_rsp_sm_set_debug_mode_id

/* Response structure */
struct gecko_msg_sm_set_debug_mode_rsp_t
{
  uint16 result;
}

Command does not have parameters (for BGAPI headers refer to link)

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

sm_set_minimum_key_size

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

C API

/* Function */
struct gecko_msg_sm_set_minimum_key_size_rsp_t *gecko_cmd_sm_set_minimum_key_size(uint8 minimum_key_size);

/* Response id */
gecko_rsp_sm_set_minimum_key_size_id

/* Response structure */
struct gecko_msg_sm_set_minimum_key_size_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 minimum_key_size Minimum allowed key size for bonding. Range: 7 to 16

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

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

C API

/* Function */
struct gecko_msg_sm_set_oob_data_rsp_t *gecko_cmd_sm_set_oob_data(uint8 oob_data_len, const uint8 *oob_data_data);

/* Response id */
gecko_rsp_sm_set_oob_data_id

/* Response structure */
struct gecko_msg_sm_set_oob_data_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 oob_data_len Array length.
uint8array oob_data_data OOB data. To set OOB data, send a 16-byte array. To clear OOB data, send a zero-length array.

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

sm_set_passkey

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

C API

/* Function */
struct gecko_msg_sm_set_passkey_rsp_t *gecko_cmd_sm_set_passkey(int32 passkey);

/* Response id */
gecko_rsp_sm_set_passkey_id

/* Response structure */
struct gecko_msg_sm_set_passkey_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
int32 passkey Passkey. Valid range: 0-999999. Set -1 to disable and start using random passkeys.

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

sm_set_sc_remote_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 sm_use_sc_oob before setting the remote device OOB data.

C API

/* Function */
struct gecko_msg_sm_set_sc_remote_oob_data_rsp_t *gecko_cmd_sm_set_sc_remote_oob_data(uint8 oob_data_len, const uint8 *oob_data_data);

/* Response id */
gecko_rsp_sm_set_sc_remote_oob_data_id

/* Response structure */
struct gecko_msg_sm_set_sc_remote_oob_data_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 oob_data_len Array length.
uint8array oob_data_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. To clear OOB data, send a zero-length array.

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

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

C API

/* Function */
struct gecko_msg_sm_store_bonding_configuration_rsp_t *gecko_cmd_sm_store_bonding_configuration(uint8 max_bonding_count, uint8 policy_flags);

/* Response id */
gecko_rsp_sm_store_bonding_configuration_id

/* Response structure */
struct gecko_msg_sm_store_bonding_configuration_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 max_bonding_count Maximum allowed bonding count. Range: 1 to 32
uint8 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

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

sm_use_sc_oob

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

C API

/* Function */
struct gecko_msg_sm_use_sc_oob_rsp_t *gecko_cmd_sm_use_sc_oob(uint8 enable);

/* Response id */
gecko_rsp_sm_use_sc_oob_id

/* Response structure */
struct gecko_msg_sm_use_sc_oob_rsp_t
{
  uint16 result;
  uint8array oob_data;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 enable Enable OOB with secure connections pairing. Values:
  • 0: disable
  • 1: enable

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes
uint8array oob_data OOB data. 32-byte array. The first 16-bytes contain randomly-generated OOB data and the last 16-bytes confirm value.

sm events

sm_passkey_display

Indicates a request to display the passkey to the user.

C API

/* event id*/
gecko_evt_sm_passkey_display_id

/* event structure*/
struct gecko_msg_sm_passkey_display_evt_t
{
  uint8 connection;
  uint32 passkey;
}

Event Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 connection Connection handle
uint32 passkey Passkey. Range: 0 to 999999.
  • NOTE! When displaying the passkey to the user, prefix the number with zeros to obtain a 6 digit number
  • Example: Passkey value is 42
  • Number to display to the user is 000042

sm_passkey_request

Indicates a request for the passkey prompt displayed on the remote device. Use the command sm_enter_passkey to input the passkey value.

C API

/* event id*/
gecko_evt_sm_passkey_request_id

/* event structure*/
struct gecko_msg_sm_passkey_request_evt_t
{
  uint8 connection;
}

Event Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 connection Connection handle

sm_confirm_passkey

Indicates a request for passkey display and confirmation by the user. Use the command sm_passkey_confirm to accept or reject the displayed passkey.

C API

/* event id*/
gecko_evt_sm_confirm_passkey_id

/* event structure*/
struct gecko_msg_sm_confirm_passkey_evt_t
{
  uint8 connection;
  uint32 passkey;
}

Event Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 connection Connection handle
uint32 passkey Passkey. Range: 0 to 999999.
  • NOTE! When displaying the passkey to the user, prefix the number with zeros to obtain a 6 digit number
  • Example: Passkey value is 42
  • Number to display to the user is 000042

sm_bonded

Triggered after the pairing or bonding procedure is successfully completed.

C API

/* event id*/
gecko_evt_sm_bonded_id

/* event structure*/
struct gecko_msg_sm_bonded_evt_t
{
  uint8 connection;
  uint8 bonding;
}

Event Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 connection Connection handle
uint8 bonding Bonding handle. Values:
  • 0xff: Pairing completed without bonding - the pairing key will be discarded after disconnection.
  • Other: Procedure completed, pairing key stored with given bonding handle

sm_bonding_failed

This event is triggered if the pairing or bonding procedure fails.

C API

/* event id*/
gecko_evt_sm_bonding_failed_id

/* event structure*/
struct gecko_msg_sm_bonding_failed_evt_t
{
  uint8 connection;
  uint16 reason;
}

Event Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 connection Connection handle
uint16 reason Describes error that occurred

sm_list_bonding_entry

Triggered by the command sm_list_all_bondings if bondings exist in the local database.

C API

/* event id*/
gecko_evt_sm_list_bonding_entry_id

/* event structure*/
struct gecko_msg_sm_list_bonding_entry_evt_t
{
  uint8 bonding;
  bd_addr address;
  uint8 address_type;
}

Event Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 bonding Bonding handle
bd_addr address Bluetooth address of the remote device
uint8 address_type Address type

sm_list_all_bondings_complete

Triggered by the sm_list_all_bondings and follows sm_list_bonding_entry events.

C API

/* event id*/
gecko_evt_sm_list_all_bondings_complete_id

/* event structure*/
struct gecko_msg_sm_list_all_bondings_complete_evt_t
{
}

Event does not have parameters (for BGAPI headers refer to link)

sm_confirm_bonding

Indicates a user request to display that the new bonding request is received and for the user to confirm the request. Use the command sm_bonding_confirm to accept or reject the bonding request.

C API

/* event id*/
gecko_evt_sm_confirm_bonding_id

/* event structure*/
struct gecko_msg_sm_confirm_bonding_evt_t
{
  uint8 connection;
  int8 bonding_handle;
}

Event Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 connection Connection handle
int8 bonding_handle Bonding handle for the request. Range: -1 to 31.
  • NOTE! When the bonding handle is anything other than -1, a bonding already exists for this connection. Overwriting the existing bonding is a potential security risk.

sm enumerations

sm_bonding_key

These values define the bonding information of the bonded device stored in the persistent store.

Enumerations

Value Name Description
1 sm_bonding_key_ltk LTK saved in master
2 sm_bonding_key_addr_public Public Address
4 sm_bonding_key_addr_static Static Address
8 sm_bonding_key_irk Identity resolving key for resolvable private addresses
16 sm_bonding_key_edivrand EDIV+RAND received from slave
32 sm_bonding_key_csrk Connection signature resolving key
64 sm_bonding_key_masterid EDIV+RAND sent to master

sm_io_capability

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

Enumerations

Value Name Description
0 sm_io_capability_displayonly Display Only
1 sm_io_capability_displayyesno Display with Yes/No-buttons
2 sm_io_capability_keyboardonly Keyboard Only
3 sm_io_capability_noinputnooutput No Input and No Output
4 sm_io_capability_keyboarddisplay Display with Keyboard