#include <SecurityManager.h>

Inherited by GenericSecurityManager.

Data Structures
class	EventHandler
	The stack will use these functions to signal events to the application, subclass to override handlers. More...
Public Types
enum	Keypress_t { KEYPRESS_STARTED, KEYPRESS_ENTERED, KEYPRESS_ERASED, KEYPRESS_CLEARED, KEYPRESS_COMPLETED }
	events sent and received when passkey is being entered More...
enum	SecurityMode_t { , SECURITY_MODE_ENCRYPTION_OPEN_LINK, SECURITY_MODE_ENCRYPTION_NO_MITM, SECURITY_MODE_ENCRYPTION_WITH_MITM, SECURITY_MODE_SIGNED_NO_MITM, SECURITY_MODE_SIGNED_WITH_MITM }
	level of security required from the link by the application More...
enum	LinkSecurityStatus_t { NOT_ENCRYPTED, ENCRYPTION_IN_PROGRESS, ENCRYPTED }
	Defines possible security status or states. More...
enum	SecurityIOCapabilities_t { IO_CAPS_DISPLAY_ONLY = 0x00, IO_CAPS_DISPLAY_YESNO = 0x01, IO_CAPS_KEYBOARD_ONLY = 0x02, IO_CAPS_NONE = 0x03, IO_CAPS_KEYBOARD_DISPLAY = 0x04 }
	Input/output capability of the device and application. More...
enum	SecurityCompletionStatus_t { SEC_STATUS_SUCCESS = 0x00, SEC_STATUS_TIMEOUT = 0x01, SEC_STATUS_PDU_INVALID = 0x02, SEC_STATUS_PASSKEY_ENTRY_FAILED = 0x81, SEC_STATUS_OOB_NOT_AVAILABLE = 0x82, SEC_STATUS_AUTH_REQ = 0x83, SEC_STATUS_CONFIRM_VALUE = 0x84, SEC_STATUS_PAIRING_NOT_SUPP = 0x85, SEC_STATUS_ENC_KEY_SIZE = 0x86, SEC_STATUS_SMP_CMD_UNSUPPORTED = 0x87, SEC_STATUS_UNSPECIFIED = 0x88, SEC_STATUS_REPEATED_ATTEMPTS = 0x89, SEC_STATUS_INVALID_PARAMS = 0x8A, SEC_STATUS_DHKEY_CHECK_FAILED = 0x8B, SEC_STATUS_COMPARISON_FAILED = 0x8C }
	Result of security requests. More...
typedef uint8_t	Passkey_t [PASSKEY_LEN]
	6-digit passkey in ASCII ('0'-'9' digits only).
Public Member Functions
virtual ble_error_t	init (bool enableBonding=true, bool requireMITM=true, SecurityIOCapabilities_t iocaps=IO_CAPS_NONE, const Passkey_t passkey=NULL, bool signing=true)
	Enable the BLE stack's Security Manager.
virtual ble_error_t	reset (void)
	Notify all registered onShutdown callbacks that the SecurityManager is about to be shutdown and clear all SecurityManager state of the associated object.
virtual ble_error_t	preserveBondingStateOnReset (bool enable)
	Normally all bonding information is lost when device is reset, this requests that the stack attempts to save the information and reload it during initialisation.
virtual ble_error_t	purgeAllBondingState (void)
	Delete all peer device context and all related bonding information from the database within the security manager.
virtual ble_error_t	generateWhitelistFromBondTable (Gap::Whitelist_t *whitelist) const
	Create a list of addresses from all peers in the bond table and generate an event which returns it as a whitelist.
virtual ble_error_t	requestPairing (ble::connection_handle_t connectionHandle)
	Request pairing with the peer.
virtual ble_error_t	acceptPairingRequest (ble::connection_handle_t connectionHandle)
	Accept the pairing request.
virtual ble_error_t	cancelPairingRequest (ble::connection_handle_t connectionHandle)
	Reject pairing request if the local device is the slave or cancel an outstanding pairing request if master.
virtual ble_error_t	setPairingRequestAuthorisation (bool required=true)
	Tell the stack whether the application needs to authorise pairing requests or should they be automatically accepted.
virtual ble_error_t	allowLegacyPairing (bool allow=true)
	Allow of disallow the use of legacy pairing in case the application only wants to force the use of Secure Connections.
virtual ble_error_t	getSecureConnectionsSupport (bool *enabled)
	Check if the Secure Connections feature is supported by the stack and controller.
