ble_master

Presentation

ble_master simulates a master’s behaviour. It is a core module for the framework, allowing to quickly build recurrent behaviours during a security audit, and is also used in chained operations (for example with ble_hijack). If a scenario is provided, the module is launched in “scenario” mode, with events given as callbacks on specific packet types, allowing to implement complex interactions. Otherwise, it is launched in “interpreter” mode, opening a CLI for the user.

Compatible devices

Input parameters

Name

Default value

Possible values

Description

INTERFACE

hci0

hciX, microbitX

Interface to use

TARGET

<BD address>

Target address

CONNECTION_TYPE

public

public|random

Connection mode

SCENARIO

<scenario>

Scenario to use

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. 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

onSlaveConnect

packet

when an incoming connection request is received (from slave)

the prompt is updated

onSlaveDisconnect

packet

when an incoming disconnection request is received (from slave)

the prompt is updated

Commands

The following commands are available in the CLI interface :

  • clear : clears the screen

  • connect <BD address> : calls the ble_connect module to initiate a connection with the device at the given address

  • connect <BD address> <type> : calls the ble_connect module to initiate a connection with the device at the given address, with the specified connection type

  • connections : lists the current connections

  • switch <connection> : switch the active connection (connection on which we make the commands) to the specified one

  • disconnect : disconnects from the active connection

  • scan : calls the calls the ble_scan module to list near BLE devices

  • scan <duration> : calls the ble_scan module for the specified duration to list near BLE devices

  • discover <what> <start> <end> <filter_by> <filter> : calls the ble_discover module with the specified (optional) parameters

  • read <handle> : sends a Read Request on the specified handle on the active connection

  • write_cmd <handle> <value> : sends a Write Command on the specified handle with the specified value on the active connection

  • write_req <handle> <value> : sends a Write Request on the specified handle with the specified value on the active connection

  • pairing <active> <parameters>: calls the ble_pairing using the specified parameters :

    • <active> : this parameter indicates if the pairing process is active or passive

    • <parameters> : this parameter allow to indicate multiple parameters in order to customize the pairing process, separated by the symbol | :

      • inputOutput : indicates the input output capabilities (yesno,display,keyboard)

      • authentication : indicates the authentication flag (bonding,ct2,mitm,secureConnections,keypress)

      • ltk : indicates the Long Term Key

      • ediv : indicates the ediv

      • rand : indicates the rand

      • irk : indicates the Identity Resolution Key

      • addr : indicates the address

      • addr_type : indicates the address type

      • csrk : indicates the Connection Signature Resolving Key

      • pin : indicates the PIN to use

      Example :

      inputOutput=yesno|authentication=bonding|ltk=112233445566778899aabbccddeeff |rand=1122334455667788|ediv=12

  • disconnect : disconnects from the current connection

  • exit : ends the execution

Usage

CLI mode

If you want to use this module in CLI mode, just calls the module without input parameters :

$ sudo mirage ble_master
[INFO] Module ble_master loaded !
[SUCCESS] HCI Device (hci0) successfully instanciated !
[MASTER]:

You can easily scan the devices using the scan command :

