path: root/nearby/presence/np_ffi_core/src/serialize/v1.rs

// Copyright 2023 Google LLC
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! NP Rust FFI structures and methods for V1 advertisement serialization.

use crate::common::*;
use crate::credentials::V1BroadcastCredential;
use crate::serialize::AdvertisementBuilderKind;
use crate::utils::FfiEnum;
use crate::v1::V1VerificationMode;
use crypto_provider_default::CryptoProviderImpl;
use handle_map::{declare_handle_map, HandleLike, HandleMapDimensions, HandleMapFullError};
use np_adv;
use np_adv_dynamic;

/// A handle to a builder for V1 advertisements.
#[derive(Clone, Copy)]
#[repr(C)]
pub struct V1AdvertisementBuilder {
    kind: AdvertisementBuilderKind,
    handle: V1AdvertisementBuilderHandle,
}

impl V1AdvertisementBuilder {
    /// Attempts to create a builder for a new public section within
    /// this advertisement, returning a handle to the newly-created
    /// section builder if successful.
    ///
    /// This method may fail if there is another currently-active
    /// section builder for the same advertisement builder, if the
    /// kind of section being added does not match the advertisement
    /// type (public/encrypted), or if the section would not manage
    /// to fit within the enclosing advertisement.
    pub fn public_section_builder(&self) -> CreateV1SectionBuilderResult {
        self.section_builder_internals(|internals| internals.public_section_builder())
    }
    /// Attempts to create a builder for a new encrypted section within
    /// this advertisement, returning a handle to the newly-created
    /// section builder if successful.
    ///
    /// The identity details for the new section builder may be specified
    /// via providing the broadcast credential data, the kind of encrypted
    /// identity being broadcast (private/trusted/provisioned), and the
    /// verification mode (MIC/Signature) to be used for the encrypted section.
    ///
    /// This method may fail if there is another currently-active
    /// section builder for the same advertisement builder, if the
    /// kind of section being added does not match the advertisement
    /// type (public/encrypted), or if the section would not manage
    /// to fit within the enclosing advertisement.
    pub fn encrypted_section_builder(
        &self,
        broadcast_cred: V1BroadcastCredential,
        identity_type: EncryptedIdentityType,
        verification_mode: V1VerificationMode,
    ) -> CreateV1SectionBuilderResult {
        self.section_builder_internals(move |internals| {
            internals.encrypted_section_builder(broadcast_cred, identity_type, verification_mode)
        })
    }

    fn section_builder_internals(
        &self,
        builder_supplier: impl FnOnce(
            &mut V1AdvertisementBuilderInternals,
        ) -> Result<usize, SectionBuilderError>,
    ) -> CreateV1SectionBuilderResult {
        match self.handle.get_mut() {
            Ok(mut adv_builder_write_guard) => {
                match builder_supplier(&mut adv_builder_write_guard) {
                    Ok(section_index) => CreateV1SectionBuilderResult::Success(V1SectionBuilder {
                        adv_builder: *self,
                        section_index: section_index as u8,
                    }),
                    Err(e) => e.into(),
                }
            }
            Err(_) => CreateV1SectionBuilderResult::InvalidAdvBuilderHandle,
        }
    }
}

/// Discriminant for `CreateV1AdvertisementBuilderResult`

#[derive(Copy, Clone)]
#[repr(u8)]
pub enum CreateV1AdvertisementBuilderResultKind {
    /// The attempt to create a new advertisement builder
    /// failed since there are no more available
    /// slots for V1 advertisement builders in their handle-map.
    NoSpaceLeft = 0,
    /// The attempt succeeded. The wrapped advertisement builder
    /// may be obtained via
    /// `CreateV1AdvertisementBuilderResult#into_success`.
    Success = 1,
}

/// The result of attempting to create a new V1 advertisement builder.
#[repr(C)]
#[allow(missing_docs)]
pub enum CreateV1AdvertisementBuilderResult {
    NoSpaceLeft,
    Success(V1AdvertisementBuilder),
}

impl From<Result<V1AdvertisementBuilder, HandleMapFullError>>
    for CreateV1AdvertisementBuilderResult
{
    fn from(result: Result<V1AdvertisementBuilder, HandleMapFullError>) -> Self {
        match result {
            Ok(builder) => CreateV1AdvertisementBuilderResult::Success(builder),
            Err(_) => CreateV1AdvertisementBuilderResult::NoSpaceLeft,
        }
    }
}

