Struct optee_utee::crypto_op::AE

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

An operation for conducting authenticated encryption / decryption.

Implementations

impl AE

pub fn init( &self, nonce: &[u8], tag_len: usize, aad_len: usize, pay_load_len: usize ) -> Result<()>

Initialize an AE opeartion. The operation must be in the initial state and remains in the initial state afterwards.

Parameters

1. nonce: The peration nonce or IV
2. tag_len: Size in bits of the tag: 2.1) for AES-GCM, can be 128, 120, 112, 104, or 96; 2.2) for AES-CCM, can be 128, 112, 96, 80, 64, 48, or 32.
3. aad_len: length in bytes of the AAD (Used only for AES-CCM. Ignored for AES-GCM).
4. pay_load_len: Length in bytes of the payload (Used only for AES-CCM. Ignored for AES-GCM).

Errors

1. NotSupported: If the tag_len is not supported by the algorithm.

Panics

1. If the algorithm is not a valid algorithm for AE.
2. If no key is programmed in the operation.
3. If the nonce length is not compatible with the length required by the algorithm.
4. If operation is not in initial state.
5. Hardware or cryptographic algorithm failure.
6. If the Implementation detects any other error.

pub fn update_aad(&self, aad_data: &[u8])

Feed a new chunk of Additional Authentication Data (AAD) to the AE operation. Subsequent calls to this function are possible. The operation SHALL be in initial state and remains in initial state afterwards.

Parameters

1. aad_data: Input buffer containing the chunk of AAD.

Panics

1. If the algorithm is not a valid algorithm for AE.
2. If the function is called before init or has been finalized.
3. For AES-CCM, if the aad_data.len() exceeds the requirement.
4. If operation is not in initial state.
5. Hardware or cryptographic algorithm failure.
6. If the Implementation detects any other error.

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

Accumulate data for an Authentication Encryption operation. 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 buffers src and dest SHALL be either completely disjoint or equal in their starting positions. The operation may be in either initial or active state and enters active state afterwards if src.len() != 0.

Parameters

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

Errors

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

Panics

1. If the algorithm is not a valid algorithm for AE.
2. If the function is called before init or has been finalized.
3. For AES-CCM, if the AAD length exceeds the requirement.
4. For AES-CCM, if the payload length is exceeds the requirement.
5. Hardware or cryptographic algorithm failure.
6. If the Implementation detects any other error.

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

Process data that has not been processed by previous calls to update as well as data supplied in src. It completes the AE operation and computes the tag. The buffers src and dest SHALL be either completely disjoint or equal in their starting positions. The operation may be in either initial or active state and enters initial state afterwards.

Parameters

1. src: Reference to final chunk of input data to be encrypted.
2. dest: Output buffer. Can be omitted if the output is to be discarded, e.g. because it is known to be empty.
3. tag: Output buffer filled with the computed tag.

Example

let key = [0xa5u8; 16];
let nonce = [0x00u8; 16];
let aad = [0xffu8; 16];
let clear1 = [0x5au8; 19];
let clear2 = [0xa5u8; 13];
let mut ciph1 = [0x00u8; 16];
let mut ciph2 = [0x00u8; 16];
let mut tag = [0x00u8; 16];
match AE::allocate(AlgorithmId::AesCcm, OperationMode::Encrypt, 128) {
    Ok(operation) => {
        match TransientObject::allocate(TransientObjectType::Aes, 128) {
            Ok(mut key_object) => {
                let attr = AttributeMemref::from_ref(AttributeId::SecretValue, &key);
                key_object.populate(&[attr.into()])?;
                operation.set_key(&key_object)?;
                operation.init(&nonce, 128, 16, 32)?;
                operation.update_aad(&aad);
                operation.update(&clear1, &mut ciph1)?;
                match operation.encrypt_final(&clear2, &mut ciph2, &mut tag) {
                    Ok((_ciph_len, _tag_len)) => {
                        // ...
                        Ok(())
                    },
                    Err(e) => Err(e),
                }
            },
            Err(e) => Err(e),
        }
    },
    Err(e) => Err(e),
}

Errors

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

Panics

1. If the algorithm is not a valid algorithm for AE.
2. If the function is called before init or has been finalized.
3. If the required payload length is known but has not been provided.
4. Hardware or cryptographic algorithm failure.
5. If the Implementation detects any other error.

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

Process data that has not been processed by previous calls to update as well as data supplied in src. It completes the AE operation and computes the tag. The buffers src and dest SHALL be either completely disjoint or equal in their starting positions. The operation may be in either initial or active state and enters initial state afterwards.

Parameters

1. src: Reference to final chunk of input data to be decrypted.
2. dest: Output buffer. Can be omitted if the output is to be discarded, e.g. because it is known to be empty.
3. tag: Input buffer containing the tag to compare.

Errors

ShortBuffer: If the output buffer is not large enough to contain the output. MacInvalid: If the computed tag does not match the supplied tag.

Panics

1. If the algorithm is not a valid algorithm for AE.
2. If the function is called before init or has been finalized.
3. If the required payload length is known but has not been provided.
4. Hardware or cryptographic algorithm failure.
5. If the Implementation detects any other error.

pub fn null() -> Self

Create an AE 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 reset(&mut self)

Function usage is similar to Digest::reset.

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

Function usage is similar to Cipher::set_key.

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

Function usage is similar to Digest::copy.

Trait Implementations

impl OpHandle for AE

fn handle(&self) -> TEE_OperationHandle

Return the handle of an operation.