1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
3
4<head>
5<META http-equiv="Content-Type" content="text/html; charset=windows-1252">
6<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 7.0.0.0 for Windows">
7<META http-equiv="Content-Style-Type" content="text/css">
8<title>AES_Ctr</title>
9<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css">
10</head>
11
12<body>
13
14<h1 align="left">AES_Ctr* <IMG src="../../image/TWL.gif" width="23" height="12" border="0" align="middle"></h1>
15<h2>Syntax</h2>
16
17<dl>
18  <dd>
19  <pre><CODE>#include &lt;twl/aes.h&gt;
20
21<a href="AESResult.html">AESResult</a> AES_Ctr( const <a href="AESCounter.html">AESCounter</a>*   pCounter,
22                   const void*         src,
23                   u32                 srcSize
24                   void*               dst,
25                   <a href="AESCallback.html">AESCallback</a>         callback,
26                   void*               arg );
27
28<a href="AESResult.html">AESResult</a> AES_CtrEncrypt( const <a href="AESCounter.html">AESCounter</a>*   pCounter,
29                          const void*         src,
30                          u32                 srcSize
31                          void*               dst,
32                          <a href="AESCallback.html">AESCallback</a>         callback,
33                          void*               arg );
34<a href="AESResult.html">AESResult</a> AES_CtrDecrypt( const <a href="AESCounter.html">AESCounter</a>*   pCounter,
35                          const void*         src,
36                          u32                 srcSize
37                          void*               dst,
38                          <a href="AESCallback.html">AESCallback</a>         callback,
39                          void*               arg );
40</CODE></pre>
41</dd>
42</dl>
43
44<h2>Arguments</h2>
45<TABLE border="1" width="100%" class="arguments">
46  <TBODY>
47    <TR>
48<TH>pCounter</TH>
49<TD>Pointer to the initial value of the counter used for encryption (decryption).</TD>
50    </TR>
51    <TR>
52<TH>src</TH>
53<TD>Pointer to the plaintext (ciphertext). Must be 4-byte aligned. In addition, it must point to a location in main memory.</TD>
54    </TR>
55    <TR>
56<TH>srcSize</TH>
57<TD>Plaintext (ciphertext) size. Must be greater than zero.</TD>
58    </TR>
59    <TR>
60<TH>dst</TH>
61<TD>Pointer to the buffer that will store the ciphertext (plaintext). Must be 4-byte aligned. In addition, it must point to a location in main memory. An area of size <span class="argument">srcSize</span> bytes is required.<br />This argument can specify the same pointer as <span class="argument">src</span>.</TD>
62    </TR>
63    <TR>
64<TH>callback</TH>
65<TD>Pointer to the callback function to call when encryption (decryption) is complete. 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
74<h2>Return Values</h2>
75<p>
76Returns <code>AES_RESULT_SUCCESS</code> if the AES operation was started successfully. Any other return values indicate an error.
77</p>
78
79<H2>Description</H2>
80<P>
81Starts the AES encryption (decryption) process in CTR mode. In CTR mode, encryption and decryption are the same operation. <code>AES_CtrEncrypt</code> and <code>AES_CtrDecrypt</code> are aliases of <code>AES_Ctr</code>, so these three functions all do the same thing.
82</p>
83
84<p>
85This function encrypts or decrypts the <span class="argument">srcSize</span> bytes starting from <span class="argument">src</span>, using the key that was set with the <a href="AES_SetKey.html"><CODE>AES_SetKey</CODE></a> function and the initial counter value <span class="argument">pCounter</span>. The encrypted or decrypted result is written to a region starting at <span class="argument">dst</span> whose size is <span class="argument">srcSize</span> bytes. When the encryption or decryption process completes, this function calls <span class="argument">callback</span>, using the processing result and <span class="argument">arg</span> as arguments. <span class="argument">callback</span> is called from the interrupt handler, so it might be called even when interrupts are disabled. Conversely, <span class="argument">callback</span> is not called when interrupts are disabled.
86</p>
87
88<p>
89This function returns control immediately once it has started the processing. If processing starts without a problem, this function returns <code>AES_RESULT_SUCCESS</code>, but if an error occurs during subsequent processing, it calls <span class="argument">callback</span> with the error value and <span class="argument">arg</span> as arguments. <B>Note:</B> Error notification using this callback is started from the interrupt handler, so depending on the situation, it is possible that the callback can deliver error notification before control returns from the function.
90</p>
91
92<p>
93The encryption or decryption key must be set beforehand using the <a href="AES_SetKey.html"><CODE>AES_SetKey</CODE></a> function.
94</p>
95
96<p>
97The same key and initial counter value must be used at encryption and decryption. The key must not be leaked, but it is not a problem if the initial counter value gets leaked. However, the initial counter value must be different each time this function is called.
98</p>
99
100
101<h2>See Also</h2>
102<p><A href="AES_SetKey.html"><CODE>AES_SetKey</CODE></A></p>
103
104<H2>Revision History</H2>
105<P>
1062009/01/30 Added mention that <SPAN class="argument">dst</SPAN> and <SPAN class="argument">src</SPAN> can be the same buffer.<br />2007/12/25 Initial version.
107</P>
108<hr><p>CONFIDENTIAL</p></body>
109</html>
110