blob: e5141e660ca7de928ecb9784a4f14b7985dc628b [file] [log] [blame]
// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.bluetooth.sys;
using fuchsia.bluetooth as bt;
type SecurityProperties = struct {
authenticated bool;
secure_connections bool;
encryption_key_size uint8;
};
/// Represents a 128-bit secret key.
type Key = struct {
value array<uint8, 16>;
};
/// Represents a key that was received from a peer.
type PeerKey = struct {
/// The security properties of this link under which this key was received.
security SecurityProperties;
/// The contents of the key.
data Key;
};
/// Represents a locally generated key that is distributed across one or more bonds.
alias LocalKey = Key;
/// Represents a LE Long-Term peer key used for link encyrption. The `ediv` and `rand`
/// fields are zero if distributed using LE Secure Connections pairing.
type Ltk = struct {
key PeerKey;
ediv uint16;
rand uint64;
};
/// The preferred LE connection parameters of the peer.
type LeConnectionParameters = struct {
connection_interval uint16;
connection_latency uint16;
supervision_timeout uint16;
};
type LeBondData = table {
/// The peer's preferred connection parameters, if known.
1: connection_parameters LeConnectionParameters;
/// Known GATT service UUIDs.
2: services vector<bt.Uuid>:MAX_PEER_SERVICES;
/// Identity Resolving RemoteKey used to generate and resolve random addresses.
3: irk PeerKey;
/// Connection Signature Resolving RemoteKey used for data signing without encryption.
4: csrk PeerKey;
/// LE long-term key used to encrypt a connection when the peer is in the LE Peripheral role.
///
/// In legacy pairing (`peer_ltk.security.secure_connections` is false), this key corresponds
/// to the key distributed by the peer. In Secure Connections pairing there is only one LTK and
/// `peer_ltk` is the same as `local_ltk`.
5: peer_ltk Ltk;
/// LE long-term key used to encrypt a connection when the peer is in the LE Central role.
///
/// In legacy pairing (`local_ltk.security.secure_connections` is false), this key corresponds
/// to the key distributed by the local device. In Secure Connections pairing there is only one
/// LTK and `local_ltk` is the same as `peer_ltk`.
6: local_ltk Ltk;
};
type BredrBondData = table {
/// The peer's preferred piconet role. This is determined by role switch procedures. Paging and
/// connecting from a peer does not automatically set this flag. If absent, the peer has not
/// expressed a preference.
1: role_preference bt.ConnectionRole;
/// Known service UUIDs obtained from EIR data or SDP.
2: services vector<bt.Uuid>:MAX_PEER_SERVICES;
/// The semi-permanent BR/EDR key. Present if link was paired with Secure Simple Pairing or
/// stronger.
3: link_key PeerKey;
};
/// Represents the bonding data for a single peer.
type BondingData = table {
/// The identifier that uniquely identifies this peer.
1: identifier bt.PeerId;
/// The local Bluetooth identity address that this bond is associated with.
2: local_address bt.Address;
/// The name of the peer, if known.
3: name bt.DeviceName;
4: reserved;
5: reserved;
/// The identity address of the peer.
6: address bt.Address;
/// Bonding data that is present when this peer is paired on the LE transport.
7: le_bond LeBondData;
/// Bonding data that is present when this peer is paired on the BR/EDR transport.
8: bredr_bond BredrBondData;
};
/// Represents persistent local host data.
type HostData = table {
/// The local Identity Resolving Key used by a bt-host device to generate Resolvable Private
/// Addresses when privacy is enabled.
///
/// May be absent for hosts that do not use LE privacy, or that only use Non-Resolvable Private
/// Addresses.
///
/// NOTE: This key is distributed to LE peers during pairing procedures. The client must take
/// care to assign an IRK that consistent with the local bt-host identity.
// TODO(https://fxbug.dev/42087125): Document behavior once there is a better privacy policy when `irk` is null.
1: irk LocalKey;
};
/// Represents the persistent configuration of a single host-subsystem instance. This is used for
/// identity presentation (inquiry, inquiry response, and advertisement) and for bonding secrets
/// recall (encrypting link data to peers associated with this identity).
///
/// Each BR/EDR BD_ADDR and Low Energy public identity address used to bond should have its own
/// Identity instance containing corresponding peers.
///
/// Each Identity instance that supports LE privacy should have an Identity Resolving Key (IRK) that
/// is consistent with that distributed to its bonded peers.
type Identity = table {
1: host HostData;
/// All bonds that use a public identity address must contain the same local address.
2: bonds vector<BondingData>:MAX;
};