The projects test_dll and time_dll are used to test and time the last DLL
built.  These use the files:

    test_dll:       Win32 (x64 for the C and AMD64 versions)
        headers:    aes.h, aescpp.h, brg_types.h, aesaux.h and aestst.h
        C source:   aesaux.c, aesrav.c
        defines:    DLL_IMPORT

    time_dll:       Win32 (x64 for the C and AMD64 versions)
        headers:    aes.h, aescpp.h, brg_types.h, aesaux.h aestst.h and rdtsc.h
        C source:   aesaux.c, aestmr.c
        defines:    DLL_IMPORT

and link to the DLL using explicit linking. However, if the lib file associated
with the DLL is linked into this project and the symbol DYNAMIC_LINK in aestst.h
is left undefined, then implicit linking will be used

The projects test_lib and time_lib are used to test and time the last static LIB
built. They use the files:

    test_lib:       Win32 (x64 for the C and AMD64 versions)
        headers:    aes.h, aescpp.h, brg_types.h, aesaux.h and aestst.h
        C source:   aesaux.c, aesrav.c
        defines:

    time_lib:       Win32 (x64 for the C and AMD64 versions)
        headers:    aes.h, aescpp.h, brg_types.h, aesaux.h, aestst.h and rdtsc.h
        C source:   aesaux.c, aestmr.c
        defines:

and link to the last static library built.

The above test take command line arguments that determine which test are run
as follows:

    test_lib /t:[knec] /k:[468]
    test_dll /t:[knec] /k:[468]

where the symbols in square brackets can be used in any combination (without
the brackets) and have the following meanings:

        /t:[knec]   selects which tests are used
        /k:[468]    selects the key lengths used
        /c          compares output with reference (see later)

        k: generate ECB Known Answer Test files
        n: generate ECB Known Answer Test files (new)
        e: generate ECB Monte Carlo Test files
        c: generate CBC Monte Carlo Test files

and the characters giving the lengths are digits representing the lengths in
32-bit units.\n\n");

The project test_modes tests the AES modes.  It uses the files:

    test_modes:     Win32 or x64
        headers:    aes.h, aescpp.h, brg_types.h, aesaux,h and aestst.h
        C source:   aesaux.c, modetest.c
        defines:    none for static library test, DLL_IMPORT for DLL test

which again links to the last library built.

F. Other Applications
---------------------

These are:

    gen_tests       builds the test_vector files. The commad line is
                        gen_tests /t:knec /k:468 /c
                    as described earlier

    gen_tables      builds a simple version of aes_tab.c (in aestab2.c)
                    for compilers that cannot handle the normal version
    aes_example     provides an example of AES use

These applications are linked to the last static library built or, if
DLL_IMPORT is defined during compilation, to the last DLL built.

G. Use of the VIA ACE Cryptography Engine
-----------------------------------------

The use of the code with the VIA ACE cryptography engine in described in the
file via_ace.txt. In outline aes_modes.c is used and USE_VIA_ACE_IF_PRESENT
is defined either in section 2 of aesopt.h or as a compilation option in Visual
Studio. If in addition ASSUME_VIA_ACE_PRESENT is also defined then all normal
AES code will be removed if not needed to support VIA ACE use.  If VIA ACE
support is needed and AES assembler is being used only the ASM_X86_V1C and
ASM_X86_V2C versions should be used since ASM_X86_V2 and ASM_AMD64 do not
support the VIA ACE engine.

H. The AES Test Vector Files
----------------------------

These files fall in the following groups (where <nn> is a two digit
number):

1. ecbvk<nn>.txt  ECB vectors with variable key
2. ecbvt<nn>.txt  ECB vectors with variable text
3. ecbnk<nn>.txt  new ECB vectors with variable key
4. ecbnt<nn>.txt  new ECB vectors with variable text
5. ecbme<nn>.txt  ECB monte carlo encryption test vectors
6. ecbmd<nn>.txt  ECB monte carlo decryption test vectors
7. cbcme<nn>.txt  CBC monte carlo encryption test vectors
8. cbcmd<nn>.txt  CBC monte carlo decryption test vectors

The first digit of the numeric suffix on the filename gives the block size
in 32 bit units and the second numeric digit gives the key size. For example,
the file ecbvk44.txt provides the test vectors for ECB encryption with a 128
bit block size and a 128 bit key size. The test routines expect to find these
files in the 'testvals' subdirectory within the aes root directory. The
'outvals' subdirectory is used for outputs that are compared with the files
in 'testvals'. Note that the monte carlo test vectors are the result of
applying AES iteratively 10000 times, not just once.

I. The Basic AES Calling Interface
----------------------------------

The basic AES code keeps its state in a context, there being different 
contexts for encryption and decryption:

    aes_encrypt_ctx
    aes_decrypt_ctx
    
The AES encryption key is set by one of the calls:
 
    aes_encrypt_key128(const unsigned char *key, aes_encrypt_ctx cx[1])
    aes_encrypt_key192(const unsigned char *key, aes_encrypt_ctx cx[1])
    aes_encrypt_key256(const unsigned char *key, aes_encrypt_ctx cx[1])

