mirage.libs.ble_utils package

Submodules

mirage.libs.ble_utils.adb module

class mirage.libs.ble_utils.adb.ADBDevice(interface)

Bases: mirage.libs.wireless_utils.device.Device

This device allows to communicate with an Android Device using adb in order to monitor Bluetooth Low Energy HCI packets.

The corresponding interfaces are : adbX (e.g. “adb0”)

The following capabilities are actually supported :

Capability

Available ?

SCANNING

no

ADVERTISING

no

SNIFFING_ADVERTISEMENTS

no

SNIFFING_NEW_CONNECTION

no

SNIFFING_EXISTING_CONNECTION

no

JAMMING_CONNECTIONS

no

JAMMING_ADVERTISEMENTS

no

HIJACKING_CONNECTIONS

no

INITIATING_CONNECTION

no

RECEIVING_CONNECTION

no

COMMUNICATING_AS_MASTER

no

COMMUNICATING_AS_SLAVE

no

HCI_MONITORING

yes

Warning

  • You must install a recent version of adb in order to monitor a smartphone.

  • The full path to the binary adb should be present in the PATH environment variable.

  • You should enable the Developper mode, USB Debugging and Bluetooth logging on your smartphone.

If you don’t know how to configure your smartphone, please follow the instructions presented here.

close()

This method closes the device.

classmethod findADBDevices(index=None)

This class method allows to find a specific ADB device, by providing the device’s index. If no index is provided, it returns a list of every devices found. If no device has been found, None is returned.

Parameters

index (int) – device’s index

Returns

string indicating the device

Return type

str

Example
>>> ADBDevice.findADBDevices(0)
'3e95c5e'
>>> ADBDevice.findADBDevices()
['3e95c5e','3e95c5f']
getAddressByHandle(handle)

This method returns the BD address associated to the provided connection handle if a corresponding connection is established. If no connection uses this handle, it returns None.

Parameters

handle (int) – connection handle

Returns

address of the corresponding connection

Return type

str

Example
>>> device.getAddressByHandle(72)
'AA:BB:CC:DD:EE:FF'
>>> device.getAddressByHandle(4)
None

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getConnections()

This method returns a list of couple (connection handle / BD address) representing the connections actually established. A connection is described by a dictionary containing an handle and a BD address : {"handle":72, "address":'AA:BB:CC:DD:EE:FF'}

Returns

list of connections established

Return type

list of dict

Example
>>> device.getConnections()
[{'handle':72, 'address':'AA:BB:CC:DD:EE:FF'}]

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentConnection()

This method returns the BD address associated to the current connection. If no connection is established, it returns None.

Returns

address of the current connection

Return type

str

Example
>>> device.getCurrentConnection()
'AA:BB:CC:DD:EE:FF'
>>> device.getCurrentConnection()
None

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentConnectionMode()

This method returns the connection mode (“public” or “random”) of the currently established connection.

Returns

connection mode of the current connection (“public” or “random”)

Return type

str

Example
>>> device.getCurrentConnectionMode()
'public'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentHandle()

This method returns the connection Handle actually in use. If no connection is established, its value is equal to -1.

Returns

connection Handle

Return type

int

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getDeviceIndex()

This method returns the index of the current ADB device.

Returns

device’s index

Return type

int

Example
>>> device.getDeviceIndex()
0

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getSerial()

This method returns the serial number of the smartphone.

Returns

serial number

Return type

str

Example
>>> device.getSerial()
'3e95c5e'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getSnoopFileLocation()

This method returns the snoop file location on the smartphone.

Returns

snoop file location

Return type

str

Example
>>> device.getSnoopFileLocation()
'/sdcard/btsnoop_hci.log'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getSnoopFileSize()

This method returns the snoop file size on the smartphone.

Returns

snoop file size

Return type

int

Example
>>> device.getSnoopFileSize()
8927994

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

init()

This method initializes the device.

isConnected()

This method returns a boolean indicating if a connection is actually established.

Returns

boolean indicating if a connection is established

Return type

bool

Example
>>> device.isConnected()
True

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

isUp()

This method allows to check if the device is initialized and available for use.

Returns

boolean indicating if the device is up

Return type

bool

recv()

This method receives some datas. If no data is available, this method returns None.

Parameters

data – raw representation of the received data

sharedMethods = ['getConnections', 'switchConnection', 'getCurrentConnection', 'getAddressByHandle', 'getCurrentHandle', 'getCurrentConnectionMode', 'isConnected', 'getSnoopFileLocation', 'getSnoopFileSize', 'getSerial', 'getDeviceIndex']
classmethod startADBDaemon()

This class method starts the ADB daemon server.

Returns

boolean indicating if the ADB server was successfully launched

Return type

bool

Example
>>> ADBDevice.startADBDaemon()
True
classmethod stopADBDaemon()

This class method stops the ADB daemon server.

Returns

boolean indicating if the ADB server was successfully stopped

Return type

bool

Example
>>> ADBDevice.stopADBDaemon()
True
switchConnection(address)

This method allows to switch the current connection to another connection established by providing the associated BD address.

Parameters

address (str) – BD Address of the new current connection

Returns

boolean indicating if the operation was successful

Return type

bool

Example
>>> device.getCurrentConnection()
'AA:BB:CC:DD:EE:FF'
>>> device.switchConnection('11:22:33:44:55:66')
>>> device.getCurrentConnection()
'11:22:33:44:55:66'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

mirage.libs.ble_utils.hcidump module

class mirage.libs.ble_utils.hcidump.BLEHcidumpDevice(interface)

Bases: mirage.libs.wireless_utils.device.Device

This device allows to monitor an HCI interface using hcidump.

The corresponding interfaces are : hcidumpX (e.g. “hcidump0” for monitoring the interface “hci0”).

The following capabilities are actually supported :

Capability

Available ?

SCANNING

no

ADVERTISING

no

SNIFFING_ADVERTISEMENTS

no

SNIFFING_NEW_CONNECTION

no

SNIFFING_EXISTING_CONNECTION

no

JAMMING_CONNECTIONS

no

JAMMING_ADVERTISEMENTS

no

HIJACKING_CONNECTIONS

no

INITIATING_CONNECTION

no

RECEIVING_CONNECTION

no

COMMUNICATING_AS_MASTER

no

COMMUNICATING_AS_SLAVE

no

HCI_MONITORING

yes

Warning

  • You must install a recent version of hcidump in order to monitor an HCI device.

  • The full path to the binary hcidump should be present in the PATH environment variable.

close()

This method closes the device.

getAddressByHandle(handle)

This method returns the BD address associated to the provided connection handle if a corresponding connection is established. If no connection uses this handle, it returns None.

Parameters

handle (int) – connection handle

Returns

address of the corresponding connection

Return type

str

Example
>>> device.getAddressByHandle(72)
'AA:BB:CC:DD:EE:FF'
>>> device.getAddressByHandle(4)
None

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getConnections()

This method returns a list of couple (connection handle / BD address) representing the connections actually established. A connection is described by a dictionary containing an handle and a BD address : {"handle":72, "address":'AA:BB:CC:DD:EE:FF'}

Returns

list of connections established

Return type

list of dict

Example
>>> device.getConnections()
[{'handle':72, 'address':'AA:BB:CC:DD:EE:FF'}]

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentConnection()

This method returns the BD address associated to the current connection. If no connection is established, it returns None.

Returns

address of the current connection

Return type

str

Example
>>> device.getCurrentConnection()
'AA:BB:CC:DD:EE:FF'
>>> device.getCurrentConnection()
None

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentConnectionMode()

This method returns the connection mode (“public” or “random”) of the currently established connection.

Returns

connection mode of the current connection (“public” or “random”)

Return type

str

Example
>>> device.getCurrentConnectionMode()
'public'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentHandle()

This method returns the connection Handle actually in use. If no connection is established, its value is equal to -1.

Returns

connection Handle

Return type

int

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getDeviceIndex()

This method returns the index of the current HCIDump device.

Returns

device’s index

Return type

int

Example
>>> device.getDeviceIndex()
0
getHCIInterface()

This method returns the HCI Interface monitored by this HCIDump device.

Returns

monitored HCI interface

Return type

str

Example
>>> device.getHCIInterface()
'hci0'
init()

This method initializes the device.

isConnected()

This method returns a boolean indicating if a connection is actually established.

Returns

boolean indicating if a connection is established

Return type

bool

Example
>>> device.isConnected()
True

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

isUp()

This method allows to check if the device is initialized and available for use.

Returns

boolean indicating if the device is up

Return type

bool

recv()

This method receives some datas. If no data is available, this method returns None.

Parameters

data – raw representation of the received data

sharedMethods = ['getConnections', 'switchConnection', 'getCurrentConnection', 'getCurrentConnectionMode', 'getAddressByHandle', 'getCurrentHandle', 'isConnected', 'getHCIInterface', 'getDeviceIndex']
switchConnection(address)

This method allows to switch the current connection to another connection established by providing the associated BD address.

Parameters

address (str) – BD Address of the new current connection

Returns

boolean indicating if the operation was successful

Return type

bool

Example
>>> device.getCurrentConnection()
'AA:BB:CC:DD:EE:FF'
>>> device.switchConnection('11:22:33:44:55:66')
>>> device.getCurrentConnection()
'11:22:33:44:55:66'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

mirage.libs.ble_utils.pcap module

class mirage.libs.ble_utils.pcap.BLEPCAPDevice(interface)

Bases: mirage.libs.wireless_utils.pcapDevice.PCAPDevice

This device allows to communicate with a PCAP file in order to write and read Bluetooth Low Energy packets.

The corresponding interfaces are : <filename>.pcap (e.g. “out.pcap”)

  • If the file exists, the BLEPCAPDevice is in read mode, and the corresponding receiver is able to use it as a classic Bluetooth Low Energy sniffer.

  • If the file doesn’t exist, the BLEPCAPDevice is in write mode, and the corresponding emitter is able to write packets in the file.

The following capabilities are actually supported :

Capability

Available ?

SCANNING

no

ADVERTISING

no

SNIFFING_ADVERTISEMENTS

yes

SNIFFING_NEW_CONNECTION

yes

SNIFFING_EXISTING_CONNECTION

no

JAMMING_CONNECTIONS

no

JAMMING_ADVERTISEMENTS

no

HIJACKING_CONNECTIONS

no

INITIATING_CONNECTION

no

RECEIVING_CONNECTION

no

COMMUNICATING_AS_MASTER

no

COMMUNICATING_AS_SLAVE

no

HCI_MONITORING

no

Warning

This PCAP Device uses the DLT 256, and can be used to read or write some Link Layer packets. It is not compatible with a PCAP file containing HCI frames.

DLT = 256
SCAPY_LAYER

alias of scapy.layers.bluetooth4LE.BTLE_RF

buildPacket(packet, timestamp)

This method is used to encapsulate the packet into a scapy frame (if SCAPY_LAYER is not None).

getAccessAddress()

This method returns the access address actually in use.

Returns

access address

Return type

int

Example
>>> hex(device.getAccessAddress())
'0xe5e296e9'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getChannelMap()

This method returns the Channel Map actually in use.

Returns

Channel Map

Return type

int

Example
>>> hex(device.getChannelMap())
'0x1fffffffff'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCrcInit()

This method returns the CRCInit actually in use.

Returns

CRCInit

Return type

int

Example
>>> hex(device.getCrcInit())
'0x0bd54a'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getHopIncrement()

This method returns the Hop Increment actually in use.

Returns

Hop Increment

Return type

int

Example
>>> device.getHopIncrement()
11

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getHopInterval()

This method returns the Hop Interval actually in use.

Returns

Hop Interval

Return type

int

Example
>>> device.getHopInterval()
36

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

init()

This method initializes the PCAP file, by checking the header (if the Device is in reading mode) or by adding the header (if the Device is in writing mode).

isSynchronized()

This method indicates if the sniffer is actually synchronized with a connection.

Returns

boolean indicating if the sniffer is synchronized

Return type

bool

Example
>>> device.isSynchronized()
True

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

