sm.h File Reference

#include <stdint.h>
#include "btstack_util.h"
#include "btstack_defines.h"
#include "hci.h"

Data Structures
struct	sm_lookup_entry_t

Functions
void	sm_add_event_handler (btstack_packet_callback_registration_t *callback_handler)
	Add event packet handler. More...
int	sm_address_resolution_lookup (uint8_t addr_type, bd_addr_t addr)
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. More...
int	sm_authenticated (hci_con_handle_t con_handle)
	Get authentication property. More...
void	sm_authorization_decline (hci_con_handle_t con_handle)
	Report user authorization decline. More...
void	sm_authorization_grant (hci_con_handle_t con_handle)
	Report user authorization grant. More...
authorization_state_t	sm_authorization_state (hci_con_handle_t con_handle)
	Queries authorization state. More...
void	sm_bonding_decline (hci_con_handle_t con_handle)
	Decline bonding triggered by event before. More...
void	sm_cmac_general_start (const sm_key_t key, uint16_t message_len, uint8_t(*get_byte_callback)(uint16_t offset), void(*done_callback)(uint8_t *hash))
int	sm_cmac_ready (void)
	Check if CMAC AES engine is ready. More...
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. More...
int	sm_encryption_key_size (hci_con_handle_t con_handle)
	Get encryption key size. More...
void	sm_init (void)
	Initializes the Security Manager, connects to L2CAP. More...
void	sm_just_works_confirm (hci_con_handle_t con_handle)
	Confirm Just Works bonding. More...
void	sm_keypress_notification (hci_con_handle_t con_handle, uint8_t action)
	Send keypress notification for keyboard only devices. More...
int	sm_le_device_index (hci_con_handle_t con_handle)
	Identify device in LE Device DB. More...
void	sm_numeric_comparison_confirm (hci_con_handle_t con_handle)
	Confirm value from SM_EVENT_NUMERIC_COMPARISON_REQUEST for Numeric Comparison bonding. More...
static uint8_t	sm_pairing_packet_get_auth_req (sm_pairing_packet_t packet)
static uint8_t	sm_pairing_packet_get_code (sm_pairing_packet_t packet)
static uint8_t	sm_pairing_packet_get_initiator_key_distribution (sm_pairing_packet_t packet)
static uint8_t	sm_pairing_packet_get_io_capability (sm_pairing_packet_t packet)
static uint8_t	sm_pairing_packet_get_max_encryption_key_size (sm_pairing_packet_t packet)
static uint8_t	sm_pairing_packet_get_oob_data_flag (sm_pairing_packet_t packet)
static uint8_t	sm_pairing_packet_get_responder_key_distribution (sm_pairing_packet_t packet)
static void	sm_pairing_packet_set_auth_req (sm_pairing_packet_t packet, uint8_t auth_req)
static void	sm_pairing_packet_set_code (sm_pairing_packet_t packet, uint8_t code)
static void	sm_pairing_packet_set_initiator_key_distribution (sm_pairing_packet_t packet, uint8_t initiator_key_distribution)
static void	sm_pairing_packet_set_io_capability (sm_pairing_packet_t packet, uint8_t io_capability)
static void	sm_pairing_packet_set_max_encryption_key_size (sm_pairing_packet_t packet, uint8_t max_encryption_key_size)
static void	sm_pairing_packet_set_oob_data_flag (sm_pairing_packet_t packet, uint8_t oob_data_flag)
static void	sm_pairing_packet_set_responder_key_distribution (sm_pairing_packet_t packet, uint8_t responder_key_distribution)
void	sm_passkey_input (hci_con_handle_t con_handle, uint32_t passkey)
	Reports passkey input by user. More...
void	sm_register_oob_data_callback (int(*get_oob_data_callback)(uint8_t addres_type, bd_addr_t addr, uint8_t *oob_data))
	Registers OOB Data Callback. More...
void	sm_request_pairing (hci_con_handle_t con_handle)
	Used by att_server.c to request user authorization. More...
