Adaptation layer of the Security Manager. More...

#include <PalSecurityManager.h>

Inherits NonCopyable< SecurityManager >.

Data Structures
class	EventHandler
	Handle events generated by ble::pal::SecurityManager. More...
Public Member Functions
virtual ble_error_t	initialize ()=0
	Initialise stack.
virtual ble_error_t	terminate ()=0
	Finalise all actions.
virtual ble_error_t	reset ()=0
	Reset to same state as after initialize.
virtual uint8_t	read_resolving_list_capacity ()=0
	Return the number of address translation entries that can be stored by the subsystem.
virtual ble_error_t	add_device_to_resolving_list (advertising_peer_address_type_t peer_identity_address_type, const address_t &peer_identity_address, const irk_t &peer_irk)=0
	Add a device definition into the resolving list of the LE subsystem.
virtual ble_error_t	remove_device_from_resolving_list (advertising_peer_address_type_t peer_identity_address_type, const address_t &peer_identity_address)=0
	Add a device definition from the resolving list of the LE subsystem.
virtual ble_error_t	clear_resolving_list ()=0
	Remove all devices from the resolving list.
virtual ble_error_t	send_pairing_request (connection_handle_t connection, bool oob_data_flag, AuthenticationMask authentication_requirements, KeyDistribution initiator_dist, KeyDistribution responder_dist)=0
	Send a pairing request to a slave.
virtual ble_error_t	send_pairing_response (connection_handle_t connection, bool oob_data_flag, AuthenticationMask authentication_requirements, KeyDistribution initiator_dist, KeyDistribution responder_dist)=0
	Send a pairing response to a master.
virtual ble_error_t	cancel_pairing (connection_handle_t connection, pairing_failure_t reason)=0
	Cancel an ongoing pairing.
virtual ble_error_t	get_secure_connections_support (bool &enabled)=0
	Check if the Secure Connections feature is supported by the stack and controller.
virtual ble_error_t	set_io_capability (io_capability_t io_capability)=0
	Set the IO capability that will be used during pairing feature exchange.
virtual ble_error_t	set_authentication_timeout (connection_handle_t connection, uint16_t timeout_in_10ms)=0
	Set the time after which an event will be generated unless we received a packet with a valid MIC.
virtual ble_error_t	get_authentication_timeout (connection_handle_t connection, uint16_t &timeout_in_10ms)=0
	Get the time after which an event will be generated unless we received a packet with a valid MIC.
virtual ble_error_t	set_encryption_key_requirements (uint8_t min_encryption_key_size, uint8_t max_encryption_key_size)=0
	Set the key size boundaries that will be used during pairing feature exchange.
virtual ble_error_t	slave_security_request (connection_handle_t connection, AuthenticationMask authentication)=0
	Request change of security level from the master.
virtual ble_error_t	enable_encryption (connection_handle_t connection, const ltk_t &ltk, const rand_t &rand, const ediv_t &ediv, bool mitm)=0
	Enabled encryption using the LTK given.
virtual ble_error_t	enable_encryption (connection_handle_t connection, const ltk_t &ltk, bool mitm)=0
	Enabled encryption using the LTK given on a connection established with secure connections pairing.
virtual ble_error_t	encrypt_data (const byte_array_t< 16 > &key, encryption_block_t &data)=0
	Encrypt data with a given key.
virtual ble_error_t	set_ltk (connection_handle_t connection, const ltk_t &ltk, bool mitm, bool secure_connections)=0
	Set the LTK that is to be used for encryption.
virtual ble_error_t	set_ltk_not_found (connection_handle_t connection)=0
	Inform the stack we don't have the LTK.
virtual ble_error_t	set_irk (const irk_t &irk)=0
	Set the local IRK.
virtual ble_error_t	set_csrk (const csrk_t &csrk)=0
	Set the local CSRK.
virtual ble_error_t	generate_public_key ()=0
	Generate the Public key.
virtual ble_error_t	get_random_data (byte_array_t< 8 > &random_data)=0
	Generate and return 8 octets of random data compliant with [FIPS PUB 140-2].
virtual ble_error_t	set_display_passkey (passkey_num_t passkey)=0
	Set the default passkey that will be used when the SM needs a passkey to be displayed.
virtual ble_error_t	passkey_request_reply (connection_handle_t connection, passkey_num_t passkey)=0
	Reply to a passkey request received from the SecurityManagerEventHandler.
