# AES_Ctr*

## Syntax

      #include <twl/aes.h>

      AESResult AES_Ctr( const AESCounter*   pCounter,
                         const void*         src,
                         u32                 srcSize
                         void*               dst,
                         AESCallback         callback,
                         void*               arg );

      AESResult AES_CtrEncrypt( const AESCounter*   pCounter,
                                const void*         src,
                                u32                 srcSize
                                void*               dst,
                                AESCallback         callback,
                                void*               arg );
      AESResult AES_CtrDecrypt( const AESCounter*   pCounter,
                                const void*         src,
                                u32                 srcSize
                                void*               dst,
                                AESCallback         callback,
                                void*               arg );

## Arguments

pCounter | Pointer to the initial value of the counter used for encryption (decryption).
src | Pointer to the plaintext (ciphertext). Must be 4-byte aligned. In addition, it must point to a location in main memory.
srcSize | Plaintext (ciphertext) size. Must be greater than zero.
dst | Pointer to the buffer that will store the ciphertext (plaintext). Must be 4-byte aligned. In addition, it must point to a location in main memory. An area of size srcSize bytes is required. This argument can specify the same pointer as src.
callback | Pointer to the callback function to call when encryption (decryption) is complete. It is possible to specify `NULL`.
arg | User-defined parameter that is passed to the above callback function. Can be any value, including `NULL`.

## Return Values

Returns `AES_RESULT_SUCCESS` if the AES operation was started successfully. Any other return values indicate an error.

## Description

Starts the AES encryption (decryption) process in CTR mode. In CTR mode, encryption and decryption are the same operation. `AES_CtrEncrypt` and `AES_CtrDecrypt` are aliases of `AES_Ctr`, so these three functions all do the same thing.

This function encrypts or decrypts the srcSize bytes starting from src, using the key that was set with the `AES_SetKey` function and the initial counter value pCounter. The encrypted or decrypted result is written to a region starting at dst whose size is srcSize bytes. When the encryption or decryption process completes, this function calls callback, using the processing result and arg as arguments. callback is called from the interrupt handler, so it might be called even when interrupts are disabled. Conversely, callback is not called when interrupts are disabled.

This function returns control immediately once it has started the processing. If processing starts without a problem, this function returns `AES_RESULT_SUCCESS`, but if an error occurs during subsequent processing, it calls callback with the error value and arg as arguments. Note: Error notification using this callback is started from the interrupt handler, so depending on the situation, it is possible that the callback can deliver error notification before control returns from the function.

The encryption or decryption key must be set beforehand using the `AES_SetKey` function.

The same key and initial counter value must be used at encryption and decryption. The key must not be leaked, but it is not a problem if the initial counter value gets leaked. However, the initial counter value must be different each time this function is called.

## See Also

`AES_SetKey`

## Revision History

2009/01/30 Added mention that dst and src can be the same buffer.
2007/12/25 Initial version.

CONFIDENTIAL