impl FfiEnum for CreateV1AdvertisementBuilderResult {
    type Kind = CreateV1AdvertisementBuilderResultKind;
    fn kind(&self) -> Self::Kind {
        match self {
            CreateV1AdvertisementBuilderResult::NoSpaceLeft => {
                CreateV1AdvertisementBuilderResultKind::NoSpaceLeft
            }
            CreateV1AdvertisementBuilderResult::Success(_) => {
                CreateV1AdvertisementBuilderResultKind::Success
            }
        }
    }
}

impl CreateV1AdvertisementBuilderResult {
    declare_enum_cast! {into_success, Success, V1AdvertisementBuilder }
}

/// Creates a new V1 advertisement builder for the given advertisement
/// kind (public/encrypted).
pub fn create_v1_advertisement_builder(
    kind: AdvertisementBuilderKind,
) -> CreateV1AdvertisementBuilderResult {
    V1AdvertisementBuilderHandle::allocate(move || V1AdvertisementBuilderInternals::new(kind))
        .map(|handle| V1AdvertisementBuilder { kind, handle })
        .into()
}

impl V1AdvertisementBuilder {
    /// Gets the kind of advertisement builder (public/encrypted)
    pub fn kind(&self) -> AdvertisementBuilderKind {
        self.kind
    }
}

pub(crate) enum V1AdvertisementBuilderState {
    /// Internal state for when we have an active advertisement
    /// builder, but no currently-active section builder.
    Advertisement(np_adv_dynamic::extended::BoxedAdvBuilder),
    /// Internal state for when we have both an active advertisement
    /// builder and an active section builder.
    Section(
        np_adv_dynamic::extended::BoxedSectionBuilder<
            np_adv::extended::serialize::AdvBuilder,
            CryptoProviderImpl,
        >,
    ),
}

/// Internal version of errors which may be raised when
/// attempting to derive a new section builder from an
/// advertisement builder.
pub(crate) enum SectionBuilderError {
    /// We're currently in the middle of building a section.
    UnclosedActiveSection,
    /// We're attempting to build a section with an identity
    /// kind (public/encrypted) which doesn't match the kind
    /// for the entire advertisement.
    IdentityKindMismatch,
    /// There isn't enough space for a new section, either
    /// because the maximum section count has been exceeded
    /// or because the advertisement is almost full, and
    /// the minimum size of a section wouldn't fit.
    NoSpaceLeft,
}

impl From<np_adv_dynamic::extended::BoxedAddSectionError> for SectionBuilderError {
    fn from(err: np_adv_dynamic::extended::BoxedAddSectionError) -> Self {
        use np_adv::extended::serialize::AddSectionError;
        use np_adv_dynamic::extended::BoxedAddSectionError;
        match err {
            BoxedAddSectionError::IdentityRequiresSaltError
            | BoxedAddSectionError::Underlying(AddSectionError::IncompatibleSectionType) => {
                SectionBuilderError::IdentityKindMismatch
            }
            BoxedAddSectionError::Underlying(AddSectionError::InsufficientAdvSpace)
            | BoxedAddSectionError::Underlying(AddSectionError::MaxSectionCountExceeded) => {
                SectionBuilderError::NoSpaceLeft
            }
        }
    }
}

/// Internal, Rust-side implementation of a V1 advertisement builder.
pub struct V1AdvertisementBuilderInternals {
    // Note: This is actually always populated from an external
    // perspective in the absence of panics. We only need
    // the `Option` in order to be able to take ownership
    // and perform a state transition when needed.
    state: Option<V1AdvertisementBuilderState>,
}

impl V1AdvertisementBuilderInternals {
    pub(crate) fn new(kind: AdvertisementBuilderKind) -> Self {
        let adv_type = kind.as_internal_v1();
        let builder = np_adv::extended::serialize::AdvBuilder::new(adv_type);
        let builder = builder.into();
        let state = Some(V1AdvertisementBuilderState::Advertisement(builder));
        Self { state }
    }
    /// Internals of section_builder-type routines. Upon success, yields the index
    /// of the newly-added section builder.
    pub(crate) fn section_builder_internal(
        &mut self,
        identity: np_adv_dynamic::extended::BoxedIdentity<CryptoProviderImpl>,
    ) -> Result<usize, SectionBuilderError> {
        let state = self.state.take();
        match state {
            Some(V1AdvertisementBuilderState::Advertisement(adv_builder)) => {
                match adv_builder.into_section_builder::<CryptoProviderImpl>(identity) {
                    Ok(section_builder) => {
                        let section_index = section_builder.section_index();
                        self.state = Some(V1AdvertisementBuilderState::Section(section_builder));
                        Ok(section_index)
                    }
                    Err((adv_builder, err)) => {
                        self.state = Some(V1AdvertisementBuilderState::Advertisement(adv_builder));
                        Err(err.into())
                    }
                }
            }
            x => {
                // Note: Technically, this case also would leave the `None` state
                // if we ever entered into it, but we never transition to that
                // state during normal operation.
                self.state = x;
                Err(SectionBuilderError::UnclosedActiveSection)
            }
        }
    }