recv()

This method gets the packets from the PCAP file asynchronously.

send(packet)

This method writes a packet synchronously into the PCAP file.

Parameters

packet (bytes or scapy frame (if SCAPY_LAYER is not None)) – packet to write

sharedMethods = ['sniffNewConnections', 'sniffAdvertisements', 'getAccessAddress', 'getCrcInit', 'getChannelMap', 'getHopInterval', 'getHopIncrement', 'isSynchronized', 'getMode']
sniffAdvertisements(address='FF:FF:FF:FF:FF:FF', channel=None)

This method starts the advertisement sniffing mode.

Parameters
  • address (str) – selected address - if not provided, no filter is applied (format : “1A:2B:3C:4D:5E:6F”)

  • channel (int) – selected channel - if not provided, channel 37 is selected

Example
>>> device.sniffAdvertisements()
>>> device.sniffAdvertisements(channel=38)
>>> device.sniffAdvertisements(address="1A:2B:3C:4D:5E:6F")

Warning

The channel parameter is not used by this method, and is present in order to provide the same API as BTLEJack and Ubertooth devices. However, the address field can be used in order to filter the advertisements frames.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sniffNewConnections(address='FF:FF:FF:FF:FF:FF', channel=None)

This method starts the new connections sniffing mode.

Parameters
  • address (str) – selected address - if not provided, no filter is applied (format : “1A:2B:3C:4D:5E:6F”)

  • channel (int) – selected channel - if not provided, channel 37 is selected

Example
>>> device.sniffNewConnections()
>>> device.sniffNewConnections(channel=38)
>>> device.sniffNewConnections(address="1A:2B:3C:4D:5E:6F")

Warning

Actually, the address and channel arguments are not used by this method. They are present in order to provide the same API as BTLEJack and Ubertooth devices.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

mirage.libs.ble_utils.btlejack module

class mirage.libs.ble_utils.btlejack.BTLEJackDevice(interface)

Bases: mirage.libs.wireless_utils.device.Device

This device allows to communicate with a BTLEJack Device in order to sniff Bluetooth Low Energy protocol. The corresponding interfaces are : microbitX (e.g. “microbit0”)

The following capabilities are actually supported :

Capability

Available ?

SCANNING

yes

ADVERTISING

no

SNIFFING_ADVERTISEMENTS

yes

SNIFFING_NEW_CONNECTION

yes

SNIFFING_EXISTING_CONNECTION

yes

JAMMING_CONNECTIONS

yes

JAMMING_ADVERTISEMENTS

yes

HIJACKING_CONNECTIONS

yes

INITIATING_CONNECTION

no

RECEIVING_CONNECTION

no

COMMUNICATING_AS_MASTER

yes

COMMUNICATING_AS_SLAVE

no

HCI_MONITORING

no

close()

This method closes the device.

disableAdvertisementsJamming()
classmethod findMicrobits(index=None)

This class method allows to find a specific BTLEJack device, by providing the device’s index. If no index is provided, it returns a list of every devices found. If no device has been found, None is returned.

Parameters

index (int) – device’s index

Returns

string indicating the device

Return type

str

Example
>>> BTLEJackDevice.findMicrobits(0)
'/dev/ttyACM0'
>>> BTLEJackDevice.findMicrobits()
['/dev/ttyACM0','/dev/ttyACM1']
getAccessAddress()

This method returns the access address actually in use.

Returns

access address

Return type

int

Example
>>> hex(device.getAccessAddress())
'0xe5e296e9'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getChannel()

This method returns the channel actually in use.

Returns

channel in use

Return type

int

Example
>>> device.getChannel()
37
>>> device.setChannel(channel=38)
>>> device.getChannel()
38

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getChannelMap()

This method returns the Channel Map actually in use.

Returns

Channel Map

Return type

int

Example
>>> hex(device.getChannelMap())
'0x1fffffffff'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getConnections()

This method returns a list of couple (connection handle / address) representing the connections actually established. A connection is described by a dictionary containing an handle and an access address : {"handle":1, "address":"0x12345678"}

Returns

list of connections established

Return type

list of dict

Example
>>> device.getConnections()
[{'handle':1, 'address':'0x12345678'}]

Warning

The connection handle is always 1, it allows to provides the same API as the HCI Device.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCrcInit()

This method returns the CRCInit actually in use.

Returns

CRCInit

Return type

int

Example
>>> hex(device.getCrcInit())
'0x0bd54a'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentConnection()

This method returns the access address associated to the current connection. If no connection is established, it returns None.

Returns

access address of the current connection

Return type

str

Example
>>> device.getCurrentConnection()
'0x12345678'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCurrentHandle()

This method returns the connection Handle actually in use. If no connection is established, its value is equal to -1.

Returns

connection Handle

Return type

int

Warning

This method always returns 1, it allows to provides the same API as the HCI Device.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getDeviceIndex()

This method returns the index of the current BTLEJack device.

Returns

device’s index

Return type

int

Example
>>> device.getDeviceIndex()
0

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getFirmwareVersion()

This method returns the firmware version of the current BTLEJack device.

Returns

firmware version as a tuple of (major, minor)

Return type

tuple of (int,int)

Example
>>> device.getFirmwareVersion()
(3,14)

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getHopIncrement()

This method returns the Hop Increment actually in use.

Returns

Hop Increment

Return type

int

Example
>>> device.getHopIncrement()
11

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getHopInterval()

This method returns the Hop Interval actually in use.

Returns

Hop Interval

Return type

int

Example
>>> device.getHopInterval()
36

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

init()

This method initializes the device.

isConnected()

This method returns a boolean indicating if a connection is actually established and hijacked.

Returns

boolean indicating if a connection is established and hijacked

Return type

bool

Example
>>> device.isConnected()
True

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

isSynchronized()

This method indicates if the sniffer is actually synchronized with a connection.

Returns

boolean indicating if the sniffer is synchronized

Return type

bool

Example
>>> device.isSynchronized()
True

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

isUp()

This method allows to check if the device is initialized and available for use.

Returns

boolean indicating if the device is up

Return type

bool

jamAdvertisements(pattern=b'', offset=0, channel=37)

This method reactively jams advertisements according to the specified pattern, offset and channel provided.

Parameters
  • pattern (bytes) – pattern contained in payload indicating that the packet must be jammed

  • offset (int) – offset indicating the position of pattern in the payload

  • channel (int) – selected channel - if not provided, channel 37 is selected

Example
>>> target = "1A:2B:3C:4D:5E:6F"
>>> pattern = bytes.fromhex(target.replace(":",""))[::-1]
>>> device.jamAdvertisements(pattern=pattern,offset=2,channel=39) # jam the advertisements transmitted by 1A:2B:3C:4D:5E:6F on channel 39

Warning

This method requires the custom Mirage Firmware in order to jam advertisements.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

recv()

This method receives some datas. If no data is available, this method returns None.

Parameters

data – raw representation of the received data

restartSniffingMode()

This method restarts the sniffing mode.

Example
>>> device.restartSniffingMode()

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

send(packet)

This method sends some datas.

Parameters

data – raw representation of the data to send

setAccessAddress(accessAddress)

This method sets the access address to use.

Parameters

accessAddress (int) – new access address

Example
>>> device.setAccessAddress(0xe5e296e9)

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setCRCChecking(enable=True)

This method enables CRC Checking.

Parameters

enable (bool) – boolean indicating if CRC Checking must be enabled

Example
>>> device.setCRCChecking(enable=True) # CRC Checking enabled
>>> device.setCRCChecking(enable=False) # CRC Checking disabled

Warning

BTLEJack calculates the CRC directly in the firmware, so this command is ignored. It is present in order to provide a similar API to Ubertooth.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setChannel(channel=37)

This method changes the channel actually in use by the provided channel.

Parameters

channel (int) – new channel

Example
>>> device.getChannel()
37
>>> device.setChannel(channel=38)
>>> device.getChannel()
38

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setHijacking(enable=True)

This method allows to enable or disable the hijacking mode.

Parameters

enable (bool) – boolean indicating if the hijacking mode must be enabled or disabled

Example
>>> device.setHijacking(enable=True) # hijacking mode enabled
>>> device.setHijacking(enable=False) # hijacking mode disabled

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setJamming(enable=True)

This method allows to enable or disable the jamming mode.

Parameters

enable (bool) – boolean indicating if the jamming mode must be enabled or disabled

Example
>>> device.setJamming(enable=True) # jamming mode enabled
>>> device.setJamming(enable=False) # jamming mode disabled

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setScan(enable=True)

This method enables or disables the scanning mode. It allows to change the channel according to the scan interval parameter.

Parameters

enable (bool) – boolean indicating if the scanning mode must be enabled

Example
>>> device.setScan(enable=True) # scanning mode enabled
>>> device.setScan(enable=False) # scanning mode disabled

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setScanInterval(seconds=1)

This method allows to provide the scan interval (in second).

Parameters

seconds (float) – number of seconds to wait between two channels

Example
>>> device.setScanInterval(seconds=1)

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setSweepingMode(enable=True, sequence=[37, 38, 39])

This method allows to enable or disable the Sweeping mode. It allows to provide a subset of advertising channels to monitor sequentially.

Parameters
  • enable (bool) – boolean indicating if the Sweeping mode is enabled.

  • sequence (list of int) – sequence of channels to use

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sharedMethods = ['getFirmwareVersion', 'getDeviceIndex', 'setCRCChecking', 'setChannel', 'getChannel', 'sniffNewConnections', 'sniffExistingConnections', 'sniffAdvertisements', 'jamAdvertisements', 'disableAdvertisementsJamming', 'setSweepingMode', 'setScan', 'setScanInterval', 'getConnections', 'switchConnection', 'getCurrentConnection', 'isConnected', 'isSynchronized', 'getCurrentHandle', 'getAccessAddress', 'getCrcInit', 'getChannelMap', 'getHopInterval', 'getHopIncrement', 'setJamming', 'setHijacking']
sniffAdvertisements(address='FF:FF:FF:FF:FF:FF', channel=None)

This method starts the advertisement sniffing mode.

Parameters
  • address (str) – selected address - if not provided, no filter is applied (format : “1A:2B:3C:4D:5E:6F”)

  • channel (int) – selected channel - if not provided, channel 37 is selected

Example
>>> device.sniffAdvertisements()
>>> device.sniffAdvertisements(channel=38)
>>> device.sniffAdvertisements(address="1A:2B:3C:4D:5E:6F")

Warning

This method requires the custom Mirage Firmware in order to sniff advertisements.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sniffExistingConnections(accessAddress=None, crcInit=None, channelMap=None)

This method starts the existing connections sniffing mode.

Parameters
  • accessAddress – selected Access Address - if not provided, the parameter is recovered

  • crcInit (int) – selected CRCInit - if not provided, the parameter is recovered

  • channelMap (int) – selected Channel Map - if not provided, the parameter is recovered

Example
>>> device.sniffExistingConnections()
>>> device.sniffExistingConnections(accessAddress=0xe5e296e9)
>>> device.sniffExistingConnections(accessAddress=0xe5e296e9, crcInit=0x0bd54a)
>>> device.sniffExistingConnections(accessAddress=0xe5e296e9, crcInit=0x0bd54a, channelMap=0x1fffffffff)

Warning

If no access address is provided, BTLEJack tries to get multiple candidate access addresses and select the most probable address.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sniffNewConnections(address='FF:FF:FF:FF:FF:FF', channel=None)

This method starts the new connections sniffing mode.

Parameters
  • address (str) – selected address - if not provided, no filter is applied (format : “1A:2B:3C:4D:5E:6F”)

  • channel (int) – selected channel - if not provided, channel 37 is selected

Example
>>> device.sniffNewConnections()
>>> device.sniffNewConnections(channel=38)
>>> device.sniffNewConnections(address="1A:2B:3C:4D:5E:6F")

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

switchConnection(address)

This method is provided in order to provide the same API as an HCI Device, it actually has no effects.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

mirage.libs.ble_utils.ubertooth module