void	sm_send_security_request (hci_con_handle_t con_handle)
	Trigger Security Request. More...
void	sm_set_accepted_stk_generation_methods (uint8_t accepted_stk_generation_methods)
	Limit the STK generation methods. More...
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. More...
void	sm_set_encryption_key_size_range (uint8_t min_size, uint8_t max_size)
	Set the accepted encryption key size range. More...
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. More...
void	sm_set_io_capabilities (io_capability_t io_capability)
	Sets the available IO Capabilities. More...
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. More...
void	sm_set_request_security (int enable)
	Let Peripheral request an encrypted connection right after connecting. More...
void	sm_test_set_irk (sm_key_t irk)
void	sm_test_use_fixed_ec_keypair (void)
void	sm_test_use_fixed_local_csrk (void)
void	sm_use_fixed_ec_keypair (uint8_t *qx, uint8_t *qy, uint8_t *d)
	Set Elliptic Key Public/Private Keypair. More...
void	sm_use_fixed_legacy_pairing_passkey_in_display_role (uint32_t passkey)
	Set passkey used with LE Legacy Pairing when we generate and show it instead of random number. More...

void sm_add_event_handler

(

btstack_packet_callback_registration_t *

callback_handler

)

Add event packet handler.

References btstack_linked_list_add_tail().

Referenced by att_server_init().

int sm_address_resolution_lookup	(	uint8_t	addr_type,
		bd_addr_t	addr
	)

References sm_lookup_entry_t::address, sm_lookup_entry_t::address_type, BTSTACK_BUSY, btstack_linked_list_add(), btstack_linked_list_iterator_has_next(), btstack_linked_list_iterator_init(), btstack_linked_list_iterator_next(), BTSTACK_MEMORY_ALLOC_FAILED, and sm_run().

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)

References sm_reconstruct_ltk_without_le_device_db_entry.

int sm_authenticated

(

hci_con_handle_t

con_handle

)

Get authentication property.

Parameters

con_handle

Returns

1 if bonded with OOB/Passkey (AND MITM protection)

References sm_get_connection_for_handle().

Referenced by att_event_packet_handler().

void sm_authorization_decline

(

hci_con_handle_t

con_handle

)

Report user authorization decline.

Parameters

con_handle

References SM_EVENT_AUTHORIZATION_RESULT, sm_get_connection_for_handle(), and sm_notify_client_authorization().

void sm_authorization_grant

(

hci_con_handle_t

con_handle

)

Report user authorization grant.

Parameters

con_handle

References SM_EVENT_AUTHORIZATION_RESULT, sm_get_connection_for_handle(), and sm_notify_client_authorization().

authorization_state_t sm_authorization_state

(

hci_con_handle_t

con_handle

)

Queries authorization state.

Parameters

con_handle

Returns

authorization_state for the current session

References sm_get_connection_for_handle().

Referenced by att_server_process_validated_request().

void sm_bonding_decline

(

hci_con_handle_t

con_handle

)

Decline bonding triggered by event before.

Parameters

con_handle

References JUST_WORKS, NK_BOTH_INPUT, OK_BOTH_INPUT, OOB, PK_INIT_INPUT, PK_RESP_INPUT, sm_get_connection_for_handle(), sm_pairing_error(), SM_REASON_NUMERIC_COMPARISON_FAILED, SM_REASON_UNSPECIFIED_REASON, sm_run(), sm_setup_context::sm_stk_generation_method, sm_setup_context::sm_user_response, and SM_USER_RESPONSE_DECLINE.

void sm_cmac_general_start	(	const sm_key_t	key,
		uint16_t	message_len,
		uint8_t(*)(uint16_t offset)	get_byte_callback,
		void(*)(uint8_t *hash)	done_callback
	)

int sm_cmac_ready

(

void

)

Check if CMAC AES engine is ready.

Returns

ready

Referenced by att_run_for_context(), gatt_client_run(), and sm_run().

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(*)(uint8_t *hash)	done_callback
	)

Support for signed writes, used by att_server.

Note

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

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

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

Parameters

