This module describes functions and data structures used to implement Security Manager. More...

Data Structures
struct	bt_sm_pairing_features_t
	Pairing features. More...

struct	bt_sm_ltk_t
	Long Term Key. More...

struct	bt_sm_session_t
	Security Manager session. More...

struct	bt_sm_evt_connected_t
	Parameter to SM_EVENT_CONNECTED event. More...

struct	bt_sm_evt_disconnected_t
	Parameter to SM_EVENT_DISCONNECTED event. More...

struct	bt_sm_evt_pairing_request_t
	Parameter to SM_EVENT_PAIRING_REQUEST event. More...

struct	bt_sm_evt_passkey_request_t
	Parameter to SM_EVENT_PASSKEY_REQUEST event. More...

struct	bt_sm_evt_oob_data_request_t
	Parameter to SM_EVENT_OOB_DATA_REQUEST event. More...

struct	bt_sm_evt_passkey_notification_t
	Parameter to SM_EVENT_PASSKEY_NOTIFICATION event. More...

struct	bt_sm_evt_confirm_passkey_t
	Parameter to SM_EVENT_PASSKEY_COMPARE event. More...

struct	bt_sm_evt_pairing_complete_t
	Parameter to SM_EVENT_PAIRING_COMPLETE event. More...

struct	bt_sm_evt_keys_request_t
	Parameter to SM_EVENT_PEER_LTK_REQUEST event. More...

struct	bt_sm_evt_ltk_missing_notif_t
	Parameter to SM_EVENT_LTK_MISSING_NOTIFICATION event. More...

struct	bt_sm_evt_auth_request_t
	Parameter to SM_EVENT_AUTH_REQUEST event. More...

struct	bt_sm_evt_auth_succeded_t
	Parameter to SM_EVENT_AUTH_SUCCEEDED event. More...

struct	bt_sm_evt_keys_notif_t
	Parameter to SM_EVENT_PEER_KEYS_NOTIFICATION event. More...

union	bt_sm_event_t
	Parameter to SM listener callback. More...

struct	bt_sm_listener_t
	SM listener. More...

struct	bt_security_mgr_t
	Security Manager. More...

Typedefs
typedef void(*	bt_sm_mgr_callback_fp) (bt_int evt, bt_sm_event_t evt_param, void param)
	SM listener callback. More...

Functions
bt_bool	bt_sm_init (void)
	Initialize the Security Manager (SM). More...

bt_security_mgr_t *	bt_sm_get_mgr (void)
	Get the Security Manager. More...

void	bt_sm_set_er (const void *key)
	Set ER key. More...

void	bt_sm_set_dhk (const void *key)
	Set DHK (Diversifier Hiding Key) key. More...

void	bt_sm_set_irk (const void *key)
	Set IRK (Identity Resolving Key) key. More...

const void *	bt_sm_get_irk (void)
	Get IRK (Identity Resolving Key) key. More...

void	bt_sm_set_csrk (const void *key)
	Set CSRK (Connection Signature Resolving Key) key. More...

void	bt_sm_start (void)
	Start the Security Manager (SM). More...

bt_bool	bt_sm_authenticate (bt_hci_conn_state_t *conn, bt_byte auth_req)
	Authenticate connection. More...

bt_uint	bt_sm_get_session_state (bt_hci_conn_state_t *conn)
	Get the Security Manager's session state. More...

bt_byte	bt_sm_get_session_key_size (bt_hci_conn_state_t *conn)
	Get the size of the key used to encrypt the connection. More...

bt_bool	bt_sm_set_pairing_features (bt_sm_session_t session, bt_byte status, const bt_sm_pairing_features_t features)
	Set pairing features. More...

bt_bool	bt_sm_set_passkey (bt_sm_session_t *session, bt_byte status, bt_ulong passkey)
	Set passkey. More...

bt_bool	bt_sm_set_oob_data (bt_sm_session_t session, bt_byte status, const bt_byte oob_data)
	Set OOB data. More...

