src.bluetooth_sig.advertising.encryption¶

Encryption key management for advertising data parsing.

This module provides protocols and implementations for managing encryption keys used by encrypted BLE advertising protocols.

Includes support for: - vendor-specific encryption (bindkeys for Xiaomi, BTHome, etc.) - BLE-standard Encrypted Advertising Data (EAD) per Core Spec Supplement 1.23

Attributes¶

Name	Description
`AsyncKeyLookup`
`logger`

Classes¶

Name	Description
`DictKeyProvider`	Simple dictionary-based encryption key provider.
`EADKeyProvider`	Protocol for EAD encryption key lookup.
`EncryptionKeyProvider`	Protocol for encryption key lookup.

Module Contents¶

class src.bluetooth_sig.advertising.encryption.DictKeyProvider(keys: dict[str, bytes] | None = None, ead_keys: dict[str, bluetooth_sig.types.ead.EADKeyMaterial] | None = None)¶

Simple dictionary-based encryption key provider.

Stores keys in a dictionary mapping MAC addresses to key bytes. Supports both legacy bindkeys and EAD key material. Logs a warning once per unknown MAC address.

keys¶: Dictionary mapping MAC addresses to encryption keys

ead_keys¶: Dictionary mapping MAC addresses to EAD key material

warned_macs¶: Set of MAC addresses that have already been warned about

Example

>>> provider = DictKeyProvider(
...     {
...         "AA:BB:CC:DD:EE:FF": bytes.fromhex("0123456789abcdef0123456789abcdef"),
...     }
... )
>>> key = provider.get_key("AA:BB:CC:DD:EE:FF")
>>> print(key.hex() if key else "No key")
0123456789abcdef0123456789abcdef

get_ead_key(mac_address: str) → bluetooth_sig.types.ead.EADKeyMaterial | None¶

Get EAD key material for a device.

Parameters:: mac_address – Device MAC address (e.g., “AA:BB:CC:DD:EE:FF”)
Returns:: EADKeyMaterial containing session key and IV, or None if no key is available for this device.

get_key(mac_address: str) → bytes | None¶

Get encryption key for a device.

Parameters:: mac_address – Device MAC address (e.g., “AA:BB:CC:DD:EE:FF”)
Returns:: Encryption key bytes, or None if no key available.

remove_ead_key(mac_address: str) → None¶

Remove EAD key material for a device.

Parameters:: mac_address – Device MAC address

remove_key(mac_address: str) → None¶

Remove encryption key for a device.

Parameters:: mac_address – Device MAC address

set_ead_key(mac_address: str, key_material: bluetooth_sig.types.ead.EADKeyMaterial) → None¶

Set or update EAD key material for a device.

Parameters:

mac_address – Device MAC address
key_material – EAD key material (session key + IV)

set_key(mac_address: str, key: bytes) → None¶

Set or update encryption key for a device.

Parameters:

mac_address – Device MAC address
key – Encryption key bytes (typically 16 bytes)

ead_keys: dict[str, bluetooth_sig.types.ead.EADKeyMaterial]¶

keys: dict[str, bytes]¶

warned_macs: set[str]¶

class src.bluetooth_sig.advertising.encryption.EADKeyProvider¶

Bases: Protocol

Protocol for EAD encryption key lookup.

Implement this protocol to provide EAD key material for devices that use BLE-standard Encrypted Advertising Data.

Example

>>> class MyEADKeyProvider:
...     def __init__(self, keys: dict[str, EADKeyMaterial]):
...         self._keys = keys
...
...     def get_ead_key(self, mac_address: str) -> EADKeyMaterial | None:
...         return self._keys.get(mac_address.upper())

get_ead_key(mac_address: str) → bluetooth_sig.types.ead.EADKeyMaterial | None¶

Get EAD key material for a device.

Parameters:: mac_address – Device MAC address (e.g., “AA:BB:CC:DD:EE:FF”)
Returns:: EADKeyMaterial containing session key and IV, or None if no key is available for this device.

class src.bluetooth_sig.advertising.encryption.EncryptionKeyProvider¶

Bases: Protocol

Protocol for encryption key lookup.

Implement this protocol to provide encryption keys for devices that use encrypted advertising (e.g., Xiaomi MiBeacon, BTHome).

Example

>>> class MyKeyProvider:
...     def __init__(self, keys: dict[str, bytes]):
...         self._keys = keys
...
...     def get_key(self, mac_address: str) -> bytes | None:
...         return self._keys.get(mac_address.upper())

get_key(mac_address: str) → bytes | None¶

Get encryption key for a device.

Parameters:: mac_address – Device MAC address (e.g., “AA:BB:CC:DD:EE:FF”)
Returns:: Encryption key bytes (typically 16 bytes for AES-CCM), or None if no key is available for this device.

src.bluetooth_sig.advertising.encryption.AsyncKeyLookup: typing_extensions.TypeAlias¶

src.bluetooth_sig.advertising.encryption.logger¶