key
opcde
attribute_handle
message_len
message
sign_counter

Referenced by att_run_for_context(), and gatt_client_run().

int sm_encryption_key_size

(

hci_con_handle_t

con_handle

)

Get encryption key size.

Parameters

con_handle

Returns

0 if not encrypted, 7-16 otherwise

References sm_get_connection_for_handle().

Referenced by att_event_packet_handler().

void sm_init

(

void

)

Initializes the Security Manager, connects to L2CAP.

References ADDRESS_RESOLUTION_IDLE, btstack_packet_callback_registration_t::callback, CMAC_IDLE, dkg_state, DKG_W4_WORKING, EC_KEY_GENERATION_IDLE, gap_random_adress_update_period, hci_add_event_handler(), HCI_CON_HANDLE_INVALID, L2CAP_CID_SECURITY_MANAGER_PROTOCOL, l2cap_register_fixed_channel(), NULL, rau_state, RAU_W4_WORKING, sm_accepted_stk_generation_methods, sm_active_connection_handle, sm_address_resolution_ah_calculation_active, sm_address_resolution_mode, sm_address_resolution_test, SM_AES128_IDLE, sm_aes128_state, sm_event_packet_handler(), sm_fixed_legacy_pairing_passkey_in_display_role, sm_max_encryption_key_size, sm_min_encryption_key_size, sm_pdu_handler(), sm_reconstruct_ltk_without_le_device_db_entry, sm_set_er(), sm_set_ir(), SM_STK_GENERATION_METHOD_JUST_WORKS, SM_STK_GENERATION_METHOD_NUMERIC_COMPARISON, SM_STK_GENERATION_METHOD_OOB, SM_STK_GENERATION_METHOD_PASSKEY, and test_use_fixed_local_csrk.

Referenced by le_counter_setup(), le_prov_app_setup(), and tss_app_setup().

void sm_just_works_confirm

(

hci_con_handle_t

con_handle

)

Confirm Just Works bonding.

Parameters

con_handle

References sm_get_connection_for_handle(), sm_run(), sm_setup_context::sm_use_secure_connections, sm_setup_context::sm_user_response, and SM_USER_RESPONSE_CONFIRM.

Referenced by sm_numeric_comparison_confirm().

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

References sm_get_connection_for_handle(), sm_setup_context::sm_keypress_notification, SM_KEYPRESS_PASSKEY_ENTRY_COMPLETED, and sm_run().

int sm_le_device_index

(

hci_con_handle_t

con_handle

)

Identify device in LE Device DB.

Parameters

handle

Returns

index from le_device_db or -1 if not found/identified

Parameters

handle

Returns

index from le_device_db or -1 if not found/identified

References sm_get_connection_for_handle().

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

References sm_just_works_confirm().

static uint8_t sm_pairing_packet_get_auth_req ( sm_pairing_packet_t  packet )

inlinestatic

Referenced by sm_setup_tk().

static uint8_t sm_pairing_packet_get_code ( sm_pairing_packet_t  packet )

inlinestatic

static uint8_t sm_pairing_packet_get_initiator_key_distribution ( sm_pairing_packet_t  packet )

inlinestatic

Referenced by sm_key_distribution_all_received(), sm_run(), and sm_stk_generation_init().

static uint8_t sm_pairing_packet_get_io_capability ( sm_pairing_packet_t  packet )

inlinestatic

Referenced by sm_setup_tk().

static uint8_t sm_pairing_packet_get_max_encryption_key_size ( sm_pairing_packet_t  packet )

inlinestatic

Referenced by sm_stk_generation_init().

static uint8_t sm_pairing_packet_get_oob_data_flag ( sm_pairing_packet_t  packet )

inlinestatic

Referenced by sm_setup_tk().

static uint8_t sm_pairing_packet_get_responder_key_distribution ( sm_pairing_packet_t  packet )

inlinestatic

Referenced by sm_key_distribution_all_received(), sm_run(), and sm_stk_generation_init().

static void sm_pairing_packet_set_auth_req ( sm_pairing_packet_t  packet, uint8_t  auth_req  )