or by:

    aes_encrypt_key(const unsigned char *key, int key_len, 
                                                aes_encrypt_ctx cx[1])

where the key length is set by 'key_len', which can be the length in bits 
or bytes.  

Similarly, the AES decryption key is set by one of:

    aes_decrypt_key128(const unsigned char *key, aes_decrypt_ctx cx[1])
    aes_decrypt_key192(const unsigned char *key, aes_decrypt_ctx cx[1])
    aes_decrypt_key256(const unsigned char *key, aes_decrypt_ctx cx[1])

or by:

    aes_decrypt_key(const unsigned char *key, int key_len, 
                                                aes_decrypt_ctx cx[1])
 
Encryption and decryption for a single 16 byte block is then achieved using:

    aes_encrypt(const unsigned char *in, unsigned char *out, 
                                            const aes_encrypt_ctx cx[1])
    aes_decrypt(const unsigned char *in, unsigned char *out, 
                                            const aes_decrypt_ctx cx[1])
                                            
If the define AES_ERR_CHK is set when AES is compiled, the above subroutines 
will return a value of EXIT_SUCCESS or EXIT_FAILURE depending on whether the
operation succeeded or failed.
 
J. The Calling Interface for the AES Modes
------------------------------------------

The subroutines for the AES modes, ECB, CBC, CFB, OFB and CTR, each process
blocks of variable length and can also be called several times to complete 
single mode operations incrementally on long messages (or those messages,
not all of which are available at the same time).  The calls:

    aes_ecb_encrypt(const unsigned char *ibuf, unsigned char *obuf,
                    int len, const aes_encrypt_ctx cx[1])

    aes_ecb_decrypt(const unsigned char *ibuf, unsigned char *obuf,
                    int len, const aes_decrypt_ctx cx[1])

for ECB operations and those for CBC:

    aes_cbc_encrypt(const unsigned char *ibuf, unsigned char *obuf,
                    int len, unsigned char *iv, const aes_encrypt_ctx cx[1])

    aes_cbc_decrypt(const unsigned char *ibuf, unsigned char *obuf,
                    int len, unsigned char *iv, const aes_decrypt_ctx cx[1])
 
can only process blocks whose lengths are multiples of 16 bytes but the calls 
for CFB, OFB and CTR mode operations:

    aes_cfb_encrypt(const unsigned char *ibuf, unsigned char *obuf,
                    int len, unsigned char *iv, aes_encrypt_ctx cx[1])

    aes_cfb_decrypt(const unsigned char *ibuf, unsigned char *obuf,
                    int len, unsigned char *iv, aes_encrypt_ctx cx[1])

    aes_ofb_encrypt(const unsigned char *ibuf, unsigned char *obuf,
                    int len, unsigned char *iv, aes_encrypt_ctx cx[1])

    aes_ofb_decrypt(const unsigned char *ibuf, unsigned char *obuf,
                    int len, unsigned char *iv, aes_encrypt_ctx cx[1])

    aes_ctr_encrypt(const unsigned char *ibuf, unsigned char *obuf,
            int len, unsigned char *cbuf, cbuf_inc ctr_inc, aes_encrypt_ctx cx[1])

    aes_ctr_decrypt(const unsigned char *ibuf, unsigned char *obuf,
            int len, unsigned char *cbuf, cbuf_inc ctr_inc, aes_encrypt_ctx cx[1])

can process blocks of any length.  Note also that CFB, OFB and CTR mode calls only
use AES encryption contexts even during decryption operations.

The calls CTR mode operations use a buffer (cbuf) which holds the counter value
together with a function parameter:

    void cbuf_inc(unsigned char *cbuf);

that is ued to update the counter value after each 16 byte AES operation. The 
counter buffer is updated appropriately to allow for incremental operations.

Please note the following IMPORTANT points about the AES mode subroutines:

    1. All modes are reset when a new AES key is set.
    
    2. Incremental calls to the different modes cannot 
       be mixed. If a change of mode is needed a new 
       key must be set or a reset must be issued (see 
       below).
       
    3. For modes with IVs, the IV value is an inpu AND
       an ouput since it is updated after each call to 
       the value needed for any subsequent incremental
       call(s). If the mode is reset, the IV hence has
       to be set (or reset) as well.
       
    4. ECB operations must be multiples of 16 bytes
       but do not need to be reset for new operations.
       
    5. CBC operations must also be multiples of 16 
       bytes and are reset for a new operation by 
       setting the IV.
       
    6. CFB, OFB and CTR mode must be reset by setting 
       a new IV value AND by calling:
       
           aes_mode_reset(aes_encrypt_ctx cx[1])
           
       For CTR mode the cbuf value also has to be reset.
       
    7. CFB, OFB and CTR modes only use AES encryption 
       operations and contexts and do not need AES
       decrytpion operations.
       
    8. AES keys remain valid across resets and changes
       of mode (but encryption and decryption keys must 
       both be set if they are needed).  
       
   Brian Gladman  01/09/2006