virtual ble_error_t	legacy_pairing_oob_data_request_reply (connection_handle_t connection, const oob_tk_t &oob_data)=0
	Reply to an oob data request received from the SecurityManagerEventHandler.
virtual ble_error_t	confirmation_entered (connection_handle_t connection, bool confirmation)=0
	Notify the stack that the user has confirmed the values during numerical comparison stage of pairing.
virtual ble_error_t	send_keypress_notification (connection_handle_t connection, Keypress_t keypress)=0
	Notify the stack that the user pressed a key.
virtual ble_error_t	oob_data_verified (connection_handle_t connection, const oob_lesc_value_t &local_random, const oob_lesc_value_t &peer_random)=0
	Notify the stack that the OOB data has been verified and supply the peer's random number.
void	set_event_handler (EventHandler *event_handler)
	Sets the event handler that us called by the PAL porters to notify the stack of events which will in turn be passed onto the user application when appropriate.
Private Member Functions
	MBED_DEPRECATED ("Invalid copy construction of a NonCopyable resource.") NonCopyable(const NonCopyable &)
	NonCopyable copy constructor.
	MBED_DEPRECATED ("Invalid copy assignment of a NonCopyable resource.") NonCopyable &operator
	NonCopyable copy assignment operator.

Detailed Description

Adaptation layer of the Security Manager.

Definition at line 207 of file PalSecurityManager.h.

Member Function Documentation

virtual ble_error_t add_device_to_resolving_list	(	advertising_peer_address_type_t	peer_identity_address_type,
		const address_t &	peer_identity_address,
		const irk_t &	peer_irk
	)		`[pure virtual]`

Add a device definition into the resolving list of the LE subsystem.

Parameters:

[in]	peer_identity_address_type	public/private indicator
[in]	peer_identity_address	address of the device whose entry is to be added
[in]	peer_irk	peer identity resolving key

See also:: BLUETOOTH SPECIFICATION Version 5.0 | Vol 2, Part E: 7.8.38

Return values:

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

virtual ble_error_t cancel_pairing	(	connection_handle_t	connection,
		pairing_failure_t	reason
	)		`[pure virtual]`

Cancel an ongoing pairing.

Parameters:

[in]	connection	connection handle
[in]	reason	pairing failure error

See also:: BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part H - 3.5.5

Return values:

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

virtual ble_error_t clear_resolving_list ( ) [pure virtual]

Remove all devices from the resolving list.

See also:: BLUETOOTH SPECIFICATION Version 5.0 | Vol 2, Part E: 7.8.40

Return values:

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

virtual ble_error_t confirmation_entered	(	connection_handle_t	connection,
		bool	confirmation
	)		`[pure virtual]`

Notify the stack that the user has confirmed the values during numerical comparison stage of pairing.

Parameters:

[in]	connection	connection handle
[in]	confirmation	true if the user indicated the numbers match

Return values:

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

virtual ble_error_t enable_encryption	(	connection_handle_t	connection,
		const ltk_t &	ltk,
		const rand_t &	rand,
		const ediv_t &	ediv,
		bool	mitm
	)		`[pure virtual]`

Enabled encryption using the LTK given.

The EDIV and RAND will be sent to the peer and used to identify the LTK. This is called by the master. This will refresh the key if enabled on an already encrypted link.

Parameters:

[in]	connection	connection handle
[in]	ltk	long term key from the peer
[in]	ediv	encryption diversifier from the peer
[in]	rand	random value from the peer
[in]	mitm	does the LTK have man in the middle protection

Return values:

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

virtual ble_error_t enable_encryption	(	connection_handle_t	connection,
		const ltk_t &	ltk,
		bool	mitm
	)		`[pure virtual]`

Enabled encryption using the LTK given on a connection established with secure connections pairing.

Parameters:

[in]	connection	connection handle
[in]	ltk	long term key from the peer
[in]	mitm	does the LTK have man in the middle protection

Return values:

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

virtual ble_error_t encrypt_data	(	const byte_array_t< 16 > &	key,
		encryption_block_t &	data
	)		`[pure virtual]`

Encrypt data with a given key.

This uses the facility on the controller to perform the encryption.

Parameters:

[in]	key	encryption key
[in,out]	data	data to be encrypted, if successful contains the result

Return values:

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

virtual ble_error_t generate_public_key ( ) [pure virtual]

Generate the Public key.

This will also generate the private key. Public key will be returned as an event handler callback when it's ready.

