Adaptation layer of the Security Manager. More...

#include <PalSecurityManager.h>

Inherits NonCopyable< SecurityManager< Impl, EventHandler > >.

Public Member Functions
ble_error_t	initialize ()
	Initialise stack.
ble_error_t	terminate ()
	Finalise all actions.
ble_error_t	reset ()
	Reset to same state as after initialize.
uint8_t	read_resolving_list_capacity ()
	Return the number of address translation entries that can be stored by the subsystem.
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)
	Add a device definition into the resolving list of the LE subsystem.
ble_error_t	remove_device_from_resolving_list (advertising_peer_address_type_t peer_identity_address_type, const address_t &peer_identity_address)
	Add a device definition from the resolving list of the LE subsystem.
ble_error_t	clear_resolving_list ()
	Remove all devices from the resolving list.
ble_error_t	send_pairing_request (connection_handle_t connection, bool oob_data_flag, AuthenticationMask authentication_requirements, KeyDistribution initiator_dist, KeyDistribution responder_dist)
	Send a pairing request to a slave.
ble_error_t	send_pairing_response (connection_handle_t connection, bool oob_data_flag, AuthenticationMask authentication_requirements, KeyDistribution initiator_dist, KeyDistribution responder_dist)
	Send a pairing response to a master.
ble_error_t	cancel_pairing (connection_handle_t connection, pairing_failure_t reason)
	Cancel an ongoing pairing.
ble_error_t	get_secure_connections_support (bool &enabled)
	Check if the Secure Connections feature is supported by the stack and controller.
ble_error_t	set_io_capability (io_capability_t io_capability)
	Set the IO capability that will be used during pairing feature exchange.
ble_error_t	set_authentication_timeout (connection_handle_t connection, uint16_t timeout_in_10ms)
	Set the time after which an event will be generated unless we received a packet with a valid MIC.
ble_error_t	get_authentication_timeout (connection_handle_t connection, uint16_t &timeout_in_10ms)
	Get the time after which an event will be generated unless we received a packet with a valid MIC.
ble_error_t	set_encryption_key_requirements (uint8_t min_encryption_key_size, uint8_t max_encryption_key_size)
	Set the key size boundaries that will be used during pairing feature exchange.
ble_error_t	slave_security_request (connection_handle_t connection, AuthenticationMask authentication)
	Request change of security level from the master.
ble_error_t	enable_encryption (connection_handle_t connection, const ltk_t &ltk, const rand_t &rand, const ediv_t &ediv, bool mitm)
	Enabled encryption using the LTK given.
ble_error_t	enable_encryption (connection_handle_t connection, const ltk_t &ltk, bool mitm)
	Enabled encryption using the LTK given on a connection established with secure connections pairing.
ble_error_t	encrypt_data (const byte_array_t< 16 > &key, encryption_block_t &data)
	Encrypt data with a given key.
ble_error_t	set_ltk (connection_handle_t connection, const ltk_t &ltk, bool mitm, bool secure_connections)
	Set the LTK that is to be used for encryption.
ble_error_t	set_ltk_not_found (connection_handle_t connection)
	Inform the stack we don't have the LTK.
ble_error_t	set_irk (const irk_t &irk)
	Set the local IRK.
ble_error_t	set_csrk (const csrk_t &csrk, sign_count_t sign_counter)
	Set the local CSRK.
ble_error_t	set_peer_csrk (connection_handle_t connection, const csrk_t &csrk, bool authenticated, sign_count_t sign_counter)
	Set the peer CSRK for particular connection.
ble_error_t	get_random_data (byte_array_t< 8 > &random_data)
	Generate and return 8 octets of random data compliant with [FIPS PUB 140-2].
ble_error_t	set_display_passkey (passkey_num_t passkey)
	Set the default passkey that will be used when the SM needs a passkey to be displayed.
ble_error_t	passkey_request_reply (connection_handle_t connection, passkey_num_t passkey)
	Reply to a passkey request received from the SecurityManagerEventHandler.
ble_error_t	secure_connections_oob_request_reply (connection_handle_t connection, const oob_lesc_value_t &local_random, const oob_lesc_value_t &peer_random, const oob_confirm_t &peer_confirm)
	Reply to a Secure Connections oob data request received from the SecurityManagerEventHandler.