[MASTER]: scan
┌Devices found──────┬──────┬─────────┬───────────────────────────────────────────────────┬────────────────────────────────────────────────────────────────────┐
│ BD Address        │ Name │ Company │ Flags                                             │ Advertising data                                                   │
├───────────────────┼──────┼─────────┼───────────────────────────────────────────────────┼────────────────────────────────────────────────────────────────────┤
│ 1C:1E:E3:88:4A:C0 │      │         │ LE General Discoverable Mode                      │ 0201021107fc9dd0b3cb84e0840642f3f7e1e0bfcb (ADV_IND)               │
│ 44:7E:03:CC:4C:4F │      │ Google  │                                                   │ 03039ffe17169ffe0000000000000000000000000000000000000000 (ADV_IND) │
│                   │      │         │                                                   │ 09ffe0000130ca72fc5b (SCAN_RSP)                                    │
│ C7:FD:F2:07:36:2E │ Tile │         │ LE General Discoverable Mode,BR/EDR not supported │ 0201060303edfe050954696c65 (ADV_IND)                               │
└───────────────────┴──────┴─────────┴───────────────────────────────────────────────────┴────────────────────────────────────────────────────────────────────┘
┌Devices found──────┬───────┬────────────────────────┬───────────────────────────────────────────────────┬────────────────────────────────────────────────────────────────────┐
│ BD Address        │ Name  │ Company                │ Flags                                             │ Advertising data                                                   │
├───────────────────┼───────┼────────────────────────┼───────────────────────────────────────────────────┼────────────────────────────────────────────────────────────────────┤
│ 1C:1E:E3:88:4A:C0 │       │                        │ LE General Discoverable Mode                      │ 0201021107fc9dd0b3cb84e0840642f3f7e1e0bfcb (ADV_IND)               │
│ 44:7E:03:CC:4C:4F │       │ Google                 │                                                   │ 03039ffe17169ffe0000000000000000000000000000000000000000 (ADV_IND) │
│                   │       │                        │                                                   │ 09ffe0000130ca72fc5b (SCAN_RSP)                                    │
│ C7:FD:F2:07:36:2E │ Tile  │                        │ LE General Discoverable Mode,BR/EDR not supported │ 0201060303edfe050954696c65 (ADV_IND)                               │
│ C4:BE:84:39:8E:07 │ Salon │ Texas Instruments Inc. │ LE General Discoverable Mode,BR/EDR not supported │ 0201060bff0d0086484f4d45424545 (ADV_IND)                           │
│                   │       │                        │                                                   │ 100953616c6f6e00000000000000000000051228005000020a00 (SCAN_RSP)    │
└───────────────────┴───────┴────────────────────────┴───────────────────────────────────────────────────┴────────────────────────────────────────────────────────────────────┘

Then, you can connect on a specific device using connect :

[MASTER]: connect C4:BE:84:39:8E:07
[INFO] Trying to connect to : C4:BE:84:39:8E:07 (type : public)
[INFO] Updating connection handle : 16
[SUCCESS] Connected on device : C4:BE:84:39:8E:07
[MASTER|C4:BE:84:39:8E:07]: connections
┌Active connections──────────────┬────────┐
│ Identifier │ Address           │ Handle │
├────────────┼───────────────────┼────────┤
│ 1          │ C4:BE:84:39:8E:07 │ 16     │
└────────────┴───────────────────┴────────┘

You can discover the GATT layer using the discover command :

[MASTER|C4:BE:84:39:8E:07]: discover
[INFO] Services discovery ...
┌Services──────┬────────────┬────────┬──────────────────────────────────┬────────────────────┐
│ Start Handle │ End Handle │ UUID16 │ UUID128                          │ Name               │
├──────────────┼────────────┼────────┼──────────────────────────────────┼────────────────────┤
│ 0x0001       │ 0x000b     │ 0x1800 │ 0000180000001000800000805f9b34fb │ Generic Access     │
│ 0x000c       │ 0x000f     │ 0x1801 │ 0000180100001000800000805f9b34fb │ Generic Attribute  │
│ 0x0010       │ 0x001e     │ 0x180a │ 0000180a00001000800000805f9b34fb │ Device Information │
│ 0x001f       │ 0x002f     │        │ a8b3fff04834405189d03de95cddd318 │                    │
│ 0x0030       │ 0x0039     │        │ a8b3ffe04834405189d03de95cddd318 │                    │
│ 0x003a       │ 0xffff     │        │ f000ffc004514000b000000000000000 │                    │
└──────────────┴────────────┴────────┴──────────────────────────────────┴────────────────────┘
[INFO] Characteristics by service discovery ...
┌Service 'Generic Access'(start Handle = 0x0001 / end Handle = 0x000b)──────────┬────────────────────────────────────────────┬─────────────┬──────────────────┬─────────────┐
│ Declaration Handle │ Value Handle │ UUID16 │ UUID128                          │ Name                                       │ Permissions │ Value            │ Descriptors │
├────────────────────┼──────────────┼────────┼──────────────────────────────────┼────────────────────────────────────────────┼─────────────┼──────────────────┼─────────────┤
│ 0x0002             │ 0x0003       │ 0x2a00 │ 00002a0000001000800000805f9b34fb │ Device Name                                │ Read        │ Salon            │             │
│ 0x0004             │ 0x0005       │ 0x2a01 │ 00002a0100001000800000805f9b34fb │ Appearance                                 │ Read        │                  │             │
│ 0x0006             │ 0x0007       │ 0x2a02 │ 00002a0200001000800000805f9b34fb │ Peripheral Privacy Flag                    │ Read        │                  │             │
│ 0x0008             │ 0x0009       │ 0x2a03 │ 00002a0300001000800000805f9b34fb │ Reconnection Address                       │ Write       │                  │             │
│ 0x000a             │ 0x000b       │ 0x2a04 │ 00002a0400001000800000805f9b34fb │ Peripheral Preferred Connection Parameters │ Read        │ 5000a0000000e803 │             │
└────────────────────┴──────────────┴────────┴──────────────────────────────────┴────────────────────────────────────────────┴─────────────┴──────────────────┴─────────────┘