class mirage.libs.ble_utils.ubertooth.BLEUbertoothDevice(interface)

Bases: mirage.libs.bt_utils.ubertooth.BtUbertoothDevice

This device allows to communicate with an Ubertooth Device in order to sniff Bluetooth Low Energy protocol. The corresponding interfaces are : ubertoothX (e.g. “ubertooth0”)

The following capabilities are actually supported :

Capability

Available ?

SCANNING

yes

ADVERTISING

no

SNIFFING_ADVERTISEMENTS

yes

SNIFFING_NEW_CONNECTION

yes

SNIFFING_EXISTING_CONNECTION

yes

JAMMING_CONNECTIONS

yes

JAMMING_ADVERTISEMENTS

no

HIJACKING_CONNECTIONS

no

INITIATING_CONNECTION

no

RECEIVING_CONNECTION

no

COMMUNICATING_AS_MASTER

no

COMMUNICATING_AS_SLAVE

no

HCI_MONITORING

no

getAccessAddress()

This method returns the access address actually in use.

Returns

access address

Return type

int

Example
>>> hex(device.getAccessAddress())
'0xe5e296e9'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getChannel()

This method returns the channel actually in use.

Returns

channel in use

Return type

int

Example
>>> device.getChannel()
37
>>> device.setChannel(channel=38)
>>> device.getChannel()
38

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getChannelMap()

This method returns the Channel Map actually in use.

Returns

Channel Map

Return type

int

Example
>>> hex(device.getChannelMap())
'0x1fffffffff'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCrcInit()

This method returns the CRCInit actually in use.

Returns

CRCInit

Return type

int

Example
>>> hex(device.getCrcInit())
'0x0bd54a'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getHopIncrement()

This method returns the Hop Increment actually in use.

Returns

Hop Increment

Return type

int

Example
>>> device.getHopIncrement()
11

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getHopInterval()

This method returns the Hop Interval actually in use.

Returns

Hop Interval

Return type

int

Example
>>> device.getHopInterval()
36

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getMode()

This method returns the mode actually in use in the current Ubertooth Device (“Bt” or “BLE”)

Returns

string indicating the mode

Return type

str

Example
>>> device.getMode()
"BLE"

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getSerial()

This method allows to get the device’s serial number.

Returns

device’s serial number

Return type

str

Example
>>> device.getSerial()
'1160010b201835ae6d474553-79e1ff0b'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

init()

This method initializes the device.

isSynchronized()

This method indicates if the sniffer is actually synchronized with a connection.

Returns

boolean indicating if the sniffer is synchronized

Return type

bool

Example
>>> device.isSynchronized()
True

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

recv()

This method receives some datas. If no data is available, this method returns None.

Parameters

data – raw representation of the received data

restartSniffingMode()

This method restarts the sniffing mode.

Example
>>> device.restartSniffingMode()

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setCRCChecking(enable=True)

This method enables CRC Checking.

Parameters

enable (bool) – boolean indicating if CRC Checking must be enabled

Example
>>> device.setCRCChecking(enable=True) # CRC Checking enabled
>>> device.setCRCChecking(enable=False) # CRC Checking disabled

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setChannel(channel=37)

This method changes the channel actually in use by the provided channel.

Parameters

channel (int) – new channel

Example
>>> device.getChannel()
37
>>> device.setChannel(channel=38)
>>> device.getChannel()
38

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setJamming(enable=True)

This method allows to enable or disable the jamming mode.

Parameters

enable (bool) – boolean indicating if the jamming mode must be enabled or disabled

Example
>>> device.setJamming(enable=True) # jamming mode enabled
>>> device.setJamming(enable=False) # jamming mode disabled

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setScan(enable=True)

This method enables or disables the scanning mode. It allows to change the channel according to the scan interval parameter.

Parameters

enable (bool) – boolean indicating if the scanning mode must be enabled

Example
>>> device.setScan(enable=True) # scanning mode enabled
>>> device.setScan(enable=False) # scanning mode disabled

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setScanInterval(seconds=1)

This method allows to provide the scan interval (in second).

Parameters

seconds (float) – number of seconds to wait between two channels

Example
>>> device.setScanInterval(seconds=1)

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setSweepingMode(enable=True, sequence=[37, 38, 39])

This method allows to enable or disable the Sweeping mode. It allows to provide a subset of advertising channels to monitor sequentially.

Parameters
  • enable (bool) – boolean indicating if the Sweeping mode is enabled.

  • sequence (list of int) – sequence of channels to use

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sharedMethods = ['getFirmwareVersion', 'getDeviceIndex', 'getMode', 'getSerial', 'setChannel', 'setCRCChecking', 'setScanInterval', 'setScan', 'setJamming', 'isSynchronized', 'getChannel', 'getAccessAddress', 'getCrcInit', 'getChannelMap', 'getHopInterval', 'getHopIncrement', 'setSweepingMode', 'sniffNewConnections', 'sniffExistingConnections', 'sniffAdvertisements']
sniffAdvertisements(address='00:00:00:00:00:00', channel=None)

This method starts the advertisement sniffing mode.

Parameters
  • address (str) – selected address - if not provided, no filter is applied (format : “1A:2B:3C:4D:5E:6F”)

  • channel (int) – selected channel - if not provided, channel 37 is selected

Example
>>> device.sniffAdvertisements()
>>> device.sniffAdvertisements(channel=38)
>>> device.sniffAdvertisements(address="1A:2B:3C:4D:5E:6F")

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sniffExistingConnections(accessAddress=None, crcInit=None, channelMap=None)

This method starts the existing connections sniffing mode.

Parameters
  • accessAddress – selected Access Address - if not provided, the parameter is recovered

  • crcInit (int) – selected CRCInit - if not provided, the parameter is recovered

  • channelMap (int) – selected Channel Map - if not provided, the parameter is recovered

Example
>>> device.sniffExistingConnections()
>>> device.sniffExistingConnections(accessAddress=0xe5e296e9)
>>> device.sniffAdvertisements(accessAddress=0xe5e296e9, crcInit=0x0bd54a)
>>> device.sniffAdvertisements(accessAddress=0xe5e296e9, crcInit=0x0bd54a, channelMap=0x1fffffffff)

Warning

Please note the following warnings :

  • Ubertooth is actually not able to set CRC Init value and uses a full Channel Map (0x1fffffffff). This parameters are provided in order to provide the same API for Ubertooth and BTLEJack devices.

  • If no access address is provided, Ubertooth tries to get multiple candidate access addresses and select the most probable address

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sniffNewConnections(address='00:00:00:00:00:00', channel=None)

This method starts the new connections sniffing mode.

Parameters
  • address (str) – selected address - if not provided, no filter is applied (format : “1A:2B:3C:4D:5E:6F”)

  • channel (int) – selected channel - if not provided, channel 37 is selected

Example
>>> device.sniffNewConnections()
>>> device.sniffNewConnections(channel=38)
>>> device.sniffNewConnections(address="1A:2B:3C:4D:5E:6F")

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

stop()

mirage.libs.ble_utils.nrfsniffer module

class mirage.libs.ble_utils.nrfsniffer.NRFSnifferDevice(interface)

Bases: mirage.libs.wireless_utils.device.Device

This device allows to communicate with a NRFSniffer Device in order to sniff Bluetooth Low Energy protocol. The corresponding interfaces are : nrfsnifferX (e.g. “nrfsniffer0”)

The following capabilities are actually supported :

Capability

Available ?

SCANNING

yes

ADVERTISING

no

SNIFFING_ADVERTISEMENTS

yes

SNIFFING_NEW_CONNECTION

yes

SNIFFING_EXISTING_CONNECTION

no

JAMMING_CONNECTIONS

no

JAMMING_ADVERTISEMENTS

no

HIJACKING_CONNECTIONS

no

INITIATING_CONNECTION

no

RECEIVING_CONNECTION

no

COMMUNICATING_AS_MASTER

no

COMMUNICATING_AS_SLAVE

no

HCI_MONITORING

no

close()

This method closes the device.

classmethod findNRFSniffers(index=None)

This class method allows to find a specific NRFSniffer device, by providing the device’s index. If no index is provided, it returns a list of every devices found. If no device has been found, None is returned.

Parameters

index (int) – device’s index

Returns

string indicating the device

Return type

str

Example
>>> NRFSnifferDevice.findNRFSniffers(0)
'/dev/ttyACM0'
>>> NRFSnifferDevice.findNRFSniffers()
['/dev/ttyACM0','/dev/ttyACM1']
getAccessAddress()

This method returns the access address actually in use.

Returns

access address

Return type

int

Example
>>> hex(device.getAccessAddress())
'0xe5e296e9'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getChannel()

This method returns the channel actually in use.

Returns

channel in use

Return type

int

Example
>>> device.getChannel()
37
>>> device.setChannel(channel=38)
>>> device.getChannel()
38

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getChannelMap()

This method returns the Channel Map actually in use.

Returns

Channel Map

Return type

int

Example
>>> hex(device.getChannelMap())
'0x1fffffffff'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getCrcInit()

This method returns the CRCInit actually in use.

Returns

CRCInit

Return type

int

Example
>>> hex(device.getCrcInit())
'0x0bd54a'

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getDeviceIndex()

This method returns the index of the current NRFSniffer device.

Returns

device’s index

Return type

int

Example
>>> device.getDeviceIndex()
0

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getFirmwareVersion()

This method returns the firmware version of the current NRFSniffer device.

Returns

firmware version

Return type

int

Example
>>> device.getFirmwareVersion()
1111

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getHopIncrement()

This method returns the Hop Increment actually in use.

Returns

Hop Increment

Return type

int

Example
>>> device.getHopIncrement()
11

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

getHopInterval()

This method returns the Hop Interval actually in use.

Returns

Hop Interval

Return type

int

Example
>>> device.getHopInterval()
36

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

init()

This method initializes the device.

isSynchronized()

This method indicates if the sniffer is actually synchronized with a connection.

Returns

boolean indicating if the sniffer is synchronized

Return type

bool

Example
>>> device.isSynchronized()
True

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

isUp()

This method allows to check if the device is initialized and available for use.

Returns

boolean indicating if the device is up

Return type

bool

recv()

This method receives some datas. If no data is available, this method returns None.

Parameters

data – raw representation of the received data

restartSniffingMode()

This method restarts the sniffing mode.

Example
>>> device.restartSniffingMode()

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setCRCChecking(enable=True)

This method enables CRC Checking.

Parameters

enable (bool) – boolean indicating if CRC Checking must be enabled

Example
>>> device.setCRCChecking(enable=True) # CRC Checking enabled
>>> device.setCRCChecking(enable=False) # CRC Checking disabled

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setChannel(channel=37)

This method changes the channel actually in use by the provided channel.

Parameters

channel (int) – new channel

Example
>>> device.getChannel()
37
>>> device.setChannel(channel=38)
>>> device.getChannel()
38

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setScan(enable=True)

This method enables or disables the scanning mode. It allows to change the channel dynamically.

Parameters

enable (bool) – boolean indicating if the scanning mode must be enabled

Example
>>> device.setScan(enable=True) # scanning mode enabled
>>> device.setScan(enable=False) # scanning mode disabled

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setScanInterval(seconds=1)

This method allows to provide the scan interval (in second).

Parameters

seconds (float) – number of seconds to wait between two channels

Example
>>> device.setScanInterval(seconds=1)

Warning

Scan interval cannot be modified on a NRF Sniffer actually. This method is provided in order to expose the same API used by other supported sniffers.

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

setSweepingMode(enable=True, sequence=[37, 38, 39])

This method allows to enable or disable the Sweeping mode. It allows to provide a subset of advertising channels to monitor sequentially.

Parameters
  • enable (bool) – boolean indicating if the Sweeping mode is enabled.

  • sequence (list of int) – sequence of channels to use

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sharedMethods = ['getFirmwareVersion', 'getDeviceIndex', 'setCRCChecking', 'setChannel', 'getChannel', 'sniffNewConnections', 'sniffAdvertisements', 'setSweepingMode', 'setScan', 'setScanInterval', 'isSynchronized', 'getAccessAddress', 'getCrcInit', 'getChannelMap', 'getHopInterval', 'getHopIncrement']
sniffAdvertisements(address='FF:FF:FF:FF:FF:FF', channel=None)