ble_error_t	legacy_pairing_oob_request_reply (connection_handle_t connection, const oob_tk_t &oob_data)
	Reply to a legacy pairing oob data request received from the SecurityManagerEventHandler.
ble_error_t	confirmation_entered (connection_handle_t connection, bool confirmation)
	Notify the stack that the user has confirmed the values during numerical comparison stage of pairing.
ble_error_t	send_keypress_notification (connection_handle_t connection, Keypress_t keypress)
	Notify the stack that the user pressed a key.
ble_error_t	generate_secure_connections_oob ()
	Generate local OOB data to be sent to the application which sends it to the peer.
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

template<class Impl, class EventHandler>
class ble::pal::SecurityManager< Impl, EventHandler >

Adaptation layer of the Security Manager.

Definition at line 600 of file PalSecurityManager.h.

Member Function Documentation

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
	)

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

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

Definition at line 667 of file PalSecurityManager.h.

ble_error_t cancel_pairing	(	connection_handle_t	connection,
		pairing_failure_t	reason
	)

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

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

Definition at line 773 of file PalSecurityManager.h.

ble_error_t clear_resolving_list ( )

Remove all devices from the resolving list.

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

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

Definition at line 703 of file PalSecurityManager.h.

ble_error_t confirmation_entered	(	connection_handle_t	connection,
		bool	confirmation
	)

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

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

Definition at line 1164 of file PalSecurityManager.h.

ble_error_t enable_encryption	(	connection_handle_t	connection,
		const ltk_t &	ltk,
		const rand_t &	rand,
		const ediv_t &	ediv,
		bool	mitm
	)

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

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

Definition at line 910 of file PalSecurityManager.h.

ble_error_t enable_encryption	(	connection_handle_t	connection,
		const ltk_t &	ltk,
		bool	mitm
	)

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

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

Definition at line 935 of file PalSecurityManager.h.

ble_error_t encrypt_data	(	const byte_array_t< 16 > &	key,
		encryption_block_t &	data
	)

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

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

Definition at line 955 of file PalSecurityManager.h.

ble_error_t generate_secure_connections_oob ( )

Generate local OOB data to be sent to the application which sends it to the peer.

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

Definition at line 1190 of file PalSecurityManager.h.

ble_error_t get_authentication_timeout	(	connection_handle_t	connection,
		uint16_t &	timeout_in_10ms
	)

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

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

Definition at line 841 of file PalSecurityManager.h.

ble_error_t get_random_data ( byte_array_t< 8 > & random_data )

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

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

Definition at line 1070 of file PalSecurityManager.h.

ble_error_t get_secure_connections_support ( bool & enabled )

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 On success, else an error code indicating reason for failure

Definition at line 793 of file PalSecurityManager.h.

ble_error_t initialize ( )

Initialise stack.

Called before first use.

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

Definition at line 620 of file PalSecurityManager.h.

ble_error_t legacy_pairing_oob_request_reply	(	connection_handle_t	connection,
		const oob_tk_t &	oob_data
	)

Reply to a legacy pairing oob data request received from the SecurityManagerEventHandler.

Parameters:

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

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

Definition at line 1149 of file PalSecurityManager.h.

ble_error_t passkey_request_reply	(	connection_handle_t	connection,
		passkey_num_t	passkey
	)

Reply to a passkey request received from the SecurityManagerEventHandler.

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

Definition at line 1111 of file PalSecurityManager.h.

uint8_t read_resolving_list_capacity ( )

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

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

Definition at line 654 of file PalSecurityManager.h.

ble_error_t remove_device_from_resolving_list	(	advertising_peer_address_type_t	peer_identity_address_type,
		const address_t &	peer_identity_address
	)

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

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

Definition at line 687 of file PalSecurityManager.h.

ble_error_t reset ( void )

Reset to same state as after initialize.

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

Definition at line 638 of file PalSecurityManager.h.

ble_error_t secure_connections_oob_request_reply	(	connection_handle_t	connection,
		const oob_lesc_value_t &	local_random,
		const oob_lesc_value_t &	peer_random,
		const oob_confirm_t &	peer_confirm
	)

Reply to a Secure Connections oob data request received from the SecurityManagerEventHandler.

Parameters:

