Security Manager

An internal module of Peer Manager. A module for streamlining pairing, bonding, and encryption, including flash storage of shared data. More...

Data Structures
struct	sm_evt_t

Typedefs
typedef void(*	sm_evt_handler_t )(sm_evt_t const *p_event)
	Event handler for events from the Security Manager module. More...

Enumerations
enum	sm_evt_id_t {   SM_EVT_SLAVE_SECURITY_REQ = SMD_EVT_SLAVE_SECURITY_REQ,   SM_EVT_SEC_PROCEDURE_START = SMD_EVT_SEC_PROCEDURE_START,   SM_EVT_PAIRING_SUCCESS = SMD_EVT_PAIRING_SUCCESS,   SM_EVT_PAIRING_FAIL = SMD_EVT_PAIRING_FAIL,   SM_EVT_LINK_ENCRYPTION_UPDATE = SMD_EVT_LINK_ENCRYPTION_UPDATE,   SM_EVT_LINK_ENCRYPTION_FAILED = SMD_EVT_LINK_ENCRYPTION_FAILED,   SM_EVT_BONDING_INFO_STORED = SMD_EVT_BONDING_INFO_STORED,   SM_EVT_ERROR_BONDING_INFO = SMD_EVT_ERROR_BONDING_INFO,   SM_EVT_ERROR_UNEXPECTED = SMD_EVT_ERROR_UNEXPECTED,   SM_EVT_ERROR_NO_MEM,   SM_EVT_ERROR_SMP_TIMEOUT }
	Events that can come from the Security Manager module. More...

Functions
ret_code_t	sm_register (sm_evt_handler_t evt_handler)
	Function for registering with the Security Manager module. This function also initializes the module if uninitialized. More...
void	sm_ble_evt_handler (ble_evt_t *ble_evt)
	Function for dispatching SoftDevice events to the Security Manager module. More...
ret_code_t	sm_sec_params_set (ble_gap_sec_params_t *p_sec_params)
	Function for providing pairing and bonding parameters to use for pairing procedures. More...
ret_code_t	sm_sec_params_reply (uint16_t conn_handle, ble_gap_sec_params_t *p_sec_params)
	Function for providing pairing and bonding parameters to use for the current pairing procedure on a connection. More...
ret_code_t	sm_link_secure (uint16_t conn_handle, bool force_repairing)
	Function for initiating security on the link, with the specified parameters. More...

Detailed Description

An internal module of Peer Manager. A module for streamlining pairing, bonding, and encryption, including flash storage of shared data.

Typedef Documentation

typedef void(* sm_evt_handler_t)(sm_evt_t const *p_event)

Event handler for events from the Security Manager module.

Parameters

[in]	event	The event that has happened.
[in]	conn_handle	The connection handle the event pertains to.

Enumeration Type Documentation

enum sm_evt_id_t

Events that can come from the Security Manager module.

Enumerator
SM_EVT_SLAVE_SECURITY_REQ	The peer (slave) has requested link encryption, which has been enabled.
SM_EVT_SEC_PROCEDURE_START	A security procedure has started.
SM_EVT_PAIRING_SUCCESS	A pairing procedure (and bonding if applicable) has completed with success.
SM_EVT_PAIRING_FAIL	A pairing procedure has failed which means no encryption and no bond could be established.
SM_EVT_LINK_ENCRYPTION_UPDATE	The security level of the link has been updated. The link is encrypted.
SM_EVT_LINK_ENCRYPTION_FAILED	An attempt to start encryption on an unencrypted link failed because the peripheral did not have the correct keys. If the peer is the peripheral, the force_repairing flag should be set when reattempting sm_link_secure.
SM_EVT_BONDING_INFO_STORED	Information exchanged during bonding with a peer has been stored persistently.
SM_EVT_ERROR_BONDING_INFO	Information exchanged during bonding with a peer could not be stored persistently, because of an unexpected error.
SM_EVT_ERROR_UNEXPECTED	An operation failed with an unexpected error. The error is provided. This is possibly a fatal error.
SM_EVT_ERROR_NO_MEM	An operation failed because there was no available storage room in persistent storage. Please free up room and the operation will automatically continue after the next compression.
SM_EVT_ERROR_SMP_TIMEOUT	An operation failed because there has been an SMP timeout on the link, which entails that no more security operations can be performed on it.

