remote_provisioning/hwtrust/src/session.rs

//! Defines the context type for a session handling hwtrust data structures.

/// The context for a session handling hwtrust data structures.
#[derive(Default)]
pub struct Session {
    /// Options that control the behaviour during this session.
    pub options: Options,
}

/// Options that control the behaviour of a session.
#[derive(Default)]
pub struct Options {
    /// The expected format for the configuration descriptor in the first certificate of the DICE
    /// chain. When the chain is ROM-rooted, the first certificate is generated by ROM so this
    /// option can be used for compatibility with ROMs.
    pub first_dice_chain_cert_config_format: ConfigFormat,

    /// The types that are permitted for the key_ops field of COSE_Key objects in the DICE chain.
    /// This option can be used for compatibility with the RKP HAL before v3 which diverged from
    /// the COSE spec and allowed a single int instead of always requiring an array.
    pub dice_chain_key_ops_type: KeyOpsType,

    /// The types that are permitted for the mode field of the DICE certificates. This option can
    /// be used for compatibility with the RKP HAL v3 which allowed some deviations from the Open
    /// Profile for DICE specification.
    pub dice_chain_mode_type: ModeType,

    /// Whether to allow the key_usage field of the DICE certificates to be encoded in big-endian
    /// byte order. This introduces ambiguity of the exact key usage being expressed but the keys
    /// in the DICE chain are only used for verification so it may be preferable to allow for
    /// compatibility with implementations that use the wrong endianness.
    pub dice_chain_allow_big_endian_key_usage: bool,

    /// The types that are permitted for the component version field in the configuration
    /// descriptor. The specification has changed the allowed types over time and this option
    /// can be used to select which rules to apply.
    pub dice_chain_component_version_type: ComponentVersionType,

    /// Whether the configuration hash is verified to be present and derived from the configuration
    /// descriptor. This allows for compatibility with early versions of the RKP HAL which did not
    /// enforce the requirements on the configuration hash as defined by the Open Profile for DICE.
    pub dice_chain_config_hash_unverified: bool,
}

/// Format of the DICE configuration descriptor.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum ConfigFormat {
    /// The configuration descriptor format specified by Android.
    #[default]
    Android,
    /// Any configuration descriptor format is allowed.
    Permissive,
}

/// Type allowed for the COSE_Key object key_ops field in the DICE chain.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum KeyOpsType {
    /// The key_ops field must be an array as specified in the COSE RFC.
    #[default]
    Array,
    /// The key_ops field can be either a single int or an array as specified in the COSE RFC.
    IntOrArray,
}

/// Type allowed for the DICE certificate mode field.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum ModeType {
    /// The mode field must be a byte string holding a single byte as specified by the Open Profile
    /// for DICE.
    #[default]
    Bytes,
    /// The mode field can be either an int or a byte string holding a single byte.
    IntOrBytes,
}

/// Type allowed for the DICE certificate configuration descriptor's component version field.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum ComponentVersionType {
    /// The component version can be either an int or a free-form string.
    #[default]
    IntOrString,
    /// The component version must be an int.
    Int,
}

impl Options {
    /// The options use by VSR 13.
    pub fn vsr13() -> Self {
        Self {
            // Context: b/262599829#comment65
            dice_chain_key_ops_type: KeyOpsType::IntOrArray,
            // Context: b/273552826
            dice_chain_component_version_type: ComponentVersionType::Int,
            dice_chain_config_hash_unverified: true,
            ..Options::default()
        }
    }

    /// The options use by VSR 14.
    pub fn vsr14() -> Self {
        Self {
            // Context: b/261647022
            first_dice_chain_cert_config_format: ConfigFormat::Permissive,
            // Context: b/273552826
            dice_chain_mode_type: ModeType::IntOrBytes,
            dice_chain_allow_big_endian_key_usage: true,
            dice_chain_config_hash_unverified: true,
            ..Options::default()
        }
    }

    /// The options use by VSR 15.
    pub fn vsr15() -> Self {
        Options::default()
    }
}