bt_bool	bt_sm_send_ltk (bt_sm_session_t session, const bt_sm_ltk_t ltk)
	Send LTK. More...

bt_bool	bt_sm_resolve_address (bt_sm_session_t session, const bt_bdaddr_t addr, const bt_byte *irk)
	Resolve random address. More...

bt_hci_conn_state_t *	bt_sm_get_hci_connection (bt_sm_session_t *session)
	Get ACL connection for a SM session. More...

bt_bool	bt_sm_register_listener (bt_sm_listener_t *listener)
	Register an SM event listener. More...

void	bt_sm_unregister_listener (bt_sm_listener_t *listener)
	Unregister an SM event listener. More...

Events
#define	SM_EVENT_PAIRING_REQUEST 1
	SM requested pairing.

#define	SM_EVENT_PASSKEY_REQUEST 2
	SM requested a passkey.

#define	SM_EVENT_PASSKEY_NOTIFICATION 3
	SM generated a passkey.

#define	SM_EVENT_OOB_DATA_REQUEST 4
	SM requested OOB data.

#define	SM_EVENT_PAIRING_COMPLETE 5
	Pairing completed.

#define	SM_EVENT_KEYS_REQUEST 6
	SM requested keys for a peer device.

#define	SM_EVENT_CONNECTED 7
	SM connection has been established.

#define	SM_EVENT_DISCONNECTED 8
	SM connection has been terminated.

#define	SM_EVENT_KEYS_NOTIFICATION 12
	SM received security keys from a peer device.

#define	SM_EVENT_LTK_MISSING_NOTIFICATION 13
	No LTK has been found for either local or peer device.

#define	SM_EVENT_AUTH_SUCCEEDED 14
	Authentication succeeded.

#define	SM_EVENT_AUTH_REQUEST 15
	Authentication is required.

#define	SM_EVENT_CONFIRM_PASSKEY 16
	SM generated a passkey and asking to confirm that the same passkey is displayed on both devices.

Detailed Description

This module describes functions and data structures used to implement Security Manager.

Typedef Documentation

typedef void(* bt_sm_mgr_callback_fp) (bt_int evt, bt_sm_event_t *evt_param, void *param)

SM listener callback.

In order to be notified of various events a user's application has to register at least one listener. The stack will call the callback function specified in the listener whenever a new event has been generated.

Parameters

evt	Event ID.
evt_param	Event parameter.
callback_param	A pointer to an arbitrary data set by a call to bt_sm_register_listener().

Function Documentation

bt_bool bt_sm_authenticate	(	bt_hci_conn_state_t *	conn,
		bt_byte	auth_req
	)

Authenticate connection.

This function request the SM to authenticate a connection. If local device is Master this function first generates SM_EVENT_PEER_LTK_REQUEST event. In response to this event user's application should find LTK for the peer device (the address of the peer device is passed in the event's parameter). If LTK is found the app should pass it to the SM by calling bt_sm_send_ltk(). The SM will try to authenticate the connection using this LKT. If LTK is not found the appo should call bt_sm_send_ltk() with second parameter NULL. In this case the SM will start pairinf procedure. If local device is Slave this function sends a "Security Request" command to Master. The master will encrypt the link, initiate the pairing procedure, or reject the request.

Parameters

conn	ACL connection to be authenticated.
auth_req	Authentication requirements. This parameter is only used when the local device is Slave. This parametr can be a combination of the following values: SMP_AUTHENTICATION_REQUIREMENTS_NO_BONDING SMP_AUTHENTICATION_REQUIREMENTS_BONDING SMP_AUTHENTICATION_REQUIREMENTS_MITM_REQUIRED

Returns

TRUE if the function succeeds.
FALSE otherwise.

bt_hci_conn_state_t* bt_sm_get_hci_connection ( bt_sm_session_t * session )

Get ACL connection for a SM session.

This function returns a pointer to a structure that describes an ACL connection a session is open on. The return value can be used to call various function from the HCI layer. For example, if an app wants to force disconnection from a remote device it can call bt_hci_disconnect.