virtual ble_error_t	setIoCapability (SecurityIOCapabilities_t iocaps)
	Set the IO capability of the local device.
virtual ble_error_t	setDisplayPasskey (const Passkey_t passkey)
	Set the passkey that is displayed on the local device instead of using a randomly generated one.
virtual ble_error_t	setLinkSecurity (ble::connection_handle_t connectionHandle, SecurityMode_t securityMode)
	Set the security mode on a connection.
virtual ble_error_t	setKeypressNotification (bool enabled=true)
	Set whether or not we want to send and receive keypress notifications during passkey entry.
virtual ble_error_t	enableSigning (ble::connection_handle_t connectionHandle, bool enabled=true)
	Request generation and exchange of signing keys so that packet signing can be utilised on this connection.
virtual ble_error_t	setHintFutureRoleReversal (bool enable=true)
	Give a hint to the stack that the master/slave role might change in the future.
virtual ble_error_t	getLinkEncryption (ble::connection_handle_t connectionHandle, ble::link_encryption_t *encryption)
	Current state of encryption on the link.
virtual ble_error_t	setLinkEncryption (ble::connection_handle_t connectionHandle, ble::link_encryption_t encryption)
	Enabled or disable encryption on the link.
virtual ble_error_t	setEncryptionKeyRequirements (uint8_t minimumByteSize, uint8_t maximumByteSize)
	Set the requirements for encryption key size.
virtual ble_error_t	requestAuthentication (ble::connection_handle_t connectionHandle)
	Request that the link be authenticated (keys with MITM protection).
virtual ble_error_t	setOOBDataUsage (ble::connection_handle_t connectionHandle, bool useOOB, bool OOBProvidesMITM=true)
	Enable OOB data usage during paring.
virtual ble_error_t	confirmationEntered (ble::connection_handle_t connectionHandle, bool confirmation)
	Report to the stack if the passkey matches or not.
virtual ble_error_t	passkeyEntered (ble::connection_handle_t connectionHandle, Passkey_t passkey)
	Supply the stack with the user entered passkey.
virtual ble_error_t	sendKeypressNotification (ble::connection_handle_t connectionHandle, Keypress_t keypress)
	Send a notification to the peer that the user pressed a key on the local device.
virtual ble_error_t	legacyPairingOobReceived (const ble::address_t address, const ble::oob_tk_t tk)
	Supply the stack with the OOB data for legacy connections.
virtual ble_error_t	oobReceived (const ble::address_t address, const ble::oob_lesc_value_t random, const ble::oob_confirm_t *confirm)
	Supply the stack with the OOB data for secure connections.
virtual ble_error_t	getSigningKey (ble::connection_handle_t connectionHandle, bool authenticated)
	Retrieves a signing key through a signingKey event.
void	onShutdown (const SecurityManagerShutdownCallback_t &callback)
	Setup a callback to be invoked to notify the user application that the SecurityManager instance is about to shutdown (possibly as a result of a call to BLE::shutdown()).
SecurityManagerShutdownCallbackChain_t &	onShutdown ()
	Provide access to the callchain of shutdown event callbacks.
virtual void	setSecurityManagerEventHandler (EventHandler *handler)
	Assign the event handler implementation that will be used by the stack to signal events back to the application.
virtual ble_error_t	getAddressesFromBondTable (Gap::Whitelist_t &addresses) const
ble_error_t	getLinkSecurity (ble::connection_handle_t connectionHandle, LinkSecurityStatus_t *securityStatus)
virtual void	onSecuritySetupInitiated (SecuritySetupInitiatedCallback_t callback)
virtual void	onSecuritySetupCompleted (SecuritySetupCompletedCallback_t callback)
virtual void	onLinkSecured (LinkSecuredCallback_t callback)
virtual void	onSecurityContextStored (HandleSpecificEvent_t callback)
virtual void	onPasskeyDisplay (PasskeyDisplayCallback_t callback)
void	processSecuritySetupInitiatedEvent (ble::connection_handle_t connectionHandle, bool allowBonding, bool requireMITM, SecurityIOCapabilities_t iocaps)
void	processSecuritySetupCompletedEvent (ble::connection_handle_t connectionHandle, SecurityCompletionStatus_t status)
void	processLinkSecuredEvent (ble::connection_handle_t connectionHandle, SecurityMode_t securityMode)
void	processSecurityContextStoredEvent (ble::connection_handle_t connectionHandle)
void	processPasskeyDisplayEvent (ble::connection_handle_t connectionHandle, const Passkey_t passkey)
Static Public Attributes
static const unsigned	PASSKEY_LEN = 6
	Declaration of type containing a passkey to be used during pairing.

