ble_pair¶
Presentation¶
This module allows to perform a legacy Pairing, according to the Bluetooth Low Energy specification.
It allows to initiate a pairing from a master or a slave, so it can be used from ble_master or ble_slave using the pairing command.
It needs to be connected to the device beforehand, hence needing to be used from one of the previously mentionned module or inside a chain of modules containing a module initiating the connection (eg: ble_connect or ble_hijack).
The input parameter named MODE allows to choose if the pairing is generated from a master of from a slave. Another input parameter is important : ACTIVE allows to specify if the module must runs an active pairing or a passive pairing.
If MODE=master and ACTIVE=yes : the module initiates the pairing by transmitting a Pairing Request, according to the provided parameters.
If MODE=master and ACTIVE=no : the module enables some callbacks allowing to accept pairing if an incoming Security Request is received from slave, then the module terminates its execution.
If MODE=slave and ACTIVE=yes : the module initiates the pairing by transmitting a Security Request, according to the provided parameters.
If MODE=slave and ACTIVE=no : the module enables some callbacks allowing to accept pairing if an incoming Pairing Request is received from master, then the module terminates its execution.
This module allows to distribute three types of keys if the bonding is enabled (BONDING set to “yes”) : the Long Term Key (LTK), the Identity Resolving Key (IRK) and the Connection Signature Resolving Key (CSRK).
If LTK, EDIV and RAND are provided : the module enables the distribution of the Long Term Key (LTK)
If IRK, ADDR and ADDR_TYPE are provided : the module enables the distribution of the Identity Resolving Key (IRK)
If CSRK is provided : the module enables the distribution of the Connection Signature Resolving Key (CSRK)
You can provide a PIN code if you already knows it using the PIN input parameter (e.g. if you use the “Just Works” feature). If PIN is empty but required by the selected pairing method, it may be asked later during the module execution. Finally, you can define the input/output capabilities of your simulated device using the three input parameters KEYBOARD (indicating if your device has a keyboard), YESNO (indicating if your device has an input allowing to choose “yes” or “no”) and DISPLAY (indicating if your device has a screen). You can also control the authentication flag using CT2, MITM, BONDING, SECURE_CONNECTIONS and KEYPRESS.
Compatible devices¶
Input parameters¶
Name |
Default value |
Possible values |
Description |
|---|---|---|---|
INTERFACE |
hci0 |
microbitX, hciX, butterflyX, sniffleX |
Interface to use |
MODE |
master |
master|slave |
Mode to use |
PIN |
<integer> |
PIN code (6 digits) |
|
ACTIVE |
yes |
yes|no |
Boolean indicating if the pairing is active or passive |
LTK |
112233445566778899aabbccddeeff |
<hexadecimal> |
Long Term Key to distribute (128 bits) |
EDIV |
12 |
<integer> |
EDIV associated to the distributed Long Term Key |
RAND |
1122334455667788 |
<hexadecimal> |
RAND associated to the distributed Long Term Key (64 bits) |
CSRK |
<hexadecimal> |
Connection Signature Resolving Key to distribute (128 bits) |
|
IRK |
<hexadecimal> |
Identity Resolving Key to distribute (128 bits) |
|
ADDR |
<BD address> |
BD Address associated to the distributed Identity Resolving Key |
|
ADDR_TYPE |
public|random |
BD Address’ type associated to the distributed Identity Resolving Key |
|
KEYBOARD |
yes |
yes|no |
Boolean indicating if a keyboard is available |
YESNO |
yes |
yes|no |
Boolean indicating if a yes/no input is available |
DISPLAY |
no |
yes|no |
Boolean indicating if a display is available |
CT2 |
no |
yes|no |
Boolean indicating if the CT2 bit is on in the authentication flag |
MITM |
no |
yes|no |
Boolean indicating if the MITM bit is on in the authentication flag |
BONDING |
yes |
yes|no |
Boolean indicating if the Bonding bit is on in the authentication flag |
SECURE_CONNECTIONS |
no |
yes|no |
Boolean indicating if Secure Connections bit is on in the authentication flag |
KEYPRESS |
no |
yes|no |
Boolean indicating if the KeyPress bit is on in the authentication flag |
Output parameters¶
Name |
Possible values |
Description |
|---|---|---|
INTERFACE |
hciX,microbitX,butterflyX,sniffleX |
Interface used |
Usage¶
If you want to initiate an active pairing from a master, use the following sequential execution :
$ sudo mirage "ble_connect|ble_pair" ble_connect1.TARGET=C4:BE:84:39:8E:07 ble_pair2.MODE=master ble_pair2.ACTIVE=yes
[INFO] Module ble_connect loaded !
[INFO] Module ble_pair loaded !
[SUCCESS] HCI Device (hci0) successfully instanciated !
[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
[PACKET] << BLE - Pairing Request Packet | outOfBand=no | inputOutputCapability=0x4 | 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 : PasskeyEntry
[SUCCESS] Generating random : 9e9c0e1604a528a93a6df7ccfe3bf3ba
Enter the 6 digit PIN code: 000000
[SUCCESS] Generating Temporary Key : 00000000000000000000000000000000
[SUCCESS] Generating MConfirm : e604bf5cd2091c521ba8088d18002265
[PACKET] << BLE - Pairing Confirm Packet | confirm=652200188d08a81b521c09d25cbf04e6 >>
[PACKET] << BLE - Pairing Confirm Packet | confirm=1a64f4375bc6e0debae0db820e28b998 >>
[PACKET] << BLE - Pairing Random Packet | random=9e9c0e1604a528a93a6df7ccfe3bf3ba >>
[PACKET] << BLE - Pairing Random Packet | random=b34004f7d3c00a1fb346e47715c816cf >>
[SUCCESS] Confirm Value correct !
[SUCCESS] Generating Short Term Key (STK): d60e367bcb3b8f1dd86f80f9500a153d
[SUCCESS] Encryption enabled !
[PACKET] << BLE - Encryption Information Packet | ltk=d3c4d9dcc9199cd57da9fba273425b24 >>
[SUCCESS] Long Term Key (LTK) received : 245b4273a2fba97dd59c19c9dcd9c4d3
[PACKET] << BLE - Master Identification Packet | rand=c003ac90f2bd93c7 | ediv=0x1fa >>
[SUCCESS] EDIV and RAND received : 0x1fa / c003ac90f2bd93c7
[INFO] Sending LTK...
[SUCCESS] Sent !
[INFO] Mirage process terminated !
If you want to initiate a pairing from a slave or directly from the command line interface of ble_master, please refer to the following documentation pages :
slave : documentation of ble_slave
master : documentation of ble_master