Skip to content

BLEBoy is a training tool to teach users about BLE security by providing a single BLE peripheral that can be used to experiment with each BLE pairing method and demonstrates GATT security concepts.

License

Notifications You must be signed in to change notification settings

nccgroup/BLEBoy

Repository files navigation

BLEBoy

Goal

Create a BLE peripheral that supports all BLE pairing methods that can be used for training and testing, including out-of-band (OOB) pairing. The perpiheral must be configurable and easy to re-create using consumer parts.

About

BLEBoy is a BLE peripheral implemented using the Adafruit nRF52 Feather board, which has been updated to support all BLE pairing methods described in the Bluetooth specification (https://www.bluetooth.com/specifications/bluetooth-core-specification). BLEBoy allows on-the-fly GAP security parameters to be updated (LESC, OOB, MitM, IO capabilities, etc.) to allow users to experiment with the various pairing methods (and the level of security provided by each). It also supports the sending OOB data over serial to allow other tools to construct BLE OOB NFC records for OOB pairing.

This tool can be used with the training modules found in the "Training" folder to learn about BLE security.

NOTE This device is intended to be used for BLE security training. Do not use code in secure applications. There are several random number generators used in the code that are not considered to be cryptographically secure. Later versions of the NRF52 Nordic SDK provide secure RNG APIs that can be used for this purpose if needed.

Requirements

Required Hardware

Note: To handle OOB and Passkey Entry (where the passkey is entered on the peripheral) pairing association models, a Micro-USB cable will need to be connected to the nRF52 Feather and listen for serial communications (baud 9600). This same serial connection is used to print status and debug information.

Optional Hardware

  • For following the OOB NFC example
  • A LIPO battery to remove need for Micro-USB cable to power Feather
  • A hardcase for the solution. The OLED is rather fragile and can easily crack under sharp pressure.

Required Arduino Libraries

All libraries can be installed from their respective sources, except for arduino-menusystem and Bluefruit52Lib that have been modified. A changelog of the modified libraries can be found in 3rdPartyChanges.txt.

Alternatively, users can use the libraries contained in the "libraries" folder of this project to ensure the same version of the libraries used during development is used.

Hardware Setup

The following are setup instructions for constructing BLEBoy using the required hardware listed in the sections above:

  1. Solder male headers on to each of the Feather and Featherwings.
  2. On the Joy Featherwing, look at the bottom of the board and place solder on the Option Interrupt Pin pad in front on pin 27.
  3. Solder female headers on to the Tripler.
  4. Plug all 3 Feather boards on to the Tripler (any order can be used, but for simplicity I put the OLED at the top, nRF52 in the middle, and Joy at the bottom).

Software Installation

To program the nRF52 Feather with the BLEBoy code, follow these steps:

  • Install Arduino IDE.
  • Install Adafruit nRF52 Feather board resources within Arduino IDE (see https://learn.adafruit.com/bluefruit-nrf52-feather-learning-guide/arduino-bsp-setup).
    • Developed and tested against nRF52 board version 0.6.0. Success with other versions may vary.
  • Install 3rd party Arduino libraries (listed in Required Arduino Libraries section above).
  • Replace Adafruit Bluetooth52Lib with the Bluetooth52Lib folder in this repository.
  • Install modified arduino-menusystem library located in the libraries folder within this repository.
  • Upload BLEBoy to nRF52 Feather.
  • Set up serial connection to nRF52 Feather (9600 baud).
  • (Optional) Set up PN532 for OOB NFC pairing

Install Arduino with Adafruit nRF52 Resources on Debian

Install Custom Bluefruit52Lib

  • Copy the custom Bluefruit52Lib folder to ( will vary on installation):
    • OS X : ~/Library/Arduino15/packages/adafruit/hardware/nrf52/<version>/libraries
    • Linux : ~/.arduino15/packages/adafruit/hardware/nrf52/<version>/libraries
    • Windows: %APPDATA%\Local\Arduino15\packages\adafruit\hardware\nrf52\ <version> \libraries

Install 3rd Party Libraries

  • Install 3rd party libraries listed in Required Arduino Libraries
  • Copy arduino-menusystem from BLEBoy libraries folder into your user Arduino library folder.

OR

  • Copy folders in "libraries" to the user Arduino library folder
    • Commonly found in ~/Arduino/libraries or C:\Users\ <user> \Documents\Arduino\libraries

(OPTIONAL) Installation for PN352 for OOB Pairing via NFC

About

BLEBoy is a training tool to teach users about BLE security by providing a single BLE peripheral that can be used to experiment with each BLE pairing method and demonstrates GATT security concepts.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published