Parameters

session SM session.

Returns

Pointer to a structure that describes an ACL connection if the function succeeds.
NULL otherwise.

const void* bt_sm_get_irk ( void )

Get IRK (Identity Resolving Key) key.

This function return a pointer to the current IRK key previously set by bt_sm_set_irk().

bt_security_mgr_t* bt_sm_get_mgr ( void )

Get the Security Manager.

This function returns a pointer to a structure that represents the Security Manager. There is usually no need to use this function in a user's application.

bt_byte bt_sm_get_session_key_size ( bt_hci_conn_state_t * conn )

Get the size of the key used to encrypt the connection.

This function returns the size of the key used to encrypt the connection specified with conn parameter.

Parameters

conn	ACL connection.

Returns

The size of the encryption key in bytes if conn specifies connected and authenticated connection.
0 otherwise.

bt_uint bt_sm_get_session_state ( bt_hci_conn_state_t * conn )

Get the Security Manager's session state.

This function returns the state of the SM session corresponding to the ACL connection specified with conn parameter.

Parameters

conn	ACL connection.

Returns

The SM session state. This can a combination of the following values:

SM_SESSION_STATE_FREE
SM_SM_SESSION_STATE_DISCONNECTED
SM_SM_SESSION_STATE_CONNECTED
SM_SM_SESSION_STATE_PAIRING_STARTED
SM_SM_SESSION_STATE_SENDING
SM_SM_SESSION_STATE_PAIRING_FAILED
SM_SM_SESSION_STATE_CONFIRM_GENERATED
SM_SM_SESSION_STATE_WAIT_STK_ENCRYPTION
SM_SM_SESSION_STATE_CONFIRM_RECEIVED
SM_SM_SESSION_STATE_AUTHENTICATED

bt_bool bt_sm_init ( void )

Initialize the Security Manager (SM).

This function initializes the Security Manage. It must be called prior to any other SM function can be called.

bt_bool bt_sm_register_listener ( bt_sm_listener_t * listener )

Register an SM event listener.

In order to be notified of various events a user's application has to register at least one event listener. The listener is a structure that contains a pointer to a callback function and a callback parameter - a pointer to arbitrary data to be passed to the callback function. The stack will call the callback whenever a new event has been generated passing the code of the event as the first parameter. The event can be one of the following values:

SM_EVENT_PAIRING_REQUEST
SM_EVENT_PASSKEY_REQUEST
SM_EVENT_PASSKEY_NOTIFICATION
SM_EVENT_OOB_DATA_REQUEST
SM_EVENT_PAIRING_COMPLETE
SM_EVENT_KEYS_REQUEST
SM_EVENT_CONNECTED
SM_EVENT_DISCONNECTED
SM_EVENT_LOCAL_LTK_REQUEST
SM_EVENT_KEYS_NOTIFICATION
SM_EVENT_LTK_MISSING_NOTIFICATION
SM_EVENT_ADDRESS_RESOLVED
SM_EVENT_AUTH_SUCCEEDED
SM_EVENT_AUTH_REQUEST

Parameters

listener A pointer to a structure containing the listener parameters. The pointer has to be persistent, i.e., it cannot be allocate on the stack.

Returns

TRUE if the function succeeds.
FALSE otherwise.

bt_bool bt_sm_resolve_address	(	bt_sm_session_t *	session,
		const bt_bdaddr_t *	addr,
		const bt_byte *	irk
	)

Resolve random address.

This function tries to resolve a random address using provided identity resolving key. When the SM generates SM_EVENT_PEER_LTK_REQUEST event and the peer's address is random resolvable address, user's application should go through all stored peer keys and try to resolve the address by calling this function. The result of this function is SM_EVENT_ADDRESS_RESOLVED event. A parameter to this event indicates whether the address has been resolved or not. In the former case the app should call bt_sm_send_ltk() with the LTK associated with the resolved address. If all peer IRKs were tried but the address has not been resolved, the app should call bt_sm_send_ltk() with second parameter NULL.

