blatann.gap.smp module¶

class blatann.gap.smp.SecurityLevel(value)¶

Bases: Enum

Security levels used for defining GATT server characteristics

NO_ACCESS = 0¶

OPEN = 1¶

JUST_WORKS = 2¶

MITM = 3¶

LESC_MITM = 4¶

class blatann.gap.smp.PairingPolicy(value)¶

Bases: IntFlag

An enumeration.

allow_all = 0¶

reject_new_pairing_requests = 1¶

reject_nonbonded_peripheral_requests = 2¶

reject_bonded_peripheral_requests = 4¶

reject_bonded_device_repairing_requests = 8¶

reject_peripheral_requests = 6¶

reject_all_requests = 15¶

static combine(*policies)¶

class blatann.gap.smp.SecurityParameters(passcode_pairing=False, io_capabilities=BLEGapIoCaps.KEYBOARD_DISPLAY, bond=False, out_of_band=False, reject_pairing_requests=False, lesc_pairing=False)¶

Bases: object

Class representing the desired security parameters for a given connection

class blatann.gap.smp.SecurityManager(ble_device, peer, security_parameters)¶

Bases: object

Handles performing security procedures with a connected peer

property on_pairing_complete: Event[Peer, PairingCompleteEventArgs]¶

Event that is triggered when pairing completes with the peer

Returns: an Event which can have handlers registered to and deregistered from

property on_security_level_changed: Event[Peer, SecurityLevelChangedEventArgs]¶

Event that is triggered when the security/encryption level changes. This can be triggered from a pairing sequence or if a bonded client starts the encryption handshaking using the stored LTKs.

Note: This event is triggered before on_pairing_complete

Returns: an Event which can have handlers registered to and deregestestered from

property on_passkey_display_required: Event[Peer, PasskeyDisplayEventArgs]¶

Event that is triggered when a passkey needs to be displayed to the user and depending on the pairing mode the user must confirm that keys match (PasskeyDisplayEventArgs.match_request == True).

Note

If multiple handlers are registered to this event, the first handler which resolves the match confirmation will set the response. All others will be ignored.

Returns: an Event which can have handlers registered to and deregistered from
Return type: Event

property on_passkey_required: Event[Peer, PasskeyEntryEventArgs]¶

Event that is triggered when a passkey needs to be entered by the user

Note

If multiple handlers are registered to this event, the first handler which resolves the passkey will set the value. All others will be ignored.

Returns: an Event which can have handlers registered to and deregistered from

property on_peripheral_security_request: Event[Peer, PeripheralSecurityRequestEventArgs]¶

Event that is triggered when the connected peripheral explicitly requests pairing/encryption to be enabled. The event provides the higher levels an opportunity to accept, reject, or force re-pair with the peripheral.

If no handler is registered to this event, pairing requests will be accepted unless the reject_pairing_requests parameter is set.

Note

If a handler is registered to this event, it must respond with one of the options (accept/reject/repair).

Note

If multiple handlers are registered to this event, the first handler to respond is the response used. All other inputs will be ignored

Returns: Event that is triggered when the peripheral requests a secure connection

property on_pairing_request_rejected: Event[Peer, PairingRejectedEventArgs]¶

Event that’s emitted when a pairing request is rejected locally, either due to the user event handler or due to the rejection policy set in the security parameters

Returns: Event that is triggered when a pairing request is rejected

property is_previously_bonded: bool¶

Gets if the peer this security manager is for was bonded in a previous connection

Returns: True if previously bonded, False if not

property pairing_in_process: bool¶: Gets whether or not pairing/encryption is currently in process

property security_level: SecurityLevel¶: Gets the current security level of the connection

property security_params: SecurityParameters¶: Gets the security parameters structure

set_security_params(passcode_pairing, io_capabilities, bond, out_of_band, reject_pairing_requests=False, lesc_pairing=False)¶

Sets the security parameters to use with the peer

Parameters

passcode_pairing (bool) – Flag indicating that passcode pairing is required
io_capabilities (BLEGapIoCaps) – The input/output capabilities of this device
bond (bool) – Flag indicating that long-term bonding should be performed
out_of_band (bool) – Flag indicating if out-of-band pairing is supported
reject_pairing_requests (Union[bool, PairingPolicy]) – Flag indicating that all security requests by the peer should be rejected
lesc_pairing (bool) – Flag indicating that LE Secure Pairing methods are supported

pair(force_repairing=False)¶

Starts the pairing process with the peer with the set security parameters.

If the peer is already bonded, initiates the encryption process unless force_repairing is set to True

If the peer is a central and we are a local device, sends the peripheral security request to the central so they can start the pairing/encryption process

Return type: EventWaitable[Peer, PairingCompleteEventArgs]
Returns: A waitable that will trigger when pairing is complete

use_debug_lesc_key()¶: Changes the security settings to use the debug public/private key-pair for future LESC pairing interactions. The key is defined in the Core Bluetooth Specification v4.2 Vol.3, Part H, Section 2.3.5.6.

Warning

Using this key allows Bluetooth sniffers to be able to decode the encrypted traffic over the air

delete_bonding_data()¶: Deletes the bonding data for the peer, if any. Cannot be called during pairing, will throw an InvalidOperationException