Detailed Description

Overview.

Security Manager is used to provide link security through encryption, signing and authentication which are made possible by pairing and optionally bonding. Pairing is the process of establishing and/or exchanging keys used for the current connection. Bonding means saving this information so that it can later be used after reconnecting without having to pair again. This saves time and power.

There are many ways to provide these at different levels of security depending on your requirements and the facilities provided by the application. The process starts with initialising the SecurityManager with default options for new connections. Some settings can later be changed per link or globally.

The important settings in the init() function are the MITM requirement and IO capabilities. Man in the Middle (MITM) protection prevents an attack where one device can impersonate another device by pairing with both devices at the same time. This protection is achieved by sharing some information between the devices through some independent channel. The IO capabilities of both devices dictate what algorithm is used. For details

See also:: BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part H - 2.3.5.1. You can change the IO capabilities after initialisation with setIoCapability(). This will take effect for all subsequent pairings.

Sharing this information through IO capabilities means user interaction which limits the degree of protection due to the limit of the amount of data that we can expect the user to transfer. Another solution is using OOB (out of band) communication to transfer this data instead which can send much more data making MITM attack even less likely to succeed. OOB data has to be exchanged by the application and provided to the Security Manager. Use setOOBDataUsage() to indicate you want to use it. The same call also allows you to set whether or not the communication channel you are using to transmit the OOB data is itself secure against MITM protection - this will set the level of the link security achieved using pairing that uses this data.

The most secure pairing is provided by Secure Connections which relies on Elliptical Curve Cryptography. Support for Secure Connections is dependent on both the stack and controller on both sides supporting it. If either side doesn't support it Legacy Pairing will be used. This is an older standard of pairing. If higher security is required legacy pairing can be disabled by calling allowLegacyPairing(false);

How to use

First thing you need to do is to initialise the manager by calling init() with your chosen settings.

The SecurityManager communicates with your application through events. These will trigger calls in the EventHandler which you must provide by calling the setSecurityManagerEventHandler() function.

The most important process is pairing. This may be triggered manually by calling requestPairing() or may be called as a result of the application requiring encryption by calling setLinkEncryption() or as a result of the application requiring MITM protection through requestAuthentication().

All these can be implicitly called by using setLinkSecurity() to conveniently set the required security for the link. The SecurityManager will trigger all the process required to achieve the set security level. Security level can only be escalated. Asking the Security Manager for a lower security level than the existing one will not fail but will result in a event informing the application through linkEncryptionResult() of the current level (which remains unchanged).

Depending on the IO capabilities and OOB usage settings different pairing algorithms will be chosen. They will produce appropriate events which must be handled by your EventHandler. If your event handler doesn't support all the calls you must not set IO capabilities or set OOB usage in such a way that would trigger them or else the pairing will fail (usually by timing out).

The simplest example is a pairing of a device with no IO capabilities and no OOB data available. With such limited pairing capabilities the "just works" method will be employed. This does not provide any MITM protection. The pairing (triggered implicitly or called explicitly) will result in an event being generated on the peer calling pairingRequest(). The event handler must make a decision (either in the application itself or based on user interaction) whether to accept the pairing and call accetPairing() or cancelPairing(). The result will be communicated on both peers through an event calling pairingResult() in the EventHandler.

Sequence diagrams

Sequence diagram "Just Works" pairing

 *  /----------- Device 1 --------------\  *------ BLE link ------*  /-------------- Device 2 -------------\
 *
 * App  EventHandler              SecurityManager              SecurityManager           EventHandler     App
 *  |        |                          |                            |                        |            |
 *  |---------------------------> requestPairing()                   |                        |            |
 *  |        |                          |------[pairing start]------>|                        |            |
 *  |        |                          |                            |----------------> pairingRequest() ->|
 *  |        |                          |                        acceptPairing() <------------------------ |
 *  |        |                          |<---[pairing complete]----->|                        |            |
 *  |<- pairingResult() <---------------|                            |----------------> pairingResult() -->|
 *  |        |                          |                            |                        |            |
 *

Note:: the requestPairing() call isn't required to trigger pairing. Pairing will also be triggered if you request encryption and authentication and no bonding information is available. The sequence will be the same save for the lack of explicit requestPairing() call.