Return values:

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

virtual ble_error_t get_authentication_timeout	(	connection_handle_t	connection,
		uint16_t &	timeout_in_10ms
	)		`[pure virtual]`

Get the time after which an event will be generated unless we received a packet with a valid MIC.

Parameters:

[in]	connection	connection handle
[out]	timeout_in_10ms	time measured in units of 10 milliseconds

Return values:

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

virtual ble_error_t get_random_data ( byte_array_t< 8 > & random_data ) [pure virtual]

Generate and return 8 octets of random data compliant with [FIPS PUB 140-2].

Parameters:

[out] random_data returns 8 octets of random data

See also:: BLUETOOTH SPECIFICATION Version 5.0 | Vol 2, Part H 2

Return values:

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

virtual ble_error_t get_secure_connections_support ( bool & enabled ) [pure virtual]

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

Parameters:

[out] enabled true if SC are supported

Return values:

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

virtual ble_error_t initialize ( ) [pure virtual]

Initialise stack.

Called before first use.

Return values:

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

virtual ble_error_t legacy_pairing_oob_data_request_reply	(	connection_handle_t	connection,
		const oob_tk_t &	oob_data
	)		`[pure virtual]`

Reply to an oob data request received from the SecurityManagerEventHandler.

Parameters:

[in]	connection	connection handle
[in]	oob_data	pointer to out of band data

Return values:

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

virtual ble_error_t oob_data_verified	(	connection_handle_t	connection,
		const oob_lesc_value_t &	local_random,
		const oob_lesc_value_t &	peer_random
	)		`[pure virtual]`

Notify the stack that the OOB data has been verified and supply the peer's random number.

If the verification failed this will not be called and cancel_pairing will be called instead.

Parameters:

[in]	connection	connection handle
[in]	local_random	random number sent from the local device to be used in further calculations by the stack, set to 0 if peer reported no OOB present
[in]	peer_random	random number from the peer to be used in further calculations by the stack, set to 0 if no OOB data received

Return values:

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

virtual ble_error_t passkey_request_reply	(	connection_handle_t	connection,
		passkey_num_t	passkey
	)		`[pure virtual]`

Reply to a passkey request received from the SecurityManagerEventHandler.

Return values:

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

virtual uint8_t read_resolving_list_capacity ( ) [pure virtual]

Return the number of address translation entries that can be stored by the subsystem.

Warning:: : The number of entries is considered fixed.

See also:: BLUETOOTH SPECIFICATION Version 5.0 | Vol 2, Part E: 7.8.41

Return values:

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

virtual ble_error_t remove_device_from_resolving_list	(	advertising_peer_address_type_t	peer_identity_address_type,
		const address_t &	peer_identity_address
	)		`[pure virtual]`

Add a device definition from the resolving list of the LE subsystem.

Parameters:

[in]	peer_identity_address_type	public/private indicator
[in]	peer_identity_address	address of the device whose entry is to be removed

See also:: BLUETOOTH SPECIFICATION Version 5.0 | Vol 2, Part E: 7.8.39

Return values:

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

virtual ble_error_t reset ( ) [pure virtual]

Reset to same state as after initialize.

Return values:

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

virtual ble_error_t send_keypress_notification	(	connection_handle_t	connection,
		Keypress_t	keypress
	)		`[pure virtual]`

Notify the stack that the user pressed a key.

This will be sent to the peer and create an appropriate event there if the keypress protocol is enabled.

Parameters:

[in]	connection	connection handle
[in]	keypress	type of keypress event

Return values:

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

virtual ble_error_t send_pairing_request	(	connection_handle_t	connection,
		bool	oob_data_flag,
		AuthenticationMask	authentication_requirements,
		KeyDistribution	initiator_dist,
		KeyDistribution	responder_dist
	)		`[pure virtual]`

Send a pairing request to a slave.

Parameters:

[in]	connection	connection handle
[in]	oob_data_flag	is oob data present
[in]	authentication_requirements	authentication requirements
[in]	initiator_dist	key distribution
[in]	responder_dist	key distribution

See also:: BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part H - 3.5.1

Return values:

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

virtual ble_error_t send_pairing_response	(	connection_handle_t	connection,
		bool	oob_data_flag,
		AuthenticationMask	authentication_requirements,
		KeyDistribution	initiator_dist,
		KeyDistribution	responder_dist
	)		`[pure virtual]`

