c7222::SecurityManager Class Reference

Manages BLE security configuration and pairing-related events. More...

#include <security_manager.hpp>

Inheritance diagram for c7222::SecurityManager:

Collaboration diagram for c7222::SecurityManager:

Classes
struct	EventHandler
	Security Manager event callback interface. More...
struct	SecurityParameters
	Cached security configuration parameters. More...

Public Types
enum class	EventId : uint8_t {   kJustWorksRequest , kNumericComparisonRequest , kPasskeyDisplay , kPasskeyInput ,   kPairingComplete , kReencryptionComplete , kAuthorizationRequest , kAuthorizationResult }
	Security-related event identifiers. More...
enum class	IoCapability : uint8_t {   kDisplayOnly , kDisplayYesNo , kKeyboardOnly , kNoInputNoOutput ,   kKeyboardDisplay }
	Local device IO capabilities used during pairing. More...
enum class	AuthenticationRequirement : uint8_t {   kNone = 0 , kBonding = 1u << 0 , kMitmProtection = 1u << 1 , kSecureConnections = 1u << 2 ,   kKeypressNotifications = 1u << 3 }
	Authentication requirement flags. More...
enum class	PairingStatus : uint8_t {   kSuccess = 0x00 , kFailed = 0x01 , kTimeout = 0x02 , kUnsupported = 0x03 ,   kUnknown = 0xFF }
	Pairing outcome classification. More...
enum class	AuthorizationResult : uint8_t { kDenied = 0 , kGranted = 1 }
	Authorization decision. More...
enum class	FixedPasskeyRole : uint8_t { kNone = 0 , kDisplay = 1 , kKeyboard = 2 }
	Role used for fixed passkey configuration. More...
enum class	GattClientSecurityLevel : uint8_t {   kLevel0 = 0 , kLevel1 = 1 , kLevel2 = 2 , kLevel3 = 3 ,   kLevel4 = 4 }
	Required security level for the BTstack GATT client. More...

Public Member Functions
BleError	Configure (const SecurityParameters &params)
	Apply a full configuration object at once.
BleError	SetIoCapability (IoCapability capability)
	Set the local IO capability.
BleError	SetAuthenticationRequirements (AuthenticationRequirement auth)
	Set authentication requirement bitfield.
BleError	SetEncryptionKeySizeRange (uint8_t min_key_size, uint8_t max_key_size)
	Set minimum and maximum encryption key sizes.
BleError	SetBondable (bool bondable)
	Enable or disable bonding.
BleError	SetSecureConnectionsOnly (bool enabled)
	Enable or disable Secure Connections only mode.
BleError	SetGattClientRequiredSecurityLevel (GattClientSecurityLevel level)
	Set required security level for GATT client operations.
BleError	SetFixedPasskeyDisplay (uint32_t passkey)
	Configure fixed passkey for display role.
BleError	SetFixedPasskeyKeyboard (uint32_t passkey)
	Configure fixed passkey for keyboard role.
BleError	ClearFixedPasskey ()
	Clear fixed passkey configuration.
SecurityParameters	GetSecurityParameters () const
	Get the cached security parameters.
bool	IsConfigured () const
	Check whether security has been explicitly configured by the application.
bool	IsApplied () const
	Check whether the configuration has been applied to the platform stack.
bool	ValidateConfiguration (bool authentication_required, bool authorization_required, bool encryption_required) const
	Validate that the current configuration can satisfy requirements.
void	AddEventHandler (const EventHandler &handler)
	Add an event handler (stored as a pointer).
bool	RemoveEventHandler (const EventHandler &handler)
	Remove an event handler.
void	AddEventHandler (const EventHandler *handler)
	Add an event handler pointer (no ownership).
bool	RemoveEventHandler (const EventHandler *handler)
	Remove an event handler pointer.
void	ClearEventHandlers ()
	Remove all registered event handlers.
size_t	GetEventHandlerCount () const
	Get the number of registered event handlers.
BleError	ConfirmJustWorks (ConnectionHandle con_handle)
	Confirm a "Just Works" pairing request.
BleError	ConfirmNumericComparison (ConnectionHandle con_handle, bool accept)
	Accept or reject a numeric comparison pairing request.
