This is an automated email from the ASF dual-hosted git repository. ivila pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/incubator-teaclave-trustzone-sdk.git
commit 4d3c7f0901eaeddcb51f4aa37e6f09d5b80483e4 Author: ivila <[email protected]> AuthorDate: Thu Jul 10 15:27:57 2025 +0800 optee-utee: object: update doc * fix doc links * update outdated docs Signed-off-by: Zehui Chen <[email protected]> Reviewed-by: Yuan Zhuang <[email protected]> Reviewed-by: Zhaofeng Chen <[email protected]> --- optee-utee/src/object/attribute.rs | 12 +- optee-utee/src/object/enum_handle.rs | 21 +-- optee-utee/src/object/object_define.rs | 23 ++-- optee-utee/src/object/object_info.rs | 47 ++++--- optee-utee/src/object/persistent_object.rs | 201 +++++++++++++++++------------ optee-utee/src/object/transient_object.rs | 137 ++++++++++++-------- 6 files changed, 268 insertions(+), 173 deletions(-) diff --git a/optee-utee/src/object/attribute.rs b/optee-utee/src/object/attribute.rs index 965acdc..caa8e07 100644 --- a/optee-utee/src/object/attribute.rs +++ b/optee-utee/src/object/attribute.rs @@ -32,14 +32,16 @@ impl Attribute { } } -/// Convert the buffer attribute [AttributeMemref](AttributeMemref) to the general attribute. +/// Convert the buffer attribute [AttributeMemref](crate::AttributeMemref) to +/// the general attribute. impl<'attrref> From<AttributeMemref<'attrref>> for Attribute { fn from(attr: AttributeMemref) -> Self { Self { raw: attr.raw() } } } -/// Convert the value attribute [AttributeValue](AttributeValue) to the general attribute. +/// Convert the value attribute [AttributeValue](crate::AttributeValue) to +/// the general attribute. impl From<AttributeValue> for Attribute { fn from(attr: AttributeValue) -> Self { Self { raw: attr.raw() } @@ -79,7 +81,8 @@ impl<'attrref> AttributeMemref<'attrref> { /// /// # Parameters /// - /// 1) `id`: The AttributeId[AttributeId] is an identifier of the attribute to populate. + /// 1) `id`: The [AttributeId](crate::AttributeId) is an identifier of the + /// attribute to populate. /// 2) `buffer`: Input buffer that holds the content of the attribute. /// /// # Example @@ -127,7 +130,8 @@ impl AttributeValue { /// /// # Parameters /// - /// 1) `id`: The AttributeId[AttributeId] is an identifier of the attribute to populate. + /// 1) `id`: The [AttributeId](crate::AttributeId) is an identifier of the + /// attribute to populate. /// 2) `a`, `b`: u32 values to assign to the members of the value attribute. /// /// # Example diff --git a/optee-utee/src/object/enum_handle.rs b/optee-utee/src/object/enum_handle.rs index 160a052..bf1eff6 100644 --- a/optee-utee/src/object/enum_handle.rs +++ b/optee-utee/src/object/enum_handle.rs @@ -22,16 +22,17 @@ use optee_utee_sys as raw; use super::ObjectInfo; use crate::{Error, Result}; -// TODO: The examples and detailed function explanation will be added after we test this struct and its -// functions. -/// An enumerator for [PersistentObject](PersistentObject)s. +// TODO: The examples and detailed function explanation will be added after we +// test this struct and its functions. +/// An enumerator for [PersistentObject](crate::PersistentObject)s. pub struct ObjectEnumHandle { raw: *mut raw::TEE_ObjectEnumHandle, } impl ObjectEnumHandle { /// Allocate an object enumerator. - /// Once an object enumerator has been allocated, it can be reused for multiple enumerations. + /// Once an object enumerator has been allocated, it can be reused for + /// multiple enumerations. pub fn allocate() -> Result<Self> { let raw_handle: *mut raw::TEE_ObjectEnumHandle = Box::into_raw(Box::new(core::ptr::null_mut())); match unsafe { raw::TEE_AllocatePersistentObjectEnumerator(raw_handle) } { @@ -53,9 +54,11 @@ impl ObjectEnumHandle { } } - /// Start the enumeration of all the [PersistentObject](PersistentObject)s in a given Trusted Storage. + /// Start the enumeration of all the + /// [PersistentObject](crate::PersistentObject)s in a given Trusted Storage. /// The object information can be retrieved by calling the function - /// [ObjectEnumHandle::get_next](ObjectEnumHandle::get_next) repeatedly. + /// [ObjectEnumHandle::get_next](crate::ObjectEnumHandle::get_next) + /// repeatedly. pub fn start(&mut self, storage_id: u32) -> Result<()> { match unsafe { raw::TEE_StartPersistentObjectEnumerator(*self.raw, storage_id) } { raw::TEE_SUCCESS => Ok(()), @@ -63,7 +66,8 @@ impl ObjectEnumHandle { } } - /// Get the next object in an enumeration and returns information about the object: type, size, identifier, etc. + /// Get the next object in an enumeration and returns information about the + /// object: type, size, identifier, etc. pub fn get_next<T>( &mut self, object_info: &mut ObjectInfo, @@ -85,7 +89,8 @@ impl ObjectEnumHandle { } impl Drop for ObjectEnumHandle { - /// Deallocates all resources associated with an object enumerator handle. After this function is called, the handle is no longer valid. + /// Deallocates all resources associated with an object enumerator handle. + /// After this function is called, the handle is no longer valid. /// /// # Panics /// diff --git a/optee-utee/src/object/object_define.rs b/optee-utee/src/object/object_define.rs index 0c54064..a5586ae 100644 --- a/optee-utee/src/object/object_define.rs +++ b/optee-utee/src/object/object_define.rs @@ -18,7 +18,8 @@ use bitflags::bitflags; use optee_utee_sys as raw; -/// Indicate the possible start offset when moving a data position in the data stream associated with a [PersistentObject](PersistentObject). +/// Indicate the possible start offset when moving a data position in the data +/// stream associated with a [PersistentObject](crate::PersistentObject). pub enum Whence { /// The data position is set to offset bytes from the beginning of the data stream. DataSeekSet, @@ -57,7 +58,8 @@ bitflags! { const ACCESS_WRITE = 0x00000002; /// The object is opened with the write-meta access right. This allows /// the Trusted Application to call the functions - /// `TEE_CloseAndDeletePersistentObject1` and `TEE_RenamePersistentObject`. + /// `TEE_CloseAndDeletePersistentObject1` and + /// `TEE_RenamePersistentObject`. const ACCESS_WRITE_META = 0x00000004; /// The caller allows another handle on the object to be created with /// read access. @@ -66,8 +68,8 @@ bitflags! { /// write access. const SHARE_WRITE = 0x00000020; /// * If this flag is present and the object exists, then the object is - /// deleted and re-created as an atomic operation: that is, the TA sees - /// either the old object or the new one. + /// deleted and re-created as an atomic operation: that is, the TA + /// sees either the old object or the new one. /// * If the flag is absent and the object exists, then the function /// SHALL return `TEE_ERROR_ACCESS_CONFLICT`. const OVERWRITE = 0x00000400; @@ -106,17 +108,20 @@ pub enum MiscellaneousConstants { bitflags! { /// A set of flags that defines Handle features. pub struct HandleFlag: u32{ - /// Set for a [PersistentObject](PersistentObject). + /// Set for a [PersistentObject](crate::PersistentObject). const PERSISTENT = 0x00010000; - /// 1) For a [PersistentObject](PersistentObject), always set. - /// 2) For a [TransientObject](TransientObject), initially cleared, then set when the object becomes initialized. + /// 1) For a [PersistentObject](crate::PersistentObject), always set. + /// 2) For a [TransientObject](crate::TransientObject), initially + /// cleared, then set when the object becomes initialized. const INITIALIZED = 0x00020000; /// Following two flags are for crypto operation handles: /// 1) Set if the required operation key has been set. /// 2) Always set for digest operations. const KEY_SET = 0x00040000; - /// Set if the algorithm expects two keys to be set, using `TEE_SetOperationKey2`. - /// This happens only if algorithm is set to [AesXts](../crypto_op/enum.AlgorithmId.html#variant.AesXts) + /// Set if the algorithm expects two keys to be set, using + /// `TEE_SetOperationKey2`. + /// This happens only if algorithm is set to + /// [AesXts](crate::AlgorithmId::AesXts) /// or `TEE_ALG_SM2_KEP`(not supported now). const EXPECT_TWO_KEYS = 0x00080000; } diff --git a/optee-utee/src/object/object_info.rs b/optee-utee/src/object/object_info.rs index 5a31347..33e6e17 100644 --- a/optee-utee/src/object/object_info.rs +++ b/optee-utee/src/object/object_info.rs @@ -18,36 +18,45 @@ use optee_utee_sys as raw; /// Represent the characteristics of an object. -/// This info can be returned by [TransientObject](TransientObject) function -/// [info](TransientObject::info) -/// or [PersistentObject](PersistentObject) function -/// [info](PersistentObject::info). +/// This info can be returned by [GenericObject](crate::GenericObject) function +/// [info](crate::GenericObject::info) pub struct ObjectInfo { pub(crate) raw: raw::TEE_ObjectInfo, } -// Since raw struct is not implemented Copy attribute yet, every item in raw struct needs a function to extract. +// Since raw struct is not implemented Copy attribute yet, every item in raw +// struct needs a function to extract. impl ObjectInfo { - /// Return an [ObjectInfo](ObjectInfo) struct based on the raw structure `TEE_ObjectInfo`. + /// Return an [ObjectInfo](crate::ObjectInfo) struct based on the raw + /// structure `TEE_ObjectInfo`. /// The raw structure contains following fields: /// /// 1) `objectType`: The parameter represents one of the - /// [TransientObjectType](TransientObjectType). - /// 2) `objectSize`: The current size in bits of the object as determined by its attributes. - /// This will always be less than or equal to maxObjectSize. Set to 0 for uninitialized and data only objects. - /// 3) `maxObjectSize`: The maximum objectSize which this object can represent. - /// 3.1) For a [PersistentObject](PersistentObject), set to `objectSize`. - /// 3.2) For a [TransientObject](TransientObject), set to the parameter `maxObjectSize` passed to - /// [allocate](TransientObject::allocate). + /// [TransientObjectType](crate::TransientObjectType). + /// 2) `objectSize`: The current size in bits of the object as determined + /// by its attributes. + /// This will always be less than or equal to maxObjectSize. Set to 0 for + /// uninitialized and data only objects. + /// 3) `maxObjectSize`: The maximum objectSize which this object can + /// represent. + /// * For a [PersistentObject](crate::PersistentObject), set to + /// `objectSize`. + /// * For a [TransientObject](crate::TransientObject), set to the + /// parameter `maxObjectSize` passed to + /// [allocate](crate::TransientObject::allocate). /// 4) `objectUsage`: A bit vector of UsageFlag. /// 5) `dataSize`: - /// 5.1) For a [PersistentObject](PersistentObject), set to the current size of the data associated with the object. - /// 5.2) For a [TransientObject](TransientObject), always set to 0. + /// * For a [PersistentObject](crate::PersistentObject), set to the + /// current size of the data associated with the object. + /// * For a [TransientObject](crate::TransientObject), always set to 0. /// 6) `dataPosition`: - /// 6.1) For a [PersistentObject](PersistentObject), set to the current position in the data for this handle. - /// Data positions for different handles on the same object may differ. - /// 6.2) For a [TransientObject](TransientObject), set to 0. - /// 7) `handleFlags`: A bit vector containing one or more [HandleFlag](HandleFlag) or [DataFlag](DataFlag). + /// * For a [PersistentObject](crate::PersistentObject), set to the + /// current position in the data for this handle. + /// Data positions for different handles on the same object may + /// differ. + /// * For a [TransientObject](crate::TransientObject), set to 0. + /// 7) `handleFlags`: A bit vector containing one or more + /// [HandleFlag](crate::HandleFlag) or [DataFlag](crate::DataFlag). pub fn from_raw(raw: raw::TEE_ObjectInfo) -> Self { Self { raw } } diff --git a/optee-utee/src/object/persistent_object.rs b/optee-utee/src/object/persistent_object.rs index f34c650..706ad10 100644 --- a/optee-utee/src/object/persistent_object.rs +++ b/optee-utee/src/object/persistent_object.rs @@ -22,19 +22,21 @@ use crate::{Error, Result}; /// An object identified by an Object Identifier and including a Data Stream. /// -/// Contrast [TransientObject](TransientObject). +/// Contrast [TransientObject](crate::TransientObject). #[derive(Debug)] pub struct PersistentObject(ObjectHandle); impl PersistentObject { - /// Open an existing [PersistentObject](PersistentObject). + /// Open an existing persistent object. /// /// # Parameters /// /// 1) `storage_id`: The storage to use which is defined in - /// [ObjectStorageConstants](ObjectStorageConstants). - /// 2) `object_id`: The object identifier. Note that this buffer cannot reside in shared memory. - /// 3) `flags`: The [DataFlag](DataFlag) which determine the settings under which the object is opened. + /// [ObjectStorageConstants](crate::ObjectStorageConstants). + /// 2) `object_id`: The object identifier. Note that this buffer cannot + /// reside in shared memory. + /// 3) `flags`: The [DataFlag](crate::DataFlag) which determine the settings + /// under which the object is opened. /// /// # Example /// @@ -58,20 +60,25 @@ impl PersistentObject { /// /// # Errors /// - /// 1) `ItemNotFound`: If the storage denoted by storage_id does not exist or if the object - /// identifier cannot be found in the storage. - /// 2) `Access_Conflict`: If an access right conflict was detected while opening the object. - /// 3) `OutOfMemory`: If there is not enough memory to complete the operation. - /// 4) `CorruptObject`: If the [PersistentObject](PersistentObject) is corrupt. The object handle is closed. - /// 5) `StorageNotAvailable`: If the [PersistentObject](PersistentObject) is stored in a storage area which is - /// currently inaccessible. + /// 1) `ItemNotFound`: If the storage denoted by storage_id does not exist + /// or if the object identifier cannot be found in the storage. + /// 2) `Access_Conflict`: If an access right conflict was detected while + /// opening the object. + /// 3) `OutOfMemory`: If there is not enough memory to complete the + /// operation. + /// 4) `CorruptObject`: If the object is corrupt. The object handle SHALL + /// behave based on the `gpd.ta.doesNotCloseHandleOnCorruptObject` + /// property. + /// 5) `StorageNotAvailable`: If the object is stored in a storage area + /// which is currently inaccessible. /// /// # Panics /// /// 1) If object_id.len() > - /// [MiscellaneousConstants::TeeObjectIdMaxLen](MiscellaneousConstants::TeeObjectIdMaxLen) - /// 2) If the Implementation detects any other error associated with this function which is not - /// explicitly associated with a defined return code for this function. + /// [MiscellaneousConstants::TeeObjectIdMaxLen](crate::MiscellaneousConstants::TeeObjectIdMaxLen) + /// 2) If the Implementation detects any other error associated with this + /// function which is not explicitly associated with a defined return + /// code for this function. pub fn open( storage_id: ObjectStorageConstants, object_id: &[u8], @@ -95,18 +102,23 @@ impl PersistentObject { } } - /// Create a [PersistentObject](PersistentObject) with initial attributes and an initial data stream content. + /// Create an object with initial attributes and an initial data stream + /// content. /// /// # Parameters /// /// 1) `storage_id`: The storage to use which is defined in - /// [ObjectStorageConstants](ObjectStorageConstants). - /// 2) `object_id`: The object identifier. Note that this buffer cannot reside in shared memory. - /// 3) `flags`: The [DataFlag](DataFlag) which determine the settings under which the object is opened. - /// 4) `attributes`: A handle on a [PersistentObject](PersistentObject) or an initialized [TransientObject](TransientObject) - /// from which to take the [PersistentObject](PersistentObject) attributes. - /// Can be NONE if the [PersistentObject](PersistentObject) contains no attribute. - /// For example,if it is a pure data object. + /// [ObjectStorageConstants](crate::ObjectStorageConstants). + /// 2) `object_id`: The object identifier. Note that this buffer cannot + /// reside in shared memory. + /// 3) `flags`: The [DataFlag](crate::DataFlag) which determine the settings + /// under which the object is opened. + /// 4) `attributes`: A handle on a + /// [PersistentObject](crate::PersistentObject) or an initialized + /// [TransientObject](crate::TransientObject) from which to take the + /// [PersistentObject](crate::PersistentObject) attributes. + /// Can be NONE if the [PersistentObject](crate::PersistentObject) + /// contains no attribute. For example,if it is a pure data object. /// /// # Example /// @@ -133,22 +145,26 @@ impl PersistentObject { /// /// # Errors /// - /// 1) `ItemNotFound`: If the storage denoted by storage_id does not exist or if the object - /// identifier cannot be found in the storage. - /// 2) `Access_Conflict`: If an access right conflict was detected while opening the object. - /// 3) `OutOfMemory`: If there is not enough memory to complete the operation. - /// 4) `CorruptObject`: If the [PersistentObject](PersistentObject) is corrupt. The object handle is closed. - /// 5) `StorageNotAvailable`: If the [PersistentObject](PersistentObject) is stored in a storage area which is - /// currently inaccessible. + /// 1) `ItemNotFound`: If the storage denoted by storage_id does not exist. + /// 2) `Access_Conflict`: If an access right conflict was detected while + /// opening the object. + /// 3) `OutOfMemory`: If there is not enough memory to complete the + /// operation. + /// 4) `StorageNoSpace`: If insufficient space is available to create the + /// persistent object. + /// 5) `CorruptObject`: If the storage is corrupt. + /// 6) `StorageNotAvailable`: If the object is stored in a storage area + /// which is currently inaccessible. /// /// # Panics /// /// 1) If object_id.len() > - /// [MiscellaneousConstants::TeeObjectIdMaxLen](MiscellaneousConstants::TeeObjectIdMaxLen). - /// 2) If attributes is not NONE and is not a valid handle on an initialized object containing - /// the type and attributes of the [PersistentObject](PersistentObject) to create. - /// 3) If the Implementation detects any other error associated with this function which is not - /// explicitly associated with a defined return code for this function. + /// [MiscellaneousConstants::TeeObjectIdMaxLen](crate::MiscellaneousConstants::TeeObjectIdMaxLen). + /// 2) If attributes is not NONE and is not a valid handle on an initialized + /// object containing the type and attributes of the object to create. + /// 3) If the Implementation detects any other error associated with this + /// function which is not explicitly associated with a defined return + /// code for this function. pub fn create( storage_id: ObjectStorageConstants, object_id: &[u8], @@ -205,14 +221,15 @@ impl PersistentObject { /// /// # Errors /// - /// 1) `StorageNotAvailable`: If the [PersistentObject](PersistentObject) is stored in a storage - /// area which is currently inaccessible. + /// 1) `StorageNotAvailable`: If the object is stored in a storage area + /// which is currently inaccessible. /// /// # Panics /// /// 1) If object is not a valid opened object. - /// 2) If the Implementation detects any other error associated with this function which is not - /// explicitly associated with a defined return code for this function. + /// 2) If the Implementation detects any other error associated with this + /// function which is not explicitly associated with a defined return + /// code for this function. /// /// # Breaking Changes /// @@ -249,7 +266,9 @@ impl PersistentObject { } /// Changes the identifier of an object. - /// The object SHALL have been opened with the [DataFlag::ACCESS_WRITE_META](DataFlag::ACCESS_WRITE_META) right, which means access to the object is exclusive. + /// The object SHALL have been opened with the + /// [DataFlag::ACCESS_WRITE_META](crate::DataFlag::ACCESS_WRITE_META) right, + /// which means access to the object is exclusive. /// /// # Example /// @@ -274,19 +293,24 @@ impl PersistentObject { /// /// # Errors /// - /// 1) `Access_Conflict`: If an access right conflict was detected while opening the object. - /// 2) `CorruptObject`: If the [PersistentObject](PersistentObject) is corrupt. The object handle is closed. - /// 3) `StorageNotAvailable`: If the [PersistentObject](PersistentObject) is stored in a storage area which is - /// currently inaccessible. + /// 1) `AccessConflict`: If an object with the same identifier already + /// exists. + /// 2) `CorruptObject`: If the object is corrupt. The object handle SHALL + /// behave based on the `gpd.ta.doesNotCloseHandleOnCorruptObject` + /// property. + /// 3) `StorageNotAvailable`: If the object is stored in a storage area + /// which is currently inaccessible. /// /// # Panics /// - /// 1) If object is not a valid opened object. + /// 1) If object is not a valid handle on a persistent object that has been + /// opened with the write-meta access right. /// 2) If new_object_id resides in shared memory. /// 3) If new_object_id.len() > - /// [MiscellaneousConstants::TeeObjectIdMaxLen](MiscellaneousConstants::TeeObjectIdMaxLen). - /// 4) If the Implementation detects any other error associated with this function which is not - /// explicitly associated with a defined return code for this function. + /// [MiscellaneousConstants::TeeObjectIdMaxLen](crate::MiscellaneousConstants::TeeObjectIdMaxLen). + /// 4) If the Implementation detects any other error associated with this + /// function which is not explicitly associated with a defined return + /// code for this function. pub fn rename(&mut self, new_object_id: &[u8]) -> Result<()> { match unsafe { raw::TEE_RenamePersistentObject( @@ -300,7 +324,8 @@ impl PersistentObject { } } - /// Read requested size from the data stream associate with the object into the buffer. + /// Read requested size from the data stream associate with the object into + /// the buffer. /// /// # Parameters /// @@ -329,15 +354,19 @@ impl PersistentObject { /// /// # Errors /// - /// 1) `CorruptObject`: If the [PersistentObject](PersistentObject) is corrupt. The object handle is closed. - /// 2) `StorageNotAvailable`: If the [PersistentObject](PersistentObject) is stored in a storage area which is - /// currently inaccessible. + /// 1) `CorruptObject`: If the object is corrupt. The object handle SHALL + /// behave based on the `gpd.ta.doesNotCloseHandleOnCorruptObject` + /// property. + /// 2) `StorageNotAvailable`: If the object is stored in a storage area + /// which is currently inaccessible. /// /// # Panics /// - /// 1) If object is not a valid opened object. - /// 2) If the Implementation detects any other error associated with this function which is not - /// explicitly associated with a defined return code for this function. + /// 1) If object is not a valid handle on a persistent object opened with + /// the read access right. + /// 2) If the Implementation detects any other error associated with this + /// function which is not explicitly associated with a defined return + /// code for this function. pub fn read(&self, buf: &mut [u8]) -> Result<u32> { let mut count: usize = 0; match unsafe { @@ -348,7 +377,8 @@ impl PersistentObject { } } - /// Write the passed in buffer data into from the data stream associate with the object. + /// Write the passed in buffer data into from the data stream associate with + /// the object. /// /// # Parameters /// @@ -378,18 +408,22 @@ impl PersistentObject { /// # Errors /// /// 1) `StorageNoSpace`: If insufficient storage space is available. - /// 2) `Overflow`: If the value of the data position indicator resulting from this operation - /// would be greater than - /// [MiscellaneousConstants::TeeDataMaxPosition](MiscellaneousConstants::TeeDataMaxPosition). - /// 3) `CorruptObject`: If the [PersistentObject](PersistentObject) is corrupt. The object handle is closed. - /// 4) `StorageNotAvailable`: If the [PersistentObject](PersistentObject) is stored in a storage area which is - /// currently inaccessible. + /// 2) `Overflow`: If the value of the data position indicator resulting + /// from this operation would be greater than + /// [MiscellaneousConstants::TeeDataMaxPosition](crate::MiscellaneousConstants::TeeDataMaxPosition). + /// 3) `CorruptObject`: If the object is corrupt. The object handle SHALL + /// behave based on the `gpd.ta.doesNotCloseHandleOnCorruptObject` + /// property. + /// 4) `StorageNotAvailable`: If the object is stored in a storage area + /// which is currently inaccessible. /// /// # Panics /// - /// 1) If object is not a valid opened object. - /// 2) If the Implementation detects any other error associated with this function which is not - /// explicitly associated with a defined return code for this function. + /// 1) If object is not a valid handle on a persistent object opened with + /// the write access right + /// 2) If the Implementation detects any other error associated with this + /// function which is not explicitly associated with a defined return + /// code for this function. pub fn write(&mut self, buf: &[u8]) -> Result<()> { match unsafe { raw::TEE_WriteObjectData(self.handle(), buf.as_ptr() as _, buf.len()) } { raw::TEE_SUCCESS => Ok(()), @@ -422,17 +456,19 @@ impl PersistentObject { /// # Errors /// /// 1) `StorageNoSpace`: If insufficient storage space is available. - /// would be greater than - /// [MiscellaneousConstants::TeeDataMaxPosition](MiscellaneousConstants::TeeDataMaxPosition). - /// 2) `CorruptObject`: If the [PersistentObject](PersistentObject) is corrupt. The object handle is closed. - /// 3) `StorageNotAvailable`: If the [PersistentObject](PersistentObject) is stored in a storage area which is - /// currently inaccessible. + /// 2) `CorruptObject`: If the object is corrupt. The object handle SHALL + /// behave based on the `gpd.ta.doesNotCloseHandleOnCorruptObject` + /// property. + /// 3) `StorageNotAvailable`: If the object is stored in a storage area + /// which is currently inaccessible. /// /// # Panics /// - /// 1) If object is not a valid opened object. - /// 2) If the Implementation detects any other error associated with this function which is not - /// explicitly associated with a defined return code for this function. + /// 1) If object is not a valid handle on a persistent object opened with + /// the write access right. + /// 2) If the Implementation detects any other error associated with this + /// function which is not explicitly associated with a defined return + /// code for this function. pub fn truncate(&self, size: u32) -> Result<()> { match unsafe { raw::TEE_TruncateObjectData(self.handle(), size as usize) } { raw::TEE_SUCCESS => Ok(()), @@ -443,7 +479,7 @@ impl PersistentObject { /// Set the data position indicator associate with the object. /// /// # Parameters - /// 1) `whence`: Defined in [Whence](Whence). + /// 1) `whence`: Defined in [Whence](crate::Whence). /// 2) `offset`: The bytes shifted based on `whence`. /// /// # Example @@ -469,16 +505,19 @@ impl PersistentObject { /// # Errors /// /// 1) `Overflow`: If data position indicator is greater than - /// [MiscellaneousConstants::TeeDataMaxPosition](MiscellaneousConstants::TeeDataMaxPosition). - /// 2) `CorruptObject`: If the [PersistentObject](PersistentObject) is corrupt. The object handle is closed. - /// 3) `StorageNotAvailable`: If the [PersistentObject](PersistentObject) is stored in a storage area which is - /// currently inaccessible. + /// [MiscellaneousConstants::TeeDataMaxPosition](crate::MiscellaneousConstants::TeeDataMaxPosition). + /// 2) `CorruptObject`: If the object is corrupt. The object handle SHALL + /// behave based on the `gpd.ta.doesNotCloseHandleOnCorruptObject` + /// property. + /// 3) `StorageNotAvailable`: If the object is stored in a storage area + /// which is currently inaccessible. /// /// # Panics /// - /// 1) If object is not a valid opened object. - /// 2) If the Implementation detects any other error associated with this function which is not - /// explicitly associated with a defined return code for this function. + /// 1) If object is not a valid handle on a persistent object. + /// 2) If the Implementation detects any other error associated with this + /// function which is not explicitly associated with a defined return + /// code for this function. pub fn seek(&self, offset: i32, whence: Whence) -> Result<()> { match unsafe { raw::TEE_SeekObjectData(self.handle(), offset.into(), whence.into()) } { raw::TEE_SUCCESS => Ok(()), diff --git a/optee-utee/src/object/transient_object.rs b/optee-utee/src/object/transient_object.rs index b0fb198..44f985f 100644 --- a/optee-utee/src/object/transient_object.rs +++ b/optee-utee/src/object/transient_object.rs @@ -22,14 +22,17 @@ use optee_utee_sys as raw; use super::{Attribute, GenericObject, ObjectHandle}; use crate::{Error, Result}; -/// Define types of [TransientObject](TransientObject) with predefined maximum sizes. +/// Define types of [TransientObject](crate::TransientObject) with +/// predefined maximum sizes. #[repr(u32)] pub enum TransientObjectType { /// 128, 192, or 256 bits Aes = 0xA0000010, - /// Always 64 bits including the parity bits. This gives an effective key size of 56 bits + /// Always 64 bits including the parity bits. This gives an effective key + /// size of 56 bits Des = 0xA0000011, - /// 128 or 192 bits including the parity bits. This gives effective key sizes of 112 or 168 bits + /// 128 or 192 bits including the parity bits. This gives effective key + /// sizes of 112 or 168 bits Des3 = 0xA0000013, /// Between 64 and 512 bits, multiple of 8 bits HmacMd5 = 0xA0000001, @@ -43,19 +46,22 @@ pub enum TransientObjectType { HmacSha384 = 0xA0000005, /// Between 256 and 1024 bits, multiple of 8 bits HmacSha512 = 0xA0000006, - /// The number of bits in the modulus. 256, 512, 768, 1024, 1536 and 2048-bit keys SHALL be supported. + /// The number of bits in the modulus. 256, 512, 768, 1024, 1536 and + /// 2048-bit keys SHALL be supported. /// Support for other key sizes including bigger key sizes is /// implementation-dependent. Minimum key size is 256 bits RsaPublicKey = 0xA0000030, - /// Same as [RsaPublicKey](TransientObjectType::RsaPublicKey) key size. + /// Same as [RsaPublicKey](crate::TransientObjectType::RsaPublicKey) key + /// size. RsaKeypair = 0xA1000030, /// Depends on Algorithm: - /// 1) [DsaSha1](../crypto_op/enum.AlgorithmId.html#variant.DsaSha1): + /// 1) [DsaSha1](crate::AlgorithmId::DsaSha1): /// Between 512 and 1024 bits, multiple of 64 bits - /// 2) [DsaSha224](../crypto_op/enum.AlgorithmId.html#variant.DsaSha224): 2048 bits - /// 3) [DsaSha256](../crypto_op/enum.AlgorithmId.html#variant.DsaSha256): 2048 or 3072 bits + /// 2) [DsaSha224](crate::AlgorithmId::DsaSha224): 2048 bits + /// 3) [DsaSha256](crate::AlgorithmId::DsaSha256): 2048 or 3072 bits DsaPublicKey = 0xA0000031, - /// Same as [DsaPublicKey](TransientObjectType::DsaPublicKey) key size. + /// Same as [DsaPublicKey](crate::TransientObjectType::DsaPublicKey) key + /// size. DsaKeypair = 0xA1000031, /// From 256 to 2048 bits, multiple of 8 bits. DhKeypair = 0xA1000032, @@ -100,12 +106,12 @@ pub enum TransientObjectType { /// when closed or when the TA instance is destroyed. /// Transient objects are used to hold a cryptographic object (key or key-pair). /// -/// Contrast [PersistentObject](PersistentObject). +/// Contrast [PersistentObject](crate::PersistentObject). #[derive(Debug)] pub struct TransientObject(ObjectHandle); impl TransientObject { - /// Create a [TransientObject](TransientObject) with a null handle which points to nothing. + /// Create an object with a null handle which points to nothing. // // TODO: This function is only used in examples and should be removed when // TransientObject is fully refactored in the future. Keep it for now and @@ -123,18 +129,20 @@ impl TransientObject { self.0.is_null() } - /// Allocate an uninitialized [TransientObject](TransientObject), i.e. a container for attributes. + /// Allocate an uninitialized object, i.e. a container for attributes. /// /// As allocated, the object is uninitialized. - /// It can be initialized by subsequently importing the object material, generating an object, - /// deriving an object, or loading an object from the Trusted Storage. + /// It can be initialized by subsequently importing the object material, + /// generating an object, deriving an object, or loading an object from the + /// Trusted Storage. /// /// # Parameters /// - /// 1) `object_type`: Type of uninitialized object container to be created as defined in - /// [TransientObjectType](TransientObjectType). - /// 2) `max_object_size`: Key Size of the object. Valid values depend on the object type and are - /// defined in [TransientObjectType](TransientObjectType). + /// 1) `object_type`: Type of uninitialized object container to be created + /// as defined in [TransientObjectType](crate::TransientObjectType). + /// 2) `max_object_size`: Key Size of the object. Valid values depend on the + /// object type and are defined in + /// [TransientObjectType](crate::TransientObjectType). /// /// # Example /// @@ -154,13 +162,16 @@ impl TransientObject { /// /// # Errors /// - /// 1) `OutOfMemory`: If not enough resources are available to allocate the object handle. - /// 2) `NotSupported`: If the key size is not supported or the object type is not supported. + /// 1) `OutOfMemory`: If not enough resources are available to allocate the + /// object handle. + /// 2) `NotSupported`: If the key size is not supported or the object type + /// is not supported. /// /// # Panics /// - /// 1) If the Implementation detects any error associated with this function which is not - /// explicitly associated with a defined return code for this function. + /// 1) If the Implementation detects any error associated with this function + /// which is not explicitly associated with a defined return code for + /// this function. pub fn allocate(object_type: TransientObjectType, max_object_size: usize) -> Result<Self> { let mut handle: raw::TEE_ObjectHandle = core::ptr::null_mut(); // Move as much code as possible out of unsafe blocks to maximize Rust’s @@ -174,19 +185,23 @@ impl TransientObject { } } - ///Reset a [TransientObject](TransientObject) to its initial state after allocation. - ///If the object is currently initialized, the function clears the object of all its material. - ///The object is then uninitialized again. + /// Reset the object to its initial state after allocation. + /// If the object is currently initialized, the function clears the object + /// of all its material. + /// The object is then uninitialized again. pub fn reset(&mut self) { unsafe { raw::TEE_ResetTransientObject(self.handle()); } } - /// Populate an uninitialized object container with object attributes passed by the TA in the `attrs` parameter. + /// Populate an uninitialized object container with object attributes passed + /// by the TA in the `attrs` parameter. /// When this function is called, the object SHALL be uninitialized. - /// If the object is initialized, the caller SHALL first clear it using the function reset. - /// Note that if the object type is a key-pair, then this function sets both the private and public attributes of the keypair. + /// If the object is initialized, the caller SHALL first clear it using the + /// function reset. + /// Note that if the object type is a key-pair, then this function sets both + /// the private and public attributes of the keypair. /// /// # Parameters /// @@ -216,17 +231,22 @@ impl TransientObject { /// /// # Errors /// - /// 1) `BadParameters`: If an incorrect or inconsistent attribute value is detected. In this case, - /// the content of the object SHALL remain uninitialized. + /// 1) `BadParameters`: If an incorrect or inconsistent attribute value is + /// detected. In this case, the content of the object SHALL remain + /// uninitialized. /// /// # Panics /// - /// 1) If object is not a valid opened object that is transient and uninitialized. + /// 1) If object is not a valid opened object that is transient and + /// uninitialized. /// 2) If some mandatory attribute is missing. - /// 3) If an attribute which is not defined for the object’s type is present in attrs. - /// 4) If an attribute value is too big to fit within the maximum object size specified when the object was created. - /// 5) If the Implementation detects any other error associated with this function which is not - /// explicitly associated with a defined return code for this function. + /// 3) If an attribute which is not defined for the object’s type is + /// present in attrs. + /// 4) If an attribute value is too big to fit within the maximum object + /// size specified when the object was created. + /// 5) If the Implementation detects any other error associated with this + /// function which is not explicitly associated with a defined return + /// code for this function. pub fn populate(&mut self, attrs: &[Attribute]) -> Result<()> { let p: Vec<raw::TEE_Attribute> = attrs.iter().map(|p| p.raw()).collect(); match unsafe { @@ -237,15 +257,21 @@ impl TransientObject { } } - /// Populates an uninitialized object handle with the attributes of another object handle; - /// that is, it populates the attributes of this handle with the attributes of src_handle. + /// Populates an uninitialized object handle with the attributes of another + /// object handle; + /// that is, it populates the attributes of this handle with the attributes + /// of src_handle. /// It is most useful in the following situations: /// 1) To extract the public key attributes from a key-pair object. - /// 2) To copy the attributes from a [PersistentObject](PersistentObject) into a [TransientObject](TransientObject). + /// 2) To copy the attributes from a + /// [PersistentObject](crate::PersistentObject) into a + /// [TransientObject](crate::TransientObject). /// /// # Parameters /// - /// 1) `src_object`: Can be either a [TransientObject](TransientObject) or [PersistentObject](PersistentObject). + /// 1) `src_object`: Can be either a + /// [TransientObject](crate::TransientObject) or + /// [PersistentObject](crate::PersistentObject). /// /// # Example /// @@ -270,17 +296,20 @@ impl TransientObject { /// /// # Errors /// - /// 1) `CorruptObject`: If the persistent` object is corrupt. The object handle is closed. - /// 2) `StorageNotAvailable`: If the [PersistentObject](PersistentObject) is stored in a storage area which is - /// currently inaccessible. + /// 1) `CorruptObject`: If the persistent object is corrupt. The object + /// handle SHALL behave based on the + /// `gpd.ta.doesNotCloseHandleOnCorruptObject` property. + /// 2) `StorageNotAvailable`: If the persistent object is stored in a + /// storage area which is currently inaccessible. /// /// # Panics /// /// 1) If src_object is not initialized. /// 2) If self is initialized. /// 3) If the type and size of src_object and self are not compatible. - /// 4) If the Implementation detects any other error associated with this function which is not - /// explicitly associated with a defined return code for this function. + /// 4) If the Implementation detects any other error associated with this + /// function which is not explicitly associated with a defined return + /// code for this function. pub fn copy_attribute_from<T: GenericObject>(&mut self, src_object: &T) -> Result<()> { match unsafe { raw::TEE_CopyObjectAttributes1(self.handle(), src_object.handle()) } { raw::TEE_SUCCESS => Ok(()), @@ -288,12 +317,14 @@ impl TransientObject { } } - /// Generates a random key or a key-pair and populates a transient key object with the generated key material. + /// Generates a random key or a key-pair and populates a transient key + /// object with the generated key material. /// /// # Parameters /// - /// 1) `key_size`: the size of the desired key. It SHALL be less than or equal to - /// the maximum key size specified when the [TransientObject](TransientObject) was created. + /// 1) `key_size`: the size of the desired key. It SHALL be less than or + /// equal to the maximum key size specified when the transient object + /// was created. /// /// # Example /// @@ -320,11 +351,13 @@ impl TransientObject { /// /// 1) If object is not a valid opened object. /// 2) If some mandatory attribute is missing. - /// 3) If an attribute which is not defined for the object’s type is present in attrs. - /// 4) If an attribute value is too big to fit within the maximum object size specified when - /// the object was created. - /// 5) If the Implementation detects any other error associated with this function which is not - /// explicitly associated with a defined return code for this function. + /// 3) If an attribute which is not defined for the object’s type is present + /// in attrs. + /// 4) If an attribute value is too big to fit within the maximum object + /// size specified when the object was created. + /// 5) If the Implementation detects any other error associated with this + /// function which is not explicitly associated with a defined return + /// code for this function. pub fn generate_key(&self, key_size: usize, params: &[Attribute]) -> Result<()> { let p: Vec<raw::TEE_Attribute> = params.iter().map(|p| p.raw()).collect(); unsafe { --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