Parameters

session	SM session.
addr	Address to be resolved.
irk	IRK.

Returns

TRUE if the function succeeds.
FALSE otherwise.

bt_bool bt_sm_send_ltk	(	bt_sm_session_t *	session,
		const bt_sm_ltk_t *	ltk
	)

Send LTK.

This function provides LTK (generated or read from a persistent storage) to the SM when it tries to encrypt a connection. User's application usually call this function from SM_EVENT_KEYS_REQUEST event.

Parameters

session	SM session.
ltk	LTK.

Returns

TRUE if the function succeeds.
FALSE otherwise.

void bt_sm_set_csrk ( const void * key )

Set CSRK (Connection Signature Resolving Key) key.

This function sets the CSRK key. The key is used to sign data and verify signatures on the receiving device without establishing encrypted connection. The CSRK has to be a 128-bit random number. Every device has to have a unique CSRK key. The key can be assigned or randomly generated during device manufacturing and saved in NVM storage. The key can be changed at any time and this will not invalidate pairing information, but the remote device will not be able to authenticate the ATT "Signed Write Command" until re-pairing is performed. I.e., devices will able to communicate as long as the central does not "Signed Write Command".

void bt_sm_set_dhk ( const void * key )

Set DHK (Diversifier Hiding Key) key.

This function sets the DHK key. The key is used to hide diversifier value distributed during pairing. The DHK has to be a 128-bit random number. Every device has to have a unique DHK key. The key can be assigned or randomly generated during device manufacturing and saved in NVM storage. If the DHK key is changed for some reason, all pairing information becomes invalid. Previously paired remote devices will not be able to establish a secure connection and will require re-pairing.

void bt_sm_set_er ( const void * key )

Set ER key.

This function sets the ER key. It is used to generate Long Term Key (LTK) during pairing. The ER has to be a 128-bit random number. Every device has to have a unique ER key. The key can be assigned or randomly generated during device manufacturing and saved in NVM storage. The key can also be generated every time a device is power cycled. All LTKs generated with previous ER remain valid until they are deleted.

void bt_sm_set_irk ( const void * key )

Set IRK (Identity Resolving Key) key.

This function sets the IRK key. The key is used to generate and resolve random addresses. The IRK has to be a 128-bit random number. Every device has to have a unique IRK key. The key can be assigned or randomly generated during device manufacturing and saved in NVM storage. If the IRK key is changed for some reason, all pairing information becomes invalid. Previously paired remote devices will not be able to resolve random addresses generated by the local device and establish a secure connection. Re-pairing will be required.

bt_bool bt_sm_set_oob_data	(	bt_sm_session_t *	session,
		bt_byte	status,
		const bt_byte *	oob_data
	)

Set OOB data.

This function sets the OOB data if "out of band" pairing is used. User's application should call this function in response to SM_EVENT_OOB_DATA_REQUEST event.

Parameters

session	SM session.
status	Pairing status. If pairing should not be aborted this parameter has to be set to SMP_PAIRING_ERROR_SUCCESS. If for any reason pairing should be terminated this parameter can be set to one of the following values: SMP_PAIRING_ERROR_PASSKEY_ENTRY_FAILED SMP_PAIRING_ERROR_OOB_NOT_AVAILABLE SMP_PAIRING_ERROR_AUTHENTICATION_REQUIREMENTS SMP_PAIRING_ERROR_CONFIRM_VALUE_FAILED SMP_PAIRING_ERROR_PAIRING_NOT_SUPPORTED SMP_PAIRING_ERROR_ENCRYPTION_KEY_SIZE SMP_PAIRING_ERROR_COMMAND_NOT_SUPPORTED SMP_PAIRING_ERROR_UNSPECIFIED_REASON SMP_PAIRING_ERROR_REPEATED_ATTEMPTS SMP_PAIRING_ERROR_INVALID_PARAMETERS SMP_PAIRING_ERROR_TIMEOUT SMP_PAIRING_ERROR_DISCONNECTED
oob_data	OOB data.