This method starts the advertisement sniffing mode.

Parameters
  • address (str) – selected address - if not provided, no filter is applied (format : “1A:2B:3C:4D:5E:6F”)

  • channel (int) – selected channel - if not provided, channel 37 is selected

Example
>>> device.sniffAdvertisements()
>>> device.sniffAdvertisements(channel=38)
>>> device.sniffAdvertisements(address="1A:2B:3C:4D:5E:6F")

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

sniffNewConnections(address='FF:FF:FF:FF:FF:FF', channel=None)

This method starts the new connections sniffing mode.

Parameters
  • address (str) – selected address - if not provided, no filter is applied (format : “1A:2B:3C:4D:5E:6F”)

  • channel (int) – selected channel - if not provided, channel 37 is selected

Example
>>> device.sniffNewConnections()
>>> device.sniffNewConnections(channel=38)
>>> device.sniffNewConnections(address="1A:2B:3C:4D:5E:6F")

Note

This method is a shared method and can be called from the corresponding Emitters / Receivers.

mirage.libs.ble_utils.crypto module

class mirage.libs.ble_utils.crypto.BLECrypto

Bases: object

This class provides some cryptographic functions used by the Security Manager.

Note

The temporaryKeys class attribute is used in order to precalculate the possible temporary keys. It allows to avoid some time consuming calculations during the cracking process.

classmethod c1(key, rand, payloadRequest, payloadResponse, initiatorAddressType, initiatorAddress, responderAddressType, responderAddress)

This class method implements the confirm value generation function \(C1\)

Parameters
  • key (bytes) – encryption key

  • rand (bytes) – random value

  • payloadRequest (bytes) – request’s payload

  • payloadResponse (bytes) – response’s payload

  • initiatorAddressType (bytes) – initiator address type (format : b”” if type is public or b”” if it is random)

  • initiatorAddress (str) – initiator address (format : “A1:B2:C3:D4:E5:F6”)

  • responderAddressType (bytes) – responder address type (format : b”” if type is public or b”” if it is random)

  • responderAddress (str) – responder address (format : “A1:B2:C3:D4:E5:F6”)

Returns

generated confirm value

Return type

bytes

See also

This function is described in Bluetooth Core Specification, [Vol 3] Part H, Section 2.2.3.

classmethod c1m1(key, confirm, payloadRequest, payloadResponse, initiatorAddressType, initiatorAddress, responderAddressType, responderAddress)

This class method implements the inverse function \(C1_{-1}\) of the confirm value generation function \(C1\)

Parameters
  • key (bytes) – encryption key

  • confirm (bytes) – confirm value

  • payloadRequest (bytes) – request’s payload

  • payloadResponse (bytes) – response’s payload

  • initiatorAddressType (bytes) – initiator address type (format : b”” if type is public or b”” if it is random)

  • initiatorAddress (str) – initiator address (format : “A1:B2:C3:D4:E5:F6”)

  • responderAddressType (bytes) – responder address type (format : b”” if type is public or b”” if it is random)

  • responderAddress (str) – responder address (format : “A1:B2:C3:D4:E5:F6”)

Returns

corresponding random value

Return type

bytes

See also

This function is described in Bluetooth Core Specification, [Vol 3] Part H, Section 2.2.3.

classmethod crackTemporaryKey(r, preq, pres, iat, initiatorAddress, rat, responderAddress, confirm)

This class method allows to crack a temporary key, according to multiple parameters extracted during the pairing process. It returns the corresponding PIN code.

Parameters
  • r (bytes) – random value

  • preq (bytes) – pairing request’s payload

  • pres (bytes) – pairing response’s payload

  • iat (bytes) – initiator address type

  • initiatorAddress (str) – initiator address (format : “1A:2B:3C:4D:5E:6F”)

  • rat (bytes) – responder address type

  • responderAddress (str) – responder address (format : “1A:2B:3C:4D:5E:6F”)

  • confirm (bytes) – confirm value

Returns

corresponding PIN code

Return type

int

Example
>>> random = bytes.fromhex("abb692ebfd4601f4aad3aea40f7da5fc")[::-1]
>>> pairingRequest = bytes.fromhex("01030005100001")[::-1]
>>> pairingResponse = bytes.fromhex("02000005100001")[::-1]
>>> initiatorAddress = "08:3E:8E:E1:0B:3E"
>>> initiatorAddressType = b""
>>> responderAddress = "78:C5:E5:6E:DD:E8"
>>> responderAddressType = b""
>>> confirm = bytes.fromhex("febb983ed78020e13d685bc8418d2c5d")[::-1]
>>> BLECrypto.crackTemporaryKey(random,pairingRequest,pairingResponse, initiatorAddressType,initiatorAddress,responderAddressType,responderAddress,confirm)
0

Warning

This method uses multi processes in order to optimize the time consumption of the required operation.

classmethod e(key, plaintext)

This class method implements the security function \(E\)

Parameters
  • key (bytes) – encryption key

  • plaintext (bytes) – plain text data

Returns

encrypted data

Return type

bytes

See also

This function is described in Bluetooth Core Specification, [Vol 3] Part H, Section 2.2.1.

classmethod em1(key, ciphertext)

This class method implements the inverse function \(E_{-1}\) of the security function \(E\)

Parameters
  • key (bytes) – encryption key

  • ciphertext (bytes) – encrypted data

Returns

decrypted data

Return type

bytes

See also

This function is described in Bluetooth Core Specification, [Vol 3] Part H, Section 2.2.1.

classmethod generateRandom(size=16)

This class method allows to easily generate a random value, according to the size (number of bytes) provided.

Parameters

size (int) – number of bytes of the random value

Returns

random list of bytes

Return type

bytes

Example
>>> BLECrypto.generateRandom().hex()
'd05c872faaef8bc959b801e4c30c0afa'
>>> BLECrypto.generateRandom(3).hex()
'e7bbc9'
classmethod s1(key, randMaster, randSlave)

This class method implements the key generation function \(S1\)

Parameters
  • key (bytes) – encryption key

  • randMaster (bytes) – master’s random value

  • randSlave (bytes) – slave’s random value

Returns

generated key

Return type

bytes

See also

This function is described in Bluetooth Core Specification, [Vol 3] Part H, Section 2.2.4.

classmethod xor128(a1, b1)

This class method implements the XOR operation applied to 128 bits bytes strings.

Parameters
  • a1 (bytes) – first value

  • b1 (bytes) – second value

Returns

result

Return type

bytes

class mirage.libs.ble_utils.crypto.BLELinkLayerCrypto(ltk)

Bases: object

This class provides an API allowing to manipulate the Link Layer Cryptographic functions used by Bluetooth Low Energy.

Warning

This class is used by the receiver BLEReceiver (mirage.libs.ble.BLEReceiver) and should not be used directly by an user.

decrypt(payload, masterToSlave=True)

This method decrypts the provided payload, according to the direction provided.

Parameters
  • payload (bytes) – payload to decrypt

  • masterToSlave (bool) – boolean indicating if the direction is “master to slave”

Returns

tuple composed of (two first bytes of the payload + decrypted payload, boolean indicating if the message’s integrity is valid)

Return type

tuple of (bytes,bool)

displayDetails()

This method displays a chart indicating the session keys’ diversifier, the initializations vectors and the session key. If some values have not been provided or calculated, it displays an error message.

encrypt(payload, masterToSlave=True)

This method encrypts the provided payload, according to the direction provided.

Parameters
  • payload (bytes) – payload to encrypt

  • masterToSlave (bool) – boolean indicating if the direction is “master to slave”

Returns

first two bytes of the payload + ciphertext + message integrity check

Return type

bytes

generateIv()

This method generates the initialization vector according to the provided master’s and slave’s IV.

generateNonce(masterToSlave)

This method generates a nonce.

Parameters

masterToSlave (bool) – boolean indicating if the direction is “master to slave”

Returns

generated nonce

Return type

bytes

generateSessionKey()

This method generates the session key according to the calculted session key diversifier and initialization vector.

generateSkd()

This method generates the session key diversifier according to the provided master’s and slave’s diversifier.

classmethod getInstance()

This class method returns the singleton’s instance of the current class.

Returns

instance of this class

Return type

BLELinkLayerCrypto

incrementMasterCounter()

This method increments the master’s counter.

incrementSlaveCounter()

This method increments the slave’s counter.

classmethod provideLTK(ltk)

This class method initializes a singleton’s instance of the current class. It allows to provide a Long Term Key.

Parameters

ltk (bytes) – Long Term Key

setMasterValues(skd, iv)

This method allows to provide the session key diversifier and the initialization vector from Master.

Parameters
  • skd (bytes) – session key diversifier

  • iv (bytes) – initialization vector

setSlaveValues(skd, iv)

This method allows to provide the session key diversifier and the initialization vector from Slave.

Parameters
  • skd (bytes) – session key diversifier

  • iv (bytes) – initialization vector

tryToDecrypt(payload)

This function tries to decrypt a payload. It tries to guess the direction (master to slave or slave to master) and the right counters’ values.

Parameters

payload (bytes) – payload to decrypt

Returns

tuple composed of (decrypted payload, boolean indicating if the operation was successful)

Return type

tuple of (bytes,bool)

Note

If the operation fails, the decrypted payload field of the tuple is replaced by None

mirage.libs.ble_utils.att_server module

class mirage.libs.ble_utils.att_server.ATT_Attribute(handle=None, value=None, type=None, permissions=None)

Bases: object

This class describes an ATT attribute. An ATT attribute is composed of four main fields :

  • handle : ATT handle (it can be described as the index of an attribute of an ATT Database)

  • value : binary value linked to this attribute

  • type : UUID (12 bits or 128 bits) indicating the type of attribute, such as a Device Name or a Characteristic Declaration.

  • permissions : flag indicating the access permissions attached to this attribute, such as readable or writeable.

It overloads the method __str__ in order to provide a pretty representation.

class mirage.libs.ble_utils.att_server.ATT_Database

Bases: object

This class describes an ATT Database. It acts as a classic Database, and offer multiple primitives in order to manipulate the attributes. The internal representation is just a list containing some ATT_Attribute.

findByTypeValue(start, end, type, value)

This method allows to read a set of groups of attributes according to the handles, type and value provided.

Parameters
  • start (int) – start handle

  • end (int) – end handle

  • type (int or str) – type of attributes

  • value (bytes) – value of attributes

Returns

list of attributes (represented as a dictionary of two fields : attributeHandle and endGroupHandle)

Return type

list of dict

findInformation(start, end)

This method allows to get a set of attributes’ types according to the handles provided.

Parameters
  • start (int) – start handle

  • end (int) – end handle

Returns

list of attributes’ types (represented as a dictionary of two fields : attributeHandle and type)

Return type

list of dict

Example
>>> db.setAttribute(handle=1, value=b"", type="Primary Service",permissions=["Read"])
>>> db.setAttribute(handle=2, value=b"", type="Secondary Service",permissions=["Read"])
>>> db.setAttribute(handle=3, value=b"", type="Primary Service",permissions=["Read"])
>>> db.setAttribute(handle=4, value=b"", type="Primary Service",permissions=["Read"])
>>> db.setAttribute(handle=5, value=b"", type="Secondary Service",permissions=["Read"])
>>> db.findInformation(2,5)
[{'attributeHandle': 2, 'type': b'('}, {'attributeHandle': 3, 'type': b'('}, {'attributeHandle': 4, 'type': b'('}, {'attributeHandle': 5, 'type': b'('}]
>>> db.findInformation(1,3)
[{'attributeHandle': 1, 'type': b'('}, {'attributeHandle': 2, 'type': b'('}, {'attributeHandle': 3, 'type': b'('}]
getNextHandle()

This method returns the next free handle.

Returns

next free handle

Return type

int