Sequence diagram Encryption request when bonding information is available

 *  /----------- Device 1 --------------\  *------ BLE link ------*  /-------------- Device 2 -------------\
 *
 * App  EventHandler              SecurityManager              SecurityManager           EventHandler     App
 *  |       |                           |                            |                        |            |
 *  |---------------------------> setLinkEncryption()                |                        |            |
 *  |       |                           |<-[encryption established]->|                        |            |
 *  |<- linkEncryptionResult() <--------|                            |---------> linkEncryptionResult() -->|
 *  |       |                           |                            |                        |            |
 *

Note:: if bonding information is not available, pairing will be triggered

Sequence diagram for Secure Connections passkey entry pairing with one device having a display only and other a keyboard

 *  /----------- Device 1 (keyboard) ---\  *------ BLE link ------*  /-------------- Device 2 (display) ---\
 *
 * App  EventHandler              SecurityManager              SecurityManager           EventHandler     App
 *  |        |                          |                            |                        |            |
 *  |---------------------------> requestPairing()                   |                        |            |
 *  |        |                          |------[pairing start]------>|                        |            |
 *  |        |                          |                            |----------------> pairingRequest() ->|
 *  |        |                          |                        acceptPairing() <------------------------ |
 *  |        |                          |<---[secure con. pairing]-->|                        |            |
 *  |<- passkeyRequest() <--------------|                            |----------------> passkeyDisplay() ->|
 *  |        |                          |                            |                        |            |
 *
 *                       user reads the passkey on Device 2 and inputs it on Device 1
 *
 *  |        |                          |                            |                        |            |
 *  |-------------------------->passkeyEntered()                     |                        |            |
 *  |        |                          |<---[pairing complete]----->|                        |            |
 *  |<- pairingResult() <---------------|                            |----------------> pairingResult() -->|
 *  |        |                          |                            |                        |            |
 *

Definition at line 156 of file SecurityManager.h.

Member Typedef Documentation

typedef uint8_t Passkey_t[PASSKEY_LEN]

6-digit passkey in ASCII ('0'-'9' digits only).

Definition at line 222 of file SecurityManager.h.

Member Enumeration Documentation

enum Keypress_t

events sent and received when passkey is being entered

Enumerator:

KEYPRESS_STARTED	Passkey entry started.
KEYPRESS_ENTERED	Passkey digit entered.
KEYPRESS_ERASED	Passkey digit erased.
KEYPRESS_CLEARED	Passkey cleared.
KEYPRESS_COMPLETED	Passkey entry completed.

Definition at line 159 of file SecurityManager.h.

enum LinkSecurityStatus_t

Defines possible security status or states.

Defines possible security status or states of a link when requested by getLinkSecurity().

Enumerator:

NOT_ENCRYPTED	The link is not secured.
ENCRYPTION_IN_PROGRESS	Link security is being established.
ENCRYPTED	The link is secure.

Definition at line 182 of file SecurityManager.h.

enum SecurityCompletionStatus_t

Result of security requests.

Enumerator:

SEC_STATUS_SUCCESS	Procedure completed with success.
SEC_STATUS_TIMEOUT	Procedure timed out.
SEC_STATUS_PDU_INVALID	Invalid PDU received.
SEC_STATUS_PASSKEY_ENTRY_FAILED	Passkey entry failed (user cancelled or other).
SEC_STATUS_OOB_NOT_AVAILABLE	Out of Band Key not available.
SEC_STATUS_AUTH_REQ	Authentication requirements not met.
SEC_STATUS_CONFIRM_VALUE	Confirm value failed.
SEC_STATUS_PAIRING_NOT_SUPP	Pairing not supported.
SEC_STATUS_ENC_KEY_SIZE	Encryption key size.
SEC_STATUS_SMP_CMD_UNSUPPORTED	Unsupported SMP command.
SEC_STATUS_UNSPECIFIED	Unspecified reason.
SEC_STATUS_REPEATED_ATTEMPTS	Too little time elapsed since last attempt.
SEC_STATUS_INVALID_PARAMS	Invalid parameters.
SEC_STATUS_DHKEY_CHECK_FAILED	DHKey received doesn’t match locally calculated one.
SEC_STATUS_COMPARISON_FAILED	Values in the numeric comparison protocol do not match.

Definition at line 198 of file SecurityManager.h.

enum SecurityIOCapabilities_t

