Struct optee_utee::crypto_op::Cipher

pub struct Cipher(_);

An operation for conducting symmetric cipher encryption / decryption. This operation defines the way to perform symmetric cipher operations, such as AES. They cover both block ciphers and stream ciphers.

Implementations

impl Cipher

pub fn init(&self, iv: &[u8])

Start the symmetric cipher operation. The function should be called after the set_key or set_key_2.

After called, if the operation is in active state, it is reset and then initialized. If the operation is in initial state, it is moved to active state.

Parameters

1. iv: buffer contains the operation Initialization Vector, which is used for: 1.1) AesCbcNopad: IV; 1.2) AesCtr: Initial Counter Value; 1.3) AesCts: IV; 1.4) AesXts: Tweak Value; 1.5) AesCcm: Nonce Value; 1.6) AesGcm: Nonce Value; 1.7) AesCbcNopad: IV.

Panics

1. If the algorithm is not a valid algorithm for Cipher.
2. If no key is programmed in the operation.
3. If the IV does not have the length required by the algorithm.
4. Hardware or cryptographic algorithm failure.
5. If the Implementation detects any other error.

pub fn update(&self, src: &[u8], dest: &mut [u8]) -> Result<usize>

Encrypt or decrypt the source data.

Input data does not have to be a multiple of block size. Subsequent calls to this function are possible. Unless one or more calls of this function have supplied sufficient input data, no output is generated. The function should be called after the init.

Parameters

1. src: Input data buffer to be encrypted or decrypted.
2. dest: Output buffer.

Example

let iv = [0u8, 16];
let key = [0u8, 16];
let src = [1u8; 4096];
let mut dest = [0u8; 4096];
match Cipher::allocate(AlgorithmId::AesCtr, 128) {
    Ok(operation) =>
    {
        match TransientObject::allocate(TransientObjectType::Aes, 128) {
            Ok(object) =>
            {
                let attr = AttributeMemref::from_ref(AttributeId::SecretValue, &key);
                object.populate(&[attr.into()])?;
                operation.set_key(&object)?;
                operation.init(&iv);
                operation.update(&src, &mut dest)?;
                Ok(())
            }
            Err(e) => Err(e),
        }
    }
    Err(e) => Err(e),
}

Errors

1. ShortBuffer: If the output buffer is not large enough to contain the output. In this case, the input is not fed into the algorithm.

Panics

1. If the algorithm is not a valid algorithm for Cipher.
2. If the function is called before init or after do_final.
3. Hardware or cryptographic algorithm failure.
4. If the Implementation detects any other error.

pub fn do_final(&self, src: &[u8], dest: &mut [u8]) -> Result<usize>

Finalize the cipher operation, processing data that has not been processed by previous calls to update as well as data supplied in src. The operation handle can be reused or re-initialized.

Parameters

1. src: Input data buffer to be encrypted or decrypted.
2. dest: Output buffer.

Errors

1. ShortBuffer: If the output buffer is not large enough to contain the output.

Panics

1. If the algorithm is not a valid algorithm for Cipher.
2. If the function is called before init.
3. Hardware or cryptographic algorithm failure.
4. If the Implementation detects any other error.

pub fn null() -> Self

Create a Cipher operation without any specific algorithm or other data.

pub fn allocate(
    algo: AlgorithmId,
    mode: OperationMode,
    max_key_size: usize
) -> Result<Self>

Function usage is similar to Digest::allocate.

pub fn info(&self) -> OperationInfo

Function usage is similar to Digest::info.

pub fn info_multiple(
    &self,
    info_buf: &mut [u8]
) -> Result<OperationInfoMultiple>

Function usage is similar to Digest::info_multiple.

pub fn set_key<T: ObjHandle>(&self, object: &T) -> Result<()>

Program the key of Digest operation. That ids, it associates the operation with a key.

Parameters

1. object: The object can either be a Transient or Persistent. The key material is copied from the key object handle into the operation. After the key has been set, there is no longer any link between the operation and the key object. The object handle can be closed or reset and this will not affect the operation. This copied material exists until the operation is freed or another key is set into the operation.

Errors

1. CorruptObject: If the object is corrupt. The object handle is closed.
2. StorageNotAvailable: If the object is stored in a storage area which is currently inaccessible.

Panics

1. If operation is not a valid opened object.
2. If object is not null and is not a valid key object.
3. If object is not initialized.
4. If the operation expect two keys as AesXts.
5. If the type, size, or usage of object is not compatible with the algorithm, mode, or size of the operation.
6. If operation is not in initial state.
7. Hardware or cryptographic algorithm failure.
8. If the Implementation detects any other error.

pub fn set_key_2<T: ObjHandle, D: ObjHandle>(
    &self,
    object1: &T,
    object2: &D
) -> Result<()>

Initialize an expisting operation with two keys for AesXts.

Parameters:

object1 and object2 SHALL both be non-NULL or both NULL. object1 and object2 SHALL NOT refer to keys with bitwise identical SecretValue attributes.

Errors

1. CorruptObject: If the object1 is corrupt. The object handle is closed.
2. CorruptObject2: If the object2 is corrupt. The object handle is closed.
3. StorageNotAvailable: If the object1 is stored in a storage area which is currently inaccessible.
4. StorageNotAvailable2: If the object2 is stored in a storage area which is currently inaccessible.

Panics

1. If operation is not a valid opened object.
2. If object1 and object2 are not both null and object1 or object2 or both are not a valid key object.
3. If object1 or object2 is not initialized.
4. If the operation algorithm is not AesXts.
5. If the type, size, or usage of any object is not compatible with the algorithm, mode, or size of the operation.
6. If operation is not in initial state.
7. Hardware or cryptographic algorithm failure.
8. If the Implementation detects any other error.

pub fn copy<T: OpHandle>(&mut self, src: &T)

Function usage is similar to Digest::copy.

Trait Implementations

impl OpHandle for Cipher

fn handle(&self) -> TEE_OperationHandle

Return the handle of an operation.