Example
>>> db.getNextHandle()
25
read(handle)

This method allows to read the value of a given attribute according to the provided handle.

Parameters

handle (int) – handle of the attribute

Returns

tuple composed of a boolean indicating if the attribute exists, another one indicating if it is readable and the value if possible

Return type

tuple of (bool,bool,bytes)

Example
>>> db = ATT_Database()
>>> db.setAttribute(handle=1, value=b"", type="Primary Service",permissions=["Read"])
>>> db.setAttribute(handle=2, value=b"*", type=0x2803,permissions=b"")
>>> db.read(1)
(True, True, b'')
>>> db.read(2)
(True, False, None)
>>> db.read(3)
(False, False, None)
readByGroupType(start, end, type)

This method allows to read a set of groups of attributes according to the handles and type provided.

Parameters
  • start (int) – start handle

  • end (int) – end handle

  • type (int or str) – type of attributes

Returns

list of attributes (represented as a dictionary of three fields : attributeHandle,*endGroupHandle* and value)

Return type

list of dict

readByType(start, end, type)

This method allows to read a set of attributes according to the handles and type provided.

Parameters
  • start (int) – start handle

  • end (int) – end handle

  • type (int or str) – type of attributes

Returns

list of attributes (represented as a dictionary of two fields : attributeHandle and value)

Return type

list of dict

Example
>>> db.setAttribute(handle=1, value=b"", type="Primary Service",permissions=["Read"])
>>> db.setAttribute(handle=2, value=b"", type="Secondary Service",permissions=["Read"])
>>> db.setAttribute(handle=3, value=b"", type="Primary Service",permissions=["Read"])
>>> db.setAttribute(handle=4, value=b"", type="Primary Service",permissions=["Read"])
>>> db.setAttribute(handle=5, value=b"", type="Secondary Service",permissions=["Read"])
>>> db.readByType(start=1,end=3,type="Primary Service")
[{'attributeHandle': 1, 'value': b''}, {'attributeHandle': 3, 'value': b''}]
>>> db.readByType(start=2,end=5,type=0x2801)
[{'attributeHandle': 2, 'value': b''}, {'attributeHandle': 5, 'value': b''}]
setAttribute(handle=None, value=None, type=None, permissions=None)

This method allows to add or modify an ATT attribute in the ATT Database.

Parameters
  • handle (int) – handle of the attribute

  • value (bytes) – value of the attribute

  • type (int or str) – type of the attribute

  • permissions (int or list of str) – permissions of the attribute

Example
>>> db = ATT_Database()
>>> db.setAttribute(handle=1, value=b"", type="Primary Service",permissions=["Read"])
>>> db.setAttribute(handle=2, value=b"*", type=0x2803,permissions=b"")
>>> db.show()
┌Attributes────────┬────────────────────────────────────────────┬────────────────────────────────────────┐
│ Attribute Handle │ Attribute Type                             │ Attribute Value                        │
├──────────────────┼────────────────────────────────────────────┼────────────────────────────────────────┤
│ 0x0001           │ Primary Service                            │ 0018                                   │
│ 0x0002           │ Characteristic Declaration                 │ 020300002a                             │
└──────────────────┴────────────────────────────────────────────┴────────────────────────────────────────┘
>>> db.setAttribute(handle=1,value=b"",type="Primary Service",permissions=["Read"])
>>> db.show()
┌Attributes────────┬────────────────────────────────────────────┬────────────────────────────────────────┐
│ Attribute Handle │ Attribute Type                             │ Attribute Value                        │
├──────────────────┼────────────────────────────────────────────┼────────────────────────────────────────┤
│ 0x0001           │ Primary Service                            │ 0118                                   │
│ 0x0002           │ Characteristic Declaration                 │ 020300002a                             │
└──────────────────┴────────────────────────────────────────────┴────────────────────────────────────────┘
show()

This method displays a chart to present the ATT level vision of the attributes included in the Database.

showCharacteristics(startHandle, endHandle, title='Characteristics')

This method displays the GATT characteristics described as attributes included in the Database and provide a mechanism to only select the characteristics between two handles (it is mainly used in order to print the characteristics included in a Service).

Parameters
  • startHandle (int) – first ATT handle

  • endHandle (int) – last ATT handle

  • title (str) – Title of the chart

showGATT()

This method displays a chart to present the GATT level vision of the attributes included in the Database.

showServices()

This method displays the GATT services described as attributes included in the Database.

write(handle, value)

This method allows to write a new value in a given attribute according to the provided handle.

Parameters
  • handle (int) – handle of the attribute

  • value (bytes) – new value to write

Returns

tuple composed of a boolean indicating if the attribute exists and another one indicating if it is writeable

Return type

tuple of (bool,bool)

Example
>>> db = ATT_Database()
>>> db.setAttribute(handle=1, value=b"", type="Primary Service",permissions=["Read"])
>>> db.setAttribute(handle=2, value=b"*", type=0x2803,permissions=b"")
>>> db.write(handle=1,value=b"")
(True, False)
>>> db.setAttribute(handle=1, value=b"", type="Primary Service",permissions=["Read","Write"])
>>> db.write(handle=1,value=b"")
(True, True)
>>> db.read(1)
(True, True, b'')
class mirage.libs.ble_utils.att_server.ATT_Server(database=None, mtu=23)

Bases: object

This class is a partial implementation of an ATT Server. The methods provided describe the corresponding requests, and the return value describe the response.

This class uses the ATT_Database class in order to represent the data structure.

addAttribute(handle=None, value=None, type=None, permissions=None)

This method allows to add a new attribute to the ATT Server’s database.

Parameters
  • handle (int) – handle of the attribute

  • value (bytes) – value of the attribute

  • type (int or str) – type of the attribute

  • permissions (int or list of str) – permissions of the attribute

findInformation(start, end)

This method implements the Find Information Request.

Parameters
  • start (int) – start handle included in the Find Information Request

  • end (int) – end handle included in the Find Information Request

Returns

tuple

Return type

tuple of (bool,list of dict)

Note

The returned tuple is composed of two main fields :

  • success : this field is a boolean indicating if the request was successful or not

  • body : this field is the response’s body (list of dict - see output of ATT_Database.findInformation) if the request was successful or an error code (int) if the request was not successful

read(handle)

This method implements the Read Request.

Parameters

handle (int) – handle included in the Read Request

Returns

tuple

Return type

tuple of (bool,bytes or int)

Note

The returned tuple is composed of two main fields :

  • success : this field is a boolean indicating if the request was successful or not

  • body : this field is the response’s body (array of bytes) if the request was successful or the error code (integer) if the request was not successful

readBlob(handle, offset)

This method implements the Read Blob Request.

Parameters

handle (int) – handle included in the Read Blob Request

Returns

tuple

Return type

tuple of (bool,bytes or int)

Note

The returned tuple is composed of two main fields :

  • success : this field is a boolean indicating if the request was successful or not

  • body : this field is the response’s body (array of bytes) if the request was successful or the error code (integer) if the request was not successful

readByGroupType(start, end, type)

This method implements the Read By Group Type Request.

Parameters
  • start (int) – start handle included in the Read By Group Type Request

  • end (int) – end handle included in the Read By Group Type Request

  • type (bytes or int) – type included in the Read By Group Type Request

Returns

tuple

Return type

tuple of (bool,list of dict)

Note

The returned tuple is composed of two main fields :

  • success : this field is a boolean indicating if the request was successful or not

  • body : this field is the response’s body (list of dict - see output of ATT_Database.readByGroupType) if the request was successful or an error code (int) if the request was not successful

readByType(start, end, type)

This method implements the Read By Type Request.

Parameters
  • start (int) – start handle included in the Read By Type Request

  • end (int) – end handle included in the Read By Type Request

  • type (bytes or int) – type included in the Read By Type Request

Returns

tuple

Return type

tuple of (bool,list of dict)

Note

The returned tuple is composed of two main fields :

  • success : this field is a boolean indicating if the request was successful or not

  • body : this field is the response’s body (list of dict - see output of ATT_Database.readByType) if the request was successful or an error code (int) if the request was not successful

setMtu(mtu)

This method allows to set a new MTU Value.

Parameters

mtu (int) – value of Maximum Transfer Unit

Example
>>> server = ATT_Server()
>>> server.setMtu(48)
writeCommand(handle, value)

This method implements the Write Command.

Parameters
  • handle (int) – handle included in the Write Command

  • value (bytes) – value included in the Write Command

Returns

tuple

Return type

tuple of (bool,None)

Note

The returned tuple is composed of two main fields :

  • success : this field is a boolean indicating if the request was successful or not

  • body : this field is the response’s body (None)

writeRequest(handle, value)

This method implements the Write Request.

Parameters
  • handle (int) – handle included in the Write Request

  • value (bytes) – value included in the Write Request

Returns

tuple

Return type

tuple of (bool,int)

Note

The returned tuple is composed of two main fields :

  • success : this field is a boolean indicating if the request was successful or not

  • body : this field is the error code (int) if the request was not successful

class mirage.libs.ble_utils.att_server.GATT_Server(database=None, mtu=23)

Bases: mirage.libs.ble_utils.att_server.ATT_Server

This class inherits from ATT_Server, and provides some GATT level methods in order to easily manipulate GATT layer.

addCharacteristic(uuid, value=b'', declarationHandle=None, valueHandle=None, permissions=['Read', 'Write'])

This method allows to easily add a new characteristic.

Parameters
  • uuid (bytes) – uuid associated to the characteristic

  • value (bytes) – value of the characteristic

  • declarationHandle (int) – declaration handle of the characteristic

  • valueHandle (int) – value handle of the characteristic

  • permissions (list of str) – permissions associated to the characteristic

Note

If no declaration handle is provided, the characteristic declaration is stored as the next available handle. If no value handle is provided, the characteristic value is stored as declaration handle + 1 If no permissions are provided, the characteristic value is stored with “Read” & “Write” permission.

addDescriptor(uuid, value=b'', handle=None, permissions=['Read', 'Write', 'Notify'])

This method allows to easily add a new descriptor.

Parameters
  • uuid (bytes) – uuid associated to the descriptor

  • value (bytes) – value of the descriptor

  • handle (int) – handle of the descriptor

Note

If no handle is provided, the descriptor is stored as the next available handle. If no permissions are provided, the descriptor is stored with “Read”,”Write” and “Notify” permission.

addPrimaryService(uuid, handle=None, permissions=['Read'])

This method allows to easily add a new primary service.

Parameters
  • uuid (bytes) – value stored in the service (associated UUID)

  • handle (int) – start handle of the service

  • permissions (list of str) – permissions associated to the service

Note

If no handle is provided, the service is stored as the next available handle. If no permissions are provided, the service is stored with “Read” permission.

addSecondaryService(uuid, handle=None, permissions=['Read'])

This method allows to easily add a new secondary service.

Parameters
  • uuid (bytes) – value stored in the service (associated UUID)

  • handle (int) – start handle of the service

  • permissions (list of str) – permissions associated to the service

Note

If no handle is provided, the service is stored as the next available handle. If no permissions are provided, the service is stored with “Read” permission.

mirage.libs.ble_utils.dissectors module

class mirage.libs.ble_utils.dissectors.AuthReqFlag(data=b'', length=-1, content={}, *args, **kwargs)

Bases: mirage.libs.wireless_utils.dissectors.Dissector

This class is a dissector for the Authentication Request Flag (Security Manager). It inherits from Dissector.

This dissector uses the data structure dictionary in order to use the following fields as simple attributes :
  • bonding field : boolean indicating if bonding is required

  • mitm field : boolean indicating if MiTM protection is required

  • secureConnections field : boolean indicating if a secure connection is required

  • keypress field : boolean indicating if the keypress mode is required

  • ct2 field : boolean indicating if ct2 is required

Example
>>> AuthReqFlag(bonding=True, mitm=True).data.hex()
'05'
>>> AuthReqFlag(data=data=bytes.fromhex("05"))
AuthReq Flag(0x5,bonding:yes|mitm:yes|secureConnections:no|keypress:no|ct2:no)
build()

