Commit fd6aa2a6 authored by Lars Almon's avatar Lars Almon
Browse files

public release

parents
bin
.idea
btlejack.egg-info
dist
[submodule "RIOT"]
path = RIOT
url = git://github.com/RIOT-OS/RIOT.git
Instruction to extend BtleJack:
Client:
1. Add at least new option in __init__.py
2. Adapt or create a new supervisor in supervisor.py and also its ui in ui.py
3. Pass the option from __init__.py to the corresponding supervisor
3. Add a new function to jobs.py
4. Add a new mode to interface.py or use an existing one
4. Add a new packet type in packets.py
5. Add a new function to send such a packet in link.py
6. If necessary, add a new function to ouput data in ui.py
Host:
1. Add a new mode inheriting from Mode
2. Implement start_task() and on_end_event()
3. Add the same opcode used in packets.py in serialLink.h
4. Add a corresponding case to dispatchMessage() in main.cpp
5. If necessary, add additional functions and methods wherever you want
# name of your application
APPLICATION = btlemesh
# If no BOARD is found in the environment, use this default:
BOARD ?= native
# This has to be the absolute path to the RIOT base directory:
RIOTBASE ?= $(CURDIR)/RIOT
# Comment this out to disable code in RIOT that does safety checking
# which is not needed in a production environment but helps in the
# development process:
DEVELHELP ?= 1
# Change this to 0 show compiler invocation lines by default:
QUIET ?= 1
DIRS += mode
USEMODULE += mode
# Modules to include:
USEMODULE += xtimer
USEMODULE += hashes
USEMODULE += crypto
USEMODULE += cipher_modes
# include and auto-initialize all available sensors
#USEMODULE += saul_default
CFLAGS += -DCRYPTO_AES
CFLAGS += -DCRYPTO_THREEDES
include $(RIOTBASE)/Makefile.include
btlemesh
========
This application extends BtleJack (https://github.com/virtualabs/btlejack) to support Bluetooth mesh.
We also ported the firmware to RIOT OS, so more platforms can be supported.
Usage
=====
Clone this repository, build and flash the application. Then the python host application can communicate with the board over the serial port.
Build, flash and start the application:
```
export BOARD=your_board
make
make flash
BOARD=your_board PORT=port_to_your_device make all flash
```
Example boards with Riot OS identifier:
BBC micro:bit - microbit
nRF52 DK - nrf52dk
nRF52480 DK - nrf52840dk
RuuviTag - ruuvitag
Python commands
===============
Sniffing existing connection:
```
btlejack -s
```
Sniffing for new connections (you can use any or a specific address):
```
btlejack -c any
```
Following a connection:
```
btlejack -f access_address
```
Jamming a specific connection:
```
btlejack -f access_address -j
```
Hijacking a specifc connection:
```
btlejack -f access_address -t
```
Sniffing data on advertising channels:
```
btlejack -a
```
Jamming advertising channels (for this you need three devices);
```
btlejack -a -j
```
Use -dt to set datatypes, which should be jammed. For example for mesh message and mesh beacon:
```
btlejack -a -j -dt 0x2a -dt 0x2b
```
Use -nid to set a nid of a friendship subnetwork, to terminate this friendship by jamming the friend poll messages:
```
btlejack -a -j -nid 0x5b
```
Catch a friend establishment and recover the friend key material
```
btlejack -a -fk
```
Open a prompt to sniff, jam or send packets on advertising channels:
```
btlejack -a -pt
```
Prompt commands are sniff, jam, stop_jam, stop or s (also for stop).
To specify one or more devices add
```
-d port
```
otherwise btlejack try to find them, but only search for micro:bit. For all others you must set this value.
If only the version and depending on command that cached parameters are used is displayed after execution, abort and restart.
build/
*.pcap
*.pyc
__pycache__/
*.egg-info
*.egg
dist/
wheels/
output/
[submodule "btlejack-firmware"]
path = btlejack-firmware
url = https://github.com/virtualabs/btlejack-firmware.git
version 1.3
* Added a new option (-n) to control channel map recovery timeout
* Fixed a bug in the channel mapping process
* Fixed a bug in the main program, causing trouble when hijacking
version 1.2.1
* Allowed more than 3 sniffers in active connection sniffing mode
version 1.2.0
* Added connection loss detection to Btlejack's firmware
* Cleaned up the disconnection routine when hijacking
MIT License
Copyright (c) 2018 virtualabs
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
BtleJack: a new Bluetooth Low Energy swiss-army knife
#####################################################
Btlejack provides everything you need to sniff, jam and hijack Bluetooth Low Energy devices. It relies on one or more `BBC Micro:Bit <http://microbit.org/>`_. devices running a dedicated firmware. You may also
want to use an `Adafruit's Bluefruit LE sniffer <https://www.adafruit.com/product/2269>`_ or a `nRF51822 Eval Kit <https://www.waveshare.com/wiki/BLE400>`_, as we added support for these devices.
**This tool only supports Bluetooth Low Energy 4.x.**
Requirements
============
You need a UNIX based system (for example a Raspberry Pi). If you use the BBC Micro:Bit, you will need one to three Micro:Bit devices (three devices recommended) and for each device one free USB port. The power consumption of a Micro:Bit is rather low, so you can use a single USB port and a passive hub for powering the three recommended units.
**If you connect 3 microbits at the same time on your computer, Btlejack will be able to sniff on every advertising channel and has far more chance to capture the connection request.**
How to install
==============
First, install the ``btlejack`` Python3 client software with:
::
$python3 ./setup.py install
How to use Btlejack
===================
Using Btlejack is quite easy. Btlejack can:
- use various devices
- sniff an existing BLE connection
- sniff new BLE connections
- jam an existing BLE connection
- hijack an existing BLE connection
- export captured packets to various PCAP formats
Specify devices to use
----------------------
Btlejack normally tries to autodetect and use connected compatible devices (Micro:Bit only for the moment), but since the firmware can be hacked or modified
to work with other nRF51822-based boards, it provides a specific options to allow compatibility with these devices.
The ``-d`` option lets you specify one or more devices with Btlejack. Note that this option will disable the automatic detection of devices, and you should
add as many devices as you may need:
::
$ btlejack -d /dev/ttyACM0 -d /dev/ttyACM2 -s
Sniffing an existing connection
-------------------------------
First, find an existing connection to target with ``btlejack``:
::
$ btlejack -s
BtleJack version 1.1
[i] Enumerating existing connections ...
[ - 54 dBm] 0xcd91d517 | pkts: 1
[ - 46 dBm] 0xcd91d517 | pkts: 2
The first value (in dBm) shows the power of the signal, the greater this value is the better the sniffed connection will be.
The second value (hex) is the associated *access address*, a 32-bit value identifying a link between two bluetooth low energy compatible devices.
The last value is the number of packets seen with this *access address*. The higher this value is, the more probable the corresponding *access address* is used.
Then, use the `-f` option to follow a specific connection:
::
$ btlejack -f 0xdda4845e
BtleJack version 1.1
[i] Detected sniffers:
> Sniffer #0: fw version 1.1
[i] Synchronizing with connection 0xdda4845e ...
✓ CRCInit: 0x2a035e
✓ Channel Map = 0x1fffffffff
✓ Hop interval = 39
✓ Hop increment = 15
[i] Synchronized, packet capture in progress ...
LL Data: 02 07 03 00 04 00 0a 03 00
LL Data: 0a 08 04 00 04 00 0b 5a 69 70
LL Data: 02 07 03 00 04 00 0a 03 00
LL Data: 0a 08 04 00 04 00 0b 5a 69 70
**If you are using more than 1 microbit, Btlejack will parallelize some of the sniffing operations in order to speed up the connection parametres recovery !**
Sniffing for new connections
----------------------------
The ``-c`` option supported by ``btlejack`` allows you to specify the target BD address, or you may want to use ``any`` to capture any new connection created.
::
$ btlejack -c any
BtleJack version 1.1
[i] Detected sniffers:
> Sniffer #0: version 1.1
> Sniffer #1: version 1.1
LL Data: 05 22 df b4 6f 95 c5 55 c0 0a f6 99 23 40 1d 7b 2f 0a 9a f4 93 01 12 00 27 00 00 00 d0 07 ff ff ff ff 1f 0b
[i] Got CONNECT_REQ packet from 55:c5:95:6f:b4:df to 40:23:99:f6:0a:c0
|-- Access Address: 0x0a2f7b1d
|-- CRC Init value: 0x93f49a
|-- Hop interval: 39
|-- Hop increment: 11
|-- Channel Map: 1fffffffff
|-- Timeout: 20000 ms
LL Data: 03 09 08 0f 00 00 00 00 00 00 00
LL Data: 03 09 08 0f 00 00 00 00 00 00 00
LL Data: 0b 06 0c 08 0f 00 09 41
LL Data: 03 06 0c 07 1d 00 d3 07
or you may also want to specify the target BD address:
::
$ btlejack -c 03:e1:f0:00:11:22
Jamming a connection
--------------------
Once a connection identified by its *access address*, you can provide jam it by using the ``-j`` option:
::
$ btlejack -f 0x129f3244 -j̀
Hijacking a BLE connection
--------------------------
Btlejack is also able to hijack an existing connection, use the ``-t`` option to do so. Once hijacked, Btlejack will give you a prompt allowing you to interact with the hijacked device.
First, hijack an existing connection:
::
$ btlejack -f 0x9c68fd30 -t -m 0x1fffffffff
BtleJack version 1.1
[i] Using cached parameters (created on 2018-08-11 01:48:24)
[i] Detected sniffers:
> Sniffer #0: fw version 1.1
[i] Synchronizing with connection 0x9c68fd30 ...
✓ CRCInit: 0x81f733
✓ Channel map is provided: 0x1fffffffff
✓ Hop interval = 39
✓ Hop increment = 9
[i] Synchronized, hijacking in progress ...
[i] Connection successfully hijacked, it is all yours \o/
btlejack>
Then use the following commands to interact with the device:
- **discover**: performs services and characteristics enumeration, will give you all the information about services and characteristics
- **write**: write data to a specific value handle
- **read**: read data from a specific value handle
- **ll**: sends a raw link-layer packet (for ninjas)
*discover* command
^^^^^^^^^^^^^^^^^^
The ``discover`` command will send and receive Bluetooth LE packets and retrieve all the services UUIDs and parameters, as well as characteristics UUIDs and parameters:
::
btlejack> discover
start: 0001 end: 0005
start: 0014 end: 001a
start: 0028 end: ffff
Discovered services:
Service UUID: 1801
Characteristic UUID: 2a05
| handle: 0002
| properties: indicate (20)
\ value handle: 0003
Service UUID: 1800
Characteristic UUID: 2a04
| handle: 0019
| properties: read (02)
\ value handle: 001a
Characteristic UUID: 2a00
| handle: 0015
| properties: read (02)
\ value handle: 0016
Characteristic UUID: 2a01
| handle: 0017
| properties: read (02)
\ value handle: 0018
Service UUID: 1824
Characteristic UUID: 2abc
| handle: 0029
| properties: write indicate (28)
\ value handle: 002a
*read* command
^^^^^^^^^^^^^^
The ``read`` command accepts a single parameter, the value handle corresponding to the characteristic you want to read from:
::
btlejack> read 0x16
read>> 4c 47 20 77 65 62 4f 53 20 54 56
*write* command
^^^^^^^^^^^^^^^
The ``write`` command accepts three parameters:
::
btlejack> write <value handle> <data format> <data>
Supported data formats:
- ``hex``: hex data (i.e. "414261")
- ``str``: text string, may be encapsulated in double quotes
*ll* command
^^^^^^^^^^^^
This last command allows you to send Bluetooth Low Energy Link-layer PDUs, in hex form, as specified in Volume 6, Part B, Chapter 2.4.
Sniffing for data and jamming on the advertising channels
---------------------------------------------------------
To sniff packets on the advertising channels use ``-a``:
::
$ btlejack -a
To jam packets on the advertising channels use this option with ``-j``:
::
$ btlejack -a -j
And to set specific datatypes, which should be jammed, use the ``-dt`` option once per type. For example for mesh beacons and mesh message:
::
$ btlejack -a -j -dt 0x2a -dt 0x2b
To terminate a friendship of a BT Mesh network, use the ``-nid`` option and enter the nid of the friendship subnetwork.
Catch a friend establishment and recover the friend key material
::
$ btlejack -a -fk
Open a prompt to sniff, jam or send packets on advertising channels:
::
$ btlejack -a -pt
Prompt commands are sniff, jam, stop_jam, stop or s (also for stop).
PCAP file export
----------------
One interesting feature of Btlejack is the possibility to export the captured data to a PCAP file.
Btlejack supports the following DLT formats:
* DLT_BLUETOOTH_LE_LL_WITH_PHDR (same)
* DLT_NORDIC_BLE (the one used by Nordic' sniffer)
* DLT_BLUETOOTH_LE_LL (supported on latest versions of Wireshark)
The output file may be specified using the `-o` option, while the output format may be specified with the `-x` option. Valid formats values are: `ll_phdr`, `nordic`, or `pcap` (default).
::
$ btlejack -f 0xac56bc12 -x nordic -o capture.nordic.pcap
The ``ll_phdr`` export type is useful when sniffing an encrypted connection, as it is also supported by `crackle <https://github.com/mikeryan/crackle>`_. So if you want to sniff and break encrypted connections, this is the way to go.
You may also need to tell crackle to use a specific cracking strategy, by using the `-s` option:
::
$ crackle -i some.pcap -s 1
Connection cache
----------------
Btlejack uses a *connection cache* to store some connection-related value in order to speed up
things a bit. This connection cache may cause some problems, especially if an access address has
been previously seen.
This cache can be flushed with the ``-z`` option:
::
$ btlejack -z
#!/usr/bin/python3
"""
Btlejack, a Bluetooth Low Energy Swiss-army knife
Btlejack is able to sniff newly created and already existing Bluetooth Low
Energy connections, as well as jamming or hijacking them.
It works with a compatible hardware (usually a BBC Micro:Bit) preprogrammed
with the correct firmware.
"""
import os
import signal
import sys
import datetime
import re
from subprocess import check_output
from argparse import ArgumentParser
from btlejack.pcap import PcapBleWriter, PcapNordicTapWriter, PcapBlePHDRWriter, PcapBleAdvWriter
from btlejack.ui import (CLIAccessAddressSniffer, CLIConnectionRecovery,
CLIConnectionSniffer, CLIAdvertisingSniffer, CLIMeshProvsioningMITM,
CLIMeshCatchFriendshipKey, ForcedTermination, SnifferUpgradeRequired)
from btlejack.helpers import *
from btlejack.link import DeviceError
from btlejack.version import VERSION
from btlejack.session import BtlejackSession, BtlejackSessionError
def bd_address_to_int(bd_address):
"""
Helper function converting a BD address to the corresponding integer value.
"""
addr_bytes = [int(v, 16) for v in bd_address.lower().split(':')]
if len(addr_bytes) != 6:
return None
else:
addr_value = addr_bytes[0] << (8 * 5)
addr_value |= addr_bytes[1] << (8 * 4)
addr_value |= addr_bytes[2] << (8 * 3)
addr_value |= addr_bytes[3] << (8 * 2)
addr_value |= addr_bytes[4] << (8 * 1)
addr_value |= addr_bytes[5] << (8 * 0)
return addr_value
def main():
"""
Btlejack main routine for CLI
"""
parser = ArgumentParser('btlejack')
parser.add_argument(
'-d',
'--device',
dest='devices',
action='append',
type=str,
help='Micro:Bit device serial port'
)
parser.add_argument(
'-a',
'--adv',
dest='scan_adv',
action='store_true',
default=False,
help='Scan for packets on advertising channels'
)
parser.add_argument(
'-pt',
'--prompt',
dest='prompt',
action='store_true',
default=False,
help='Open a prompt to send LL packets, sniff and jam on advertising channels (only performed in conjunction with -a option)'
)
parser.add_argument(
'-v',
'--verbose',
dest='verbose',
action='store_true',
default=False,
help='Enable verbose mode'
)
parser.add_argument(
'-o',
'--output',
dest='output',
default=None,
help='PCAP output file'
)
parser.add_argument(
'-x',
'--output-format',
dest='output_format',
default='pcap',
help='PCAP output format: `ll_phdr`, `nordic`, `adv` or `pcap`'
)
parser.add_argument(
'-j',
'--jamming',
dest='jamming',
default=False,
action='store_true',
help='Jam an active connection or the advertising channels (only performed in conjunction with -f or -a option)'
)
parser.add_argument(
'-dt',
'--datatype',
dest='datatypes',
action='append',
type=str,
help='The data type should be jamed'
)
parser.add_argument(
'-nid',
'--nid',
dest='nid',
type=str,