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.
The core Bluetooth system stores its persisted data in JSON format. This section describes the format used to serialized the data.
This section describes the schema for types that are reused by other schemas. All schemas are represented as JSON objects.
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]
}
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
}
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]
}
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
}
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]
}
}
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).
| 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 |
| 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 |
| 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 |
| 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"
]
}
}