This method converts the raw bytes to the corresponding data structure.

Example
>>> dissector.build()
dissect()

This method converts the data structure to the corresponding raw bytes.

Example
>>> dissector.dissect()
class mirage.libs.ble_utils.dissectors.CharacteristicDeclaration(data=b'', length=-1, content={}, *args, **kwargs)

Bases: mirage.libs.wireless_utils.dissectors.Dissector

This class is a dissector for the characteristic declarations (GATT). It inherits from Dissector.

This dissector uses the data structure dictionary in order to use the following fields as simple attributes :
  • UUID field : characteristic’s UUID (see also the following dissector : UUID)

  • permissions field : characteristic’s Permissions Flag (see also the following dissector : PermissionsFlag)

  • valueHandle field : characteristic’s value handle

Example
>>> CharacteristicDeclaration(data=bytes.fromhex('2a00000302'))
Characteristic Declaration( UUID=UUID(128bits:00002a00-0000-1000-8000-00805f9b34fb, 16bits:0x2a00, name:Device Name ) , valueHandle=0x3 , permissionsFlag=Flag(Read))
>>> CharacteristicDeclaration(data=bytes.fromhex('2a00000302')).UUID
UUID(128bits:00002a00-0000-1000-8000-00805f9b34fb, 16bits:0x2a00, name:Device Name )
>>> CharacteristicDeclaration(data=bytes.fromhex('2a00000302')).valueHandle
3
>>> CharacteristicDeclaration(data=bytes.fromhex('2a00000302')).permissionsFlag
Flag(Read)
>>> CharacteristicDeclaration(UUID=UUID(name="Device Name"),valueHandle=0x0003,permissionsFlag=PermissionsFlag(permissions=["Read"])).data.hex()
'2a00000302'
build()

This method converts the raw bytes to the corresponding data structure.

Example
>>> dissector.build()
dissect()

This method converts the data structure to the corresponding raw bytes.

Example
>>> dissector.dissect()
class mirage.libs.ble_utils.dissectors.CharacteristicDescriptor(data=b'', length=-1, content={}, *args, **kwargs)

Bases: mirage.libs.wireless_utils.dissectors.Dissector

This class is a dissector for the characteristic descriptors (GATT). It inherits from Dissector.

This dissector uses the data structure dictionary in order to use the following fields as simple attributes :
  • UUID field : descriptor’s UUID (see also the following dissector : UUID)

Example
>>> CharacteristicDescriptor(data=bytes.fromhex("2901"))
Characteristic Descriptor( UUID=UUID(128bits:00002901-0000-1000-8000-00805f9b34fb, 16bits:0x2901, name:Characteristic User Description ) )
>>> CharacteristicDescriptor(UUID=UUID(UUID16=0x2901)).data.hex()
'2901'
build()

This method converts the raw bytes to the corresponding data structure.

Example
>>> dissector.build()
dissect()

This method converts the data structure to the corresponding raw bytes.

Example
>>> dissector.dissect()
class mirage.libs.ble_utils.dissectors.HIDoverGATTKeystroke(data=b'', length=-1, content={}, *args, **kwargs)

Bases: mirage.libs.wireless_utils.dissectors.Dissector

This class is a dissector for the HID over GATT keystroke payload. It inherits from Dissector.

The following fields are available in the data structure :
  • locale : string indicating the locale (language layout)

  • key : string indicating the key

  • ctrl : boolean indicating if the Ctrl key is pressed

  • alt : boolean indicating if the Alt key is pressed

  • super : boolean indicating if the Super key is pressed

  • shift : boolean indicating if the Shift key is pressed

Example
>>> HIDoverGATTKeystroke(locale="fr",key="a",ctrl=False,gui=False,alt=False,shift=False)
Keystroke(key=a,ctrl=no,alt=no,shift=no,gui=no)
>>> HIDoverGATTKeystroke(locale="fr",key="a",ctrl=False,gui=False,alt=False,shift=False).data.hex()
'0000140000000000'
build()

This method converts the raw bytes to the corresponding data structure.

Example
>>> dissector.build()
dissect()

This method converts the data structure to the corresponding raw bytes.

Example
>>> dissector.dissect()
class mirage.libs.ble_utils.dissectors.InputOutputCapability(data=b'', length=-1, content={}, *args, **kwargs)

Bases: mirage.libs.wireless_utils.dissectors.Dissector

This class is a dissector for the Input Output Capability (Security Manager). It inherits from Dissector.

This dissector uses the data structure dictionary in order to use the following fields as simple attributes :
  • display field : boolean indicating if the device provides a display output

  • yesno field : boolean indicating if the device has yes/no input

  • keyboard field : boolean indicating if the device has a keyboard input

Example
>>> InputOutputCapability(display=True, yesno=False, keyboard=True).data.hex()
'04'
>>> InputOutputCapability(data=data=bytes.fromhex("04"))
Input Output Capability(0x4,keyboard:yes|yesno:no|display:yes)
build()

This method converts the raw bytes to the corresponding data structure.

Example
>>> dissector.build()
dissect()

This method converts the data structure to the corresponding raw bytes.

Example
>>> dissector.dissect()
class mirage.libs.ble_utils.dissectors.KeyDistributionFlag(data=b'', length=-1, content={}, *args, **kwargs)

Bases: mirage.libs.wireless_utils.dissectors.Dissector

This class is a dissector for the Key Distribution Flag (Security Manager). It inherits from Dissector.

This dissector uses the data structure dictionary in order to use the following fields as simple attributes :
  • encKey field : boolean indicating if an encryption key is required (LTK + Ediv + RAND)

  • idKey field : boolean indicating if an identification key is required (IRK + BD_Addr + BD_Addr mode)

  • signKey field : boolean indicating if a signing key is required (CSRK)

  • linkKey field : boolean indicating if a link key is required

Example
>>> KeyDistributionFlag(idKey=True,encKey=True).data.hex()
'03'
>>> KeyDistributionFlag(data=bytes.fromhex("03"))
Key Distribution Flag(0x3,encKey:yes|idKey:yes|signKey:no|linkKey:no)
build()

This method converts the raw bytes to the corresponding data structure.

Example
>>> dissector.build()
dissect()

This method converts the data structure to the corresponding raw bytes.

Example
>>> dissector.dissect()
class mirage.libs.ble_utils.dissectors.PermissionsFlag(data=b'', length=-1, content={}, *args, **kwargs)

Bases: mirage.libs.wireless_utils.dissectors.Dissector

This class is a dissector for the permissions flag (ATT/GATT). It inherits from Dissector.

The following fields are available in the data structure :
  • permissions : field indicating permissions as a list of strings (ex : [‘Write Without Response’, ‘Read’])

The following permissions can be used :
  • “Extended Properties”

  • “Authenticated Signed Writes”

  • “Indicate”

  • “Notify”

  • “Write”

  • “Write Without Response”

  • “Read”

  • “Broadcast”

Example
>>> dissector=PermissionsFlag(permissions=["Write", "Read"])
>>> dissector.data.hex()
'0a'
>>> dissector2=PermissionsFlag(data=bytes.fromhex("0a"))
>>> dissector2.permissions
['Write', 'Read']
>>> for permission in dissector2:
...     print(permission)
...
Write
Read
>>> dissector2.permissions += ["Write Without Response"]
>>> dissector2.data.hex()
'0e'
>>> dissector.data = bytes.fromhex("0e")
>>> dissector.dissect()
>>> dissector.permissions
['Write', 'Write Without Response', 'Read']
build()

This method converts the raw bytes to the corresponding data structure.

Example
>>> dissector.build()
dissect()

This method converts the data structure to the corresponding raw bytes.

Example
>>> dissector.dissect()
class mirage.libs.ble_utils.dissectors.Service(data=b'', length=-1, content={}, *args, **kwargs)

Bases: mirage.libs.wireless_utils.dissectors.Dissector

This class is a dissector for the services (GATT). It inherits from Dissector.

This dissector uses the data structure dictionary in order to use the following fields as simple attributes :
  • UUID field : descriptor’s UUID (see also the following dissector : UUID)

Example
>>> Service(data=bytes.fromhex("1800"))
Service( UUID=UUID(128bits:00001800-0000-1000-8000-00805f9b34fb, 16bits:0x1800, name:Generic Access ) )
>>> Service(data=bytes.fromhex("1800")).UUID
UUID(128bits:00001800-0000-1000-8000-00805f9b34fb, 16bits:0x1800, name:Generic Access )
>>> Service(UUID=UUID(UUID16=0x1800)).data.hex()
'1800'
build()

This method converts the raw bytes to the corresponding data structure.

Example
>>> dissector.build()
dissect()

This method converts the data structure to the corresponding raw bytes.

Example
>>> dissector.dissect()
class mirage.libs.ble_utils.dissectors.UUID(data=b'', length=-1, content={}, *args, **kwargs)

Bases: mirage.libs.wireless_utils.dissectors.Dissector

This class inherits from Dissector, and allows to quicky and easily use UUID (Universally Unique IDentifier). It provides a way to convert them into their multiple forms.

This dissector uses the data structure dictionary in order to use the following fields as simple attributes :
  • UUID16 field : UUID (16 bits)

  • UUID128 field : UUID (128 bits)

  • name field : name

Example
>>> UUID(name="Generic Access").data.hex()
'1800'
>>> UUID(data=bytes.fromhex('1800')).name
'Generic Access'
>>> UUID(data=bytes.fromhex('1800')).UUID16
6144
>>> UUID(data=bytes.fromhex('1800')).UUID128.hex()
'0000180000001000800000805f9b34fb'
>>> UUID(data=bytes.fromhex('1801'))
UUID(128bits:00001801-0000-1000-8000-00805f9b34fb, 16bits:0x1801, name:Generic Attribute )
build()

This method converts the raw bytes to the corresponding data structure.

Example
>>> dissector.build()
dissect()

This method converts the data structure to the corresponding raw bytes.

Example
>>> dissector.dissect()

mirage.libs.ble_utils.helpers module

This module provides some helpers in order to manipulate Bluetooth Low Energy link layer packets.

mirage.libs.ble_utils.helpers.channelToFrequency(channel)

This function converts a BLE channel to the corresponding frequency.

Parameters

channel (int) – BLE channel to convert

Returns

corresponding frequency (MHz)

Return type

int

Example
>>> channelToFrequency(37)
2402
>>> channelToFrequency(8)
2420
mirage.libs.ble_utils.helpers.crc24(data, length, init=5592405)

This function calculates the 24 bits CRC corresponding to the data provided.

Parameters
  • data (bytes) – packet’s payload

  • length (int) – length of data

  • init (int) – initialization value

Returns

24 bits crc value

Return type

bytes

Example
>>> data=bytes.fromhex("0215110006000461ca0ce41b1e430559ac74e382667051")
>>> crc24(data=data,length=len(data)).hex()
'545d96'
mirage.libs.ble_utils.helpers.frequencyToChannel(frequency)

This function converts a frequency to the corresponding BLE channel.

Parameters

frequency (int) – frequency to convert (MHz)

Returns

channel associated to the provided frequency

Return type

int

Example
>>> frequencyToChannel(2420)
8
>>> frequencyToChannel(2402)
37
mirage.libs.ble_utils.helpers.isAccessAddressValid(aa)

This function checks if the provided access address is valid.

Parameters

aa (int) – access address to validate

Returns

boolean indicating if the access address provided is valid

Return type

bool

Example
>>> isAccessAddressValid(0x870ac713)
True
>>> isAccessAddressValid(0xcc0bcc1a)
False
mirage.libs.ble_utils.helpers.rssiToDbm(rssi)

This function converts a RSSI (Received Signal Strength Indication) to a value in Dbm.

Parameters

rssi (int) – rssi to convert

Returns

corresponding value in Dbm

Return type

float

Example
>>> rssiToDbm(12)
-45.0
>>> rssiToDbm(30)
-28.8

mirage.libs.ble_utils.packets module