Input/output capability of the device and application.

Enumerator:

IO_CAPS_DISPLAY_ONLY	Display only.
IO_CAPS_DISPLAY_YESNO	Display and yes/no entry.
IO_CAPS_KEYBOARD_ONLY	Keyboard only.
IO_CAPS_NONE	No I/O capabilities.
IO_CAPS_KEYBOARD_DISPLAY	Keyboard and display.

Definition at line 189 of file SecurityManager.h.

enum SecurityMode_t

level of security required from the link by the application

Enumerator:

SECURITY_MODE_ENCRYPTION_OPEN_LINK	Require no protection, open link.
SECURITY_MODE_ENCRYPTION_NO_MITM	Require encryption, but no MITM protection.
SECURITY_MODE_ENCRYPTION_WITH_MITM	Require encryption and MITM protection.
SECURITY_MODE_SIGNED_NO_MITM	Require signing or encryption, but no MITM protection.
SECURITY_MODE_SIGNED_WITH_MITM	Require signing or encryption, and MITM protection.

Definition at line 168 of file SecurityManager.h.

Member Function Documentation

virtual ble_error_t acceptPairingRequest ( ble::connection_handle_t connectionHandle ) [virtual]

Accept the pairing request.

Called as a result of pairingRequest being called on the event handler.

Parameters:

[in] connectionHandle Handle to identify the connection.

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 528 of file SecurityManager.h.

virtual ble_error_t allowLegacyPairing ( bool allow = true ) [virtual]

Allow of disallow the use of legacy pairing in case the application only wants to force the use of Secure Connections.

If legacy pairing is disallowed and either side doesn't support Secure Connections the pairing will fail.

Parameters:

[out] allow If true legacy pairing will be used if either side doesn't support Secure Connections.

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 572 of file SecurityManager.h.

virtual ble_error_t cancelPairingRequest ( ble::connection_handle_t connectionHandle ) [virtual]

Reject pairing request if the local device is the slave or cancel an outstanding pairing request if master.

Parameters:

[in] connectionHandle Handle to identify the connection.

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 540 of file SecurityManager.h.

virtual ble_error_t confirmationEntered	(	ble::connection_handle_t	connectionHandle,
		bool	confirmation
	)		`[virtual]`

Report to the stack if the passkey matches or not.

Used during pairing to provide MITM protection.

Parameters:

[in]	connectionHandle	Handle to identify the connection.
[in]	confirmation	True value indicates the passkey displayed matches.

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 763 of file SecurityManager.h.

virtual ble_error_t enableSigning	(	ble::connection_handle_t	connectionHandle,
		bool	enabled = `true`
	)		`[virtual]`

Request generation and exchange of signing keys so that packet signing can be utilised on this connection.

Note:: This does not generate a signingKey event. Use getSigningKey for that.

Parameters:

[in]	connectionHandle	Handle to identify the connection.
[in]	enabled	If set to true, signing keys will be exchanged during subsequent pairing.

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 656 of file SecurityManager.h.

virtual ble_error_t generateWhitelistFromBondTable ( Gap::Whitelist_t * whitelist ) const [virtual]

Create a list of addresses from all peers in the bond table and generate an event which returns it as a whitelist.

Pass in the container for the whitelist. This will be returned by the event.

Parameters:

[in] whitelist Preallocated whitelist which will be filled up to its capacity. If whitelist already contains entries this will be appended to. Do not access the whitelist until callback has been called, returning the filled whitelist.

Return values:

BLE_ERROR_NONE On success, else an error code indicating reason for failure

Definition at line 501 of file SecurityManager.h.

virtual ble_error_t getAddressesFromBondTable ( Gap::Whitelist_t & addresses ) const [virtual]

Get a list of addresses from all peers in the bond table.

Parameters:

[in,out] addresses (on input) addresses.capacity contains the maximum number of addresses to be returned. (on output) The populated table with copies of the addresses in the implementation's whitelist.

Return values:

BLE_ERROR_NONE	On success, else an error code indicating reason for failure.
BLE_ERROR_INVALID_STATE	If the API is called without module initialization or application registration.

Definition at line 918 of file SecurityManager.h.

virtual ble_error_t getLinkEncryption	(	ble::connection_handle_t	connectionHandle,
		ble::link_encryption_t *	encryption
	)		`[virtual]`

Current state of encryption on the link.

Parameters:

[in]	connectionHandle	Handle to identify the connection.
[out]	encryption

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 684 of file SecurityManager.h.

