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_MASTER
no
HIJACKING_SLAVE
no
INJECTING
no
MITMING_EXISTING_CONNECTION
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
-
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_MASTER
no
HIJACKING_SLAVE
no
INJECTING
no
MITMING_EXISTING_CONNECTION
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
-
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_MASTER
no
HIJACKING_SLAVE
no
INJECTING
no
MITMING_EXISTING_CONNECTION
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
-
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_MASTER
yes
HIJACKING_SLAVE
no
INJECTING
no
MITMING_EXISTING_CONNECTION
no
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.
-
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_MASTER
no
HIJACKING_SLAVE
no
INJECTING
no
MITMING_EXISTING_CONNECTION
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.
-
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_MASTER
no
HIJACKING_SLAVE
no
INJECTING
no
MITMING_EXISTING_CONNECTION
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.
-
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.sniffle module¶
-
class
mirage.libs.ble_utils.sniffle.
SniffleDevice
(interface)¶ Bases:
mirage.libs.wireless_utils.device.Device
This device allows to communicate with a Sniffle Device in order to sniff Bluetooth Low Energy protocol. The corresponding interfaces are :
sniffleX
(e.g. “sniffle0”)The following capabilities are actually supported :
Capability
Available ?
SCANNING
yes
ADVERTISING
yes
SNIFFING_ADVERTISEMENTS
yes
SNIFFING_NEW_CONNECTION
yes
SNIFFING_EXISTING_CONNECTION
no
JAMMING_CONNECTIONS
no
JAMMING_ADVERTISEMENTS
no
INJECTING
no
MITMING_EXISTING_CONNECTION
no
HIJACKING_MASTER
no
HIJACKING_SLAVE
no
INITIATING_CONNECTION
yes
RECEIVING_CONNECTION
no
COMMUNICATING_AS_MASTER
yes
COMMUNICATING_AS_SLAVE
no
HCI_MONITORING
no
-
close
()¶ This method closes the device.
-
classmethod
findSniffleSniffers
(index=None)¶ This class method allows to find a specific Sniffle 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.findSniffleSniffers(0) '/dev/ttyACM0' >>> NRFSnifferDevice.findSniffleSniffers() ['/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.
-
getAddress
()¶ This method returns the actual BD address of the device.
- Returns
str indicating the BD address
- Return type
str
- Example
>>> device.getAddress() '1A:2B:3C:4D:5E:6F'
Note
This method is a shared method and can be called from the corresponding Emitters / Receivers.
-
getAddressMode
()¶ This method returns the address mode currently in use.
- Returns
address mode (“public” or “random”)
- Return type
str
- Example
>>> device.getAddressMode() 'public'
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 Sniffle 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 Sniffle device.
- Returns
firmware version
- Return type
int
- Example
>>> device.getFirmwareVersion() (1,5)
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 the device is connected.
- Returns
boolean indicating if the device is connected
- 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
-
recv
()¶ This method receives some datas. If no data is available, this method returns None.
- Parameters
data – raw representation of the received data
-
send
(pkt)¶ This method sends some datas.
- Parameters
data – raw representation of the data to send
-
setAddress
(address, random=False)¶ This method allows to modify the BD address and the BD address type of the device, if it is possible.
- Parameters
address (str) – new BD address
random (bool) – boolean indicating if the address is random
- Returns
boolean indicating if the operation was successful
- Return type
bool
- Example
>>> device.setAddress("11:22:33:44:55:66") True
Note
This method is a shared method and can be called from the corresponding Emitters / Receivers.
-
setAdvertising
(enable=True)¶ This method enables or disables the advertising mode.
- Parameters
enable (bool) – boolean indicating if the advertising mode must be enabled
- Example
>>> device.setAdvertising(enable=True) # advertising mode enabled >>> device.setAdvertising(enable=False) # advertising mode disabled
Warning
Please note that if no advertising and scanning data has been provided before this function call, nothing will be advertised. You have to set the scanning Parameters and the advertising Parameters before calling this method.
Note
This method is a shared method and can be called from the corresponding Emitters / Receivers.
-
setAdvertisingParameters
(type='ADV_IND', destAddr='00:00:00:00:00:00', data=b'', intervalMin=200, intervalMax=210, daType='public', oaType='public')¶ This method sets advertising parameters according to the data provided. It will mainly be used by ADV_IND-like packets.
- Parameters
type (str) – type of advertisement (available values : “ADV_IND”, “ADV_DIRECT_IND”, “ADV_SCAN_IND”, “ADV_NONCONN_IND”, “ADV_DIRECT_IND_LOW”)
destAddress (str) – destination address (it will be used if needed)
data (bytes) – data included in the payload
intervalMin (int) – minimal interval
intervalMax (int) – maximal interval
daType (str) – string indicating the destination address type (“public” or “random”)
oaType – string indicating the origin address type (“public” or “random”)
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
Sniffle 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.
-
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.
-
setScanningParameters
(data=b'')¶ This method sets scanning parameters according to the data provided. It will mainly be used by SCAN_RESP packets.
- Parameters
data (bytes) – data to use in SCAN_RESP
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.
-
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.
-
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.
-
updateConnectionParameters
(minInterval=0, maxInterval=0, latency=0, timeout=0, minCe=0, maxCe=65535)¶ This method allows to update connection parameters according to the data provided. It will mainly be used if an incoming BLEConnectionParameterUpdateRequest is received.
- Parameters
minInterval (int) – minimal interval
maxInterval (int) – maximal interval
latency (int) – connection latency
timeout (int) – connection timeout
minCe (int) – minimum connection event length
maxCe (int) – maximum connection event length
Note
This method is a shared method and can be called from the corresponding Emitters / Receivers.
-
mirage.libs.ble_utils.butterfly module¶
-
class
mirage.libs.ble_utils.butterfly.
BLEButterflyDevice
(interface)¶ Bases:
mirage.libs.wireless_utils.butterfly.ButterflyDevice
This device allows to communicate with a ButteRFly Device in order to interact with Bluetooth Low Energy protocol. The corresponding interfaces are :
butterflyX
(e.g. “butterfly0”)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
INJECTING
yes
MITMING_EXISTING_CONNECTION
yes
HIJACKING_MASTER
yes
HIJACKING_SLAVE
yes
INITIATING_CONNECTION
no
RECEIVING_CONNECTION
no
COMMUNICATING_AS_MASTER
no
COMMUNICATING_AS_SLAVE
no
HCI_MONITORING
no
-
attachSubDevice
(subDevice, identifier)¶ This method allows to attach a given subdevice to the current ButteRFly device.
- Parameters
subDevice (BLEButterflySubdevice) – sub device instance
identifier (str) – string indicating if the subdevice communicates as a Master (“master”) or as a Slave (“slave”)
Note
This method is called directly by the subdevice, it is not intended to be used directly.
-
close
()¶ This method closes the device.
-
detachSubDevice
(identifier)¶ This method allows to detach a given subdevice.
- Parameters
identifier (str) – string indicating the subdevice to detach (“master” or “slave”)
Note
This method is called directly by the subdevice, it is not intended to be used directly.
-
disableController
()¶ This method disables the current controller.
-
enableController
()¶ This method enables the current controller.
-
classmethod
get
(interface)¶ This class method implements the Register device pattern. According to the interface parameter, only one instance of a given specific device will be instanciated if multiple Emitters and/or Receivers tries to access it.
-
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.
-
getController
()¶ This method returns the controller used by the current Butterfly device.
- Returns
controller in use
- Return type
str
- Example
>>> device.getController() 'BLE'
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 Butterfly 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 Butterfly device.
- Returns
firmware version as a tuple of (major, minor)
- Return type
tuple of (int,int)
- Example
>>> device.getFirmwareVersion() (1,0)
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.
-
getSubInterfaces
()¶ This method returns the interfaces of the available subdevices.
- Returns
a tuple of strings linked to the available interfaces
- Return type
(str,str)
- Example
>>> device.getSubInterfaces()
Note
This method is a shared method and can be called from the corresponding Emitters / Receivers.
-
hasCapabilities
(*capability)¶ This method allows to check if the device implements some specific capabilities.
- Parameters
*capability (str (multiple)) – capabilities to check
- Returns
boolean indicating if the device implements the capabilities provided
- Return type
bool
- Example
>>> device.capabilities = ["SNIFFING", "INJECTING", "CHANGING_ADDRESS"] >>> device.hasCapabilities("SNIFFING", "INJECTING") True >>> device.hasCapabilities("MAKING_COFFEE") False
-
init
()¶ This method initializes the device.
-
instances
= {}¶
-
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.
-
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
-
publish
(event, *args, **kwargs)¶ This method allows to publish an event. It may be used to call from the device a method implemented on the corresponding Emitters / Receivers, subscribers by default.
- Parameters
event (str) – method’s name to call
- Example
>>> device.publish("stop")
-
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.
-
selectController
(controller)¶
-
send
(pkt)¶ 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.
-
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
(target='master', enable=True)¶ This method allows to enable or disable the hijacking mode.
- Parameters
target – target role to hijack (“master” for master hijacking, “slave” for slave hijacking)
enable (bool) – boolean indicating if the hijacking mode must be enabled or disabled
- Example
>>> device.setHijacking(target="master",enable=True) # master hijacking mode enabled >>> device.setHijacking(target="master",enable=False) # master hijacking mode disabled >>> device.setHijacking(target="slave",enable=True) # slave hijacking mode enabled >>> device.setHijacking(target="slave",enable=False) # slave hijacking mode disabled
Note
This method is a shared method and can be called from the corresponding Emitters / Receivers.
-
setMitm
(enable=True)¶ This method performs a Man-in-the-Middle attack targeting an established connection..
- Parameters
enable (bool) – boolean indicating if the mitm mode must be enabled or disabled
- Example
>>> device.setMitm(enable=True) # mitm mode enabled >>> device.setMitm(enable=False) # mitm 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.
-
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.
-
subscribe
(subscriber)¶ This method allows to register a subscriber, according to the design pattern named Publish/subscribe. It allows a Device to call a method of the corresponding Emitter / Receiver, subscribers by default.
- Parameters
subscriber (Object) – instance of an object subscribing to the device
-
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.
-
-
class
mirage.libs.ble_utils.butterfly.
BLEButterflySubdevice
(interface)¶ Bases:
mirage.libs.wireless_utils.device.Device
This (sub)device allows to interact with one specific role (Master or Slave) of a BLE connection when an InjectaBLE complex attack is performed using ButteRFly Device. It is directly related to the approach used by ButteRFly firmware when an attack is performed. Indeed, some of the experimental InjectaBLE attacks (especially MiTM) makes use of a “trick” allowing to use only one physical ButteRFly Device to interact with the two roles involved in the targeted connection simultaneously. The attacker injects a CONNECTION_UPDATE_IND packet including carefully chosen WinOffset and WinSize fields allowing to desynchronize the legitimate Master and Slave without altering the other channel hopping parameters. Then, the attacker synchronises with the two legitimate roles, and the two connections follow the same channel hopping pattern with a simple time offset. As a consequence, only one physical device is needed to perform this attack.
However, Mirage’s ble_mitm module requires two separate devices, according to the existing Man-in-the-Middle strategies (GATTacker and BTLEJuice). As a consequence, this subdevice mimick the behaviour of a normal device from the module’s perspective, but acts as a software proxy to interact with the ButteRFly device. This subdevice can’t be used directly, it will be automatically instantiated by the ButteRFly Device when an attack is performed.
The corresponding interfaces are :
butterflyX:subY
(e.g. “butterfly0:sub0” mimicks a master and “butterfly0:sub1” mimicks a slave)The following capabilities are supported :
Capability
Available ?
COMMUNICATING_AS_MASTER
yes (if Y == 0)
COMMUNICATING_AS_SLAVE
yes (if Y == 1)
-
close
()¶ This method closes the device.
-
classmethod
get
(interface)¶ This class method implements the Register device pattern. According to the interface parameter, only one instance of a given specific device will be instanciated if multiple Emitters and/or Receivers tries to access it.
-
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.
-
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.
-
hasCapabilities
(*capability)¶ This method allows to check if the device implements some specific capabilities.
- Parameters
*capability (str (multiple)) – capabilities to check
- Returns
boolean indicating if the device implements the capabilities provided
- Return type
bool
- Example
>>> device.capabilities = ["SNIFFING", "INJECTING", "CHANGING_ADDRESS"] >>> device.hasCapabilities("SNIFFING", "INJECTING") True >>> device.hasCapabilities("MAKING_COFFEE") False
-
init
()¶ This method initializes the device.
-
instances
= {}¶
-
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.
-
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
-
publish
(event, *args, **kwargs)¶ This method allows to publish an event. It may be used to call from the device a method implemented on the corresponding Emitters / Receivers, subscribers by default.
- Parameters
event (str) – method’s name to call
- Example
>>> device.publish("stop")
-
recv
()¶ This method receives some datas. If no data is available, this method returns None.
- Parameters
data – raw representation of the received data
-
send
(packet)¶ This method sends some datas.
- Parameters
data – raw representation of the data to send
-
subscribe
(subscriber)¶ This method allows to register a subscriber, according to the design pattern named Publish/subscribe. It allows a Device to call a method of the corresponding Emitter / Receiver, subscribers by default.
- Parameters
subscriber (Object) – instance of an object subscribing to the device
-
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.hackrf module¶
-
class
mirage.libs.ble_utils.hackrf.
BLEHackRFDevice
(interface)¶ Bases:
mirage.libs.wireless_utils.device.SDRDevice
This device allows to communicate with a HackRF Device in order to interact with Bluetooth Low Energy protocol. HackRF support is experimental, the demodulator is slow and it can only deal with advertisements.
The corresponding interfaces are :
hackrfX
(e.g. “hackrf0”)The following capabilities are actually supported :
Capability
Available ?
SCANNING
yes
ADVERTISING
yes
SNIFFING_ADVERTISEMENTS
yes
SNIFFING_NEW_CONNECTION
no
SNIFFING_EXISTING_CONNECTION
no
JAMMING_CONNECTIONS
no
JAMMING_ADVERTISEMENTS
no
INJECTING
no
MITMING_EXISTING_CONNECTION
no
HIJACKING_MASTER
no
HIJACKING_SLAVE
no
INITIATING_CONNECTION
no
RECEIVING_CONNECTION
no
COMMUNICATING_AS_MASTER
no
COMMUNICATING_AS_SLAVE
no
HCI_MONITORING
no
-
SDR_PARAMETERS
= {'BANDWIDTH': (['source', 'sink'], 'setBandwidth', <class 'int'>), 'EXPERIMENTAL_DEMODULATOR': (['device'], 'setExperimentalDemodulator', <function booleanArg>), 'FREQUENCY': (['source', 'sink'], 'setFrequency', <class 'int'>), 'GAIN': (['source'], 'setGain', <class 'int'>), 'LNA_GAIN': (['source'], 'setLNAGain', <class 'int'>), 'SAMPLE_RATE': (['source', 'sink'], 'setSampleRate', <class 'int'>), 'TX_GAIN': (['sink'], 'setTXGain', <class 'int'>)}¶
-
applySDRConfig
()¶ This method applies the SDR-related configuration.
-
buildReceivePipeline
(interface)¶ This method allows to build the receive pipeline of the current device.
- Parameters
interface (str) – string indicating the interface to use
- Returns
receive pipeline instance
- Return type
SDRPipeline
-
buildTransmitPipeline
(interface)¶ This method allows to build the transmit pipeline of the current device.
- Parameters
interface (str) – string indicating the interface to use
- Returns
transmit pipeline instance
- Return type
SDRPipeline
-
close
()¶ This method closes the device.
-
classmethod
get
(interface)¶ This class method implements the Register device pattern. According to the interface parameter, only one instance of a given specific device will be instanciated if multiple Emitters and/or Receivers tries to access it.
-
getAPIVersion
()¶ This method returns the API version of the HackRF library.
- Returns
API version as a tuple of (major, minor)
- Return type
tuple of (int,int)
- Example
>>> device.getAPIVersion() (1, 4)
Note
This method is a shared method and can be called from the corresponding Emitters / Receivers.
-
getAddress
()¶ This method returns the actual BD address of the device.
- Returns
str indicating the BD address
- Return type
str
- Example
>>> device.getAddress() '1A:2B:3C:4D:5E:6F'
Note
This method is a shared method and can be called from the corresponding Emitters / Receivers.
-
getBoardID
()¶ This method returns the board identifier of the current HackRF.
- Returns
board identifier
- Return type
int
- Example
>>> device.getBoardID() 2
Note
This method is a shared method and can be called from the corresponding Emitters / Receivers.
-
getBoardName
()¶ This method returns the board name of the current HackRF.
- Returns
board name
- Return type
str
- Example
>>> device.getBoardName() 'HackRF One'
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.
-
getDeviceIndex
()¶ This method returns the device index of the current HackRF.
- Returns
device 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 HackRF device.
- Returns
firmware version
- Return type
str
- Example
>>> device.getFirmwareVersion() 'git-a9945ff'
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 current HackRF device.
- Returns
serial number
- Return type
str
- Example
>>> device.getSerialNumber() '0000000000000000a06063c8234e925f'
Note
This method is a shared method and can be called from the corresponding Emitters / Receivers.
-
hasCapabilities
(*capability)¶ This method allows to check if the device implements some specific capabilities.
- Parameters
*capability (str (multiple)) – capabilities to check
- Returns
boolean indicating if the device implements the capabilities provided
- Return type
bool
- Example
>>> device.capabilities = ["SNIFFING", "INJECTING", "CHANGING_ADDRESS"] >>> device.hasCapabilities("SNIFFING", "INJECTING") True >>> device.hasCapabilities("MAKING_COFFEE") False
-
init
()¶ This method initializes the device.
-
instances
= {}¶
-
isConnected
()¶ This method returns a boolean indicating if the device is connected.
- Returns
boolean indicating if the device is connected
- Return type
bool
Warning
This method always returns False, 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.
-
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
-
publish
(event, *args, **kwargs)¶ This method allows to publish an event. It may be used to call from the device a method implemented on the corresponding Emitters / Receivers, subscribers by default.
- Parameters
event (str) – method’s name to call
- Example
>>> device.publish("stop")
-
recv
()¶ This method receives some datas. If no data is available, this method returns None.
- Parameters
data – raw representation of the received data
-
send
(packet)¶ This method sends some datas.
- Parameters
data – raw representation of the data to send
-
setAddress
(address, random=False)¶ This method allows to modify the BD address and the BD address type of the device, if it is possible.
- Parameters
address (str) – new BD address
random (bool) – boolean indicating if the address is random
- Returns
boolean indicating if the operation was successful
- Return type
bool
- Example
>>> hackrfDevice.setAddress("11:22:33:44:55:66")
Note
This method is a shared method and can be called from the corresponding Emitters / Receivers.
-
setAdvertising
(enable=True)¶ This method enables or disables the advertising mode.
- Parameters
enable (bool) – boolean indicating if the advertising mode must be enabled
- Example
>>> device.setAdvertising(enable=True) # advertising mode enabled >>> device.setAdvertising(enable=False) # advertising mode disabled
Warning
Please note that if no advertising and scanning data has been provided before this function call, nothing will be advertised. You have to set the scanning Parameters and the advertising Parameters before calling this method.
Note
This method is a shared method and can be called from the corresponding Emitters / Receivers.
-
setAdvertisingParameters
(type='ADV_IND', destAddr='00:00:00:00:00:00', data=b'', intervalMin=200, intervalMax=210, daType='public', oaType='public')¶ This method sets advertising parameters according to the data provided. It will mainly be used by ADV_IND-like packets.
- Parameters
type (str) – type of advertisement (available values : “ADV_IND”, “ADV_DIRECT_IND”, “ADV_SCAN_IND”, “ADV_NONCONN_IND”, “ADV_DIRECT_IND_LOW”)
destAddress (str) – destination address (it will be used if needed)
data (bytes) – data included in the payload
intervalMin (int) – minimal interval
intervalMax (int) – maximal interval
daType (str) – string indicating the destination address type (“public” or “random”)
oaType – string indicating the origin address type (“public” or “random”)
Note
This method is a shared method and can be called from the corresponding Emitters / Receivers.
-
setChannel
(channel)¶ 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.
-
setExperimentalDemodulator
(enable=True)¶
-
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.
-
setScanningParameters
(data)¶ This method sets scanning parameters according to the data provided. It will mainly be used by SCAN_RESP packets.
- Parameters
data (bytes) – data to use in SCAN_RESP
Warning
This method does nothing, 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.
-
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.
-
subscribe
(subscriber)¶ This method allows to register a subscriber, according to the design pattern named Publish/subscribe. It allows a Device to call a method of the corresponding Emitter / Receiver, subscribers by default.
- Parameters
subscriber (Object) – instance of an object subscribing to the device
-
updateSDRConfig
(sdrConfig)¶ - This method updates the SDR-related configuration. The supported parameters are:
GAIN: Receive (RX) Gain (integer value)
TX_GAIN: Tranmit (TX) Gain (integer value)
LNA_GAIN: Low Noise Amplifier (LNA) Gain (integer value)
FREQUENCY: Frequency (integer value)
BANDWIDTH: Bandwidth (integer value)
SAMPLE_RATE: Sample Rate (integer value)
EXPERIMENTAL_DEMODULATOR: Use the experimental demodulator if available (boolean value)
- Parameters
sdrConfig (dict) – dictionary describing the SDR parameters name and their value as string
-
mirage.libs.ble_utils.decoders module¶
-
class
mirage.libs.ble_utils.decoders.
BLEDecoder
(samplesPerSymbol=1, samplesBefore=60, samplesAfter=60, crcChecking=True, channel=37, crcInit=5592405)¶ Bases:
mirage.libs.common.sdr.decoders.SDRDecoder
Software Defined Radio decoder for Bluetooth Low Energy protocol.
-
decode
(demodulatedData, iqSamples)¶ This method implements the BLE decoding process and transforms a binary string into a BLE packet.
- Parameters
demodulatedData (str) – data to decode
iqSamples (list of complex) – IQ samples corresponding with the demodulated data
- Returns
tuple composed of the decoded data and the correspond IQ samples
- Return type
(bytes, list of complex)
-
setCRCChecking
(enable=True)¶ This method enables CRC checking.
- Parameters
enable (bool) – indicates if the CRC checking should be enabled or disabled
- Example
>>> decoder.setCRCChecking(True)
-
setChannel
(channel)¶ This method sets the channel used by the dewhitening algorithm.
- Parameters
channel (int) – channel to use
- Example
>>> decoder.setChannel(37)
-
mirage.libs.ble_utils.encoders module¶
-
class
mirage.libs.ble_utils.encoders.
BLEEncoder
(channel=37, crcInit=5592405)¶ Bases:
mirage.libs.common.sdr.encoders.SDREncoder
Software Defined Radio encoder for Bluetooth Low Energy protocol.
-
encode
(data)¶ This method implements the encoding process and transforms a sequence of bytes into a binary string.
- Parameters
data (bytes) – data to encode
- Returns
binary string
- Return type
str
-
setChannel
(channel)¶ This method sets the channel used by the dewhitening algorithm.
- Parameters
channel (int) – channel to use
- Example
>>> decoder.setChannel(37)
-
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
-
classmethod
-
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
-
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.
dewhiten
(data, channel)¶ This function allows to dewhiten a given raw data according to the channel value.
- Parameters
data (bytes) – raw data to dewhiten
channel (int) – channel number
- Returns
dewhitened data
- Return type
bytes
-
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
(l2capCmdId=0, 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
l2capCmdId (int) – L2CAP Command Identifier
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
(l2capCmdId=0, moveResult=0, connectionHandle=- 1)¶ Bases:
mirage.libs.ble_utils.packets.BLEPacket
Mirage Bluetooth Low Energy Packet - Connection Parameter Update Response
- Parameters
l2capCmdId (int) – L2CAP Command Identifier
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'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')¶ 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.
BLEFindByTypeValueRequest
(startHandle=0, endHandle=65535, uuid=0, data=b'', connectionHandle=- 1)¶ Bases:
mirage.libs.ble_utils.packets.BLEPacket
Mirage Bluetooth Low Energy Packet - Find By Type Value Request
- Parameters
startHandle (int) – lowest ATT handle included in the request
endHandle (int) – highest ATT handle included in the request
uuid (int) – 2 octet UUID to find
data (bytes) – Attribute value to find
connectionHandle (int) – connection handle associated to the connection
-
class
mirage.libs.ble_utils.packets.
BLEFindByTypeValueResponse
(handles=[], connectionHandle=- 1)¶ Bases:
mirage.libs.ble_utils.packets.BLEPacket
Mirage Bluetooth Low Energy Packet - Find By Type Value Response
- Parameters
handles (list) – list indicating the handles contained in the Information Response
connectionHandle (int) – connection handle associated to the connection
-
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'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')¶ 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'\x00\x00\x00\x00\x00\x00\x00\x00', ediv=0, ltk=b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')¶ 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'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')¶ 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'\x00\x00\x00\x00\x00\x00\x00\x00')¶ 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'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')¶ 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'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')¶ 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 fieldmirage.libs.ble_utils.dissectors.InputOutputCapability
: input output capability fieldmirage.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'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00')¶ 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, rawPacket=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 aWrite 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 Sniffle 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.
mirage.libs.ble_utils.scapy_link_layers module¶
This module contains some scapy definitions of Link Layer Bluetooth Low Energy packets.