Function Documentation

void sm_ble_evt_handler

(

ble_evt_t *

ble_evt

)

Function for dispatching SoftDevice events to the Security Manager module.

Parameters

[in]

ble_evt

The SoftDevice event.

ret_code_t sm_link_secure	(	uint16_t	conn_handle,
		bool	force_repairing
	)

Function for initiating security on the link, with the specified parameters.

Note

If the connection is a peripheral connection, this will send a security request to the master, but the master is not obligated to initiate pairing or encryption in response.

If the connection is a central connection and a key is available, the parameters will be used to determine whether to re-pair or to encrypt using the existing key. If no key is available, pairing will be started.

Parameters

[in]	conn_handle	Handle of the connection to initiate pairing on.
[in]	force_repairing	Whether to force a pairing procedure to happen regardless of whether an encryption key already exists. This argument is only relevant for the central role. Recommended value: false

Return values

NRF_SUCCESS	Success.
NRF_ERROR_TIMEOUT	There has been an SMP timeout, so no more SMP operations can be performed on this link.
BLE_ERROR_INVALID_CONN_HANDLE	Invalid connection handle.
NRF_ERROR_NOT_FOUND	Security parameters have not been set.
NRF_ERROR_INVALID_STATE	Module is not initialized.
NRF_ERROR_INTERNAL	An unexpected error occurred.

ret_code_t sm_register

(

sm_evt_handler_t

evt_handler

)

Function for registering with the Security Manager module. This function also initializes the module if uninitialized.

Parameters

[in]

evt_handler

Callback for events from the Security Manager module.

Return values

NRF_SUCCESS	Registration was successful.
NRF_ERROR_NO_MEM	No more registrations possible.
NRF_ERROR_NULL	evt_handler was NULL.
NRF_ERROR_INTERNAL	An unexpected error occurred.

ret_code_t sm_sec_params_reply	(	uint16_t	conn_handle,
		ble_gap_sec_params_t *	p_sec_params
	)

Function for providing pairing and bonding parameters to use for the current pairing procedure on a connection.

Warning

This function is not yet implemented.

Note

If this function returns an NRF_ERROR_NULL, NRF_ERROR_INVALID_PARAM, BLE_ERROR_INVALID_CONN_HANDLE, or NRF_ERROR_NO_MEM, this function can be called again after corrective action.

To reject a request, call this function with NULL p_sec_params.

Parameters

[in]	conn_handle	The connection handle of the connection the pairing is happening on.
[in]	p_sec_params	The security parameters to use for this link.

Return values

NRF_SUCCESS	Success.
NRF_ERROR_INVALID_STATE	Module is not initialized, or no parameters have been requested on that conn_handle, or this error originates from the SoftDevice.
NRF_ERROR_INVALID_PARAM	Invalid combination of parameters (not including conn_handle).
NRF_ERROR_TIMEOUT	There has been an SMP timeout, so no more SMP operations can be performed on this link.
BLE_ERROR_INVALID_CONN_HANDLE	Invalid connection handle.
NRF_ERROR_NO_MEM	No more room in flash. Fix and reattempt later.
NRF_ERROR_BUSY	No write buffer. Reattempt later.

ret_code_t sm_sec_params_set

(

ble_gap_sec_params_t *

p_sec_params

)

Function for providing pairing and bonding parameters to use for pairing procedures.

Until this is called, all bonding procedures initiated by the peer will be rejected. This function can be called multiple times, even with NULL p_sec_params, in which case it will go back to rejecting all procedures.

Parameters

[in]

p_sec_params

The security parameters to use for this link. Can be NULL to reject all pairing procedures.

Return values

NRF_SUCCESS	Success.
NRF_ERROR_INVALID_PARAM	Invalid combination of parameters.
NRF_ERROR_INVALID_STATE	Module is not initialized.