mirror of
https://github.com/bluekitchen/btstack.git
synced 2025-02-10 06:40:23 +00:00
docu: ENABLE_LE_SECURE_CONNECTIONS. Intro in SM protocol
This commit is contained in:
Matthias Ringwald
parent
a83a05444b
commit
007ef129e6
@ -41,7 +41,6 @@ System properties:
|
||||
-----------------------------------|-------------------------------------
|
||||
HAVE_MALLOC | Use dynamic memory
|
||||
|
||||
|
||||
Embedded platform properties:
|
||||
|
||||
#define | Description
|
||||
@ -65,16 +64,17 @@ HAVE_POSIX_TIME | System provides time function
|
||||
### ENABLE_* directives {#sec:enableDirectives}
|
||||
BTstack properties:
|
||||
|
||||
#define | Description
|
||||
-------------------------|---------------------------------------------
|
||||
ENABLE_CLASSIC | Enable Classic related code in HCI and L2CAP
|
||||
ENABLE_BLE | Enable BLE related code in HCI and L2CAP
|
||||
ENABLE_EHCILL | Enable eHCILL low power mode on TI CC256x/WL18xx chipsets
|
||||
ENABLE_LOG_DEBUG | Enable log_debug messages
|
||||
ENABLE_LOG_ERROR | Enable log_error messages
|
||||
ENABLE_LOG_INFO | Enable log_info messages
|
||||
ENABLE_LOG_INTO_HCI_DUMP | Log debug messages as part of packet log
|
||||
ENABLE_SCO_OVER_HCI | Enable SCO over HCI for chipsets (only CC256x/WL18xx currently)
|
||||
#define | Description
|
||||
-----------------------------|---------------------------------------------
|
||||
ENABLE_CLASSIC | Enable Classic related code in HCI and L2CAP
|
||||
ENABLE_BLE | Enable BLE related code in HCI and L2CAP
|
||||
ENABLE_EHCILL | Enable eHCILL low power mode on TI CC256x/WL18xx chipsets
|
||||
ENABLE_LOG_DEBUG | Enable log_debug messages
|
||||
ENABLE_LOG_ERROR | Enable log_error messages
|
||||
ENABLE_LOG_INFO | Enable log_info messages
|
||||
ENABLE_LOG_INTO_HCI_DUMP | Log debug messages as part of packet log
|
||||
ENABLE_SCO_OVER_HCI | Enable SCO over HCI for chipsets (only CC256x/WL18xx and USB CSR controllers)
|
||||
ENABLE_LE_SECURE_CONNECTIONS | Enable LE Secure Connections using [mbed TLS library](https://tls.mbed.org)
|
||||
|
||||
|
||||
### Memory configuration directives {#sec:memoryConfigurationHowTo}
|
||||
|
||||
@ -753,10 +753,35 @@ notifications and indications can be sent. Please see Section on
|
||||
|
||||
The SMP protocol allows to setup authenticated and encrypted LE
|
||||
connection. After initialization and configuration, SMP handles security
|
||||
related functions on it’s own but emits events when feedback from the
|
||||
related functions on its own but emits events when feedback from the
|
||||
main app or the user is required. The two main tasks of the SMP protocol
|
||||
are: bonding and identity resolving.
|
||||
|
||||
### LE Legacy Pairing and LE Secure Connections
|
||||
|
||||
The original pairing algorithm introduced in Bluetooth Core V4.0 does not
|
||||
provide security in case of an attacker present during the initial pairing.
|
||||
To fix this, the Bluetooth Core V4.2 specification introduced the new
|
||||
*LE Secure Connections* method, while referring to the original method as *LE Legacy Pairing*.
|
||||
|
||||
BTstack supports both pairing methods. To enable the more secure LE Secure Connections method,
|
||||
*ENABLE_LE_SECURE_CONNECTIONS* needs to be defined in *btstack_config.h*.
|
||||
|
||||
LE Secure Connections are based on Elliptic Curve Diffie-Hellman (ECDH) keypairs.
|
||||
On start, a new public/private key pair is generated. During pairing, the
|
||||
Long Term Key (LTK) is generated based on the local keypair and the remote public key.
|
||||
To facilitate the creation of such a keypairs and the calculation of the LTK,
|
||||
the Bluetooth Core V4.2 specification introduced appropriate commands for the Bluetooth controller.
|
||||
|
||||
As an alternative for controller that don't provide these primitives, BTstack implements
|
||||
the crytographic functions in software with the help of the Apache 2.0 Licensed [mbed TLS library](https://tls.mbed.org).
|
||||
|
||||
There are two drawbacks when using LE Secure Connections:
|
||||
|
||||
- More RAM: It requires an additional 1.5 kB RAM in the current configuration (with mbed TLS).
|
||||
- Peripheral must store LTK: Even an LE Peripheral needs to store the LTK in non-volatile memory.
|
||||
|
||||
|
||||
### Initialization
|
||||
|
||||
To activate the security manager, call *sm_init()*.
|
||||
@ -793,7 +818,9 @@ The default SMP configuration in BTstack is to be as open as possible:
|
||||
|
||||
- accept encryption key size from 7..16 bytes,
|
||||
|
||||
- expect no authentication requirements, and
|
||||
- expect no authentication requirements,
|
||||
|
||||
- don't support LE Secure Connections, and
|
||||
|
||||
- IO Capabilities set to *IO_CAPABILITY_NO_INPUT_NO_OUTPUT*.
|
||||
|
||||
@ -804,10 +831,11 @@ respectively:
|
||||
|
||||
- *sm_set_encryption_key_size_range*
|
||||
|
||||
- *sm_set_authentication_requirements*
|
||||
- *sm_set_authentication_requirements* : add SM_AUTHREQ_SECURE_CONNECTION to enable LE Secure Connections
|
||||
|
||||
- *sm_set_io_capabilities*
|
||||
|
||||
|
||||
### Identity Resolving
|
||||
|
||||
Identity resolving is the process of matching a private, resolvable
|
||||
@ -824,35 +852,37 @@ and later:
|
||||
|
||||
- *SM_EVENT_IDENTITY_RESOLVING_FAILED* on lookup failure.
|
||||
|
||||
### Bonding process
|
||||
### User interaction
|
||||
|
||||
In Bluetooth LE, there are three main methods of establishing an
|
||||
encrypted connection. From the most to the least secure, these are:
|
||||
Out-of-Band (OOB) Data , Passkey, and Just Works.
|
||||
|
||||
With OOB data, there needs to be a pre-shared secret 16 byte key. In
|
||||
most cases, this is not an option, especially since popular OS like iOS
|
||||
don’t provide a way to specify it. It some applications, where both
|
||||
sides of a Bluetooth link are developed together, this could provide a
|
||||
viable option.
|
||||
|
||||
To provide OOB data, you can register an OOB data callback with
|
||||
*sm_register_oob_data_callback*.
|
||||
|
||||
Depending on the authentication requirements, available OOB data, and
|
||||
the enabled STK generation methods, BTstack will request feedback from
|
||||
Depending on the authentication requirements, IO capabilities,
|
||||
available OOB data, and the enabled STK generation methods,
|
||||
BTstack will request feedback from
|
||||
the app in the form of an event:
|
||||
|
||||
- *SM_EVENT_JUST_WORKS_REQUEST*: request a user to accept a Just Works
|
||||
pairing
|
||||
|
||||
- *SM_EVENT_PASSKEY_INPUT_NUMBER*: request user to input a passkey
|
||||
|
||||
- *SM_EVENT_PASSKEY_DISPLAY_NUMBER*: show a passkey to the user
|
||||
|
||||
- *SM_EVENT_JUST_WORKS_REQUEST*: request a user to accept a Just Works
|
||||
pairing
|
||||
- *SM_EVENT_NUMERIC_COMPARISON_REQUEST*: show a passkey to the user and request confirmation
|
||||
|
||||
To stop the bonding process, *sm_bonding_decline* should be called.
|
||||
Otherwise, *sm_just_works_confirm* or *sm_passkey_input* can be
|
||||
called.
|
||||
|
||||
After the bonding process, *SM_EVENT_PASSKEY_DISPLAY_CANCEL* is emitted to
|
||||
update the user interface.
|
||||
After the bonding process, *SM_EVENT_JUST_WORKS_CANCEL*, *SM_EVENT_PASSKEY_DISPLAY_CANCEL*, or *SM_EVENT_NUMERIC_COMPARISON_CANCEL* is emitted to update the user interface if an Just Works request or a passkey has been shown before.
|
||||
|
||||
|
||||
### Out-of-Band Data with LE Legacy Pairing
|
||||
|
||||
LE Legacy Pairing can be made secure by providing a way for both devices
|
||||
to aquire a pre-shared secret 16 byte key by some fancy method.
|
||||
In most cases, this is not an option, especially since popular OS like iOS
|
||||
don’t provide a way to specify it. In some applications, where both
|
||||
sides of a Bluetooth link are developed together, this could provide a
|
||||
viable option.
|
||||
|
||||
To provide OOB data, you can register an OOB data callback with
|
||||
*sm_register_oob_data_callback*.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user