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

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

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

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

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.

Key Value Type Description
security 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

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

Key Value Type Description
irk (optional) 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

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

Key Value Type Description
connectionParameters (optional) LE Connection Parameters The peer's preferred connection parameters
peerLtk (optional) Long Term Key Long Term Key distributed by the peer
localLtk (optional) Long Term Key Long Term Key generated locally and distributed to the peer
irk (optional) Peer key The peer's Identity Resolving Key

BR/EDR bond data

Key Value Type Description
rolePreference (optional) String "leader" or "follower"
linkKey (optional) 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 The identity address of the peer
hostAddress 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 Bonding data for the Low Energy transport
bredr (optional) BR/EDR bond 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"
        ]
    }
}