AES API

Includes:

"APSCommonServices.h"
"APSDebugServices.h"
"gcm.h"
"aes.h"
"Wincrypt.h"
<openssl/aes.h>

Introduction

APIs and platform interfaces for using the Advanced Encryption Standard (AES).

Support is provided for the following cryptographic libraries:

- Brian Gladman's AES. (default) - OpenSSL.

If one of these libraries is not available, these APIs will need to be implemented for your platform.

Groups

AES 128-bit CBC Frame Mode API

API to encrypt or decrypt using AES-128 in CBC frame mode.

Discussion

Call AES_CBCFrame_Init to initialize the context. Don't use the context until it has been initialized. Call AES_CBCFrame_Update to encrypt or decrypt N bytes of input and generate N bytes of output. Call AES_CBCFrame_Final to finalize the context. After finalizing, you must call AES_CBCFrame_Init to use it again.

See the unit test for an example of using it.

Group members:

AES_CBCFrame_Final: Finalizes a context for AES-128 in CBC frame mode when no longer needed. Context must not be used after this.
AES_CBCFrame_Init: Initializes a context for AES-128 in CBC frame mode. Must be called before other AES_CBCFrame_* functions.
AES_CBCFrame_Update: Encrypts or decrypts N bytes of data using AES-128 in CBC frame mode.
AES_CBCFrame_Update2: Encrypts or decrypts 2 chunnks of data, N bytes each using AES-128 in CBC frame mode.

AES 128-bit Counter Mode API

API to encrypt or decrypt using AES-128 in counter mode.

Discussion

Call AES_CTR_Init to initialize the context. Don't use the context until it has been initialized. Call AES_CTR_Update to encrypt or decrypt N bytes of input and generate N bytes of output. Call AES_CTR_Final to finalize the context. After finalizing, you must call AES_CTR_Init to use it again.

See the unit test for an example of using it.

Group members:

AES_CTR_Final: Finalizes a context for AES-128 in counter mode when no longer needed. Context must not be used after this.
AES_CTR_Init: Initializes a context for AES-128 in counter mode. Must be called before other AES_CTR_* functions.
AES_CTR_Update: Encrypts or decrypts N bytes of data using AES-128 in counter mode.

Functions

AES_CBCFrame_Final: Finalizes a context for AES-128 in CBC frame mode when no longer needed. Context must not be used after this.
AES_CBCFrame_Init: Initializes a context for AES-128 in CBC frame mode. Must be called before other AES_CBCFrame_* functions.
AES_CBCFrame_Update: Encrypts or decrypts N bytes of data using AES-128 in CBC frame mode.
AES_CBCFrame_Update2: Encrypts or decrypts 2 chunnks of data, N bytes each using AES-128 in CBC frame mode.
AES_CTR_Final: Finalizes a context for AES-128 in counter mode when no longer needed. Context must not be used after this.
AES_CTR_Init: Initializes a context for AES-128 in counter mode. Must be called before other AES_CTR_* functions.
AES_CTR_Update: Encrypts or decrypts N bytes of data using AES-128 in counter mode.

AES_CBCFrame_Final

Finalizes a context for AES-128 in CBC frame mode when no longer needed. Context must not be used after this.

void AES_CBCFrame_Final(
    AES_CBCFrame_Context *inContext );

Parameters

inContext: Context to be finalized.

AES_CBCFrame_Init

Initializes a context for AES-128 in CBC frame mode. Must be called before other AES_CBCFrame_* functions.

OSStatus AES_CBCFrame_Init( 
    AES_CBCFrame_Context *inContext, 
    const uint8_t inKey[ kAES_CBCFrame_Size ], 
    const uint8_t inIV[ kAES_CBCFrame_Size ], 
    Boolean inEncrypt );

Parameters

inContext: Context to be initialized.
inKey: 16-byte key material to be used.
inIV: 16-byte initialization vector to be used.
inEncypt: true to encrypt, false to decrypt.

Return Value

kNoErr if successful or an error code indicating failure.

AES_CBCFrame_Update

Encrypts or decrypts N bytes of data using AES-128 in CBC frame mode.

OSStatus AES_CBCFrame_Update(
    AES_CBCFrame_Context *inContext,
    const void *inSrc,
    size_t inLen,
    void *inDst );

Parameters

inContext: Context previously initialized with AES_CBCFrame_Init.
inSrc: Pointer to data to encrypt/decrypt. Must be at least inLen bytes.
inLen: Number of bytes to encrypt/decrypt.
inDst: Pointer to buffer where output data is stored. Must be at least inLen bytes. inDst may be equal to inSrc for in-place encryption/decryption, but they cannot otherwise overlap.

Return Value

kNoErr if successful or an error code indicating failure.

AES_CBCFrame_Update2

Encrypts or decrypts 2 chunnks of data, N bytes each using AES-128 in CBC frame mode.

OSStatus AES_CBCFrame_Update2( 
    AES_CBCFrame_Context *inContext, 
    const void *inSrc1, 
    size_t inLen1, 
    const void *inSrc2, 
    size_t inLen2, 
    void *inDst );

Parameters

inContext: Context previously initialized with AES_CBCFrame_Init.
inSrc1: Pointer to first chunk of data to encrypt/decrypt. Must be at least inLen1 bytes.
inLen1: Number of bytes to encrypt/decrypt from inSrc1.
inSrc2: Pointer to second chunk of data to encrypt/decrypt. Must be at least inLen2 bytes.
inLen2: Number of bytes to encrypt/decrypt from inSrc2.
inDst: Pointer to buffer where output data is stored. Must be at least inLen1 + inLen2 bytes.

Return Value

kNoErr if successful or an error code indicating failure.

AES_CTR_Final

Finalizes a context for AES-128 in counter mode when no longer needed. Context must not be used after this.

void AES_CTR_Final(
    AES_CTR_Context *inContext );

Parameters

inContext: Context to be finalized.

AES_CTR_Init

Initializes a context for AES-128 in counter mode. Must be called before other AES_CTR_* functions.

OSStatus AES_CTR_Init( 
    AES_CTR_Context *inContext, 
    const uint8_t inKey[ kAES_CTR_Size ], 
    const uint8_t inNonce[ kAES_CTR_Size ] );

Parameters

inContext: Context to be initialized.
inKey: 16-byte key material to be used.
inNonce: 16-byte nonce/IV to be used. This must be chosen such that a key/nonce pair is never used twice.

Return Value

kNoErr if successful or an error code indicating failure.

AES_CTR_Update

Encrypts or decrypts N bytes of data using AES-128 in counter mode.

OSStatus AES_CTR_Update(
    AES_CTR_Context *inContext,
    const void *inSrc,
    size_t inLen,
    void *inDst );

Parameters

inContext: Context previously initialized with AES_CTR_Init.
inSrc: Pointer to data to encrypt/decrypt. Must be at least inLen bytes.
inLen: Number of bytes to encrypt/decrypt.
inDst: Pointer to buffer where output data is stored. Must be at least inLen bytes. inDst may be equal to inSrc for in-place encryption/decryption, but they cannot otherwise overlap.

Return Value

kNoErr if successful or an error code indicating failure.

Last Updated: Friday, August 29, 2014