rust/bt-csis/src/types.rs

// Copyright 2026 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.

use core::num::NonZeroU8;

use bt_common::packet_encoding::{Decodable, Encodable, Error as PacketError};
use bt_common::{decodable_enum, Uuid};

use crate::crypto::set_identity_hash;

/// 16-bit UUID value for the Coordinated Set Identification Service and its
/// characteristics.
pub const COORDINATED_SET_IDENTIFICATION_SERVICE_UUID: Uuid = Uuid::from_u16(0x1846);
pub const SET_IDENTITY_RESOLVING_KEY_UUID: Uuid = Uuid::from_u16(0x2B84);
pub const COORDINATED_SET_SIZE_UUID: Uuid = Uuid::from_u16(0x2B85);
pub const SET_MEMBER_LOCK_UUID: Uuid = Uuid::from_u16(0x2B86);
pub const SET_MEMBER_RANK_UUID: Uuid = Uuid::from_u16(0x2B87);

// TODO(b/534436497): Add Coordinated Set Name characteristic (CSIS v1.1 Section
// 5.5).
// TODO(b/534436497): Add CsisApplicationError enum.

decodable_enum! {
    /// The type of the Set Identity Resolving Key (SIRK).
    /// See CSIS v1.1 Section 5.1.1, Table 5.2.
    pub enum SirkType<u8, bt_common::packet_encoding::Error, OutOfRange> {
        Encrypted = 0x00,
        Plaintext = 0x01,
    }
}

/// The Set Identity Resolving Key (SIRK) characteristic exposes the key
/// associated with the Coordinated Set (1 octet Type + 16 octets Value).
/// See CSIS v1.1 Section 5.1.
#[derive(Clone, Copy, PartialEq, Eq, Hash)]
pub struct SetIdentityResolvingKey {
    sirk_type: SirkType,
    value: [u8; 16],
}

impl SetIdentityResolvingKey {
    pub const BYTE_SIZE: usize = 17;

    pub fn new(sirk_type: SirkType, value: [u8; 16]) -> Self {
        Self { sirk_type, value }
    }

    pub fn sirk_type(&self) -> SirkType {
        self.sirk_type
    }

    /// Resolves `rsi` with this SIRK. See CSIS v1.1 Section 4.9.
    // TODO(b/534436497): Decrypt an encrypted SIRK with the LTK (CSIS v1.1
    // Section 4.6).
    pub fn resolve_rsi(&self, rsi: ResolvableSetIdentifier) -> RsiResolution {
        if self.sirk_type == SirkType::Encrypted {
            return RsiResolution::NeedsDecryption;
        }

        if set_identity_hash(&self.value, rsi.prand()) == *rsi.hash() {
            RsiResolution::Resolved
        } else {
            RsiResolution::NotResolved
        }
    }
}

/// The outcome of resolving a Resolvable Set Identifier with a SIRK.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RsiResolution {
    /// The RSI was generated from this SIRK.
    Resolved,
    /// The RSI was not generated from this SIRK.
    NotResolved,
    /// The SIRK is encrypted and has to be decrypted before it can resolve the
    /// RSI.
    NeedsDecryption,
}

/// The Resolvable Set Identifier that a Set Member advertises so that a Set
/// Coordinator holding the SIRK can recognize it without connecting.
///
/// Carried as `hash || prand`, least significant octet first, over six octets.
/// See CSIS v1.1 Section 4.8.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct ResolvableSetIdentifier {
    hash: [u8; 3],
    prand: [u8; 3],
}

impl ResolvableSetIdentifier {
    pub const BYTE_SIZE: usize = 6;

    pub fn hash(&self) -> &[u8; 3] {
        &self.hash
    }

    pub fn prand(&self) -> &[u8; 3] {
        &self.prand
    }
}

impl TryFrom<[u8; 6]> for ResolvableSetIdentifier {
    type Error = PacketError;

    /// Rejects `bytes` unless the two most significant bits of its prand are 0
    /// and 1, as Core Spec v5.3 Vol 3, Part H, Section 1.3 requires.
    fn try_from(bytes: [u8; 6]) -> Result<Self, Self::Error> {
        if (bytes[5] & 0xc0) != 0x40 {
            return Err(PacketError::InvalidParameter(format!(
                "prand has invalid most significant bits: {:#04x}",
                bytes[5]
            )));
        }

        Ok(Self { hash: [bytes[0], bytes[1], bytes[2]], prand: [bytes[3], bytes[4], bytes[5]] })
    }
}

/// Omits the key.
impl std::fmt::Debug for SetIdentityResolvingKey {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SetIdentityResolvingKey")
            .field("sirk_type", &self.sirk_type)
            .finish_non_exhaustive()
    }
}

/// Omits the key.
impl std::fmt::Display for SetIdentityResolvingKey {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{:?} SIRK", self.sirk_type)
    }
}

impl Decodable for SetIdentityResolvingKey {
    type Error = PacketError;

    fn decode(buf: &[u8]) -> (core::result::Result<Self, Self::Error>, usize) {
        if buf.len() < Self::BYTE_SIZE {
            return (Err(PacketError::UnexpectedDataLength), buf.len());
        }
        let sirk_type = match SirkType::try_from(buf[0]) {
            Ok(t) => t,
            Err(e) => return (Err(e), Self::BYTE_SIZE),
        };
        let mut value = [0; 16];
        value.copy_from_slice(&buf[1..17]);

        (Ok(Self { sirk_type, value }), Self::BYTE_SIZE)
    }
}

/// The Set Member Rank characteristic exposes a numeric value that is unique
/// within a Coordinated Set (0x01 to set size). See CSIS v1.1 Section 5.4.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct SetMemberRank(NonZeroU8);

impl SetMemberRank {
    pub const BYTE_SIZE: usize = 1;

    pub fn new(rank: NonZeroU8) -> Self {
        Self(rank)
    }

    pub fn value(&self) -> NonZeroU8 {
        self.0
    }
}

impl Decodable for SetMemberRank {
    type Error = PacketError;

    fn decode(buf: &[u8]) -> (core::result::Result<Self, Self::Error>, usize) {
        if buf.is_empty() {
            return (Err(PacketError::UnexpectedDataLength), 0);
        }
        let val = match NonZeroU8::new(buf[0]) {
            Some(v) => v,
            None => {
                return (
                    Err(PacketError::InvalidParameter("SetMemberRank cannot be 0".to_string())),
                    1,
                )
            }
        };
        (Ok(Self(val)), Self::BYTE_SIZE)
    }
}

impl Encodable for SetMemberRank {
    type Error = PacketError;

    fn encoded_len(&self) -> usize {
        Self::BYTE_SIZE
    }

    fn encode(&self, buf: &mut [u8]) -> Result<(), Self::Error> {
        if buf.is_empty() {
            return Err(PacketError::BufferTooSmall);
        }
        buf[0] = self.0.get();
        Ok(())
    }
}

/// The Coordinated Set Size characteristic exposes the number of devices
/// comprising the Coordinated Set (0x01 to 0xFF). See CSIS v1.1 Section 5.2.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct CoordinatedSetSize(NonZeroU8);

impl CoordinatedSetSize {
    pub const BYTE_SIZE: usize = 1;

    pub fn new(size: NonZeroU8) -> Self {
        Self(size)
    }

    pub fn value(&self) -> NonZeroU8 {
        self.0
    }
}

impl Decodable for CoordinatedSetSize {
    type Error = PacketError;

