hu_AESDecryptMsg()

Decrypts a ciphertext buffer using the given AES parameters and key.

Synopsis:

#include "huaes.h"

int hu_AESDecryptMsg(sb_Params aesParams, sb_Key aesKey, size_t ivLen, const unsigned char *iv, size_t length, const unsigned char *ciphertext, unsigned char *plaintext, sb_GlobalCtx sbCtx)

Since:

BlackBerry 10.0.0

Arguments:

aesParams: The AES parameters object.

aesKey: The AES key object.

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

iv: The initial vector.

length: The length (in bytes) of ciphertext. For ECB, CBC and XTS modes of operation the length must be a multiple of SB_AES_128_BLOCK_BYTES. For XTS mode, the data length shall not exceed the data size that Data Unit Sequence Number can represent. The Data Unit Sequence Number is limited to the value that can be expressed in type size_t.

ciphertext: The ciphertext buffer.

plaintext: The plaintext buffer.

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, SB_AES_CTR(ctrBits) and SB_AES_XTS(unitBytes) modes of operation.

For SB_AES_CTR(ctrBits), iv will be used as the initial counter block.

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

iv is ignored for SB_AES_ECB, as an initial vector is not required for that mode. The plaintext and ciphertext buffers must be the same length, and may overlap in memory subject to the constraints described in the API Reference section on overlapping buffers.

This function should only be called for blocks of plaintext and ciphertext that can be stored entirely in memory.

Returns:

SB_ERR_NULL_PARAMS: The aesParams object is NULL.

SB_ERR_BAD_PARAMS: The tag for the params object is not of the expected type.

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_NULL_INPUT_BUF: The ciphertext buffer is NULL.

SB_ERR_BAD_INPUT_BUF_LEN: The ciphertext buffer length, length, is invalid.

SB_ERR_NULL_OUTPUT_BUF: The plaintext buffer is NULL.

SB_SUCCESS: Success.