Send a pairing response to a master.

See also:: BLUETOOTH SPECIFICATION Version 5.0 | Vol 3, Part H - 3.5.2*

Parameters:

[in]	connection	connection handle
[in]	oob_data_flag	is oob data present
[in]	authentication_requirements	authentication requirements
[in]	initiator_dist	key distribution
[in]	responder_dist	key distribution

Return values:

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

virtual ble_error_t set_authentication_timeout	(	connection_handle_t	connection,
		uint16_t	timeout_in_10ms
	)		`[pure virtual]`

Set the time after which an event will be generated unless we received a packet with a valid MIC.

Parameters:

[in]	connection	connection handle
[in]	timeout_in_10ms	time measured in units of 10 milliseconds

Return values:

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

virtual ble_error_t set_csrk ( const csrk_t & csrk ) [pure virtual]

Set the local CSRK.

Parameters:

[in] csrk signing key

Return values:

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

virtual ble_error_t set_display_passkey ( passkey_num_t passkey ) [pure virtual]

Set the default passkey that will be used when the SM needs a passkey to be displayed.

By default, the pal security manager generates a random passkey when a passkey has to be displayed by the application. A call to this function with a valid passkey alter this behaviour and the SecurityManager shall pass the passkey set into SecurityManagerEvent::on_passkey_display .

A call to this function with a zero value will reset the behaviour and indicates to the security manager that passkeys passed to SecurityManagerEvent::on_passkey_display shall be randomly generated.

Parameters:

[in] passkey Set the passkey that shall be used by the security manager when SecurityManagerEvent::on_passkey_display is called. If passkey is set to 0 then the security manager generates a random passkey every time it calls SecurityManagerEvent::on_passkey_display.

Return values:

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

virtual ble_error_t set_encryption_key_requirements	(	uint8_t	min_encryption_key_size,
		uint8_t	max_encryption_key_size
	)		`[pure virtual]`

Set the key size boundaries that will be used during pairing feature exchange.

Parameters:

[in]	min_encryption_key_size	The minimum encryption key size in bytes required for pairing. This value shall be in the range [7 : 16].
[in]	max_encryption_key_size	The maximum encryption key size in bytes required for pairing. This value shall be in the range [min_encryption_key_size : 16].

Return values:

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

void set_event_handler ( EventHandler * event_handler )

Sets the event handler that us called by the PAL porters to notify the stack of events which will in turn be passed onto the user application when appropriate.

Parameters:

[in] event_handler the new event handler interface implementation. Memory owned by caller who is responsible for updating this pointer if interface changes.

Definition at line 991 of file PalSecurityManager.h.

virtual ble_error_t set_io_capability ( io_capability_t io_capability ) [pure virtual]

Set the IO capability that will be used during pairing feature exchange.

Parameters:

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

Return values:

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

virtual ble_error_t set_irk ( const irk_t & irk ) [pure virtual]

Set the local IRK.

Parameters:

[in] irk identity resolution key

Return values:

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

virtual ble_error_t set_ltk	(	connection_handle_t	connection,
		const ltk_t &	ltk,
		bool	mitm,
		bool	secure_connections
	)		`[pure virtual]`

Set the LTK that is to be used for encryption.

Parameters:

[in]	connection	connection handle
[in]	ltk	long term key
[in]	mitm	does the LTK have man in the middle protection
[in]	secure_connections	is this a secure_connections pairing

Return values:

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

virtual ble_error_t set_ltk_not_found ( connection_handle_t connection ) [pure virtual]

Inform the stack we don't have the LTK.

Parameters:

[in] connection connection handle

Return values:

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

virtual ble_error_t slave_security_request	(	connection_handle_t	connection,
		AuthenticationMask	authentication
	)		`[pure virtual]`

Request change of security level from the master.

This is called by the slave when it needs to elevate the security level as it can't change it itself. This will be received by the master who will take the decision about what action to take (encryption, pairing, re-paring).

Parameters:

[in]	connection	connection handle
[in]	authentication	authentication requirements

Return values:

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

virtual ble_error_t terminate ( ) [pure virtual]

Finalise all actions.

Called before shutdown.

Return values:

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

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

Important changes to repositories hosted on mbed.com

SecurityManager Class Reference

Data Structures

Public Member Functions

Private Member Functions

Detailed Description

Member Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

SecurityManager Class Reference

Data Structures

Public Member Functions

Private Member Functions

Detailed Description

Member Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning