aes-modes-src-07-10-08.zip_in

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_GOOD 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_GOOD, 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_GOOD 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 enc