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

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

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 :