ble_error_t getLinkSecurity	(	ble::connection_handle_t	connectionHandle,
		LinkSecurityStatus_t *	securityStatus
	)

Get the security status of a connection.

Parameters:

[in]	connectionHandle	Handle to identify the connection.
[out]	securityStatus	Security status.

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 934 of file SecurityManager.h.

virtual ble_error_t getSecureConnectionsSupport ( bool * enabled ) [virtual]

Check if the Secure Connections feature is supported by the stack and controller.

Parameters:

[out] enabled true if SC are supported

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 583 of file SecurityManager.h.

virtual ble_error_t getSigningKey	(	ble::connection_handle_t	connectionHandle,
		bool	authenticated
	)		`[virtual]`

Retrieves a signing key through a signingKey event.

If a signing key is not present, pairing/authentication will be attempted.

Note:: This will attempt to retrieve the key even if enableSigning hasn't been called prior to pairing.

Parameters:

[in]	connectionHandle	Handle to identify the connection.
[in]	authenticated	Whether the signing key needs to be authenticated (provide MITM protection).

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 840 of file SecurityManager.h.

virtual ble_error_t init	(	bool	enableBonding = `true`,
		bool	requireMITM = `true`,
		SecurityIOCapabilities_t	iocaps = `IO_CAPS_NONE`,
		const Passkey_t	passkey = `NULL`,
		bool	signing = `true`
	)		`[virtual]`

Enable the BLE stack's Security Manager.

The Security Manager implements the actual cryptographic algorithms and protocol exchanges that allow two devices to securely exchange data and privately detect each other. Calling this API is a prerequisite for encryption and pairing (bonding).

Parameters:

[in]	enableBonding	Allow for bonding.
[in]	requireMITM	Require protection for man-in-the-middle attacks.
[in]	iocaps	To specify the I/O capabilities of this peripheral, such as availability of a display or keyboard, to support out-of-band exchanges of security data.
[in]	passkey	To specify a static passkey.
[in]	signing	Generate and distribute signing key during pairing

Returns:: BLE_ERROR_NONE on success.

Definition at line 423 of file SecurityManager.h.

virtual ble_error_t legacyPairingOobReceived	(	const ble::address_t *	address,
		const ble::oob_tk_t *	tk
	)		`[virtual]`

Supply the stack with the OOB data for legacy connections.

Parameters:

[in]	address	address of the peer device this data comes from
[in]	tk	pointer to out of band data received containing the temporary key.

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 803 of file SecurityManager.h.

virtual void onLinkSecured ( LinkSecuredCallback_t callback ) [virtual]

To indicate that the link with the peer is secured. For bonded devices, subsequent reconnections with a bonded peer will result only in this callback when the link is secured; setup procedures will not occur (unless the bonding information is either lost or deleted on either or both sides).

Definition at line 973 of file SecurityManager.h.

virtual void onPasskeyDisplay ( PasskeyDisplayCallback_t callback ) [virtual]

To set the callback for when the passkey needs to be displayed on a peripheral with DISPLAY capability.

Definition at line 990 of file SecurityManager.h.

virtual void onSecurityContextStored ( HandleSpecificEvent_t callback ) [virtual]

To indicate that device context is stored persistently.

Definition at line 982 of file SecurityManager.h.

virtual void onSecuritySetupCompleted ( SecuritySetupCompletedCallback_t callback ) [virtual]

To indicate that the security procedure for the link has completed.

Definition at line 961 of file SecurityManager.h.

virtual void onSecuritySetupInitiated ( SecuritySetupInitiatedCallback_t callback ) [virtual]

To indicate that a security procedure for the link has started.

Definition at line 952 of file SecurityManager.h.

void onShutdown ( const SecurityManagerShutdownCallback_t & callback )

Setup a callback to be invoked to notify the user application that the SecurityManager instance is about to shutdown (possibly as a result of a call to BLE::shutdown()).

Note:: It is possible to chain together multiple onShutdown callbacks (potentially from different modules of an application) to be notified before the SecurityManager is shutdown.; It is also possible to set up a callback into a member function of some object.; It is possible to unregister a callback using onShutdown().detach(callback)

Definition at line 862 of file SecurityManager.h.

SecurityManagerShutdownCallbackChain_t& onShutdown ( )

Provide access to the callchain of shutdown event callbacks.