    fn decode(buf: &[u8]) -> (core::result::Result<Self, Self::Error>, usize) {
        if buf.is_empty() {
            return (Err(PacketError::UnexpectedDataLength), 0);
        }
        let val = match NonZeroU8::new(buf[0]) {
            Some(v) => v,
            None => {
                return (
                    Err(PacketError::InvalidParameter(
                        "CoordinatedSetSize cannot be 0".to_string(),
                    )),
                    1,
                );
            }
        };
        (Ok(Self(val)), Self::BYTE_SIZE)
    }
}

impl Encodable for CoordinatedSetSize {
    type Error = PacketError;

    fn encoded_len(&self) -> usize {
        Self::BYTE_SIZE
    }

    fn encode(&self, buf: &mut [u8]) -> Result<(), Self::Error> {
        if buf.is_empty() {
            return Err(PacketError::BufferTooSmall);
        }
        buf[0] = self.0.get();
        Ok(())
    }
}

decodable_enum! {
    /// The Set Member Lock characteristic value. All other values are RFU.
    /// See CSIS v1.1 Section 5.3, Table 5.4.
    pub enum SetMemberLock<u8, bt_common::packet_encoding::Error, OutOfRange> {
        Unlocked = 0x01,
        Locked = 0x02,
    }
}

impl SetMemberLock {
    pub const BYTE_SIZE: usize = 1;
}

impl Decodable for SetMemberLock {
    type Error = PacketError;

    fn decode(buf: &[u8]) -> (core::result::Result<Self, Self::Error>, usize) {
        if buf.is_empty() {
            return (Err(PacketError::UnexpectedDataLength), 0);
        }
        let lock = match Self::try_from(buf[0]) {
            Ok(val) => val,
            Err(e) => return (Err(e), Self::BYTE_SIZE),
        };
        (Ok(lock), Self::BYTE_SIZE)
    }
}

impl Encodable for SetMemberLock {
    type Error = PacketError;

    fn encoded_len(&self) -> usize {
        Self::BYTE_SIZE
    }

