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
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
- er: key
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
- ir: key
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
- get_oob_data_callback
sm_add_event_handler
void sm_add_event_handler(btstack_packet_callback_registration_t * callback_handler);
Add event packet handler.
Parameters
- callback_handler
sm_remove_event_handler
void sm_remove_event_handler(btstack_packet_callback_registration_t * callback_handler);
Remove event packet handler.
Parameters
- callback_handler
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
- OR: combination of SM_STK_GENERATION_METHOD_
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
- min_size: (default 16)
- max_size: (default 16)
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
- OR: combination of SM_AUTHREQ_ flags
sm_set_io_capabilities
void sm_set_io_capabilities(io_capability_t io_capability);
Sets the available IO Capabilities
Parameters
- IO_CAPABILITY_
sm_set_secure_connections_only_mode
void sm_set_secure_connections_only_mode(bool enable);
Enable/disable Secure Connections Mode only
Parameters
- enable: secure connections only mode (default: true, if ENABLE_LE_SECURE_CONNECTIONS enabled)
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
- enable
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
sm_bonding_decline
void sm_bonding_decline(hci_con_handle_t con_handle);
Decline bonding triggered by event before
Parameters
- con_handle
sm_just_works_confirm
void sm_just_works_confirm(hci_con_handle_t con_handle);
Confirm Just Works bonding
Parameters
- con_handle
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
- con_handle
sm_passkey_input
void sm_passkey_input(hci_con_handle_t con_handle, uint32_t passkey);
Reports passkey input by user
Parameters
- con_handle
- passkey: in [0..999999]
sm_keypress_notification
void sm_keypress_notification(hci_con_handle_t con_handle, uint8_t action);
Send keypress notification for keyboard only devices
Parameters
- con_handle
- action: see SM_KEYPRESS_* in bluetooth.h
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
- con_handle
sm_authorization_decline
void sm_authorization_decline(hci_con_handle_t con_handle);
Report user authorization decline.
Parameters
- con_handle
sm_authorization_grant
void sm_authorization_grant(hci_con_handle_t con_handle);
Report user authorization grant.
Parameters
- con_handle
sm_cmac_ready
int sm_cmac_ready(void);
Support for signed writes, used by att_server.
Returns
- int: ready
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
- key
- opcde
- attribute_handle
- message_len
- message
- sign_counter
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
- address_type
- address
Returns
- int: 0 if successfully added to lookup queue
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
- con_handle
Returns
- irk_lookup_state_t: irk_lookup_state_t
sm_le_device_index
int sm_le_device_index(hci_con_handle_t con_handle);
Identify device in LE Device DB.
Parameters
- con_handle
Returns
- int: index from le_device_db or -1 if not found/identified
sm_get_ltk
uint8_t sm_get_ltk(hci_con_handle_t con_handle, sm_key_t ltk);
Get LTK for encrypted connection
Parameters
- con_handle
- ltk: buffer to store long term key
Returns
- uint8_t: ERROR_CODE_SUCCESS ok ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no connection for this con handle exists ERROR_CODE_PIN_OR_KEY_MISSING if connection is not encrypted
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
- passkey
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
- allow: encryption using reconstructed LTK without stored entry (Default: 1)
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
- callback
Returns
- uint8_t: status
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
- get_oob_data_callback
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
- get_ltk_callback