It is possible to register callbacks using onShutdown().add(callback). It is possible to unregister callbacks using onShutdown().detach(callback).

Returns:: The shutdown event callbacks chain

Definition at line 877 of file SecurityManager.h.

virtual ble_error_t oobReceived	(	const ble::address_t *	address,
		const ble::oob_lesc_value_t *	random,
		const ble::oob_confirm_t *	confirm
	)		`[virtual]`

Supply the stack with the OOB data for secure connections.

Parameters:

[in]	address	address of the peer device this data comes from
[in]	random	random number used to generate the confirmation
[in]	confirm	confirmation value to be use for authentication in secure connections pairing

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 818 of file SecurityManager.h.

virtual ble_error_t passkeyEntered	(	ble::connection_handle_t	connectionHandle,
		Passkey_t	passkey
	)		`[virtual]`

Supply the stack with the user entered passkey.

Parameters:

[in]	connectionHandle	Handle to identify the connection.
[in]	passkey	ASCII string of digits entered by the user.

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 776 of file SecurityManager.h.

virtual ble_error_t preserveBondingStateOnReset ( bool enable ) [virtual]

Normally all bonding information is lost when device is reset, this requests that the stack attempts to save the information and reload it during initialisation.

This is not guaranteed.

Parameters:

[in] enable if true the stack will attempt to preserve bonding information on reset.

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 466 of file SecurityManager.h.

void processLinkSecuredEvent	(	ble::connection_handle_t	connectionHandle,
		SecurityMode_t	securityMode
	)

Definition at line 1007 of file SecurityManager.h.

void processPasskeyDisplayEvent	(	ble::connection_handle_t	connectionHandle,
		const Passkey_t	passkey
	)

Definition at line 1021 of file SecurityManager.h.

void processSecurityContextStoredEvent ( ble::connection_handle_t connectionHandle )

Definition at line 1015 of file SecurityManager.h.

void processSecuritySetupCompletedEvent	(	ble::connection_handle_t	connectionHandle,
		SecurityCompletionStatus_t	status
	)

Definition at line 1003 of file SecurityManager.h.

void processSecuritySetupInitiatedEvent	(	ble::connection_handle_t	connectionHandle,
		bool	allowBonding,
		bool	requireMITM,
		SecurityIOCapabilities_t	iocaps
	)

Definition at line 997 of file SecurityManager.h.

virtual ble_error_t purgeAllBondingState ( void ) [virtual]

Delete all peer device context and all related bonding information from the database within the security manager.

Return values:

BLE_ERROR_NONE	On success, else an error code indicating reason for failure.
BLE_ERROR_INVALID_STATE	If the API is called without module initialization or application registration.

Definition at line 485 of file SecurityManager.h.

virtual ble_error_t requestAuthentication ( ble::connection_handle_t connectionHandle ) [virtual]

Request that the link be authenticated (keys with MITM protection).

This might trigger encryption or pairing/re-pairing. The success will be indicated through an event indicating security level change.

Parameters:

[in] connectionHandle Handle to identify the connection.

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 729 of file SecurityManager.h.

virtual ble_error_t requestPairing ( ble::connection_handle_t connectionHandle ) [virtual]

Request pairing with the peer.

Called by the master.

Note:: Slave can call requestAuthentication or setLinkEncryption to achieve security.

Parameters:

[in] connectionHandle Handle to identify the connection.

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 516 of file SecurityManager.h.

virtual ble_error_t reset ( void ) [virtual]

Notify all registered onShutdown callbacks that the SecurityManager is about to be shutdown and clear all SecurityManager state of the associated object.

This function is meant to be overridden in the platform-specific sub-class. Nevertheless, the sub-class is only expected to reset its state and not the data held in SecurityManager members. This shall be achieved by a call to SecurityManager::reset() from the sub-class' reset() implementation.

Returns:: BLE_ERROR_NONE on success.

Definition at line 450 of file SecurityManager.h.

virtual ble_error_t sendKeypressNotification	(	ble::connection_handle_t	connectionHandle,
		Keypress_t	keypress
	)		`[virtual]`

Send a notification to the peer that the user pressed a key on the local device.

Note:: This will only be delivered if the keypress notifications have been enabled during pairing.

Parameters:

[in]	connectionHandle	Handle to identify the connection.
[in]	keypress	Type of keypress event.

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 790 of file SecurityManager.h.

virtual ble_error_t setDisplayPasskey ( const Passkey_t passkey ) [virtual]

