# 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     | Size of the encryption key used for the exchange

Example:

```
{
    "authenticated": false,
    "secureConnections": true,
    "encryptionKeySize": 16
}
```

#### Key {#key}

128-bit number that represents a pairing secret. Common types of keys that use this schema are the
Identity Resolving Key (IRK) and the Connection Signature Resolving Key (CSRK).

Each key has a 128-bit value and may optionally have [security properties](#security-properties).
Security properties are usually present for keys distributed to a Fuchsia system by a peer during
pairing and represent the security of the connection under which the key was received.

A locally generated key that is stored for future distribution may not have security properties.

Key                           | Value Type                                  | Description
------------------------------|---------------------------------------------|-----------------------------------------
securityProperties (optional) | [Security Properties](#security-properties) | Link security during distribution
value                         | Array of Number (8-bits)                    | 16-octet key in little-endian byte order

The following example represents a key with MITM protection of value `0x100f0e0d0c0b0a090807060504030201`:

```
{
    "securityProperies": {
        "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 both the Low
Energy Long Term Key (LTK) and the BR/EDR Link Key.

Unlike the [Key](#key) type, a Long Term Key always has [security properties](#security-properties).
The security properties of a Long Term 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             | [Key](#key)     | The encryption key.
ediv (optional) | Number (16-bit) | Encrypted Diversifier; required for legacy LE LTK
rand (optional) | Number (64-bit) | Random value; required for legacy LE LTK

Example:

```
{
    "key": {
        "securityProperies": {
            "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             | [Key](#key)         | Identity Resolving Key that is distributed to all peers of the bt-host

Example:

```
{
    "identityAddress": {
        "type": "public",
        "value": [202, 202, 254, 202, 239, 190]
    },
    "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 data {#le-data}

Key                             | Value Type                                        | Description
--------------------------------|---------------------------------------------------|----------------------------------------------
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
peerIrk (optional)              | [Key](#key)                                       | The peer's Identity Resolving Key
connectionParameters (optional) | [LE Connection Parameters](#le-connection-params) | The peer's preferred connection parameters

#### BR/EDR data {#bredr-data}

Key            | Value Type            | Description
---------------|-----------------------|-----------------------------------------------------------
rolePreference | String                | `"leader"` or `"follower"`
linkKey        | [Long Term Key](#ltk) | 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
hostAddress      | [Address](#address)        | The identity address of the local bt-host the peer is bonded to
address          | [Address](#address)        | The identity address of the peer
name             | String                     | The complete or short "local name" of the peer.
le (optional)    | [LE Data](#le-data)        | Bonding data for the Low Energy transport
bredr (optional) | [BR/EDR Data](#bredr-data) | Bonding data for the BR/EDR transport

Example:

```
{
    "identifier": 1,
    "identityAddress: {
        "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": {
                "securityProperies": {
                    "authenticated": true,
                    "secureConnections": false,
                    "encryptionKeySize": 16
                },
                "value": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]
            },
            "keySize": 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"
        ]
    }
}
```