class mirage.libs.ble_utils.packets.BLEAdvDirectInd(srcAddr='00:00:00:00:00:00', srcAddrType='public', dstAddr='00:00:00:00:00:00', dstAddrType='public')

Bases: mirage.libs.ble_utils.packets.BLEAdvertisement

Mirage Bluetooth Low Energy Packet - ADV_DIRECT_IND

Parameters
  • srcAddr (str) – BD address of the emitter

  • dstAddr (str) – BD address of the receiver

Note

This class inherits from BLEAdvertisement.

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEAdvInd(addr='00:00:00:00:00:00', addrType='public', data=b'')

Bases: mirage.libs.ble_utils.packets.BLEAdvertisement

Mirage Bluetooth Low Energy Packet - ADV_IND

Parameters
  • addr (str) – BD address of the emitter

  • data (bytes) – bytes indicating the data included in the Advertisement packet

Note

This class inherits from BLEAdvertisement.

class mirage.libs.ble_utils.packets.BLEAdvNonConnInd

Bases: mirage.libs.ble_utils.packets.BLEAdvertisement

Mirage Bluetooth Low Energy Packet - ADV_NONCONN_IND

Note

This class inherits from BLEAdvertisement.

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEAdvScanInd

Bases: mirage.libs.ble_utils.packets.BLEAdvertisement

Mirage Bluetooth Low Energy Packet - ADV_SCAN_IND

Note

This class inherits from BLEAdvertisement.

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEAdvertisement(addr='00:00:00:00:00:00', type='ADV_IND', addrType='public', data=b'', intervalMin=200, intervalMax=210)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Advertisement

Parameters
  • addr (str) – BD address of the emitter

  • type (str) – type of Advertisement (“ADV_IND”, “ADV_NONCONN_IND” …)

  • addrType (str) – type of BD address used by the emitter (“public” or “random”)

  • data (bytes) – bytes indicating the data included in the Advertisement packet

  • intervalMin (int) – minimal interval of advertisement

  • intervalMax (int) – maximal interval of advertisement

Note

Some other classes inherits from this class, allowing to adapt the content of the Packet.

getRawDatas()

This method returns the raw data : indeed, some devices provides a scapy representation in the data field, and this method can be used to convert it into a list of bytes.

Example
>>> device.getRawDatas()
b' [...]
toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEConnect(dstAddr='00:00:00:00:00:00', srcAddr='00:00:00:00:00:00', type='public', initiatorType='public')

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Connect

Parameters
  • dstAddr (str) – destination BD Address (format: 1A:22:33:44:55:66)

  • srcAddr (str) – source BD Address (format: 1A:22:33:44:55:66)

  • type (str) – string indicating if the responder’s address is in public (“public”) or random (“random”) mode.

  • initiatorType (str) – string indicating if the initiator’s address is in public (“public”) or random (“random”) mode.

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEConnectRequest(srcAddr='00:00:00:00:00:00', dstAddr='00:00:00:00:00:00', srcAddrType='public', dstAddrType='public', accessAddress=2391391958, crcInit=0, winSize=0, winOffset=0, hopInterval=0, latency=0, timeout=0, channelMap=0, SCA=0, hopIncrement=0, data=None)

Bases: mirage.libs.ble_utils.packets.BLEAdvertisement

Mirage Bluetooth Low Energy Packet - SCAN_RSP

Parameters
  • srcAddr (str) – BD address of the emitter

  • dstAddr (str) – BD address of the receiver

  • srcAddrType (str) – type of BD address used by the emitter (“public” or “random”)

  • dstAddrType (str) – type of BD address used by the receiver (“public” or “random”)

  • accessAddress (int) – access address associated to the connection

  • crcInit (int) – CRCInit associated to the connection

  • winSize (int) – window’s size associated to the connection

  • winOffset (int) – window’s offset associated to the connection

  • hopInterval (int) – Hop Interval associated to the connection

  • latency (int) – latency associated to the connection

  • timeout (int) – timeout associated to the connection

  • channelMap (int) – channel Map associated to the connection

  • SCA (int) – SCA associated to the connection

  • hopIncrement (int) – Hop increment associated to the connection

  • data (bytes) – data associated to this advertisement packet

Note

This class inherits from BLEAdvertisement.

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEConnectResponse(dstAddr='00:00:00:00:00:00', srcAddr='00:00:00:00:00:00', type='public', success=True, role='', interval=0)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Connect Response

Parameters
  • dstAddr (str) – destination BD Address (format: 1A:22:33:44:55:66)

  • srcAddr (str) – source BD Address (format: 1A:22:33:44:55:66)

  • type (str) – string indicating if the responder’s address is in public (“public”) or random (“random”) mode.

  • success (bool) – boolean indicating if the operation was successful

  • role (str) – string indicating the role (“master” or “slave”) of the initiator

  • interval (int) – integer indicating the interval

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEConnectionCancel

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Connection Cancel

