Name Date Size #Lines LOC

..--

meta/H25-Apr-2025-2019

BUILD.bazelH A D25-Apr-20252.7 KiB10294

BUILD.gnH A D25-Apr-20253.5 KiB139121

README.mdH A D25-Apr-202510.3 KiB7758

ecdh_key.ccH A D25-Apr-20255.2 KiB176137

ecdh_key_test.ccH A D25-Apr-20259.3 KiB178121

error.ccH A D25-Apr-20252.6 KiB7956

error_test.ccH A D25-Apr-2025944 2910

packet.ccH A D25-Apr-20252.1 KiB5835

packet_test.ccH A D25-Apr-20253.7 KiB9162

pairing_channel.ccH A D25-Apr-20253.1 KiB8759

pairing_channel_test.ccH A D25-Apr-20256.9 KiB197147

pairing_phase.ccH A D25-Apr-20252 KiB6439

pairing_phase_test.ccH A D25-Apr-20255.6 KiB154102

phase_1.ccH A D25-Apr-202515.7 KiB385271

phase_1_test.ccH A D25-Apr-202565.8 KiB1,6141,344

phase_2_legacy.ccH A D25-Apr-202513.9 KiB400287

phase_2_legacy_test.ccH A D25-Apr-202531.9 KiB874675

phase_2_secure_connections.ccH A D25-Apr-202514.3 KiB402331

phase_2_secure_connections_test.ccH A D25-Apr-202533.3 KiB852736

phase_3.ccH A D25-Apr-202513.7 KiB431307

phase_3_test.ccH A D25-Apr-202535.5 KiB911714

sc_stage_1_just_works_numeric_comparison.ccH A D25-Apr-20257.6 KiB207169

sc_stage_1_just_works_numeric_comparison_test.ccH A D25-Apr-202516.9 KiB449371

sc_stage_1_passkey.ccH A D25-Apr-20259.9 KiB270219

sc_stage_1_passkey_test.ccH A D25-Apr-202521.4 KiB573483

security_manager.ccH A D25-Apr-202538 KiB1,039771

security_manager_test.ccH A D25-Apr-2025142.9 KiB3,9232,829

security_request_phase.ccH A D25-Apr-20253 KiB8963

security_request_phase_test.ccH A D25-Apr-20257.8 KiB210162

test_security_manager.ccH A D25-Apr-20253.2 KiB8460

types.ccH A D25-Apr-20258 KiB214161

types_test.ccH A D25-Apr-202514.5 KiB358288

util.ccH A D25-Apr-202523.4 KiB643477

util_test.ccH A D25-Apr-202550.5 KiB1,2481,106

valid_packet_reader_parse_sdu_fuzztest.ccH A D25-Apr-20251.2 KiB3616

README.md

1# Security Manager (SM)
2This directory contains Fuchsia's implementation of the Security Manager Protocol (SMP) from the Bluetooth Core Specification v5.2 Volume 3 Part H. At a high level, SM works to ensure the integrity and privacy of sensitive communication over Bluetooth. Internally, this is done through the generation, distribution, and usage of Bluetooth security keys. SMP is the standard protocol for security management of Bluetooth LE transports. For dual-mode devices, SMP also provides means for managing BR/EDR transport security.
3
4
5## Feature support
6Description                                                | Level of Support
7-----------------------------------------------------------|---------------------------
8SMP over BR/EDR                                            | Not Supported
9GAP LE Security Mode 1 (encrypted security levels)         | Supported
10GAP LE Security Mode 2 (unencrypted, data-signed security) | Not Supported
11GAP LE Security Mode 3 (Broadcast_Code encrypted security) | Not Supported
12GAP LE Secure Connections Only Mode                        | Supported
13Legacy Pairing                                             | Supported
14Secure Connections Pairing                                 | Supported
15Out of Band Pairing                                        | Not Supported
16Identity Resolving Key (IRK) Exchange                      | Supported
17Connection Signature Resolving Key (CSRK) Exchange         | Not Supported
18Cross-Transport Key Generation                             | Not Supported
19SMP Security Request                                       | Supported
20
21See Core Specification v5.2 Volume 3 Part C Section 10.2 for more information about the GAP LE Security Modes.
22
23## Library interface
24The Fuchsia SMP library exposes its functionality through the [`SecurityManager`](/src/connectivity/bluetooth/core/bt-host/sm/security_manager.h) abstract class. Each Bluetooth connection is expected to instantiate its own `SecurityManager`, i.e. there is no singleton which manages security for all of Fuchsia Bluetooth. For production, this is done through the `SecurityManagerImpl::Create` factory function, as `SecurityManagerImpl` provides the production implementation of the `SecurityManager` interface. **The SM library expects that clients will only directly instantiate `SecurityManagers`, not any other internal classes. All callbacks related to SMP, including HCI link and L2CAP channel callbacks, must be run on the same thread as the instantiated SecurityManager.** The public interface of SecurityManager is the intended public interface for the SM library as a whole. Documentation can be found in the [`SecurityManager` header](/src/connectivity/bluetooth/core/bt-host/sm/security_manager.h).
25
26
27### Interface concepts
28**Security upgrade** - While most of the code in [this library](/src/connectivity/bluetooth/core/bt-host/sm/) relates to pairing, SM does not allow clients to directly start pairing. Instead, clients request a security upgrade to a certain level. SM tracks the current security properties of the link (i.e. encrypted / authenticated / encryption key size), and may (or may not) determine that pairing and/or link encryption are required to bring the link to the client's desired security level. In response to a security upgrade request, clients are only told whether their request was fulfilled along with the current security properties of the link, not any specifics e.g. about whether their request was directly responsible for pairing.
29
30**PairingDelegate** - Pairing with a peer may give that device access to sensitive information and/or capabilities, so it is good practice (and in some cases, required) to condition pairing on explicit user input. Thus SM must be able to display input prompts and handle user input during pairing. The [`bt-host`](/src/connectivity/bluetooth/core/bt-host/README.md) driver is device-agnostic, so SM cannot directly display output or query for user input from an unknown device. Instead, SM uses the `bt-host`-internal [`sm::Delegate`](/src/connectivity/bluetooth/core/bt-host/sm/delegate.h) class to display information and request user input, which eventually bubbles up to the system [PairingDelegate FIDL protocol](/sdk/fidl/fuchsia.bluetooth.sys/pairing_delegate.fidl).
31
32**Link-layer encryption and SM** - A reasonable, but incorrect, assumption is that SM is directly responsible for encrypting BLE data. SM, the Bluetooth controller, and `hci::Connection` all play roles in encrypting data with the encryption key. SM is responsible for generating (and optionally storing/bonding) the key for the link through pairing. The Bluetooth controller is responsible for validating that both devices agree on the key and then using the key to actually (en|de)crypt data over the link. `SecurityManager` takes a pointer to [`hci::Connection`](/src/connectivity/bluetooth/core/bt-host/hci/connection.h) in its constructor, which serves as the bridge between the two. SM assigns the encryption key to `hci::Connection`, which stores it internally. It then responds to HCI encryption key request events from the controller with this key. **The `hci::Connection` LE encryption key should only ever be modified by SM**.
33
34### Testing
35The SM library exposes the `TestSecurityManager` test double through its `sm:testing` GN target. For SM-dependent code, this test double can be used for more deterministic/simpler unit tests. Clients can obtain instances through the `TestSecurityManager::Create` factory function (analogous to production usage of `SecurityManagerImpl::Create`).
36
37
38## Implementation details
39The remainder of this document is aimed at developers who plan to change SM, and explains how the protocol is implemented in Fuchsia.
40
41
42### Ownership and source hierarchy
43This section aims to give a high-level understanding of how the various files and classes in the sm/ directory are related.
44
45#### Stateful pairing classes
46Each of these files represents a single stateful class which implements a portion of the SMP pairing state machine. Indentation is used to indicate ownership, with the `SecurityManager` class at the top level - this is consistent with the expectation that only the `SecurityManager` class should be directly instantiated by non-SM code. While the `*Phase*` classes are always owned by `SecurityManager`, the SecurityManager uses a `std::variant` to store the current class, meaning that only 1 `*Phase*` class is ever present at once. Documentation for each class can be found in the linked header file.
47
48- [`SecurityManager`](/src/connectivity/bluetooth/core/bt-host/sm/security_manager.h)
49  - [`PairingChannel`](/src/connectivity/bluetooth/core/bt-host/sm/pairing_channel.h)
50  - [`SecurityRequestPhase`](/src/connectivity/bluetooth/core/bt-host/sm/security_request_phase.h)
51  - [`Phase1`](/src/connectivity/bluetooth/core/bt-host/sm/phase_1.h)
52  - [`Phase2Legacy`](/src/connectivity/bluetooth/core/bt-host/sm/phase_2_legacy.h)
53  - [`Phase2SecureConnections`](/src/connectivity/bluetooth/core/bt-host/sm/phase_2_secure_connections.h)
54    - [`ScStage1JustWorksNumericComparison`](/src/connectivity/bluetooth/core/bt-host/sm/sc_stage_1_just_works_numeric_comparison.h)
55    - [`ScStage1Passkey`](/src/connectivity/bluetooth/core/bt-host/sm/sc_stage_1_passkey.h)
56  - [`Phase3`](/src/connectivity/bluetooth/core/bt-host/sm/phase_3.h)
57
58#### Abstract pairing classes
59These are abstract classes subclassed by many of the "stateful pairing classes".
60* [`PairingPhase`](/src/connectivity/bluetooth/core/bt-host/sm/pairing_phase.h) - `SecurityRequestPhase`, `Phase1`, `Phase2Legacy`, `Phase2SecureConnections`, and `Phase3` subclass this class. `PairingPhase` provides interfaces and functionality relevant to all phases of pairing.
61* [`ScStage1`](/src/connectivity/bluetooth/core/bt-host/sm/sc_stage_1.h) - `ScStage1JustWorksNumericComparison` and `ScStage1Passkey` subclass this pure interface. `ScStage1` provides methods for `Phase2SecureConnections` to polymorphically interact with both of the Stage 1 classes.
62
63#### Utility files:
64These files provide commonly-used functionality in SM. They easily could be (and sometimes are) used outside of SM. These files contain definitions, pure functions of their input, or small structs/classes with little internal state:
65  * [`delegate.h`](/src/connectivity/bluetooth/core/bt-host/sm/delegate.h) - details the interface required by the `SecurityManager` constructor for SMP to interact with the rest of the BT stack.
66  * [`ecdh_key.h`](/src/connectivity/bluetooth/core/bt-host/sm/ecdh_key.h) - utility C++ wrapper class for BoringSSL ECDH key functionality used in Secure Connections pairing.
67  * [`packet.h`](/src/connectivity/bluetooth/core/bt-host/sm/packet.h) - SM-specific packet parsing and writing classes.
68  * [`error.h`](/src/connectivity/bluetooth/core/bt-host/sm/error.h) - SM-specific version of the `bt-host` [`Error`](/pw_bluetooth_sapphire/internal/host/common/error.h) class and associated type aliases.
69  * [`smp.h`](/src/connectivity/bluetooth/core/bt-host/sm/smp.h) - definitions of Security Manager Protocol constants from the specification section (see Section 3 of the SM spec section).
70  * [`types.h`](/src/connectivity/bluetooth/core/bt-host/sm/types.h) - definitions of structs and enums used in SM code that are not part of the SMP specification.
71  * [`util.h`](/src/connectivity/bluetooth/core/bt-host/sm/util.h) - cryptographic primitives and other pure-function utilities used in the SMP stack.
72
73#### Test files:
74Besides the `bt-host` standard `<source_file_stem>_test.cc` files, SM provides the following test helpers:
75* [`TestSecurityManager(Factory)`](/src/connectivity/bluetooth/core/bt-host/sm/test_security_manager.h) - a test implementation of SM's public interface, `SecurityManager`. Provides a `TestSecurityManagerFactory` with a `CreateSm` method which stores a reference to the created `TestSecurityManager`. A `TestSecurityManagerFactory` can be used to inject `TestSecurityManager`s into production code while keeping them accessible by unit tests. The current implementation is a very minimal test spy. It provides basic argument snooping and stub responses for a few methods and noop implementations for others. More functionality may be added as necessary to expand test coverage of SM-dependent code.
76* [`FakeListener`](/src/connectivity/bluetooth/core/bt-host/sm/fake_phase_listener.h) - fakes an implementation of the `PairingPhase::Listener` interface, which the `PairingPhase` subclasses require for unit testing.
77