Struct optee_utee::object::TransientObject

pub struct TransientObject(_);

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 a TransientObject with a null handle which points to nothing.

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

Allocate an uninitialized TransientObject, 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 a 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.

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(object) =>
    {
        let attrs = [AttributeMemref::from_ref(AttributeId::SecretValue, &[0u8;1])];
        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 info(&self) -> Result<ObjectInfo>

Return the characteristics of an object.

Example

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

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.

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

The initial value of the key usage contains all usage flags.

Parameters

1. obj_usage: New object usage, an OR comination of one or more of the UsageFlag.

Example

match TransientObject::allocate(TransientObjectType::Aes, 128) {
    Ok(object) =>
    {
        object.restrict_usage(UsageFlag::ENCRYPT)?;
        Ok(())
    }
    Err(e) => Err(e),
}

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.

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

Parameters

1. id: Identifier of the attribute to retrieve.
2. ref_attr: Output buffer to get the content of the attribute.

Example

match TransientObject::allocate(TransientObjectType::Aes, 128) {
    Ok(object) => {
        let mut attr = [0u8; 16];
        match object.ref_attribute(id, &mut attr) {
            Ok(size) => {
                // ...
                Ok(())
            }
            Err(e) => Err(e),
        }
    }
    Err(e) => Err(e),
}

Errors

1. ItemNotFound: If the attribute is not found on this object.
2. ShortBuffer: If buffer is NULL or too small to contain the key part.

Panics

1. If object is not a valid opened object.
2. If the object is not initialized.
3. If the Attribute is not a buffer attribute.

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

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

Parameters

1. id: Identifier of the attribute to retrieve.
2. value_attr: Two value placeholders to get the content of the attribute.

Example

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

Errors

1. ItemNotFound: If the attribute is not found on this object.

Panics

1. If object is not a valid opened object.
2. If the object is not initialized.
3. If the Attribute is not a value attribute.

pub fn copy_attribute_from<T: ObjHandle>(
    &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(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 persistentd` object is corrupt. The object handle is closed.
2. StorageNotAvailable: If the PersistentObject 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 TransientObject 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 Drop for TransientObject

fn drop(&mut self)

Deallocates a TransientObject previously allocated. After this function has been called, the object handle is no longer valid and all resources associated with the TransientObject SHALL have been reclaimed.

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.

impl ObjHandle for TransientObject

fn handle(&self) -> TEE_ObjectHandle

Return the handle of an object.