<commit_before>.. -*- mode: rst; fill-column: 80 -*-

###############################
Bluetooth Secure Simple Pairing
###############################

.. note:: This is "work in progress" towards version 0.3

.. versionadded:: 0.3

Overview
========

.. _Bluetooth Assigned Numbers: https://www.bluetooth.com/specifications/assigned-numbers

Bluetooth Secure Simple Pairing (SSP) has been introduced in Bluetooth Core
Specification Version 2.1 + EDR as a method by which two Bluetooth devices can
establish secure communication through data exchange over an out-of-band channel
such as NFC. With Bluetooth Core Specification Version 4.0 this was extended to
cover Bluetooth Low Energy devices and Bluetooth LE Secure Connections pairing
has been introduced in Bluetooth Core Specification Version 4.2.

Bluetooth devices since version 2.1 use Secure Simple Pairing (SSP) to securely
connect. SSP provides a stronger level of security, yet makes it easier for the
user to perform pairing. SSP explicitly introduces the notion of Out-of-Band
(OOB) pairing. The information (Hash C and Randomizer R used for Bluetooth
BR/EDR devices and TK-value and/or LE Secure Connections Confirmation Value and
Random Value used for Bluetooth LE devices) can be exchanged over an NFC link to
be used as part of the OOB pairing process.

A Bluetooth BR/EDR Device may support Interlaced Page Scan to reduce the
connection time. It is recommended that after OOB Data has been exchanged over
NFC, Interlaced Page Scan is enabled for at least 60 seconds. As this consumes
more power than normal page scan, it is also recommended to limit the maximum
duration of Interlaced Page Scan to 120 seconds.

Bluetooth LE Central and Peripheral Devices should use the fast connection
establishment parameters recommended by the Bluetooth SIG (Bluetooth
Specification 4.2, Volume 3, Part C, Sections 9.3.11 and 9.3.12) to reduce the
Bluetooth LE connection setup time.

Connection Handover
-------------------

Bluetooth Secure Simple Pairing defines four different association models, one
of them using an Out-of-Band channel such as NFC. This is defined since Bluetooth version 2.1

The Bluetooth SIG defined a mechanism called “Secure Simple Pairing”
([BLUETOOTH_CORE], Volume 2, Part H, Section 7) to simplify the process of pairing two
Bluetooth BR/EDR devices. Pairing between Bluetooth LE devices is defined in
[BLUETOOTH_CORE], Volume 3, Part H.
Secure Simple Pairing defines four different association models, one of them using an Out-of-
Band channel such as NFC.
The [BLUETOOTH_CORE] Version 4.2 introduces following terms for Bluetooth LE pairing:

LE Secure Connections pairing

LE legacy pairing (LE pairing as defined in [BLUETOOTH_CORE] Versions 4.0 and 4.1)
Four different association models are defined for LE Secure Connections pairing and three for LE
legacy pairing, one of them is the Out-Of-Band association model (defined for both LE Secure
Connections pairing and LE legacy pairing).

Bluetooth BR/EDR Out-of-Band Data
---------------------------------

