Google is committed to advancing racial equity for Black communities. See how.

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

Example:

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

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

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 type, a Long Term Key always has 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 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) for every available controller. Fuchsia stores some metadata for a bt-host that is in use.

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

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

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

BR/EDR data

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