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 component. The data is stored using the 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

Represents a Bluetooth Device Address

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

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".

Example:

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

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.

Peer 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) and security properties, which represent the security of the connection when the key was distributed.

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

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.

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) for every available controller. Fuchsia stores some metadata for a bt-host that is in use.

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 bond data

BR/EDR bond data

Bonding data schema

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"
        ]
    }
}