    fn encode(&self, buf: &mut [u8]) -> Result<(), Self::Error> {
        if buf.is_empty() {
            return Err(PacketError::BufferTooSmall);
        }
        buf[0] = (*self).into();
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::crypto::test_vectors::{RSI, SIRK};
    use assert_matches::assert_matches;

    fn rsi(bytes: [u8; 6]) -> ResolvableSetIdentifier {
        ResolvableSetIdentifier::try_from(bytes).expect("bytes are a well formed RSI")
    }

    #[test]
    fn sirk_decoding() {
        let mut buf = [0; 17];
        buf[0] = 0x01; // Plaintext
        buf[1..17].copy_from_slice(&[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]);

        let (res, consumed) = SetIdentityResolvingKey::decode(&buf);
        assert_eq!(consumed, 17);
        assert_eq!(
            res.unwrap(),
            SetIdentityResolvingKey::new(
                SirkType::Plaintext,
                [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]
            )
        );
    }

    #[test]
    fn plaintext_sirk_resolves_its_own_rsi() {
        let sirk = SetIdentityResolvingKey::new(SirkType::Plaintext, SIRK);
        assert_eq!(sirk.resolve_rsi(rsi(RSI)), RsiResolution::Resolved);

        let mut foreign = RSI;
        foreign[0] ^= 0xff;
        assert_eq!(sirk.resolve_rsi(rsi(foreign)), RsiResolution::NotResolved);
    }

    #[test]
    fn encrypted_sirk_needs_decryption() {
        let sirk = SetIdentityResolvingKey::new(SirkType::Encrypted, SIRK);
        assert_eq!(sirk.resolve_rsi(rsi(RSI)), RsiResolution::NeedsDecryption);
    }

    #[test]
    fn rsi_splits_into_hash_and_prand() {
        let rsi = rsi(RSI);
        assert_eq!(rsi.hash(), &[RSI[0], RSI[1], RSI[2]]);
        assert_eq!(rsi.prand(), &[RSI[3], RSI[4], RSI[5]]);
    }

    #[test]
    fn rsi_with_malformed_prand_is_rejected() {
        // The two most significant bits of prand must be 0 and 1.
        for msbs in [0x00, 0x80, 0xc0] {
            let mut bytes = RSI;
            bytes[5] = msbs | (RSI[5] & 0x3f);

            assert_matches!(
                ResolvableSetIdentifier::try_from(bytes),
                Err(PacketError::InvalidParameter(_)),
                "prand MSBs {msbs:#04x} should be rejected"
            );
        }
    }

    #[test]
    fn set_member_rank_decoding() {
        let mut buf = [0; 1];
        buf[0] = 0x05;
        let (res, consumed) = SetMemberRank::decode(&buf);
        assert_eq!(consumed, 1);
        assert_eq!(res.unwrap().value().get(), 5);

        buf[0] = 0x00; // Invalid
        let (res, _) = SetMemberRank::decode(&buf);
        assert_matches!(res, Err(PacketError::InvalidParameter(_)));
    }

    #[test]
    fn set_member_rank_encoding() {
        let rank = SetMemberRank::new(NonZeroU8::new(5).unwrap());
        assert_eq!(rank.encoded_len(), 1);

        let mut buf = [0; 1];
        rank.encode(&mut buf).unwrap();
        assert_eq!(buf[0], 0x05);

        let mut empty_buf = [];
        assert_matches!(rank.encode(&mut empty_buf), Err(PacketError::BufferTooSmall));
    }

    #[test]
    fn coordinated_set_size_decoding() {
        let mut buf = [0; 1];
        buf[0] = 0x02;
        let (res, consumed) = CoordinatedSetSize::decode(&buf);
        assert_eq!(consumed, 1);
        assert_eq!(res.unwrap().value().get(), 2);

        buf[0] = 0x00; // Invalid
        let (res, _) = CoordinatedSetSize::decode(&buf);
        assert_matches!(res, Err(PacketError::InvalidParameter(_)));
    }

    #[test]
    fn coordinated_set_size_encoding() {
        let size = CoordinatedSetSize::new(NonZeroU8::new(2).unwrap());
        assert_eq!(size.encoded_len(), 1);

        let mut buf = [0; 1];
        size.encode(&mut buf).unwrap();
        assert_eq!(buf[0], 0x02);

        let mut empty_buf = [];
        assert_matches!(size.encode(&mut empty_buf), Err(PacketError::BufferTooSmall));
    }

    #[test]
    fn set_member_lock_decoding() {
        let (res, consumed) = SetMemberLock::decode(&[0x01]);
        assert_eq!(consumed, 1);
        assert_eq!(res.unwrap(), SetMemberLock::Unlocked);

        let (res, consumed) = SetMemberLock::decode(&[0x02]);
        assert_eq!(consumed, 1);
        assert_eq!(res.unwrap(), SetMemberLock::Locked);

        // 0x00 and anything above 0x02 are RFU per CSIS v1.1 Section 5.3.
        let (res, _) = SetMemberLock::decode(&[0x00]);
        assert_matches!(res, Err(_));
        let (res, _) = SetMemberLock::decode(&[0x03]);
        assert_matches!(res, Err(_));

        let (res, consumed) = SetMemberLock::decode(&[]);
        assert_eq!(consumed, 0);
        assert_matches!(res, Err(PacketError::UnexpectedDataLength));
    }

    #[test]
    fn set_member_lock_encoding() {
        let lock = SetMemberLock::Locked;
        assert_eq!(lock.encoded_len(), 1);

        let mut buf = [0; 1];
        lock.encode(&mut buf).unwrap();
        assert_eq!(buf[0], 0x02);

        SetMemberLock::Unlocked.encode(&mut buf).unwrap();
        assert_eq!(buf[0], 0x01);

        let mut empty_buf = [];
        assert_matches!(lock.encode(&mut empty_buf), Err(PacketError::BufferTooSmall));
    }
}