inlinestatic

Referenced by sm_init_setup().

static void sm_pairing_packet_set_code ( sm_pairing_packet_t  packet, uint8_t  code  )

inlinestatic

Referenced by sm_run().

static void sm_pairing_packet_set_initiator_key_distribution ( sm_pairing_packet_t  packet, uint8_t  initiator_key_distribution  )

inlinestatic

Referenced by sm_init_setup(), and sm_run().

static void sm_pairing_packet_set_io_capability ( sm_pairing_packet_t  packet, uint8_t  io_capability  )

inlinestatic

Referenced by sm_init_setup().

static void sm_pairing_packet_set_max_encryption_key_size ( sm_pairing_packet_t  packet, uint8_t  max_encryption_key_size  )

inlinestatic

Referenced by sm_init_setup().

static void sm_pairing_packet_set_oob_data_flag ( sm_pairing_packet_t  packet, uint8_t  oob_data_flag  )

inlinestatic

Referenced by sm_init_setup().

static void sm_pairing_packet_set_responder_key_distribution ( sm_pairing_packet_t  packet, uint8_t  responder_key_distribution  )

inlinestatic

Referenced by sm_init_setup(), and sm_run().

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]

References big_endian_store_32(), sm_get_connection_for_handle(), sm_reset_tk(), sm_run(), sm_setup_context::sm_tk, sm_setup_context::sm_user_response, and SM_USER_RESPONSE_PASSKEY.

void sm_register_oob_data_callback

(

int(*)(uint8_t addres_type, bd_addr_t addr, uint8_t *oob_data)

get_oob_data_callback

)

Registers OOB Data Callback.

The callback should set the oob_data and return 1 if OOB data is availble

Parameters

get_oob_data_callback

References sm_get_oob_data.

void sm_request_pairing

(

hci_con_handle_t

con_handle

)

Used by att_server.c to request user authorization.

Parameters

con_handle

References IS_RESPONDER, le_device_db_encryption_get(), log_info, NULL, sm_get_connection_for_handle(), sm_is_null_key(), sm_run(), and sm_send_security_request_for_connection().

Referenced by att_server_process_validated_request().

void sm_send_security_request

(

hci_con_handle_t

con_handle

)

Trigger Security Request.

Note

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

References sm_get_connection_for_handle(), and sm_send_security_request_for_connection().

Referenced by handle_hci_event().

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_

References sm_accepted_stk_generation_methods.

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

References log_error, sm_auth_req, and SM_AUTHREQ_SECURE_CONNECTION.

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 7)
max_size	(default 16)

References sm_max_encryption_key_size, and sm_min_encryption_key_size.

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.

Parameters

er

References sm_persistent_er.

Referenced by sm_init().

void sm_set_io_capabilities

(

io_capability_t

io_capability

)

Sets the available IO Capabilities.

Parameters

IO_CAPABILITY_

References sm_io_capabilities.

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.

References sm_persistent_ir.

Referenced by sm_init().

void sm_set_request_security

(

int

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

void sm_test_set_irk

(

sm_key_t

irk

)

References sm_persistent_irk, and sm_persistent_irk_ready.

void sm_test_use_fixed_ec_keypair

(

void

)

References EC_KEY_GENERATION_DONE.

void sm_test_use_fixed_local_csrk

(

void

)

References test_use_fixed_local_csrk.

void sm_use_fixed_ec_keypair	(	uint8_t *	qx,
		uint8_t *	qy,
		uint8_t *	d
	)

Set Elliptic Key Public/Private Keypair.

Note

Using the same key for more than one device is not recommended.

Parameters

qx	32 bytes
qy	32 bytes
d	32 bytes

References EC_KEY_GENERATION_DONE, and UNUSED.

void sm_use_fixed_legacy_pairing_passkey_in_display_role

(

uint32_t

passkey

)

Set passkey used with LE Legacy Pairing when we generate and show it instead of 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

References sm_fixed_legacy_pairing_passkey_in_display_role.