Returns

TRUE if the function succeeds.
FALSE otherwise.

bt_bool bt_sm_set_pairing_features	(	bt_sm_session_t *	session,
		bt_byte	status,
		const bt_sm_pairing_features_t *	features
	)

Set pairing features.

This function sets pairing features during pairing process. The features are set when the SM generates SM_EVENT_PAIRING_REQUEST event. User's application has to fill out bt_sm_pairing_features_t structure with required features and call this function. The features that can be specified are:

IO capabilities
Presence of OOB data
Authentication requirements
Minimum keys size
Maximum keys size
Initiator key distribution
Responder key distribution

Parameters

session	SM session.
status	Pairing status. If pairing should not be aborted this parameter has to be set to SMP_PAIRING_ERROR_SUCCESS. If for any reason pairing should be terminated this parameter can be set to one of the following values: SMP_PAIRING_ERROR_PASSKEY_ENTRY_FAILED SMP_PAIRING_ERROR_OOB_NOT_AVAILABLE SMP_PAIRING_ERROR_AUTHENTICATION_REQUIREMENTS SMP_PAIRING_ERROR_CONFIRM_VALUE_FAILED SMP_PAIRING_ERROR_PAIRING_NOT_SUPPORTED SMP_PAIRING_ERROR_ENCRYPTION_KEY_SIZE SMP_PAIRING_ERROR_COMMAND_NOT_SUPPORTED SMP_PAIRING_ERROR_UNSPECIFIED_REASON SMP_PAIRING_ERROR_REPEATED_ATTEMPTS SMP_PAIRING_ERROR_INVALID_PARAMETERS SMP_PAIRING_ERROR_TIMEOUT SMP_PAIRING_ERROR_DISCONNECTED
features	Pairing features.

Returns

TRUE if the function succeeds.
FALSE otherwise.

bt_bool bt_sm_set_passkey	(	bt_sm_session_t *	session,
		bt_byte	status,
		bt_ulong	passkey
	)

Set passkey.

This function sets the passkey if "passkey entry" pairing is used. User's application should call this function in response to SM_EVENT_PASSKEY_REQUEST event.

Parameters

session	SM session.
status	Pairing status. If pairing should not be aborted this parameter has to be set to SMP_PAIRING_ERROR_SUCCESS. If for any reason pairing should be terminated this parameter can be set to one of the following values: SMP_PAIRING_ERROR_PASSKEY_ENTRY_FAILED SMP_PAIRING_ERROR_OOB_NOT_AVAILABLE SMP_PAIRING_ERROR_AUTHENTICATION_REQUIREMENTS SMP_PAIRING_ERROR_CONFIRM_VALUE_FAILED SMP_PAIRING_ERROR_PAIRING_NOT_SUPPORTED SMP_PAIRING_ERROR_ENCRYPTION_KEY_SIZE SMP_PAIRING_ERROR_COMMAND_NOT_SUPPORTED SMP_PAIRING_ERROR_UNSPECIFIED_REASON SMP_PAIRING_ERROR_REPEATED_ATTEMPTS SMP_PAIRING_ERROR_INVALID_PARAMETERS SMP_PAIRING_ERROR_TIMEOUT SMP_PAIRING_ERROR_DISCONNECTED
passkey	Passkey.

Returns

TRUE if the function succeeds.
FALSE otherwise.

void bt_sm_start ( void )

Start the Security Manager (SM).

This function starts the Security Manage. It must be called after bt_sm_init() but not before bt_sys_start() has completed. I.e., the earliest to call bt_sm_start() is in the bt_sys_start() callback.

void bt_sm_unregister_listener ( bt_sm_listener_t * listener )

Unregister an SM event listener.

Remove a listener previously registered with bt_sm_register_listener().

Parameters

listener A pointer to a structure containing the listener parameters. It has to be the the same pinter passed to bt_sm_register_listener().

Data Structures

Typedefs

Functions

Events

Detailed Description

Typedef Documentation

Function Documentation