[in]	connection	connection handle
[in]	local_random	local random number used for the last oob exchange
[in]	peer_random	random number used to generate the confirmation on peer
[in]	peer_confirm	confirmation value to be use for authentication in secure connections pairing

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

Definition at line 1128 of file PalSecurityManager.h.

ble_error_t send_keypress_notification	(	connection_handle_t	connection,
		Keypress_t	keypress
	)

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

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

Definition at line 1179 of file PalSecurityManager.h.

ble_error_t send_pairing_request	(	connection_handle_t	connection,
		bool	oob_data_flag,
		AuthenticationMask	authentication_requirements,
		KeyDistribution	initiator_dist,
		KeyDistribution	responder_dist
	)

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

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

Definition at line 722 of file PalSecurityManager.h.

ble_error_t send_pairing_response	(	connection_handle_t	connection,
		bool	oob_data_flag,
		AuthenticationMask	authentication_requirements,
		KeyDistribution	initiator_dist,
		KeyDistribution	responder_dist
	)

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

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

Definition at line 749 of file PalSecurityManager.h.

ble_error_t set_authentication_timeout	(	connection_handle_t	connection,
		uint16_t	timeout_in_10ms
	)

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

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

Definition at line 823 of file PalSecurityManager.h.

ble_error_t set_csrk	(	const csrk_t &	csrk,
		sign_count_t	sign_counter
	)

Set the local CSRK.

Parameters:

[in]	csrk	local signing key
[in]	sign_counter	local signing counter

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

Definition at line 1025 of file PalSecurityManager.h.

ble_error_t set_display_passkey ( passkey_num_t passkey )

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.

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

Definition at line 1100 of file PalSecurityManager.h.

ble_error_t set_encryption_key_requirements	(	uint8_t	min_encryption_key_size,
		uint8_t	max_encryption_key_size
	)

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].

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

Definition at line 864 of file PalSecurityManager.h.

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 1203 of file PalSecurityManager.h.

ble_error_t set_io_capability ( io_capability_t io_capability )

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

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

Definition at line 805 of file PalSecurityManager.h.

ble_error_t set_irk ( const irk_t & irk )

Set the local IRK.

Parameters:

[in] irk identity resolution key

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

Definition at line 1012 of file PalSecurityManager.h.

ble_error_t set_ltk	(	connection_handle_t	connection,
		const ltk_t &	ltk,
		bool	mitm,
		bool	secure_connections
	)

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

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

Definition at line 985 of file PalSecurityManager.h.

ble_error_t set_ltk_not_found ( connection_handle_t connection )

Inform the stack we don't have the LTK.

Parameters:

[in] connection connection handle

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

Definition at line 1000 of file PalSecurityManager.h.

ble_error_t set_peer_csrk	(	connection_handle_t	connection,
		const csrk_t &	csrk,
		bool	authenticated,
		sign_count_t	sign_counter
	)

Set the peer CSRK for particular connection.

Parameters:

[in]	connection	connection handle
[in]	csrk	signing key
[in]	authenticated	is the CSRK authenticated
[in]	sign_counter	signing counter

Return values:

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

Definition at line 1041 of file PalSecurityManager.h.

ble_error_t slave_security_request	(	connection_handle_t	connection,
		AuthenticationMask	authentication
	)

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

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

Definition at line 884 of file PalSecurityManager.h.

ble_error_t terminate ( )

Finalise all actions.

Called before shutdown.

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

Definition at line 629 of file PalSecurityManager.h.

Type:	Library
Created:	17 Dec 2019
Imports:	79
Forks:	0
Commits:	2
Dependents:	2
Dependencies:	0
Followers:	1

Important changes to repositories hosted on mbed.com

SecurityManager< Impl, EventHandler > Class Template Reference

Public Member Functions

Private Member Functions

Detailed Description

template<class Impl, class EventHandler>
class ble::pal::SecurityManager< Impl, EventHandler >

Member Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

SecurityManager< Impl, EventHandler > Class Template Reference

Public Member Functions

Private Member Functions

Detailed Description

template<class Impl, class EventHandler> class ble::pal::SecurityManager< Impl, EventHandler >

Member Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning

template<class Impl, class EventHandler>
class ble::pal::SecurityManager< Impl, EventHandler >