.. table:: Bluetooth BR/EDR Secure Simple Pairing OOB Data

   +-------------------+------+--------------------------------------------------------+
   | Element           | Size | Description                                            |
   +===================+======+========================================================+
   | OOB Data Length   | 2    | Total length of OOB data including the Length field    |
   +-------------------+------+--------------------------------------------------------+
   | Bluetooth Address | 6    | The 48-bit Bluetooth Device Address (MAC Address)      |
   +-------------------+------+--------------------------------------------------------+
   | OOB Optional Data | N    | Additional OOB data as Extended Inquiry Response [#]_  |
   +-+-----------------+------+--------------------------------------------------------+
   | | EIR 0x02 or 0x03 --- Incomplete or Complete List of 16-bit Service Class UUIDs  |
   +-+---------------------------------------------------------------------------------+
   | | EIR 0x04 or 0x05 --- Incomplete or Complete List of 32-bit Service Class UUIDs  |
   +-+---------------------------------------------------------------------------------+
   | | EIR 0x06 or 0x07 --- Incomplete or Complete List of 128-bit Service Class UUIDs |
   +-+---------------------------------------------------------------------------------+
   | | EIR 0x08 or 0x09 --- Shortened or Complete Bluetooth Local Name                 |
   +-+---------------------------------------------------------------------------------+<commit_msg>further work on Bluetooth documentation<commit_after>.. -*- mode: rst; fill-column: 80 -*-

###############################
Bluetooth Secure Simple Pairing
###############################

.. note:: This is "work in progress" towards version 0.3

.. versionadded:: 0.3

Overview
========

.. _Bluetooth Assigned Numbers: https://www.bluetooth.com/specifications/assigned-numbers

Bluetooth Secure Simple Pairing (SSP) has been introduced in Bluetooth Core
Specification Version 2.1 + EDR as a method by which two Bluetooth devices can
establish secure communication. With Bluetooth Core Specification Version 4.0
this was extended to cover Bluetooth Low Energy devices.

Bluetooth Secure Simple Pairing defines four different association models, one
of them is using an out-of-band channel such as NFC. Secure Simple Pairing
introduced in Bluetooth Version 2.1 + EDR uses Elliptic Curve Diffie-Hellman
with curve P-192. Bluetooth Version 4.1 added the Secure Connections feature,
which upgraded Secure Simple Pairing to utilize the P-256 elliptic curve. In
either case the out-of-band communication transfers a public key commitment
through a 128-bit hash and randomizer prior to in-band public key
exchange. Bluetooth BR/EDR key generation is performed in the Controller.

Bluetooth Low Energy, introduced with Core Specification Version 4.0, uses a
Security Manager component on the device host to generate keys. Three pairing
methods - Just Works, Passkey Entry, and Out of Band - were initially defined
with protection levels depending on the secrecy of temporary keys exchanged
while pairing. Bluetooth Version 4.2 then added LE Secure Connections with the
same pairing methods and P-256 based Elliptic Curve Diffie-Hellman as for BR/EDR
Secure Connections.


Bluetooth BR/EDR Out-of-Band Data
---------------------------------

.. table:: Bluetooth BR/EDR Secure Simple Pairing OOB Data

   +-------------------+------+--------------------------------------------------------+
   | Element           | Size | Description                                            |
   +===================+======+========================================================+
   | OOB Data Length   | 2    | Total length of OOB data including the Length field    |
   +-------------------+------+--------------------------------------------------------+
   | Bluetooth Address | 6    | The 48-bit Bluetooth Device Address (MAC Address)      |
   +-------------------+------+--------------------------------------------------------+
   | OOB Optional Data | N    | Additional OOB data as Extended Inquiry Response [#]_  |
   +-+-----------------+------+--------------------------------------------------------+
   | | EIR 0x02 or 0x03 --- Incomplete or Complete List of 16-bit Service Class UUIDs  |
   +-+---------------------------------------------------------------------------------+
   | | EIR 0x04 or 0x05 --- Incomplete or Complete List of 32-bit Service Class UUIDs  |
   +-+---------------------------------------------------------------------------------+
   | | EIR 0x06 or 0x07 --- Incomplete or Complete List of 128-bit Service Class UUIDs |
   +-+---------------------------------------------------------------------------------+
   | | EIR 0x08 or 0x09 --- Shortened or Complete Bluetooth Local Name                 |
   +-+---------------------------------------------------------------------------------+
{'fraction_non_alphanumeric': 0.25761910685408634, 'fraction_numerical': 0.01753949496205996, 'mean_word_length': 1.8490432317505316, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4594919', 'n_tokens_mistral': 1966, 'n_tokens_neox': 1700, 'n_words': 851}