hu_AESBeginV2()

Creates an AES context initialized with the given parameters (with the ability to override the mode in the parameters) and key.

Synopsis:

#include "huaes.h"

int hu_AESBeginV2(sb_Params aesParams, sb_Key aesKey, int mode, size_t ivLen, const unsigned char *iv, sb_Context *aesContext, sb_GlobalCtx sbCtx)

Since:

BlackBerry 10.0.0

Arguments:

aesParams: The AES parameters object.

aesKey: The AES key object.

mode: The mode of operation. The acceptable values are 0, SB_AES_ECB, SB_AES_CBC, SB_AES_CFB128, SB_AES_CFB8, SB_AES_OFB128, SB_AES_KEYWRAP, SB_AES_CTR(ctrBits) and SB_AES_XTS(unitBytes). For SB_AES_CTR(ctrBits), ctrBits is the number of bits that will be used for the counter. ctrBits must be less than or equal to SB_AES_128_BLOCK_BITS. Specifying 0 will use the mode from the parameters object. For SB_AES_XTS(unitBytes), unitBytes is the number of bytes in a data unit. The number of bytes in a data unit must be a multiple of 16. By NIST SP 800-38E, the minimum number of bytes in a data unit is 16, and the maximum number of bytes allowed in a data unit is 2^24 = (0x1000000). Note that on the platforms where int is 4 bytes, only up to 2^24 - 16 (=0xFFFFF0) can be specified.

ivLen: The length (in bytes) of initial vector. The only acceptable value is SB_AES_128_BLOCK_BYTES.

iv: The initial vector.

aesContext: The AES context object pointer.

sbCtx: A global context.

Library:

libhuapi (For the qcc command, use the -l huapi option to link against this library)

Description:

An initial vector is required for the SB_AES_CBC, SB_AES_CFB128, SB_AES_CFB8, SB_AES_OFB128, and SB_AES_CTR(ctrBits) modes of operation. For SB_AES_CTR(ctrBits), iv will be used as the initial counter block, where the initial counter value must be set in the most significant (higher index) ctrBits/8 bytes of the initial counter, and the counter value must be represented in big-endian. The counter is incremented by 1. iv is ignored for SB_AES_ECB, as an initial vector is not required for that mode.

For XTS mode, IV is used to specify the Data Unit Sequence Number and block index within the data unit to start the operation. The following rules apply to the value of IV for XTS mode:

The Data Unit Sequence Number is internally represented by size_t.
On platforms where the size of size_t is 4 bytes, the first 4 bytes of IV are used to specify the Data Unit Sequence Number, and the subsequent 4 bytes are ignored.
On the platforms where the size of size_t is 8 bytes, the first 8 bytes of IV are used to specify the Data Unit Sequence Number.
The 9th to 11th bytes are used to specify the block index in a data unit.
Block index in a data unit starts at 0.
The remaining bytes in IV are ignored.
The Data Unit Sequence Number and block index are represented in little-endian order, where the first byte is the least significant byte.
If the specified block index exceeds the size of a data unit, SB_ERR_BAD_IV will be returned.
IV for the specified Data Unit Sequence Number and block index can be set by using the hu_AESXTSIVSet() function.

If XTS mode is used and XTS mode was not specified in the hu_AESParamsCreate function, SB_ERR_BAD_KEY will be returned.

Returns:

SB_ERR_NULL_PARAMS: The aesParams object is NULL.

SB_ERR_BAD_PARAMS: The aesParams object is invalid.

SB_ERR_NULL_KEY: The aesKey object is NULL.

SB_ERR_BAD_KEY: The aesKey object is invalid.

SB_ERR_NULL_IV: iv, the initial vector, is NULL.

SB_ERR_BAD_IV_LEN: ivLen is an invalid vector length.

SB_ERR_BAD_IV: The value iv is invalid.

SB_ERR_NULL_CONTEXT_PTR: The context object pointer is NULL.

SB_ERR_NO_MODE: No mode has been specified.

SB_FAIL_ALLOC: Memory allocation failure.

SB_SUCCESS: Success.