    pub(crate) fn public_section_builder(&mut self) -> Result<usize, SectionBuilderError> {
        let identity = np_adv_dynamic::extended::BoxedIdentity::PublicIdentity;
        self.section_builder_internal(identity)
    }
    pub(crate) fn encrypted_section_builder(
        &mut self,
        broadcast_cred: V1BroadcastCredential,
        identity_type: EncryptedIdentityType,
        verification_mode: V1VerificationMode,
    ) -> Result<usize, SectionBuilderError> {
        let mut rng = get_global_crypto_rng();
        let rng = rng.get_rng();
        let identity_type = identity_type.into();
        let internal_broadcast_cred = broadcast_cred.into_internal();
        let identity = match verification_mode {
            V1VerificationMode::Mic => {
                let encoder = np_adv::extended::serialize::MicEncryptedSectionEncoder::<
                    CryptoProviderImpl,
                >::new_random_salt(
                    rng, identity_type, &internal_broadcast_cred
                );
                np_adv_dynamic::extended::BoxedIdentity::MicEncrypted(encoder)
            }
            V1VerificationMode::Signature => {
                let encoder = np_adv::extended::serialize::SignedEncryptedSectionEncoder::<
                    CryptoProviderImpl,
                >::new_random_salt(
                    rng, identity_type, &internal_broadcast_cred
                );
                np_adv_dynamic::extended::BoxedIdentity::SignedEncrypted(encoder)
            }
        };
        self.section_builder_internal(identity)
    }
}

fn get_v1_advertisement_builder_handle_map_dimensions() -> HandleMapDimensions {
    HandleMapDimensions {
        num_shards: global_num_shards(),
        max_active_handles: global_max_num_v1_advertisement_builders(),
    }
}

declare_handle_map! {
    mod advertisement_builder {
        #[dimensions = super::get_v1_advertisement_builder_handle_map_dimensions()]
        type V1AdvertisementBuilderHandle: HandleLike<Object = super::V1AdvertisementBuilderInternals>;
    }
}
use crate::serialize::v1::advertisement_builder::V1AdvertisementBuilderHandle;

/// Discriminant for `CreateV1SectionBuilderResult`
#[derive(Copy, Clone)]
#[repr(u8)]
pub enum CreateV1SectionBuilderResultKind {
    /// The attempt to create a new section builder succeeded.
    Success = 0,
    /// We're currently in the middle of building a section.
    UnclosedActiveSection = 1,
    /// The advertisement builder handle was invalid.
    InvalidAdvBuilderHandle = 2,
    /// We're attempting to build a section with an identity
    /// kind (public/encrypted) which doesn't match the kind
    /// for the entire advertisement.
    IdentityKindMismatch = 3,
    /// There isn't enough space for a new section, either
    /// because the maximum section count has been exceeded
    /// or because the advertisement is almost full, and
    /// the minimum size of a section wouldn't fit.
    NoSpaceLeft = 4,
}

/// The result of attempting to create a new V1 section builder.
#[repr(C)]
#[allow(missing_docs)]
pub enum CreateV1SectionBuilderResult {
    Success(V1SectionBuilder),
    UnclosedActiveSection,
    InvalidAdvBuilderHandle,
    IdentityKindMismatch,
    NoSpaceLeft,
}

impl FfiEnum for CreateV1SectionBuilderResult {
    type Kind = CreateV1SectionBuilderResultKind;
    fn kind(&self) -> Self::Kind {
        match self {
            Self::Success(_) => CreateV1SectionBuilderResultKind::Success,
            Self::UnclosedActiveSection => CreateV1SectionBuilderResultKind::UnclosedActiveSection,
            Self::InvalidAdvBuilderHandle => {
                CreateV1SectionBuilderResultKind::InvalidAdvBuilderHandle
            }
            Self::IdentityKindMismatch => CreateV1SectionBuilderResultKind::IdentityKindMismatch,
            Self::NoSpaceLeft => CreateV1SectionBuilderResultKind::NoSpaceLeft,
        }
    }
}

