Struct optee_utee::object::PersistentObject

pub struct PersistentObject(/* private fields */);

An object identified by an Object Identifier and including a Data Stream.

Contrast TransientObject.

Implementations

impl PersistentObject

pub fn open( storage_id: ObjectStorageConstants, object_id: &[u8], flags: DataFlag ) -> Result<Self>

Open an existing persistent object.

Parameters

1. storage_id: The storage to use which is defined in ObjectStorageConstants.
2. object_id: The object identifier. Note that this buffer cannot reside in shared memory.
3. flags: The DataFlag which determine the settings under which the object is opened.

Example

let obj_id = [1u8;1];
match PersistentObject::open(
        ObjectStorageConstants::Private,
        &obj_id,
        DataFlag::ACCESS_READ) {
    Ok(object) =>
    {
        // ...
        Ok(())
    }
    Err(e) => Err(e),
}

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 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
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 create( storage_id: ObjectStorageConstants, object_id: &[u8], flags: DataFlag, attributes: Option<ObjectHandle>, initial_data: &[u8] ) -> Result<Self>

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.
2. object_id: The object identifier. Note that this buffer cannot reside in shared memory.
3. flags: The DataFlag which determine the settings under which the object is opened.
4. attributes: A handle on a PersistentObject or an initialized TransientObject from which to take the PersistentObject attributes. Can be NONE if the PersistentObject contains no attribute. For example,if it is a pure data object.

Example

let obj_id = [1u8;1];
let mut init_data: [u8; 0] = [0; 0];
match PersistentObject::create(
        ObjectStorageConstants::Private,
        &obj_id,
        DataFlag::ACCESS_READ | DataFlag::ACCESS_WRITE,
        None,
        &mut init_data) {
    Ok(object) =>
    {
        // ...
        Ok(())
    }
    Err(e) => Err(e),
}

Errors

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.
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 close_and_delete(self) -> Result<()>

Marks an object for deletion and closes the object.

Example

let obj_id = [1u8;1];
match PersistentObject::open (
        ObjectStorageConstants::Private,
        &obj_id,
        DataFlag::ACCESS_READ) {
    Ok(mut object) =>
    {
        object.close_and_delete()?;
        Ok(())
    }
    Err(e) => Err(e),
}

Errors

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.

Breaking Changes

Now we no longer need to call core::mem::forget after successfully calling close_and_delete, and code like this will now produce a compilation error.

let mut obj = PersistentObject::open (
        ObjectStorageConstants::Private,
        &obj_id,
        DataFlag::ACCESS_READ,
)?;
obj.close_and_delete()?;
core::mem::forget(obj); // will get compilation error in this line
//                ^^^ value used here after move

pub fn rename(&mut self, new_object_id: &[u8]) -> Result<()>

Changes the identifier of an object. The object SHALL have been opened with the DataFlag::ACCESS_WRITE_META right, which means access to the object is exclusive.

Example

let obj_id = [1u8;1];
let new_obj_id = [2u8;1];
match PersistentObject::open (
        ObjectStorageConstants::Private,
        &obj_id,
        DataFlag::ACCESS_WRITE_META) {
    Ok(mut object) =>
    {
        object.rename(&new_obj_id)?;
        Ok(())
    }
    Err(e) => Err(e),
}

Errors

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 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.
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 read(&self, buf: &mut [u8]) -> Result<u32>

Read requested size from the data stream associate with the object into the buffer.

Parameters

1. buffer: A pre-allocated buffer for saving the object’s data stream.
2. count: The returned value contains the number of bytes read.

Example

let obj_id = [1u8;1];
match PersistentObject::open (
        ObjectStorageConstants::Private,
        &obj_id,
        DataFlag::ACCESS_READ) {
    Ok(object) =>
    {
        let mut read_buf = [0u8;16];
        object.read(&mut read_buf)?;
        Ok(())
    }
    Err(e) => Err(e),
}

Errors

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 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 write(&mut self, buf: &[u8]) -> Result<()>

Write the passed in buffer data into from the data stream associate with the object.

Parameters

1. buffer: A pre-allocated buffer for saving the object’s data stream.

Example

let obj_id = [1u8;1];
match PersistentObject::open (
        ObjectStorageConstants::Private,
        &obj_id,
        DataFlag::ACCESS_WRITE) {
    Ok(mut object) =>
    {
        let write_buf = [1u8;16];
        object.write(& write_buf)?;
        Ok(())
    }
    Err(e) => Err(e),
}

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.
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 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<()>

Change the size of a data stream associate with the object.

Example

let obj_id = [1u8;1];
match PersistentObject::open (
        ObjectStorageConstants::Private,
        &obj_id,
        DataFlag::ACCESS_WRITE) {
    Ok(object) =>
    {
        object.truncate(1u32)?;
        Ok(())
    }
    Err(e) => Err(e),
}

Errors

1. StorageNoSpace: If insufficient storage space is available.
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 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 seek(&self, offset: i32, whence: Whence) -> Result<()>

Set the data position indicator associate with the object.

Parameters

1. whence: Defined in Whence.
2. offset: The bytes shifted based on whence.

Example

let obj_id = [1u8;1];
match PersistentObject::open(
        ObjectStorageConstants::Private,
        &obj_id,
        DataFlag::ACCESS_WRITE) {
    Ok(object) =>
    {
        object.seek(0i32, Whence::DataSeekSet)?;
        Ok(())
    }
    Err(e) => Err(e),
}

Errors

1. Overflow: If data position indicator is greater than 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 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.

Trait Implementations

impl Debug for PersistentObject

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl GenericObject for PersistentObject

fn handle(&self) -> TEE_ObjectHandle

Return the handle of an object.

fn info(&self) -> Result<ObjectInfo>

Return the characteristics of an object.

fn restrict_usage(&mut self, obj_usage: UsageFlag) -> Result<()>

Restrict the object usage flags of an object handle to contain at most the flags passed in the obj_usage parameter.

fn ref_attribute(&self, id: AttributeId, buffer: &mut [u8]) -> Result<usize>

Extract one buffer attribute from an object. The attribute is identified by the argument id.

fn value_attribute(&self, id: u32) -> Result<(u32, u32)>

Extract one value attribute from an object. The attribute is identified by the argument id.