Struct optee_utee::object::TransientObject

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

An object containing attributes but no data stream, which is reclaimed when closed or when the TA instance is destroyed. Transient objects are used to hold a cryptographic object (key or key-pair).

Contrast PersistentObject.

Implementations

impl TransientObject

pub fn null_object() -> Self

Create an object with a null handle which points to nothing.

pub fn is_null_object(&self) -> bool

Check if current object is created with null handle.

See Also

• Self::null_object.

pub fn allocate( object_type: TransientObjectType, max_object_size: usize ) -> Result<Self>

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.

Parameters

1. object_type: Type of uninitialized object container to be created as defined in TransientObjectType.
2. max_object_size: Key Size of the object. Valid values depend on the object type and are defined in TransientObjectType.

Example

match TransientObject::allocate(TransientObjectType::Aes, 128) {
    Ok(object) =>
    {
        // ...
        Ok(())
    }
    Err(e) => Err(e),
}

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.

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.

pub fn reset(&mut self)

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 populate(&mut self, attrs: &[Attribute]) -> Result<()>

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.

Parameters

1. attrs: Array of object attributes.

Example

match TransientObject::allocate(TransientObjectType::Aes, 128) {
    Ok(mut object) =>
    {
        let attrs = [AttributeMemref::from_ref(AttributeId::SecretValue, &[0u8;1]).into()];
        object.populate(&attrs);
        Ok(())
    }
    Err(e) => Err(e),
}

Errors

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

pub fn copy_attribute_from<T: GenericObject>( &mut self, src_object: &T ) -> Result<()>

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 into a TransientObject.

Parameters

1. src_object: Can be either a TransientObject or PersistentObject.

Example

match TransientObject::allocate(TransientObjectType::Aes, 128) {
    Ok(mut object1) =>
    {
        match TransientObject::allocate(TransientObjectType::Aes, 256) {
            Ok(object2) => {
                object1.copy_attribute_from(&object2);
                Ok(())
            }
            Err(e) => Err(e),
        }
    }
    Err(e) => Err(e),
}

Errors

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.

pub fn generate_key(&self, key_size: usize, params: &[Attribute]) -> Result<()>

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 transient object was created.

Example

match TransientObject::allocate(TransientObjectType::Aes, 128) {
    Ok(object) =>
    {
        object.generate_key(128, &[])?;
        Ok(())
    }
    Err(e) => Err(e),
}

Errors

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

Trait Implementations

impl Debug for TransientObject

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

Formats the value using the given formatter.

impl GenericObject for TransientObject

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.