impl CreateV1SectionBuilderResult {
    declare_enum_cast! {into_success, Success, V1SectionBuilder}
}

impl From<SectionBuilderError> for CreateV1SectionBuilderResult {
    fn from(err: SectionBuilderError) -> Self {
        match err {
            SectionBuilderError::UnclosedActiveSection => Self::UnclosedActiveSection,
            SectionBuilderError::IdentityKindMismatch => Self::IdentityKindMismatch,
            SectionBuilderError::NoSpaceLeft => Self::NoSpaceLeft,
        }
    }
}

/// Result code for [`V1SectionBuilder#add_to_advertisement`].
#[derive(Clone, Copy)]
#[repr(u8)]
pub enum AddV1SectionToAdvertisementResult {
    /// The section referenced by the given handle
    /// couldn't be added to the containing advertisement,
    /// possibly because the handle is invalid or the section
    /// has already been added to the containing section.
    Error = 0,
    /// The section referenced by the given handle
    /// was successfully added to the containing advertisement.
    /// After obtaining this result code, the section
    /// handle will no longer be valid.
    Success = 1,
}

/// Result code for operations adding DEs to a section builder.
#[derive(Clone, Copy)]
#[repr(u8)]
pub enum AddV1DEResult {
    /// The DE was successfully added to the section builder
    /// behind the given handle.
    Success = 0,
    /// The handle for the section builder was invalid.
    InvalidSectionHandle = 1,
    /// There was no more space left in the advertisement
    /// to fit the DE in the containing section.
    InsufficientSectionSpace = 2,
    /// The data element itself had invalid characteristics,
    /// most likely a length above 127.
    InvalidDataElement = 3,
}

/// Discriminant for `NextV1DE16ByteSaltResult`.
#[derive(Clone, Copy)]
#[repr(u8)]
pub enum NextV1DE16ByteSaltResultKind {
    /// We couldn't return a 16-byte DE salt, possibly
    /// because the handle to the section builder
    /// was invalid, or possibly because the section
    /// builder was for a public section.
    Error = 0,
    /// A 16-byte DE salt was returned successfully.
    Success = 1,
}

/// The result of attempting to get the derived V1 DE
/// 16-byte salt for the next-added DE to the section
/// builder behind the given handle.
#[derive(Clone, Copy)]
#[repr(C)]
#[allow(missing_docs)]
pub enum NextV1DE16ByteSaltResult {
    Error,
    Success([u8; 16]),
}

impl FfiEnum for NextV1DE16ByteSaltResult {
    type Kind = NextV1DE16ByteSaltResultKind;
    fn kind(&self) -> Self::Kind {
        match self {
            Self::Error => NextV1DE16ByteSaltResultKind::Error,
            Self::Success(_) => NextV1DE16ByteSaltResultKind::Success,
        }
    }
}

impl NextV1DE16ByteSaltResult {
    declare_enum_cast! {into_success, Success, [u8; 16] }
}

impl From<Option<np_adv::extended::serialize::DeSalt<CryptoProviderImpl>>>
    for NextV1DE16ByteSaltResult
{
    fn from(maybe_salt: Option<np_adv::extended::serialize::DeSalt<CryptoProviderImpl>>) -> Self {
        match maybe_salt.and_then(|salt| salt.derive::<16>()) {
            Some(salt) => NextV1DE16ByteSaltResult::Success(salt),
            None => NextV1DE16ByteSaltResult::Error,
        }
    }
}

/// A handle to a builder for V1 sections.
#[derive(Clone, Copy)]
#[repr(C)]
pub struct V1SectionBuilder {
    adv_builder: V1AdvertisementBuilder,
    section_index: u8,
}