Set the passkey that is displayed on the local device instead of using a randomly generated one.

Parameters:

[in] passkey ASCII string of 6 digits

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 610 of file SecurityManager.h.

virtual ble_error_t setEncryptionKeyRequirements	(	uint8_t	minimumByteSize,
		uint8_t	maximumByteSize
	)		`[virtual]`

Set the requirements for encryption key size.

If the peer cannot comply with the requirements paring will fail.

Parameters:

[in]	minimumByteSize	Smallest allowed encryption key size in bytes. (no smaller than 7)
[in]	maximumByteSize	Largest allowed encryption key size in bytes. (no larger than 16)

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 712 of file SecurityManager.h.

virtual ble_error_t setHintFutureRoleReversal ( bool enable = true ) [virtual]

Give a hint to the stack that the master/slave role might change in the future.

Parameters:

[in] enable If set to true it hints the roles are likely to swap in the future.

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 668 of file SecurityManager.h.

virtual ble_error_t setIoCapability ( SecurityIOCapabilities_t iocaps ) [virtual]

Set the IO capability of the local device.

Parameters:

[in] iocaps type of IO capabilities available on the local device

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 598 of file SecurityManager.h.

virtual ble_error_t setKeypressNotification ( bool enabled = true ) [virtual]

Set whether or not we want to send and receive keypress notifications during passkey entry.

Parameters:

[in] enabled if true pairing will try to enable keypress notifications (dependent on other side supporting it)

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 641 of file SecurityManager.h.

virtual ble_error_t setLinkEncryption	(	ble::connection_handle_t	connectionHandle,
		ble::link_encryption_t	encryption
	)		`[virtual]`

Enabled or disable encryption on the link.

The result of this request will be indicated by a call to linkEncryptionResult in the event handler when the action is completed.

Parameters:

[in]	connectionHandle	Handle to identify the connection.
[in]	encryption	encryption state requested

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 698 of file SecurityManager.h.

virtual ble_error_t setLinkSecurity	(	ble::connection_handle_t	connectionHandle,
		SecurityMode_t	securityMode
	)		`[virtual]`

Set the security mode on a connection.

Useful for elevating the security mode once certain conditions are met, e.g., a particular service is found.

Parameters:

[in]	connectionHandle	Handle to identify the connection.
[in]	securityMode	Requested security mode.

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 624 of file SecurityManager.h.

virtual ble_error_t setOOBDataUsage	(	ble::connection_handle_t	connectionHandle,
		bool	useOOB,
		bool	OOBProvidesMITM = `true`
	)		`[virtual]`

Enable OOB data usage during paring.

Parameters:

[in]	connectionHandle	Handle to identify the connection.
[in]	useOOB	If set to true, authenticate using OOB data.
[in]	OOBProvidesMITM	If set to true keys exchanged during pairing using OOB data will provide MITM protection. This indicates that the form of exchange used by the OOB data itself provides MITM protection.

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 748 of file SecurityManager.h.

virtual ble_error_t setPairingRequestAuthorisation ( bool required = true ) [virtual]

Tell the stack whether the application needs to authorise pairing requests or should they be automatically accepted.

Parameters:

[in] required If set to true, pairingRequest in the event handler will will be called and will require an action from the application to continue with pairing by calling acceptPairingRequest or cancelPairingRequest if the user wishes to reject it.

Returns:: BLE_ERROR_NONE or appropriate error code indicating the failure reason.

Definition at line 555 of file SecurityManager.h.

virtual void setSecurityManagerEventHandler ( EventHandler * handler ) [virtual]

Assign the event handler implementation that will be used by the stack to signal events back to the application.

Parameters:

[in] handler Event Handler interface implementation.

Definition at line 887 of file SecurityManager.h.

Field Documentation

const unsigned PASSKEY_LEN = 6 [static]

Declaration of type containing a passkey to be used during pairing.

This is passed into initializeSecurity() to specify a pre-programmed passkey for authentication instead of generating a random one.

Definition at line 221 of file SecurityManager.h.

Type:	Program
Mbed OS support:	Mbed OS
Created:	29 Mar 2018
Imports:	22
Forks:	0
Commits:	5
Dependents:	0
Dependencies:	0
Followers:	6

SecurityManager Class Reference

Data Structures

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Member Function Documentation

Field Documentation

Repository toolbox

Repository details

Important Information for this Arm website

SecurityManager Class Reference

Data Structures

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Member Function Documentation

Field Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning