| # Bluetooth persistent data schema |
| |
| The Fuchsia Bluetooth subsystem persists bonding information for any peer that has been successfully |
| associated with Fuchsia using the standard Bluetooth pairing procedures. Bonding information |
| includes pairing secrets (such as encryption keys) as well as metadata about the peer used to |
| establish a connection. |
| |
| The persistent bonding storage is maintained by the |
| [`bt-gap`](/src/connectivity/bluetooth/core/bt-gap) component. The data is stored using the |
| [`stash`](/sdk/fidl/fuchsia.stash/) library. There are two kinds of persisted data: Host Data and |
| Bonding Data. |
| |
| ## JSON schema |
| |
| The core Bluetooth system stores its persisted data in JSON format. This section describes |
| the format used to serialized the data. |
| |
| ### Basic types |
| |
| This section describes the schema for types that are reused by other schemas. All schemas are |
| represented as JSON objects. |
| |
| #### Address {#address} |
| |
| Represents a Bluetooth Device Address |
| |
| Key | Value Type | Description |
| ------|--------------------------|----------------------- |
| type | String | `public` or `random` |
| value | Array of Number (8-bits) | 6-octet device address in little-endian byte order |
| |
| The following example represents a random address with value `FF:FF:00:00:00:01`: |
| |
| ``` |
| { |
| "type": "random" |
| "value": [1, 0, 0, 0, 255, 255] |
| } |
| ``` |
| |
| #### Security properties {#security-properties} |
| |
| The security properties of a Bluetooth connection under which pairing secrets were exchanged. For |
| example, an Identity Resolving Key that was distributed by a peer over a link encrypted with an |
| unauthenticated Temporary Key is considered to be "unauthenticated". |
| |
| Key | Value Type | Description |
| ------------------|----------------|-------------------------------------------------------------------- |
| authenticated | Boolean | `true` if MITM protection was enabled |
| secureConnections | Boolean | `true` if the secret was exchanged using Secure Connections pairing |
| encryptionKeySize | Number (8-bit) | Size of the encryption key used for the exchange |
| |
| Example: |
| |
| ``` |
| { |
| "authenticated": false, |
| "secureConnections": true, |
| "encryptionKeySize": 16 |
| } |
| ``` |
| |
| #### Key {#key} |
| |
| 128-bit number that represents a secret associated with pairing. A common key that uses this schema |
| is the local device's Identity Resolving Key (IRK). |
| |
| When used by itself, a Key represents a locally generated key stored for future distribution. |
| |
| Key | Value Type | Description |
| ------|---------------------------------------------|----------------------------------------- |
| value | Array of Number (8-bits) | 16-octet key in little-endian byte order |
| |
| #### Peer key {#key} |
| |
| 128-bit key that represents a pairing-related secret from the peer. A common key that uses this |
| schema is the peer's Identity Resolving Key (IRK). |
| |
| Each key has a 128-bit value (like [Key](#key)) and [security properties](#security-properties), |
| which represent the security of the connection when the key was distributed. |
| |
| Key | Value Type | Description |
| ---------|---------------------------------------------|----------------------------------------- |
| security | [Security properties](#security-properties) | Link security during distribution |
| value | Array of Number (8-bits) | Underlying 16-octet key in little-endian byte order |
| |
| The following example represents a key with MITM protection of value `0x100f0e0d0c0b0a090807060504030201`: |
| |
| ``` |
| { |
| "security": { |
| "authenticated": true, |
| "secureConnections": false, |
| "encryptionKeySize": 16 |
| }, |
| "value": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16] |
| } |
| ``` |
| |
| #### Long term key {#ltk} |
| |
| 128-bit key used to establish an encrypted connection. This schema is used to represent the Low |
| Energy Long Term Key (LTK). |
| |
| The security properties of a Long Term Key's peer key represent not only the security of the |
| connection used to distribute and generate the key, but also the security of the key itself. |
| |
| Key | Value Type | Description |
| -----|---------------------------|--------------------- |
| key | [Peer key](#peer-key) | The encryption key. |
| ediv | Number (16-bit) | Encrypted Diversifier |
| rand | Number (64-bit) | Random value |
| |
| Example: |
| |
| ``` |
| { |
| "key": { |
| "security": { |
| "authenticated": true, |
| "secureConnections": false, |
| "encryptionKeySize": 16 |
| }, |
| "value": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16] |
| }, |
| "ediv": 48879, |
| "rand": 9223372036854775807 |
| } |
| ``` |
| |
| ### Host data |
| |
| The Fuchsia Bluetooth system is compatible with one or more Bluetooth controllers. The system |
| instantiates a Bluetooth Host Subsystem ([bt-host](/src/connectivity/bluetooth/core/bt-host)) |
| for every available controller. Fuchsia stores some metadata for a bt-host that is in use. |
| |
| Key | Value Type | Description |
| ----------------|---------------------|----------------------- |
| irk (optional) | [Key](#key) | Identity Resolving Key that is distributed to all peers of the bt-host |
| |
| Example: |
| |
| ``` |
| { |
| "irk": { |
| "value": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16] |
| } |
| } |
| ``` |
| |
| ### Bonding data |
| |
| Every peer that has been associated with the Fuchsia system using a standard Bluetooth pairing |
| procedure is considered to have a bond with the Fuchsia system. Fuchsia persists metadata for each |
| bonded peer to re-establish an encrypted link on future connections without needing to repeat |
| security and pairing procedures. Fuchsia also persists additional metadata to speed up the |
| connection establishment process. |
| |
| Separate JSON object schemas are defined for LE and BR/EDR transports. The Fuchsia system may |
| persist LE data, BR/EDR data, or both based on peer support for the particular transport (e.g. a |
| dual-mode peer may result in bonding data for both transports). |
| |
| #### LE connection parameters {#le-connection-params} |
| |
| Key | Value Type | Description |
| -------------------|-----------------|------------------ |
| connectionInterval | Number (16-bit) | Connection interval in controller timeslices |
| connectionLatency | Number (16-bit) | Connection latency in controller timeslices |
| supervisionTimeout | Number (16-bit) | Supervision timeout in controller timeslices |
| |
| #### LE bond data {#le-data} |
| |
| Key | Value Type | Description |
| --------------------------------|----------------------------------------------------|---------------------------------------------- |
| connectionParameters (optional) | [LE Connection Parameters](#le-connection-params) | The peer's preferred connection parameters |
| peerLtk (optional) | [Long Term Key](#ltk) | Long Term Key distributed by the peer |
| localLtk (optional) | [Long Term Key](#ltk) | Long Term Key generated locally and distributed to the peer |
| irk (optional) | [Peer key](#peer-key) | The peer's Identity Resolving Key |
| |
| #### BR/EDR bond data {#bredr-data} |
| |
| Key | Value Type | Description |
| --------------------------|-----------------------|----------------------------------------------------------- |
| rolePreference (optional) | String | `"leader"` or `"follower"` |
| linkKey (optional) | [Peer key](#peer-key) | The link encryption key |
| services | Array of String | Cached discovered service UUIDs |
| |
| #### Bonding data schema |
| |
| Key | Value Type | Description |
| -----------------|---------------------------------|------------------------ |
| identifier | Number | 64-bit opaque peer ID |
| address | [Address](#address) | The identity address of the peer |
| hostAddress | [Address](#address) | The identity address of the local bt-host the peer is bonded to |
| name (optional) | String | The complete or short "local name" of the peer. |
| le (optional) | [LE bond data](#le-data) | Bonding data for the Low Energy transport |
| bredr (optional) | [BR/EDR bond data](#bredr-data) | Bonding data for the BR/EDR transport |
| |
| Example: |
| |
| ``` |
| { |
| "identifier": 1, |
| "address: { |
| "type": "random", |
| "value": [202, 202, 254, 202, 239, 190] |
| }, |
| "hostAddress": { |
| "type": "public", |
| "value": [1, 2, 3, 4, 5, 6] |
| }, |
| "name": "My Device", |
| "le": { |
| "peerLtk": { |
| "key": { |
| "security": { |
| "authenticated": true, |
| "secureConnections": false, |
| "encryptionKeySize": 16 |
| }, |
| "value": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16] |
| }, |
| "ediv": 0, |
| "rand": 0, |
| }, |
| }, |
| "bredr": { |
| "rolePreference": "follower", |
| "linkKey": { |
| "security": { |
| "authenticated": true, |
| "secureConnections": true, |
| "encryptionKeySize": 16 |
| }, |
| "value": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16] |
| }, |
| "services": [ |
| "0000110a-0000-1000-8000-00805f9b34fb", |
| "0000110b-0000-1000-8000-00805f9b34fb" |
| ] |
| } |
| } |
| ``` |