[...]

┌Service f000ffc004514000b000000000000000(start Handle = 0x003a / end Handle = 0xffff)─┬─────────────────────────────────────┬───────┬────────────────────────────────────────────────┐
│ Declaration Handle │ Value Handle │ UUID16 │ UUID128                          │ Name │ Permissions                         │ Value │ Descriptors                                    │
├────────────────────┼──────────────┼────────┼──────────────────────────────────┼──────┼─────────────────────────────────────┼───────┼────────────────────────────────────────────────┤
│ 0x003b             │ 0x003c       │        │ f000ffc104514000b000000000000000 │      │ Notify,Write,Write Without Response │       │ Client Characteristic Configuration :          │
│                    │              │        │                                  │      │                                     │       │ Characteristic User Description : Img Identify │
│ 0x003f             │ 0x0040       │        │ f000ffc204514000b000000000000000 │      │ Notify,Write,Write Without Response │       │ Client Characteristic Configuration :          │
│                    │              │        │                                  │      │                                     │       │ Characteristic User Description : Img Block    │
└────────────────────┴──────────────┴────────┴──────────────────────────────────┴──────┴─────────────────────────────────────┴───────┴────────────────────────────────────────────────┘

You can easily initiate a specific request using read, write_req or write_cmd :

[MASTER|C4:BE:84:39:8E:07]: read 0x0021
[INFO] Read Request : handle = 0x0021
[SUCCESS] Response : handle = 0x0021 / Values (hex) = 00
[MASTER|C4:BE:84:39:8E:07]: write_req 0x0021 5510000d0a
[INFO] Write Request : handle = 0x0021 / value = 5510000d0a
[SUCCESS] Response : success
[MASTER|C4:BE:84:39:8E:07]: write_cmd 0x0021 5510010d0a
[SUCCESS] Write Command : handle = 0x0021 / value = 5510010d0a

You can initiate a pairing process using the following command :