BleError	ProvidePasskey (ConnectionHandle con_handle, uint32_t passkey)
	Provide a passkey for keyboard input role.
BleError	RequestPairing (ConnectionHandle con_handle)
	Initiate pairing as a client or server.
BleError	SetAuthorization (ConnectionHandle con_handle, AuthorizationResult result)
	Provide an authorization decision for the given connection.
BleError	DispatchBleHciPacket (uint8_t packet_type, const uint8_t *packet, uint16_t size)
	Dispatch a raw HCI packet into the security event pipeline.
Public Member Functions inherited from c7222::NonCopyable
	NonCopyable (const NonCopyable &)=delete
NonCopyable &	operator= (const NonCopyable &)=delete
	NonCopyable (NonCopyable &&)=default
NonCopyable &	operator= (NonCopyable &&)=default
Public Member Functions inherited from c7222::NonMovable
	NonMovable (const NonMovable &)=default
NonMovable &	operator= (const NonMovable &)=default
	NonMovable (NonMovable &&)=delete
NonMovable &	operator= (NonMovable &&)=delete

Static Public Member Functions
static SecurityManager *	GetInstance ()
	Get the singleton instance.

Additional Inherited Members
Protected Member Functions inherited from c7222::NonCopyableNonMovable
	NonCopyableNonMovable ()=default
	~NonCopyableNonMovable ()=default
Protected Member Functions inherited from c7222::NonCopyable
	NonCopyable ()=default
	~NonCopyable ()=default
Protected Member Functions inherited from c7222::NonMovable
	NonMovable ()=default
	~NonMovable ()=default

Detailed Description

Manages BLE security configuration and pairing-related events.

This class provides a platform-agnostic interface for configuring security requirements before connections are established (IO capabilities, pairing flags, key sizes, and GATT client requirements) and for handling pairing and authorization events at runtime.

---

Responsibilities

• Configuration: Collects security parameters and applies them to the underlying stack (BTstack on Pico W).
• Validation: Ensures the requested security level is achievable for the current IO capability and stack configuration.
• Events: Dispatches pairing prompts and results to registered handlers.
• Responses: Provides APIs to confirm or reject pairing operations.

---

Configuration Workflow

Configure security before enabling the stack or accepting connections:

auto* sm = c7222::SecurityManager::GetInstance();
c7222::SecurityManager::SecurityParameters params;
params.io_capability =
    c7222::SecurityManager::IoCapability::kKeyboardDisplay;
params.authentication =
    c7222::SecurityManager::AuthenticationRequirement::kMitmProtection;
params.min_encryption_key_size = 7;
params.max_encryption_key_size = 16;
sm->Configure(params);

The BLE layer will apply the configuration when SecurityManager is enabled.

---

Event Handling

Implement EventHandler and register it to receive pairing prompts and authorization callbacks. Event payloads are only valid during the call.

---

Validation

Use ValidateConfiguration(authentication_required, authorization_required, encryption_required) to ensure the current configuration can satisfy the security requirements of your GATT database.

---

Typical Usage

class MySmHandler : public c7222::SecurityManager::EventHandler {
 public:
  void OnJustWorksRequest(c7222::ConnectionHandle handle) const override {
    c7222::SecurityManager::GetInstance()->ConfirmJustWorks(handle);
  }
  void OnPasskeyDisplay(c7222::ConnectionHandle, uint32_t passkey) const override {
    printf("Passkey: %u\n", passkey);
  }
};
 
auto* sm = c7222::SecurityManager::GetInstance();
MySmHandler handler;
sm->AddEventHandler(handler);
sm->SetIoCapability(c7222::SecurityManager::IoCapability::kDisplayOnly);
sm->SetAuthenticationRequirements(
    c7222::SecurityManager::AuthenticationRequirement::kMitmProtection);

---

Raspberry Pi Pico (BTstack) Port

The Pico W/RP2040 implementation lives in libs/elec_c7222/ble/security_manager/platform/rpi_pico/. The platform layer applies configuration via BTstack APIs and dispatches SM events to the handlers registered on this class. It also performs platform-specific validation in ValidateConfiguration() based on the BTstack configuration and available key storage backend.

