aes.ae-modes.txt

加密认证联合模式的源代码

The Use of AES Combined Encryption and Authentication Modes
===========================================================

This file describes the use of the routines that implement the AES
combined encryption and autheication modes.  The modes implemented
are CCM, GCM, EAX and CWC although the latter is no longer being
actively supported.  In what follows 'xxx' wil stand for one of the
strings 'ccm', 'gcm', 'eax' or 'cwc'

A context for mode operation is declared in one of the two styles:

    xxx_ctx ctx[1];		-- used in routine calls as 'ctx'
    xxx_ctx    ctx;		-- used in routine calls as '&ctx'

All routinjes retrun a result code in the type ret_type defined in their
respective header files.  The main return codes are:

    RETURN_WARN     a possible error condition
    RETURN_OK       normal error free retrun value
    RETURN_ERROR    an error has occurred

CCM offers more detailed codes as given in its header file.

1. INITIALISATION, KEYING AND COMPLETION

The first routine:

ret_type xxx_init_and_key(              /* initialise mode and set key  */
            const unsigned char key[],  /* the key value                */
            unsigned long key_len,      /* and its length in bytes      */
            xxx_ctx ctx[1]);            /* the mode context             */

initialises the mode and sets up the AES encryption key that will be used.
This routine does not need to be called for each new message but only once
when a new context is declared.

The call:

ret_type xxx_end(                       /* clean up and end operation   */
            xxx_ctx ctx[1]);            /* the mode context             */

is used to end a sequence of message encryption or decryption operations.
It does not need to be called between individual message operations.

2. COMPLETE MESSAGE OPERATIONS

The call:

ret_type xxx_encrypt_message(           /* encrypt an entire message    */
            const unsigned char iv[],   /* the initialisation vector    */
            unsigned long iv_len,       /* and its length in bytes      */
            const unsigned char hdr[],  /* the header buffer            */
            unsigned long hdr_len,      /* and its length in bytes      */
            unsigned char msg[],        /* the message buffer           */
            unsigned long msg_len,      /* and its length in bytes      */
            unsigned char tag[],        /* the buffer for the tag       */
            unsigned long tag_len,      /* and its length in bytes      */
            xxx_ctx ctx[1]);            /* the mode context             */

is used to encrypt and authenticate an entire message and its header in
a single call. The encryption occurs 'in place' (the input and output
buffers are the same) and the authentication tag is output in tag[];

The call:

ret_type xxx_decrypt_message(           /* decrypt an entire message    */
            const unsigned char iv[],   /* the initialisation vector    */
            unsigned long iv_len,       /* and its length in bytes      */
            const unsigned char hdr[],  /* the header buffer            */
            unsigned long  hdr_len,     /* and its length in bytes      */
            unsigned char msg[],        /* the message buffer           */
            unsigned long msg_len,      /* and its length in bytes      */
            const unsigned char tag[],  /* the buffer for the tag       */
            unsigned long tag_len,      /* and its length in bytes      */
            xxx_ctx ctx[1]);            /* the mode context             */

is used to decrypt and verify an entire mesage and its header in a
single call. The decryption occurs 'in place' (the input and output
buffers are the same). After decryption the authentication tag is
computed and compared with that input in tag[]; if this matches the
return value is RETURN_OK, if not it is RETURN_ERROR.

3. INCREMENTAL HEADER AND MESSAGE PROCESSING

The following five calls are used for messages that are too long to be
processed in one step.

The call:

ret_type xxx_init_message(              /* initialise a new message     */
            const unsigned char iv[],   /* the initialisation vector    */
            unsigned long iv_len,       /* the nonce length             */
            length_t hdr_len,           /* the associated data length   */
            length_t msg_len,           /* message data length          */
            unsigned long tag_len,      /* authentication field length  */
            xxx_ctx ctx[1]);            /* the mode context             */

is used to initialise the mode for a new message operation.

The call:

ret_type xxx_auth_header(               /* authenticate message header  */
            const unsigned char hdr[],  /* the header buffer            */
            unsigned long hdr_len,      /* and its length in bytes      */
            xxx_ctx ctx[1]);            /* the mode context             */

is used to authenticate the header data for the message. It can be called
as many times as is necessary for long headers or headers that have more
than one piece.

The call:

ret_type xxx_encrypt(                   /* encrypt & authenticate data  */
            unsigned char data[],       /* the data buffer              */
            unsigned long data_len,     /* and its length in bytes      */
            xxx_ctx ctx[1]);            /* the mode context             */

is used to encrypt and authenticate message data. It can be called as
many times as is necessary for long messages or messages that have
more than one piece.

ret_type xxx_decrypt(                   /* authenticate & decrypt data  */
            unsigned char data[],       /* the data buffer              */
            unsigned long data_len,     /* and its length in bytes      */
            xxx_ctx ctx[1]);            /* the mode context             */

is used to decrypt and verify the authenticity of message data. It can be
called as many times as is necessary for long messages or messages that
have more than one piece.

The call:

ret_type xxx_compute_tag(               /* compute authentication tag   */
            unsigned char tag[],        /* the buffer for the tag       */
            unsigned long tag_len,      /* and its length in bytes      */
            xxx_ctx ctx[1]);            /* the mode context             */

is used to compute the authentication tag for a message after the above
calls have been completed.  It returns RETURN_OK if the total lengths of
the data processed by the previous encryption and authentication calls
are the same, RETURN_WARN if there has been authentication but no
encryption or decryption operations, and RETURN_ERROR otherwise.

4. SEPARATE INCREMENTAL AUTHENTICATION, ENCRYPTION AND DECRYPTION

The use of the following calls should be avoided if at all possible 
because their use requires a very good understanding of the way 
encryption modes work and the way in which this code implements 
them in order to use it correctly.

In CCM mode plaintext data is authenticated so authentciation with 
ccm_auth_data() preceeds calls to ccm_crypt_data() on encryption 
and follows such calls on decryption.  In contrast, GCM and EAX modes 
authenticate ciphertext so calls to xxx_auth_data() follow those to 
xxx_crypt_data() on encryption and preceed them on decryption.  For GCM 
and EAX it is hence possible to authenticate the ciphertext before 
decrypting it whereas this is not possible for CCM mode.

If these calls are used it is up to the user to ensure that these 
routines are called in the correct order and that the correct data is 
passed to them.

When xxx_compute_tag is called it is assumed that an error has occurred 
if encryption (decryption) and authentication have taken place but the 
total lengths of the message data authenticated and encrypted (decrypted) 
are not the same. If authentication has taken place but there has been no 
corresponding encryption or decryption (that is, none at all) only a 
warning is issued since this might possibly be intentional.

In practice this warning should be treated as an error on encryption for 
both GCM and EAX since authentication follows encryption and a length 
mismatch implies either that some ciphertext was not authenticated or 
that some of the authenticated data was not ciphertext.  For CCM, since 
it is possible to authenticate the plaintext prior to encryption, this
warning message might not indicate an error although this is most likely
to be the case. For GCM and EAX modes this warning message might not 
indicate an error during decryption since it is possible with these modes 
to authenticate ciphertext without necessarily decrypting it.  

ret_type xxx_auth_data(                 /* authenticate plaintext data  */
            const unsigned char data[], /* the data buffer              */
            unsigned long data_len,     /* and its length in bytes      */
            xxx_ctx ctx[1]);            /* the mode context             */

ret_type xxx_crypt_data(                /* encrypt or decrypt data      */
            unsigned char data[],       /* the data buffer              */
            unsigned long data_len,     /* and its length in bytes      */
            xxx_ctx ctx[1]);            /* the mode context             */