class mirage.libs.ble_utils.packets.BLEConnectionParameterUpdateRequest(minInterval=0, maxInterval=0, slaveLatency=0, timeoutMult=0, connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Connection Parameter Update Request

Parameters
  • timeoutMult (int) – timeout Multiplier

  • slaveLatency (int) – slave Latency

  • minInterval (int) – minimal Interval

  • maxInterval (int) – maximal Interval

  • connectionHandle (int) – connection handle associated to the connection

Example
>>> emitter.sendp(ble.BLEConnectionParameterUpdateRequest(timeoutMult=65535, minInterval=65535, maxInterval=65535, slaveLatency=0))
toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEConnectionParameterUpdateResponse(moveResult=0, connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Connection Parameter Update Response

Parameters
  • moveResult (int) – move Result

  • connectionHandle (int) – connection handle associated to the connection

Example
>>> emitter.sendp(ble.BLEConnectionParameterUpdateResponse(moveResult=0))
toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEControlPDU(type=None, data=b'')

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Control PDU

Parameters
  • type (str) – string indicating the type of control PDU (“LL_ENC_REQ”, “LL_ENC_RESP” …)

  • data (bytes) – data associated to the Packet

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEDisconnect(connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Disconnect

Parameters

connectionHandle (int) – connection handle associated to the connection to terminate

class mirage.libs.ble_utils.packets.BLEEmptyPDU

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Empty PDU

class mirage.libs.ble_utils.packets.BLEEncryptedPacket(connectionHandle=-1, data=b'')

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Encrypted Packet This class is an abstraction : it provides a way to solve the problems linked to the encryption. In Mirage, an encrypted packet is just another Mirage Packet, allowing to manipulate it easily.

Parameters
  • connectionHandle (int) – connection handle of the connection actually established.

  • data (bytes) – encrypted datas associated to the Packet

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEEncryptionInformation(connectionHandle=-1, ltk=b'x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00')

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Encryption Information

Parameters
  • connectionHandle (int) – connection handle associated to the connection

  • ltk (bytes) – Long Term Key

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEErrorResponse(request=0, handle=0, ecode=0, connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Error Request

Parameters
  • request (int) – Request opcode

  • handle (int) – ATT handle linked to the error

  • ecode (int) – error code

  • connectionHandle (int) – connection handle associated to the connection

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEExchangeMTURequest(mtu=0, connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Exchange MTU Request

Parameters
  • mtu (float) – float indicating the Maximum transmission unit

  • connectionHandle – connection handle of the connection actually established.

class mirage.libs.ble_utils.packets.BLEExchangeMTUResponse(mtu=0, connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Exchange MTU Response

Parameters
  • mtu (float) – float indicating the Maximum transmission unit

  • connectionHandle – connection handle of the connection actually established.

class mirage.libs.ble_utils.packets.BLEFindInformationRequest(startHandle=0, endHandle=65535, connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Find Information Request

Parameters
  • startHandle (int) – lowest ATT handle included in the request

  • endHandle (int) – highest ATT handle included in the request

  • connectionHandle (int) – connection handle associated to the connection

class mirage.libs.ble_utils.packets.BLEFindInformationResponse(format=0, data=b'', attributes=[], connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Find Information Response

Parameters
  • data (bytes) – data included in the Information Response

  • attributes (list of dict) – list indicating the ATT attributes contained in the Information Response

  • format (int) – integer indicating the format of the response (0x1 : short UUID (16 bits), 0x2 : long UUID (128bits))

  • connectionHandle (int) – connection handle associated to the connection

Example
>>> BLEFindInformationResponse(data=bytes.fromhex('0f000229')).attributes
[{'attributeHandle': 15, 'type': b')'}]
>>> BLEFindInformationResponse(attributes=[{'attributeHandle': 15, 'type': b')'}]).data.hex()
'0f000229'

Note

Please note the following behaviour :
  • If only the data is provided, the attributes list is automatically generated (thanks to the decode method.)

  • If the attributes are provided, the corresponding data is automatically generated (thanks to the build method)

An attribute is described as a dictionary composed of two fields :
  • attributeHandle : indicating the handle of the corresponding ATT attribute

  • type : indicating the UUID (type of the ATT attribute)

Example : {"attributeHandle":0x0001, "type":type}

build()

This method generates the data from the attributes list.

decode()

This method generates the attributes list from the data.

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEHandleValueConfirmation(connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Handle Value Confirmation

Parameters

connectionHandle (int) – connection handle associated to the connection

Example
>>> emitter.sendp(ble.BLEHandleValueConfirmation())
toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEHandleValueIndication(handle=0, value=b'', connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Handle Value Indication

Parameters
  • handle (int) – ATT value handle indicating the attribute linked to the indication

  • value (bytes) – new value to notify

  • connectionHandle (int) – connection handle associated to the connection

Example
>>> emitter.sendp(ble.BLEHandleValueIndication(handle=0x0021, value=b""))
>>> emitter.sendp(ble.BLEHandleValueIndication(handle=0x0021, value=b""))
toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEHandleValueNotification(handle=0, value=b'', connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Handle Value Notification

Parameters
  • handle (int) – ATT value handle indicating the attribute linked to the notification

  • value (bytes) – new value to notify

  • connectionHandle (int) – connection handle associated to the connection

Example
>>> emitter.sendp(ble.BLEHandleValueNotification(handle=0x0021, value=b""))
>>> emitter.sendp(ble.BLEHandleValueNotification(handle=0x0021, value=b""))
toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEIdentityAddressInformation(connectionHandle=-1, type='public', address='00:00:00:00:00:00')

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Identity Address Information

Parameters
  • connectionHandle (int) – connection handle associated to the connection

  • type (str) – string indicating if the associated BD address is random (“random”) or public (“public”)

  • address (str) – string indicating the BD address

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEIdentityInformation(connectionHandle=-1, irk=b'x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00')

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Identity Information

Parameters
  • connectionHandle (int) – connection handle associated to the connection

  • irk (bytes) – Identity Resolving Key

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLELongTermKeyRequest(connectionHandle=-1, rand=b'x00x00x00x00x00x00x00x00', ediv=0, ltk=b'x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00')

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Long Term Key Request

Parameters
  • rand (bytes) – random value associated to this Long Term Key

  • ediv (integer) – EDIV value associated to this Long Term Key

  • ltk (bytes) – Long Term Key

  • connectionHandle (int) – connection handle associated to the connection

Example
>>> emitter.sendp(ble.BLELongTermKeyRequest(ltk=bytes.fromhex("000102030405060708090a0b0c0d0e0f"))
toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLELongTermKeyRequestReply(connectionHandle=-1, positive=False, ltk=b'x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00')

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Long Term Key Request Reply

Parameters
  • positive (bool) – boolean indicating if the LTK Request was accepted (positive=True) or rejected (positive=False)

  • ltk (bytes) – Long Term Key

  • connectionHandle (int) – connection handle associated to the connection

Example
>>> emitter.sendp(ble.BLELongTermKeyRequestReply(ltk=bytes.fromhex("000102030405060708090a0b0c0d0e0f"), positive=True))
toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEMasterIdentification(connectionHandle=-1, ediv=0, rand=b'x00x00x00x00x00x00x00x00')

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Encryption Information

Parameters
  • connectionHandle (int) – connection handle associated to the connection

  • rand (bytes) – random value associated to the Long Term Key

  • ediv (integer) – EDIV value associated to the Long Term Key

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEPacket

Bases: mirage.libs.wireless_utils.packets.Packet

Mirage Bluetooth Low Energy Packet

class mirage.libs.ble_utils.packets.BLEPairingConfirm(connectionHandle=-1, confirm=b'x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00')

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Pairing Confirm

Parameters
  • connectionHandle (int) – connection handle associated to the connection

  • confirm (bytes) – confirmation value

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEPairingFailed(connectionHandle=-1, reason=0)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Pairing Failed

Parameters
  • connectionHandle (int) – connection handle associated to the connection

  • reason (int) – integer indicating the reason of failure

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEPairingRandom(connectionHandle=-1, random=b'x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00')

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Pairing Random

Parameters
  • connectionHandle (int) – connection handle associated to the connection

  • random (bytes) – random value

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEPairingRequest(connectionHandle=-1, outOfBand=False, inputOutputCapability=0, maxKeySize=16, authentication=b'x00', initiatorKeyDistribution=b'x00', responderKeyDistribution=b'x00', payload=b'')

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Pairing Request

Parameters
  • connectionHandle (int) – connection handle associated to the connection

  • outOfBand (bool) – boolean indicating if out of band is available

  • inputOutputCapability (int) – integer indicating the input output capability of Central

  • maxKeySize (int) – integer indicating the maximum key size

  • authentication (bytes) – flags indicating the authentication parameters requested

  • initiatorKeyDistribution (bytes) – bytes indicating the initiator key distribution

  • responderKeyDistribution (bytes) – bytes indicating the responder key distribution

  • payload (bytes) – bytes indicating the payload of request

Note

Some dissectors are provided in order to fill the fields included in this packet :

  • mirage.libs.ble_utils.dissectors.AuthReqFlag : authentication field

  • mirage.libs.ble_utils.dissectors.InputOutputCapability : input output capability field

  • mirage.libs.ble_utils.dissectors.KeyDistributionFlag : initiatorKeyDistribution and responderKeyDistribution fields

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEPairingResponse(connectionHandle=-1, outOfBand=0, inputOutputCapability=0, maxKeySize=16, authentication=0, initiatorKeyDistribution=0, responderKeyDistribution=0, payload=b'')

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Pairing Response

Parameters
  • connectionHandle (int) – connection handle associated to the connection

  • outOfBand (bool) – boolean indicating if out of band is available

  • inputOutputCapability (int) – integer indicating the input output capability of Peripheral

  • maxKeySize (int) – integer indicating the maximum key size

  • authentication (bytes) – flags indicating the authentication parameters requested

  • initiatorKeyDistribution (bytes) – bytes indicating the initiator key distribution

  • responderKeyDistribution (bytes) – bytes indicating the responder key distribution

  • payload (bytes) – bytes indicating the payload of response

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEReadBlobRequest(handle=0, offset=0, connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Read Blob Request

Parameters
  • handle (int) – ATT value handle indicating the attribute linked to the request

  • offset (int) – offset of the value to read

  • connectionHandle (int) – connection handle associated to the connection

Example
>>> emitter.sendp(ble.BLEReadBlobRequest(handle=0x0021, offset=26))
toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEReadBlobResponse(value=b'', connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Read Blob Response

Parameters
  • value (bytes) – ATT value

  • connectionHandle (int) – connection handle associated to the connection

Example
>>> emitter.sendp(ble.BLEReadBlobResponse(value=bytes.fromhex("01020304")))
toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEReadByGroupTypeRequest(startHandle=0, endHandle=65535, uuid=0, connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Read By Group Type Request

Parameters
  • startHandle (int) – lowest ATT handle included in the request

  • endHandle (int) – highest ATT handle included in the request

  • uuid (int) – UUID indicating a given type

  • connectionHandle (int) – connection handle associated to the connection

class mirage.libs.ble_utils.packets.BLEReadByGroupTypeResponse(length=6, data=b'', attributes=[], connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Read By Group Type Response

Parameters
  • data (bytes) – data included in the Read By Group Type Response

  • attributes (list of dict) – list indicating the ATT group type of attributes contained in the Read By Group Type Response

  • length (int) – integer indicating the length (in number of bytes) corresponding to one range of attributes providing the same value

  • connectionHandle (int) – connection handle associated to the connection

Example
>>> BLEReadByGroupTypeResponse(data=bytes.fromhex('01000b0000180c000f00011810001e000a18')).attributes
[{'attributeHandle': 1, 'endGroupHandle': 11, 'value': b''}, {'attributeHandle': 12, 'endGroupHandle': 15, 'value': b''}, {'attributeHandle': 16, 'endGroupHandle': 30, 'value': b''}]
>>> BLEReadByGroupTypeResponse(attributes=[{'attributeHandle': 1, 'endGroupHandle': 11, 'value': b''},{'attributeHandle': 12, 'endGroupHandle': 15, 'value': b''}, {'attributeHandle': 16, 'endGroupHandle': 30, 'value':b'\n'}]).data.hex()
'01000b0000180c000f00011810001e000a18'

Note

Please note the following behaviour :

  • If only the data is provided, the group type list is automatically generated (thanks to the decode method.)

  • If the attributes are provided, the corresponding data is automatically generated (thanks to the build method)

A group type of attribute is described as a dictionary composed of three fields :

  • attributeHandle : indicating the lowest handle of the corresponding ATT group type

  • value : indicating the value of the ATT attribute

  • endGroupHandle : indicating the highest handle of the corresponding ATT group type

Example : {'attributeHandle': 1, 'endGroupHandle': 11, 'value': b'\'}

build()
decode()
toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEReadByTypeRequest(startHandle=0, endHandle=65535, uuid=0, connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Read By Type Request

Parameters
  • startHandle (int) – lowest ATT handle included in the request

  • endHandle (int) – highest ATT handle included in the request

  • uuid (int) – UUID indicating a given type

  • connectionHandle (int) – connection handle associated to the connection

class mirage.libs.ble_utils.packets.BLEReadByTypeResponse(data=b'', attributes=[], connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Read By Type Response

Parameters
  • data (bytes) – data included in the Read By Type Response

  • attributes (list of dict) – list indicating the attributes contained in the Read By Type Response

  • connectionHandle (int) – connection handle associated to the connection

Example
>>> BLEReadByTypeResponse(data=bytes.fromhex("152900102a0018d3dd5ce93dd08951403448f4ffb3a8")).attributes
[{'attributeHandle': 41, 'value': b'*ÓÝ\é=ЉQ@4Hôÿ³¨'}]
>>> BLEReadByTypeResponse(attributes=[{'attributeHandle': 41, 'value': b'*ÓÝ\é=ЉQ@4Hôÿ³¨'}]).data.hex()
'152900102a0018d3dd5ce93dd08951403448f4ffb3a8'

Note

Please note the following behaviour :

  • If only the data is provided, the list of attributes is automatically generated (thanks to the decode method.)

  • If the attributes are provided, the corresponding data is automatically generated (thanks to the build method)

An attribute is described as a dictionary composed of two fields :

  • attributeHandle : indicating the handle of the ATT attribute

  • value : indicating the value of the ATT attribute

Example : {'attributeHandle': 1, 'value': b'\'}

build()
decode()
toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEReadRequest(handle=0, connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Read Request

Parameters
  • handle (int) – ATT handle indicating the attribute to read

  • connectionHandle (int) – connection handle associated to the connection

Example
>>> emitter.sendp(ble.BLEReadRequest(handle=0x0021))
toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEReadResponse(value=b'', connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Read Response

Parameters
  • value (bytes) – value read and transmitted to Central

  • connectionHandle (int) – connection handle associated to the connection

Example
>>> emitter.sendp(ble.BLEReadResponse(value=b"ª»ÌÝ"))
toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEScanRequest(srcAddr='00:00:00:00:00:00', srcAddrType='public', dstAddr='00:00:00:00:00:00', dstAddrType='public')

Bases: mirage.libs.ble_utils.packets.BLEAdvertisement

Mirage Bluetooth Low Energy Packet - SCAN_REQ

Parameters
  • srcAddr (str) – BD address of the emitter

  • dstAddr (str) – BD address of the receiver

Note

This class inherits from BLEAdvertisement.

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEScanResponse(addr='00:00:00:00:00:00', addrType='public', data=b'')

Bases: mirage.libs.ble_utils.packets.BLEAdvertisement

Mirage Bluetooth Low Energy Packet - SCAN_RSP

Parameters
  • srcAddr (str) – BD address of the emitter

  • data (bytes) – bytes indicating the data included in the Advertisement packet

Note

This class inherits from BLEAdvertisement.

class mirage.libs.ble_utils.packets.BLESecurityRequest(connectionHandle=-1, authentication=b'x00')

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Security Request

Parameters
  • connectionHandle (int) – connection handle associated to the connection

  • authentication (bytes) – flags indicating the authentication parameters requested

Note

Some dissectors are provided in order to fill the fields included in this packet :

  • mirage.libs.ble_utils.dissectors.AuthReqFlag : authentication field

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLESigningInformation(connectionHandle=-1, csrk=b'x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00x00')

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Signing Information

Parameters
  • connectionHandle (int) – connection handle associated to the connection

  • csrk (bytes) – Connection Signature Resolving Key

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLESniffingParameters(rssi=None, rssi_min=0, rssi_max=0, rssi_avg=0, rssi_count=0, clk_100ns=0, clkn_high=0, direction=None, channel=None, frequency=None)

Bases: mirage.libs.wireless_utils.packets.AdditionalInformations

This class allows to attach some sniffer’s data to a Mirage BLE Packet, such as RSSI or channel. If the frequency is provided, the corresponding channel is automatically calculated.

Parameters
  • rssi (float) – Received Signal Strength Indication

  • rssi_min (float) – Received Signal Strength Indication (min. value)

  • rssi_max (float) – Received Signal Strength Indication (max. value)

  • rssi_avg (float) – Received Signal Strength Indication (average value)

  • clk_high (float) – clock’s value (high)

  • clk_100ns – clock’s value (100ns)

  • direction (str) – direction of the packet (“master->slave” or “slave->master”)

  • channel (int) – channel of the received packet

  • frequency (float) – frequency of the received packet

toString()
class mirage.libs.ble_utils.packets.BLEWriteCommand(handle=0, value=b'', connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Write Command

Parameters
  • handle (int) – ATT value handle indicating the attribute to write

  • value (bytes) – new value to write

  • connectionHandle (int) – connection handle associated to the connection

Example
>>> emitter.sendp(ble.BLEWriteCommand(handle=0x0021, value=b""))

Note

This Packet is similar to BLEWriteRequest but it doesn’t need a Write Response

toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEWriteRequest(handle=0, value=b'', connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Write Request

Parameters
  • handle (int) – ATT value handle indicating the attribute to write

  • value (bytes) – new value to write

  • connectionHandle (int) – connection handle associated to the connection

Example
>>> emitter.sendp(ble.BLEWriteRequest(handle=0x0021, value=b""))
toString()

This method allows to explicitely define how a packet is displayed if it is converted as a string.

If this method is not overloaded, the packet is displayed as :
  • << name >> if no additional informations are linked to this packet

  • [ additionalInformations ] << name >> if some additional informations are linked to this packet

class mirage.libs.ble_utils.packets.BLEWriteResponse(connectionHandle=-1)

Bases: mirage.libs.ble_utils.packets.BLEPacket

Mirage Bluetooth Low Energy Packet - Write Response

Parameters

connectionHandle (int) – connection handle associated to the connection

Example
>>> emitter.sendp(ble.BLEWriteResponse()) # note : the connectionHandle is not provided because its value is direcly modified by the Device

mirage.libs.ble_utils.scapy_hci_layers module

This module contains some scapy definitions for communicating with an HCI device.

mirage.libs.ble_utils.scapy_btlejack_layers module

This module contains some scapy definitions for communicating with a BTLEJack device.