An AES (Rijndael) Implementation in C/C++ (as specified in FIPS-197)
====================================================================

Changes in this Version (16/04/2007)
====================================

These changes remove errors in the VC++ build files and add some 
improvements in file naming consitency and portability. There are
no changes to overcome reported bugs in the code.

1. gen_tabs() has been renamed to aes_init() to better decribe its
   function to those not familiar with AES internals.

2. via_ace.h has been renamed to aes_via_ace.h.

3. Minor changes have been made to aestab.h and aestab.c to enable
   all the code to be compiled in either C or C++.
   
4. The code for detecting memory alignment in aesmdoes.c has been
   simplified and a new routine has been added:
   
       aes_test_alignment_detection()
   
   to check that the aligment test is likely to be correct.

5. The addition of support for Structured Exception Handling (SEH) 
   to YASM (well done Peter and Michael!) has allowed the AMD64 
   x64 assembler code to be changed to comply with SEH requriements.
       
6. Corrections to build files (for win32 debug build).

Overview
========

This code implements AES for both 32 and 64 bit systems with optional
assembler support for x86 and AMD64/EM64T (but optimised for AMD64).

The basic AES source code files are as follows:

aes.h           the header file needed to use AES in C
aescpp.h        the header file required with to use AES in C++
aesopt.h        the header file for setting options (and some common code)
aestab.h        the header file for the AES table declaration
aescrypt.c      the main C source code file for encryption and decryption
aeskey.c        the main C source code file for the key schedule
aestab.c        the main file for the AES tables
brg_types.h     a header defining some standard types and DLL defines
brg_endian.h    a header containing code to detect or define endianness
aes_x86_v1.asm  x86 assembler (YASM) alternative to aescrypt.c using
                large tables
aes_x86_v2.asm  x86 assembler (YASM) alternative to aescrypt.c using
                compressed tables
aes_amd64.asm   AMD64 assembler (YASM) alternative to aescrypt.c using
                compressed tables

In addition AES modes are implemented in the files:

aes_modes.c     AES modes with optional support for VIA ACE detection and use
aes_via_ace.h   the header file for VIA ACE support

Other associated files for testing and support are:

aesaux.h        header for auxilliary routines for testsing
aesaux.c        auxilliary routines for testsingt
aestst.h        header file for setting the testing environment
rdtsc.h         a header file that provides access to the Time Stamp Counter
aestst.c        a simple test program for quick tests of the AES code
aesgav.c        a program to generate and verify the test vector files
aesrav.c        a program to verify output against the test vector files
aestmr.c        a program to time the code on x86 systems
modetest.c      a program to test the AES modes support
vbxam.doc       a demonstration of AES DLL use from Visual Basic in Microsoft Word
vb.txt          Visual Basic code from the above example (win32 only)
aesxam.c        an example of AES use
tablegen.c      a program to generate a simplified 'aestab.c' file for
                use with compilers that find aestab.c too complex
yasm.rules      the YASM build rules file for Microsoft Visual Studio 2005
via_ace.txt     describes support for the VIA ACE cryptography engine
aes.txt         this file

Building The AES Libraries
--------------------------

A. Versions
-----------

The code can be used to build static and dynamic libraries, each in five
versions:

    C           uses C source code only
    ASM_X86_V1C large table x86 assembler code for encrypt/decrypt
    ASM_X86_V2  compressed table x86 assembler for encrypt/decrypt and keying
    ASM_X86_V2C compressed table x86 assembler code for encrypt/decrypt
    ASM_AMD64   compressed table x86 assembler code for encrypt/decrypt

The C version can be compiled for Win32 or x64, the x86 assembler versions
are for Win32 only and the AMD64 version for x64 only.

B. Types
--------

The code makes use of types defined as uint_<nn>t where <nn> is the length
of the type, for example, the unsigned 32-bit type is 'uint_32t'.  These are
NOT the same as the fixed width integer types in C99, inttypes.h and stdint.h
since several attempts to use these types have shown that support for them is
still highly variable.  But a regular expression search and replace in VC++
with search on 'uint_{:z}t' and a replace with 'uint\1_t' will convert these
types to C99 types (there should be similar search/replace facilities on other
systems).

C. YASM
-------

If you wish to use the x86 assembler files you will also need the YASM open
source x86 assembler (r1331 or later) for Windows which can be obtained from:

  http://www.tortall.net/projects/yasm/

This assembler should be placed in the bin directory used by VC++, which, for
Visual Stduio 2005, is typically:

 C:\Program Files (x86)\Microsoft Visual Studio 8\VC\bin

You will also need to move the yasm.rules file from this distribution into
the directory where Visual Studio 2005 expects to find it, which is typically:

 C:\Program Files (x86)\Microsoft Visual Studio 8\VC\VCProjectDefaults

Alternatively you can configure the path for rules files within Visual Studio.

D. Configuration
----------------

The following configurations are available as projects for Visual Studio 2005
but the following descriptions should allow them to be built in other x86
environments:

    lib_generic_c       Win32 and x64
        headers:        aes.h, aesopt.h, aestab.h, brg_endian.h, tdefs,h
        C source:       aescrypt.c, aeskey.c, aestab.c, aes_modes.c
        defines
    dll_generic_c       Win32 and x64
        headers:        aes.h, aesopt.h, aestab.h, brg_endian.h, tdefs,h
        C source:       aescrypt.c, aeskey.c, aestab.c, aes_modes.c
        defines         DLL_EXPORT

    lib_asm_x86_v1c     Win32
        headers:        aes.h, aesopt.h, aestab.h, brg_endian.h, tdefs,h
        C source:       aeskey.c, aestab.c, aes_modes.c
        x86 assembler:  aes_x86_v1.asm
        defines         ASM_X86_V1C (set for C and assembler files)
    dll_asm_x86_v1c     Win32
        headers:        aes.h, aesopt.h, aestab.h, brg_endian.h, tdefs,h
        C source:       aeskey.c, aestab.c, aes_modes.c
        x86 assembler:  aes_x86_v1.asm
        defines         DLL_EXPORT, ASM_X86_V1C (set for C and assembler files)

    lib_asm_x86_v2c     Win32
        headers:        aes.h, aesopt.h, aestab.h, brg_endian.h, tdefs,h
        C source:       aeskey.c, aestab.c, aes_modes.c
        x86 assembler:  aes_x86_v2.asm
        defines         ASM_X86_V2C (set for C and assembler files)
    dll_asm_x86_v2c     Win32
        headers:        aes.h, aesopt.h, aestab.h, brg_endian.h, tdefs,h
        C source:       aeskey.c, aestab.c, aes_modes.c
        x86 assembler:  aes_x86_v1.asm
        defines         DLL_EXPORT, ASM_X86_V2C (set for C and assembler files)

    lib_asm_x86_v2      Win32
        headers:        aes.h, aesopt.h, aestab.h, brg_endian.h, tdefs,h
        C source:       aes_modes.c
        x86 assembler:  aes_x86_v1.asm
        defines         ASM_X86_V2 (set for C and assembler files)
    dll_asm_x86_v2      Win32
        headers:        aes.h, aesopt.h, aestab.h, brg_endian.h, tdefs,h
        C source:       aes_modes.c
        x86 assembler:  aes_x86_v1.asm
        defines         DLL_EXPORT, ASM_AMD64_C (set for C and assembler files)

    lib_asm_amd64_c     x64
        headers:        aes.h, aesopt.h, aestab.h, brg_endian.h, tdefs,h
        C source:       aes_modes.c
        x86 assembler:  aes_amd64.asm
        defines         ASM_X86_V2 (set for C and assembler files)
    dll_asm_amd64_c     x64
        headers:        aes.h, aesopt.h, aestab.h, brg_endian.h, tdefs,h
        C source:       aes_modes.c
        x86 assembler:  aes_amd64.asm
        defines         DLL_EXPORT, ASM_AMD64_C (set for C and assembler files)

Notes:

ASM_X86_V1C is defined if using the version 1 assembler code (aescrypt1.asm).
            The defines in the assember file must match those in aes.h and
            aesopt.h).  Also remember to include/exclude the right assembler
            and C files in the build to avoid undefined or multiply defined
            symbols - include aescrypt1.asm and exclude aescrypt.c and
            aescrypt2.asm.

ASM_X86_V2  is defined if using the version 2 assembler code (aescrypt2.asm).
            This version provides a full, self contained assembler version
            and does not use any C source code files except for the mutiple
            block encryption modes that are provided by aes_modes.c. The define
            ASM_X86_V2 must be set on the YASM command line (or in aescrypt2.asm)
            to use this version and all C files except aec_modes.c and. for the
            DLL build, aestab.c must be excluded from the build.

ASM_X86_V2C is defined when using the version 2 assembler code (aescrypt2.asm)
            with faster key scheduling provided by the in C code (the options in
            the assember file must match those in aes.h and aesopt.h).  In this
            case aeskey.c and aestab.c are needed with aescrypt2.asm and the
            define ASM_X86_V2C must be set for both the C files and for
            asecrypt2.asm command lines (or in aesopt.h and aescrypt2.asm).
            Include aescrypt2.asm aeskey.c and aestab.c, exclude aescrypt.c for
            this option.

ASM_AMD64_C is defined when using the AMD64 assembly code because the C key
            scheduling is sued in this case.

DLL_EXPORT  must be defined to generate the DLL version of the code and
            to run tests on it

DLL_IMPORT  must be defined to use the DLL version of the code in an
            application program

Directories the paths for the various directories for test vector input and
            output have to be set in aestst.h

VIA ACE     see the via_ace.txt for this item

Static      The static libraries are named:
Libraries
                aes_lib_generic_c.lib
                aes_lib_asm_x86_v1c.lib
                aes_lib_asm_x86_v2.lib
                aes_lib_asm_x86_v2c.lib
                aes_lib_asm_amd64_c.lib

            and placed in one of the the directories:

                lib\win32\release\
                lib\win32\debug\
                lib\x64\release\
                lib\x64\debug\

            in the aes root directory depending on the platform(win32 or
            x64) and the build (release or debug). After any of these is
            built it is then copied into aes.lib, which is the library
            that is subsequently used for testing. Hence testing is for
            the last static library built.

Dynamic     The static libraries are named:
Libraries
                aes_lib_generic_c.dll
                aes_lib_asm_x86_v1c.dll
                aes_lib_asm_x86_v2.dll
                aes_lib_asm_x86_v2c.dll
                aes_lib_asm_amd64_c.dll

            and placed in one of the the directories:

                dll\win32\release\
                dll\win32\debug\
                dll\x64\release\
                dll\x64\debug\

            in the aes root directory depending on the platform(win32 or
            x64) and the build (release or debug).  Each DLL library:

                aes_<ext>.dll

            has three associated files: