1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html> 3<head> 4<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 5<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 7.0.0.0 for Windows"> 6<META http-equiv="Content-Style-Type" content="text/css"> 7<title>AES_CcmEncryptAndSign</title> 8<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css"> 9</head> 10<body> 11<h1 align="left">AES_CcmEncryptAndSign <IMG src="../../image/TWL.gif" width="23" height="12" border="0" align="middle"></h1> 12<h2>Syntax</h2> 13<dl> 14 <dd> 15 <pre><CODE>#include <twl/aes.h> 16 17#define AES_BLOCK_SIZE 16 // 128 bit 18 19#define AES_ADATA_BLOCK_NUM_MAX 0xFFFF 20#define AES_PDATA_BLOCK_NUM_MAX 0xFFFF 21 22#define AES_ADATA_SIZE_MAX (AES_BLOCK_SIZE * AES_ADATA_BLOCK_NUM_MAX) 23#define AES_PDATA_SIZE_MAX (AES_BLOCK_SIZE * AES_PDATA_BLOCK_NUM_MAX) 24 25<a href="AESResult.html">AESResult</a> AES_CcmEncryptAndSign( const <a href="AESNonce.html">AESNonce</a>* pNonce, 26 const void* src, 27 u32 srcASize, 28 u32 srcPSize, 29 <a href="AESMacLength.html">AESMacLength</a> macLength, 30 void* dst, 31 <a href="AESCallback.html">AESCallback</a> callback, 32 void* arg ); 33</CODE></pre> 34</dd> 35</dl> 36<h2>Arguments</h2> 37<TABLE border="1" width="100%" class="arguments"> 38 <TBODY> 39 <TR> 40<TH>pNonce</TH> 41<TD>The nonce to use for encryption.</TD> 42 </TR> 43 <TR> 44<TH>src</TH> 45<TD>Pointer to the plaintext. Must be 4-byte aligned. In addition, it must point to a location in main memory.</TD> 46 </TR> 47 <TR> 48<TH>srcASize</TH> 49<TD>Size of the plaintext that will be subject to MAC operations but will not be encrypted. This must be between 0 and <code>AES_ADATA_SIZE_MAX</code>, inclusive, and must also be a multiple of <code>AES_BLOCK_SIZE</code> (=16).</TD> 50 </TR> 51 <TR> 52<TH>srcPSize</TH> 53<TD>Size of the plaintext that will be subject to MAC operations and encrypted. This must be between 0 and <code>AES_PDATA_SIZE_MAX</code>, inclusive.</TD> 54 </TR> 55 <TR> 56<TH>macLength</TH> 57<TD>Size of MAC.</TD> 58 </TR> 59 <TR> 60<TH>dst</TH> 61<TD>Pointer to the buffer that will store the ciphertext and MAC. Must be 4-byte aligned. In addition, it must point to a location in main memory. An area of byte length <span class="argument">srcPSize</span> + <span class="argument">macLength</span> is required.</TD> 62 </TR> 63 <TR> 64<TH>callback</TH> 65<TD>Pointer to the callback function to call when encryption completes. It is possible to specify <CODE>NULL</CODE>.</TD> 66 </TR> 67 <TR> 68<TH>arg</TH> 69<TD>User-defined parameter that is passed to the above callback function. Can be any value, including <CODE>NULL</CODE>.</TD> 70 </TR> 71 </TBODY> 72</TABLE> 73<h2>Return Values</h2> 74<p> 75Returns <code>AES_RESULT_SUCCESS</code> if the AES operation was started successfully. Any other return values indicate an error. 76</p> 77<H2>Description</H2> 78<P> 79Starts the AES encryption and signature process in CCM mode. 80</p> 81<p> 82The encryption and signature will be done using the key that was set with <code><a href="AES_SetKey.html">AES_SetKey()</a></code> and the nonce that was specified in <span class="argument">pNonce</span>. The data to sign begins at <span class="argument">src</span> and will be of size <span class="argument">srcASize</span> + <span class="argument">srcPSize</span> bytes. The data to encrypt begins at <span class="argument">src</span> + <span class="argument">srcASize</span> and will be of size <span class="argument">srcPSize</span> bytes. The encrypted result will be written to a <span class="argument">srcPSize</span>-byte area starting at <span class="argument">dst</span>, and a MAC whose size is indicated by <span class="argument">macLength</span> will be written just after that. When the encryption process completes, <span class="argument">callback</span> will be called, using the encrypted result and <span class="argument">arg</span> as arguments. <span class="argument">callback</span> is called from the interrupt handler, so note that it may be called even when interrupts are disabled. Conversely, also note that <span class="argument">callback</span> is not called when interrupts are disabled. 83</p> 84<p> 85For data layout in memory, refer to the following figure. <br> <br> <img src="ccm-encrypt.png"> 86</p> 87<p> 88This function returns control immediately once it has started the processing. If processing starts without a problem, this function will return <code>AES_RESULT_SUCCESS</code>, but if an error occurs during subsequent processing, it will call <span class="argument">callback</span> with the error value and <span class="argument">arg</span> as arguments. Note that error notification done using this callback will be started from the interrupt handler, so depending on the situation, it's possible that the callback could deliver an error notification before control returns from the function. 89</p> 90<p> 91The encryption key must be set beforehand using <code><a href="AES_SetKey.html">AES_SetKey()</a></code>. 92</p> 93<p> 94The same key and nonce must be used for encryption and decryption. The key must not be leaked, but it isn't a problem if the nonce gets leaked. However, a different value must be used for the nonce each time this function is called. 95</p> 96<p> 97In general, the Adata size will be placed immediately after the CCM header in CCM mode, and the MAC will be calculated assuming that the Adata itself continues after the Adata size. This function, however, calculates the MAC as if the Adata is placed immediately after the CCM header. If you need the Adata size, you must include it in the Adata in advance. 98</p> 99<h2>See Also</h2> 100<p><CODE><A href="AES_CcmDecryptAndVerify.html">AES_CcmDecryptAndVerify</A></CODE></p> 101<H2>Revision History</H2> 102<P> 1032008/09/03 Added a note that the Adata size is not used when calculating the MAC.<br>2008/07/11 Added <CODE>AES_ADATA_SIZE_MAX</CODE> and <CODE>PDATA_SIZE_MAX</CODE>. <br>2007/12/25 Initial version. 104</P> 105<hr><p>CONFIDENTIAL</p></body> 106</html> 107