Member Enumeration Documentation

AuthenticationRequirement

enum class c7222::SecurityManager::AuthenticationRequirement : uint8_t

strong

Authentication requirement flags.

These are modeled as a bitfield so they can be combined with |.

Enumerator
kNone	No additional authentication requirements.
kBonding	Enable bonding (store keys for reconnection).
kMitmProtection	Require MITM protection.
kSecureConnections	Require LE Secure Connections.
kKeypressNotifications	Enable keypress notifications (SC only).

AuthorizationResult

enum class c7222::SecurityManager::AuthorizationResult : uint8_t

strong

Authorization decision.

Enumerator
kDenied	Authorization denied.
kGranted	Authorization granted.

EventId

enum class c7222::SecurityManager::EventId : uint8_t

strong

Security-related event identifiers.

Enumerator
kJustWorksRequest	"Just Works" confirmation requested by the stack.
kNumericComparisonRequest	Numeric comparison requested by the stack.
kPasskeyDisplay	Passkey display requested (display role).
kPasskeyInput	Passkey input requested (keyboard role).
kPairingComplete	Pairing complete indication.
kReencryptionComplete	Re-encryption complete indication.
kAuthorizationRequest	Authorization request for an authenticated operation.
kAuthorizationResult	Authorization decision result.

FixedPasskeyRole

enum class c7222::SecurityManager::FixedPasskeyRole : uint8_t

strong

Role used for fixed passkey configuration.

Enumerator
kNone	Fixed passkey not configured.
kDisplay	Device displays a fixed passkey.
kKeyboard	Device inputs a fixed passkey.

GattClientSecurityLevel

enum class c7222::SecurityManager::GattClientSecurityLevel : uint8_t

strong

Required security level for the BTstack GATT client.

This maps to BTstack's gap_security_level_t used by gatt_client_set_required_security_level(level).

Enumerator
kLevel0	No required security.
kLevel1	Encrypted link required.
kLevel2	Authenticated + encrypted link required.
kLevel3	Authorized + authenticated + encrypted link required.
kLevel4	Secure Connections authenticated + encrypted.

IoCapability

enum class c7222::SecurityManager::IoCapability : uint8_t

strong

Local device IO capabilities used during pairing.

Enumerator
kDisplayOnly	Device can only display a passkey.
kDisplayYesNo	Device can display and confirm yes/no.
kKeyboardOnly	Device can only input a passkey.
kNoInputNoOutput	Device has no input and no output.
kKeyboardDisplay	Device can both display and input.

PairingStatus

enum class c7222::SecurityManager::PairingStatus : uint8_t

strong

Pairing outcome classification.

Enumerator
kSuccess	Pairing completed successfully.
kFailed	Pairing failed.
kTimeout	Pairing timed out.
kUnsupported	Pairing not supported by peer or stack.
kUnknown	Unknown or unclassified result.

Member Function Documentation

AddEventHandler() [1/2]

void c7222::SecurityManager::AddEventHandler

(

const EventHandler &

handler

)

Add an event handler (stored as a pointer).

Here is the caller graph for this function:

AddEventHandler() [2/2]

void c7222::SecurityManager::AddEventHandler

(

const EventHandler *

handler

)

Add an event handler pointer (no ownership).

ClearEventHandlers()

void c7222::SecurityManager::ClearEventHandlers

(

)

Remove all registered event handlers.

Here is the caller graph for this function:

ClearFixedPasskey()

BleError c7222::SecurityManager::ClearFixedPasskey

(

)

Clear fixed passkey configuration.

Configure()

BleError c7222::SecurityManager::Configure

(

const SecurityParameters &

params

)

Apply a full configuration object at once.

Marks the SecurityManager as configured; the BLE layer applies the settings to the platform when security is enabled.

Here is the caller graph for this function:

ConfirmJustWorks()

BleError c7222::SecurityManager::ConfirmJustWorks

(

ConnectionHandle

con_handle

)

Confirm a "Just Works" pairing request.

Here is the caller graph for this function:

ConfirmNumericComparison()

BleError c7222::SecurityManager::ConfirmNumericComparison	(	ConnectionHandle	con_handle,
		bool	accept
	)

