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_CcmDecryptAndVerify</title> 8<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css"> 9</head> 10<body> 11<h1 align="left">AES_CcmDecryptAndVerify <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_CcmDecryptAndVerify( const <a href="AESNonce.html">AESNonce</a>* pNonce, 26 const void* src, 27 u32 srcASize, 28 u32 srcCSize, 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 decryption.</TD> 42 </TR> 43 <TR> 44<TH>src</TH> 45<TD>Pointer to the buffer that holds the plaintext (which was subject to MAC operations but not encrypted), the ciphertext, and the MAC. 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 plaintext that was subject to MAC operations but was not 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>srcCSize</TH> 53<TD>Ciphertext size. 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 plaintext. Must be 4-byte aligned. In addition, it must point to a location in main memory. An area of size <span class="argument">srcCSize</span> bytes is required.</TD> 62 </TR> 63 <TR> 64<TH>callback</TH> 65<TD>Pointer to the callback function to call when decryption 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 decryption and signature verification process in CCM mode. 80</p> 81<p> 82The decryption and signature verification 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 verify the signature for begins at <span class="argument">src</span> and will be of size <span class="argument">srcASize</span> + <span class="argument">srcCSize</span>. The data to decrypt begins at <span class="argument">src</span> + <span class="argument">srcASize</span> and will be of size <span class="argument">srcCSize</span>. The MAC used to verify the signature must be stored in an area of byte length <span class="argument">macLength</span> that begins at <span class="argument">src</span> + <span class="argument">srcASize</span> + <span class="argument">srcCSize</span>. The decrypted result will be written to a region starting at <span class="argument">dst</span> whose size is <span class="argument">srcCSize</span> bytes. When the decryption process completes, <span class="argument">callback</span> is called, using the decrypted 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-decrypt.png"> 86</p> 87<p> 88The signature verification result will be passed as the first argument to <span class="argument">callback</span>. If <code>AES_RESULT_SUCCESS</code>, the decryption completed successfully, and the signature verification also succeeded. If <code>AES_RESULT_VERIFICATION_FAILED</code>, the decryption completed successfully, but the signature verification has failed. Any other values indicate that the decryption failed. 89</p> 90<p> 91This 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. 92</p> 93<p> 94The decryption key must be set beforehand using <code><a href="AES_SetKey.html">AES_SetKey()</a></code>. 95</p> 96<p> 97The 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. 98</p> 99<p> 100In 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. 101</p> 102<h2>See Also</h2> 103<p><CODE><A href="AES_CcmEncryptAndSign.html">AES_CcmEncryptAndSign</A></CODE></p> 104<H2>Revision History</H2> 105<P> 1062008/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. 107</P> 108<hr><p>CONFIDENTIAL</p></body> 109</html> 110