[MASTER|C4:BE:84:39:8E:07]: pairing active inputOutput=yesno|authentication=bonding|ltk=112233445566778899aabbccddeeff|rand=1122334455667788|ediv=12
┌Input parameters────┬────────────────────────────────┐
│ Name               │ Value                          │
├────────────────────┼────────────────────────────────┤
│ INTERFACE          │ hci0                           │
│ MODE               │ master                         │
│ PIN                │                                │
│ ACTIVE             │ yes                            │
│ LTK                │ 112233445566778899aabbccddeeff │
│ EDIV               │ 12                             │
│ RAND               │ 1122334455667788               │
│ IRK                │                                │
│ ADDR_TYPE          │                                │
│ ADDR               │                                │
│ CSRK               │                                │
│ KEYBOARD           │ no                             │
│ YESNO              │ yes                            │
│ DISPLAY            │ no                             │
│ CT2                │ no                             │
│ MITM               │ no                             │
│ BONDING            │ yes                            │
│ SECURE_CONNECTIONS │ no                             │
│ KEYPRESS           │ no                             │
└────────────────────┴────────────────────────────────┘
[PACKET] << BLE - Pairing Request Packet | outOfBand=no | inputOutputCapability=0x3 | authentication=0x1 | maxKeySize=16 | initiatorKeyDistribution=0x1 | responderKeyDistribution=0x1 >>
[PACKET] << BLE - Pairing Response Packet | outOfBand=no | inputOutputCapability=0x0 | authentication=0x5 | maxKeySize=16 | initiatorKeyDistribution=0x1 | responderKeyDistribution=0x1 >>
[INFO] At least one of the devices doesn't support LE secure connections
┌─────────────┬─────────────────┬────────────┐
│ Out Of Bond │ IO Capabilities │ Just Works │
├─────────────┼─────────────────┼────────────┤
│ no          │ yes             │ no         │
└─────────────┴─────────────────┴────────────┘
[SUCCESS] Pairing Method selected : JustWorks
[SUCCESS] Generating random : 6f416801c7aa05a6e64efab61e7f13f9
[SUCCESS] Generating Temporary Key : 00000000000000000000000000000000
[SUCCESS] Generating MConfirm : 1909705fe9ce9fdfb373a3a4b4d8a0e9
[PACKET] << BLE - Pairing Confirm Packet | confirm=e9a0d8b4a4a373b3df9fcee95f700919 >>
[PACKET] << BLE - Pairing Confirm Packet | confirm=2cf9eb1070422dbd2ff5baae89da323a >>
[PACKET] << BLE - Pairing Random Packet | random=6f416801c7aa05a6e64efab61e7f13f9 >>
[PACKET] << BLE - Pairing Random Packet | random=32bbdfd78919c8e56c96ee6dc60eac90 >>
[SUCCESS] Confirm Value correct !
[SUCCESS] Generating Short Term Key (STK): 864dfbf09cb46478581894d9ccf67a1d
[SUCCESS] Encryption enabled !
[PACKET] << BLE - Encryption Information Packet | ltk=2a9d8a1d78a5db22091a8005d820d9da >>
[SUCCESS] Long Term Key (LTK) received : dad920d805801a0922dba5781d8a9d2a
[PACKET] << BLE - Master Identification Packet | rand=a179123b95cffdac | ediv=0x59d9 >>
[SUCCESS] EDIV and RAND received :  0x59d9 / a179123b95cffdac
[INFO] Sending LTK...
[SUCCESS] Sent !
[SUCCESS] Active pairing enabled !

Finally, you can use the disconnect command in order to disconnect from the target device :

[MASTER|C4:BE:84:39:8E:07]: disconnect
[INFO] Disconnected !
[SUCCESS] Disconnected !

Customizing the behaviour using scenarios

If you want to use a scenario, you can use the create_scenario command in order to generate a basic code :

$ mirage --create_scenario
[QUESTION] Scenario's name : master_test
[SUCCESS] Scenario master_test successfully generated : /home/user/.mirage/scenarios/master_test.py
[INFO] Mirage process terminated !

Then, you can modify the code as you want, the following example allow to send a specific Write Command if the user press the space key:

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

class master_test(scenario.Scenario):

        def onStart(self):
                self.emitter = self.module.emitter
                self.receiver = self.module.receiver
                self.emitter.sendp(ble.BLEConnect("C4:BE:84:39:8E:07"))
                self.value = bytes.fromhex("5510000d0a")
                return True

        def onEnd(self):
                return True

        def onKey(self,key):
                if key == "space":
                        self.emitter.sendp(ble.BLEWriteCommand(handle=0x0021, value=self.value))
                        self.value = bytes.fromhex("5510010d0a") if self.value == bytes.fromhex("5510000d0a") else bytes.fromhex("5510000d0a")
                elif key == "q":
                        self.emitter.sendp(ble.BLEDisconnect())

If you want to use this scenario, just provide its name as the value of the input parameter SCENARIO :

$ sudo mirage ble_master SCENARIO=master_test
[INFO] Module ble_master loaded !
[SUCCESS] HCI Device (hci0) successfully instanciated !
[INFO] Scenario loaded !
[INFO] Updating connection handle : 16
 [INFO] Write command : 5510000d0a
 [INFO] Write command : 5510010d0a
 [INFO] Write command : 5510000d0a
 [INFO] Write command : 5510010d0a
q[INFO] Disconnected !
[INFO] Mirage process terminated !