Accept or reject a numeric comparison pairing request.

Here is the caller graph for this function:

DispatchBleHciPacket()

BleError c7222::SecurityManager::DispatchBleHciPacket	(	uint8_t	packet_type,
		const uint8_t *	packet,
		uint16_t	size
	)

Dispatch a raw HCI packet into the security event pipeline.

GetEventHandlerCount()

size_t c7222::SecurityManager::GetEventHandlerCount ( ) const

inline

Get the number of registered event handlers.

GetInstance()

static SecurityManager * c7222::SecurityManager::GetInstance ( )

static

Get the singleton instance.

GetSecurityParameters()

SecurityParameters c7222::SecurityManager::GetSecurityParameters ( ) const

inline

Get the cached security parameters.

IsApplied()

bool c7222::SecurityManager::IsApplied ( ) const

inline

Check whether the configuration has been applied to the platform stack.

This becomes true after a successful ApplyConfiguration() call.

IsConfigured()

bool c7222::SecurityManager::IsConfigured ( ) const

inline

Check whether security has been explicitly configured by the application.

This becomes true after any configuration setter (or Configure()) is called.

ProvidePasskey()

BleError c7222::SecurityManager::ProvidePasskey	(	ConnectionHandle	con_handle,
		uint32_t	passkey
	)

Provide a passkey for keyboard input role.

Here is the caller graph for this function:

RemoveEventHandler() [1/2]

bool c7222::SecurityManager::RemoveEventHandler

(

const EventHandler &

handler

)

Remove an event handler.

Here is the caller graph for this function:

RemoveEventHandler() [2/2]

bool c7222::SecurityManager::RemoveEventHandler

(

const EventHandler *

handler

)

Remove an event handler pointer.

RequestPairing()

BleError c7222::SecurityManager::RequestPairing

(

ConnectionHandle

con_handle

)

Initiate pairing as a client or server.

Here is the caller graph for this function:

SetAuthenticationRequirements()

BleError c7222::SecurityManager::SetAuthenticationRequirements

(

AuthenticationRequirement

auth

)

Set authentication requirement bitfield.

Here is the caller graph for this function:

SetAuthorization()

BleError c7222::SecurityManager::SetAuthorization	(	ConnectionHandle	con_handle,
		AuthorizationResult	result
	)

Provide an authorization decision for the given connection.

Here is the caller graph for this function:

SetBondable()

BleError c7222::SecurityManager::SetBondable

(

bool

bondable

)

Enable or disable bonding.

Here is the caller graph for this function:

SetEncryptionKeySizeRange()

BleError c7222::SecurityManager::SetEncryptionKeySizeRange	(	uint8_t	min_key_size,
		uint8_t	max_key_size
	)

Set minimum and maximum encryption key sizes.

Here is the caller graph for this function:

SetFixedPasskeyDisplay()

BleError c7222::SecurityManager::SetFixedPasskeyDisplay

(

uint32_t

passkey

)

Configure fixed passkey for display role.

SetFixedPasskeyKeyboard()

BleError c7222::SecurityManager::SetFixedPasskeyKeyboard

(

uint32_t

passkey

)

Configure fixed passkey for keyboard role.

SetGattClientRequiredSecurityLevel()

BleError c7222::SecurityManager::SetGattClientRequiredSecurityLevel

(

GattClientSecurityLevel

level

)

Set required security level for GATT client operations.

SetIoCapability()

BleError c7222::SecurityManager::SetIoCapability

(

IoCapability

capability

)

Set the local IO capability.

Here is the caller graph for this function:

SetSecureConnectionsOnly()

BleError c7222::SecurityManager::SetSecureConnectionsOnly

(

bool

enabled

)

Enable or disable Secure Connections only mode.

Here is the caller graph for this function:

ValidateConfiguration()

bool c7222::SecurityManager::ValidateConfiguration	(	bool	authentication_required,
		bool	authorization_required,
		bool	encryption_required
	)		const

Validate that the current configuration can satisfy requirements.

This check is platform-dependent and should be called before enabling BLE when the GATT database requires specific security guarantees.

---

The documentation for this class was generated from the following file:

• libs/elec_c7222/ble/security_manager/include/security_manager.hpp