impl V1SectionBuilder {
    /// Attempts to add the section constructed behind this handle
    /// to a section builder to the containing advertisement it
    /// originated from.
    pub fn add_to_advertisement(self) -> AddV1SectionToAdvertisementResult {
        match self.adv_builder.handle.get_mut() {
            Ok(mut adv_builder) => {
                let state = adv_builder.state.take();
                match state {
                    Some(V1AdvertisementBuilderState::Section(section_builder)) => {
                        // Make sure the index of the section we're trying to close
                        // matches the index of the section currently under construction.
                        let actual_section_index = section_builder.section_index() as u8;
                        if self.section_index == actual_section_index {
                            let updated_adv_builder = section_builder.add_to_advertisement();
                            adv_builder.state = Some(V1AdvertisementBuilderState::Advertisement(
                                updated_adv_builder,
                            ));
                            AddV1SectionToAdvertisementResult::Success
                        } else {
                            adv_builder.state =
                                Some(V1AdvertisementBuilderState::Section(section_builder));
                            AddV1SectionToAdvertisementResult::Error
                        }
                    }
                    x => {
                        adv_builder.state = x;
                        AddV1SectionToAdvertisementResult::Error
                    }
                }
            }
            Err(_) => AddV1SectionToAdvertisementResult::Error,
        }
    }

    /// Attempts to get the derived 16-byte V1 DE salt for the next
    /// DE to be added to this section builder. May fail if this
    /// section builder handle is invalid, or if the section
    /// is a public section.
    pub fn next_de_salt(&self) -> NextV1DE16ByteSaltResult {
        self.try_apply_to_internals(
            |section_builder| section_builder.next_de_salt().into(),
            NextV1DE16ByteSaltResult::Error,
        )
    }

    /// Attempts to add the given DE to the section builder behind
    /// this handle. The passed DE may have a payload of up to 127
    /// bytes, the maximum for a V1 DE.
    pub fn add_127_byte_buffer_de(&self, de: V1DE127ByteBuffer) -> AddV1DEResult {
        match de.into_internal() {
            Some(generic_de) => self
                .add_de_internals(np_adv_dynamic::extended::BoxedWriteDataElement::new(generic_de)),
            None => AddV1DEResult::InvalidDataElement,
        }
    }

    fn add_de_internals(
        &self,
        de: np_adv_dynamic::extended::BoxedWriteDataElement,
    ) -> AddV1DEResult {
        self.try_apply_to_internals(
            move |section_builder| match section_builder.add_de(move |_| de) {
                Ok(_) => AddV1DEResult::Success,
                Err(_) => AddV1DEResult::InsufficientSectionSpace,
            },
            AddV1DEResult::InvalidSectionHandle,
        )
    }

    fn try_apply_to_internals<R>(
        &self,
        func: impl FnOnce(
            &mut np_adv_dynamic::extended::BoxedSectionBuilder<
                np_adv::extended::serialize::AdvBuilder,
                CryptoProviderImpl,
            >,
        ) -> R,
        invalid_handle_error: R,
    ) -> R {
        match self.adv_builder.handle.get_mut() {
            Ok(mut adv_builder) => {
                match adv_builder.state.as_mut() {
                    Some(V1AdvertisementBuilderState::Section(ref mut section_builder)) => {
                        // Check to make sure that the section index matches, otherwise
                        // we have an invalid handle.
                        let current_section_index = section_builder.section_index() as u8;
                        if current_section_index == self.section_index {
                            func(section_builder)
                        } else {
                            invalid_handle_error
                        }
                    }
                    Some(V1AdvertisementBuilderState::Advertisement(_)) => invalid_handle_error,
                    None => invalid_handle_error,
                }
            }
            Err(_) => invalid_handle_error,
        }
    }
}

/// Represents the contents of a V1 DE whose payload
/// is stored in a buffer which may contain up to 127 bytes,
/// which is the maximum for any V1 DE.
///
/// This representation is stable, and so you may directly
/// reference this struct's fields if you wish.
#[repr(C)]
//TODO: Partial unification with `deserialize::v1::GenericV1DataElement`?
pub struct V1DE127ByteBuffer {
    /// The DE type code of this generic data-element.
    pub de_type: u32,
    /// The raw data-element byte payload, up to
    /// 127 bytes in length.
    pub payload: ByteBuffer<127>,
}

impl V1DE127ByteBuffer {
    /// Attempts to convert this FFI-friendly DE with a byte-buffer size of 127
    /// to the internal representation of a generic DE. May fail in the case
    /// where the underlying payload byte-buffer has an invalid length above 127.
    fn into_internal(self) -> Option<np_adv::extended::data_elements::GenericDataElement> {
        let de_type = np_adv::extended::de_type::DeType::from(self.de_type);
        self.payload.as_slice().and_then(move |payload_slice| {
            np_adv::extended::data_elements::GenericDataElement::try_from(de_type, payload_slice)
                .ok()
        })
    }
}