Security Manager API

#include "src/ble/sm.h"

@TLV 'SMER' @TLV 'SMIR'

sm_init

void sm_init(void);

Initializes the Security Manager, connects to L2CAP

Source


sm_set_er

void sm_set_er(sm_key_t er);

Set secret ER key for key generation as described in Core V4.0, Vol 3, Part G, 5.2.2

Note: If not set and btstack_tlv is configured, ER key is generated and stored in TLV by SM

Parameters

Source


sm_set_ir

void sm_set_ir(sm_key_t ir);

Set secret IR key for key generation as described in Core V4.0, Vol 3, Part G, 5.2.2

Note: If not set and btstack_tlv is configured, IR key is generated and stored in TLV by SM

Parameters

Source


sm_register_oob_data_callback

void sm_register_oob_data_callback( int (*get_oob_data_callback)(uint8_t address_type, bd_addr_t addr, uint8_t * oob_data));

Registers OOB Data Callback. The callback should set the oob_data and return 1 if OOB data is availble

Parameters

Source


sm_add_event_handler

void sm_add_event_handler(btstack_packet_callback_registration_t * callback_handler);

Add event packet handler.

Parameters

Source


sm_remove_event_handler

void sm_remove_event_handler(btstack_packet_callback_registration_t * callback_handler);

Remove event packet handler.

Parameters

Source


sm_set_accepted_stk_generation_methods

void sm_set_accepted_stk_generation_methods(uint8_t accepted_stk_generation_methods);

Limit the STK generation methods. Bonding is stopped if the resulting one isn't in the list

Parameters

Source


sm_set_encryption_key_size_range

void sm_set_encryption_key_size_range(uint8_t min_size, uint8_t max_size);

Set the accepted encryption key size range. Bonding is stopped if the result isn't within the range

Parameters

Source


sm_set_authentication_requirements

void sm_set_authentication_requirements(uint8_t auth_req);

Sets the requested authentication requirements, bonding yes/no, MITM yes/no, SC yes/no, keypress yes/no

Parameters

Source


sm_set_io_capabilities

void sm_set_io_capabilities(io_capability_t io_capability);

Sets the available IO Capabilities

Parameters

Source


sm_set_secure_connections_only_mode

void sm_set_secure_connections_only_mode(bool enable);

Enable/disable Secure Connections Mode only

Parameters

Source


sm_set_request_security

void sm_set_request_security(bool enable);

Let Peripheral request an encrypted connection right after connecting

Note: Not used normally. Bonding is triggered by access to protected attributes in ATT Server

Parameters

Source


sm_send_security_request

void sm_send_security_request(hci_con_handle_t con_handle);

Trigger Security Request

@deprecated: please use sm_request_pairing instead

Source


sm_bonding_decline

void sm_bonding_decline(hci_con_handle_t con_handle);

Decline bonding triggered by event before

Parameters

Source


sm_just_works_confirm

void sm_just_works_confirm(hci_con_handle_t con_handle);

Confirm Just Works bonding

Parameters

Source


sm_numeric_comparison_confirm

void sm_numeric_comparison_confirm(hci_con_handle_t con_handle);

Confirm value from SM_EVENT_NUMERIC_COMPARISON_REQUEST for Numeric Comparison bonding

Parameters

Source


sm_passkey_input

void sm_passkey_input(hci_con_handle_t con_handle, uint32_t passkey);

Reports passkey input by user

Parameters

Source


sm_keypress_notification

void sm_keypress_notification(hci_con_handle_t con_handle, uint8_t action);

Send keypress notification for keyboard only devices

Parameters

Source


sm_request_pairing

void sm_request_pairing(hci_con_handle_t con_handle);

Used by att_server.c and gatt_client.c to request user authentication

Parameters

Source


sm_authorization_decline

void sm_authorization_decline(hci_con_handle_t con_handle);

Report user authorization decline.

Parameters

Source


sm_authorization_grant

void sm_authorization_grant(hci_con_handle_t con_handle);

Report user authorization grant.

Parameters

Source


sm_cmac_ready

int sm_cmac_ready(void);

Support for signed writes, used by att_server.

Returns

Source


sm_cmac_signed_write_start

void sm_cmac_signed_write_start(const sm_key_t key, uint8_t opcode, uint16_t attribute_handle, uint16_t message_len, const uint8_t * message, uint32_t sign_counter, void (*done_callback)(uint8_t * hash));

Support for signed writes, used by att_server.

Note: Message is in little endian to allows passing in ATT PDU without flipping.

Note: signing data: [opcode, attribute_handle, message, sign_counter]

Note: calculated hash in done_callback is big endian and has 16 byte.

Parameters

Source


sm_address_resolution_lookup

int sm_address_resolution_lookup(uint8_t address_type, bd_addr_t address);

Match address against bonded devices

Note: Triggers SM_IDENTITY_RESOLVING_* events

Parameters

Returns

Source


sm_identity_resolving_state

irk_lookup_state_t sm_identity_resolving_state(hci_con_handle_t con_handle);

Get Identity Resolving state

Note: return IRK_LOOKUP_IDLE if connection does not exist

Parameters

Returns

Source


sm_le_device_index

int sm_le_device_index(hci_con_handle_t con_handle);

Identify device in LE Device DB.

Parameters

Returns

Source


sm_get_ltk

uint8_t sm_get_ltk(hci_con_handle_t con_handle, sm_key_t ltk);

Get LTK for encrypted connection

Parameters

Returns

Source


sm_use_fixed_passkey_in_display_role

void sm_use_fixed_passkey_in_display_role(uint32_t passkey);

Use fixec passkey for Legacy and SC instead of generating a random number

Note: Can be used to improve security over Just Works if no keyboard or displary are present and individual random passkey can be printed on the device during production

Parameters

Source


sm_allow_ltk_reconstruction_without_le_device_db_entry

void sm_allow_ltk_reconstruction_without_le_device_db_entry(int allow);

Allow connection re-encryption in Peripheral (Responder) role for LE Legacy Pairing without entry for Central device stored in LE Device DB

Note: BTstack in Peripheral Role (Responder) supports LE Legacy Pairing without a persistent LE Device DB as the LTK is reconstructed from a local secret IRK and EDIV + Random stored on Central (Initiator) device On the downside, it's not really possible to delete a pairing if this is enabled.

Parameters

Source


sm_generate_sc_oob_data

uint8_t sm_generate_sc_oob_data(void (*callback)(const uint8_t * confirm_value, const uint8_t * random_value));

Generate OOB data for LE Secure Connections

Note: This generates a 128 bit random number ra and then calculates Ca = f4(PKa, PKa, ra, 0) New OOB data should be generated for each pairing. Ra is used for subsequent OOB pairings

Parameters

Returns

Source


sm_register_sc_oob_data_callback

void sm_register_sc_oob_data_callback( int (*get_sc_oob_data_callback)(uint8_t address_type, bd_addr_t addr, uint8_t * oob_sc_peer_confirm, uint8_t * oob_sc_peer_random));

Registers OOB Data Callback for LE Secure Conections. The callback should set all arguments and return 1 if OOB data is availble

Note: the oob_sc_local_random usually is the random_value returend by sm_generate_sc_oob_data

Parameters

Source


sm_register_ltk_callback

void sm_register_ltk_callback( bool (*get_ltk_callback)(hci_con_handle_t con_handle, uint8_t address_type, bd_addr_t addr, uint8_t * ltk));

@bbrief: Register LTK Callback that allows to provide a custom LTK on re-encryption. The callback returns true if LTK was modified

Parameters

Source