arduinolibs/doc/crypto.dox

/*
 * Copyright (C) 2015 Southern Storm Software, Pty Ltd.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included
 * in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 */

/**
\file crypto.dox
\page crypto Cryptographic Library

\section crypto_algorithms Supported Algorithms

\li Block ciphers: AES128, AES192, AES256, Speck
\li Block cipher modes: CTR, CFB, CBC, OFB, GCM
\li Stream ciphers: ChaCha
\li Authenticated encryption with associated data (AEAD): ChaChaPoly, EAX, GCM
\li Hash algorithms: SHA1, SHA256, SHA512, SHA3_256, SHA3_512, BLAKE2s, BLAKE2b (regular and HMAC modes)
\li Message authenticators: Poly1305, GHASH
\li Public key algorithms: Curve25519, Ed25519
\li Random number generation: \link RNGClass RNG\endlink, TransistorNoiseSource, RingOscillatorNoiseSource

All cryptographic algorithms have been optimized for 8-bit Arduino platforms
like the Uno.  Memory usage is also reduced, particularly for SHA1, SHA256,
and SHA512 which save 256, 192, and 512 bytes respectively over traditional
implementations.  For all algorithms, static sbox tables and the like are
placed into program memory to further reduce data memory usage.

ChaCha with 20 rounds and 256-bit keys is the recommended
symmetric encryption algorithm because it is twice as fast as AES128,
constant-time, and much more secure.  AES128, AES192, and AES256 are
provided for use in applications where compatibility with other systems
is desirable.

If code size is an issue for your application (for example on very low end
Arduino variants), then Speck on AVR is less than half the code size of
ChaCha, at the cost of more data memory for the state and longer key
setup times.  The SpeckLowMemory class is even smaller at the cost of
some performance when encrypting.

BLAKE2s and BLAKE2b are variations on the ChaCha stream cipher, designed for
hashing, with 256-bit and 512-bit hash outputs respectively.  They are
intended as high performance replacements for SHA256 and SHA512 for when
speed is critical but exact bit-compatibility of hash values is not.

\section crypto_other Examples and other topics

\li \ref crypto_rng "Generating random numbers"

\section crypto_performance Performance

\subsection crypto_performance_avr Performance on AVR

All figures are for the Arduino Uno running at 16 MHz.  Figures for the
Ardunino Mega 2560 running at 16 MHz are similar:

<table>
<tr><td>Encryption Algorithm</td><td align="right">Encryption (per byte)</td><td align="right">Decryption (per byte)</td><td>Key Setup</td><td>State Size (bytes)</td></tr>
<tr><td>AES128 (ECB mode)</td><td align="right">36.90us</td><td align="right">66.48us</td><td align="right">160.00us</td><td align="right">213</td></tr>
<tr><td>AES192 (ECB mode)</td><td align="right">44.20us</td><td align="right">80.35us</td><td align="right">166.54us</td><td align="right">245</td></tr>
<tr><td>AES256 (ECB mode)</td><td align="right">51.50us</td><td align="right">94.22us</td><td align="right">227.97us</td><td align="right">277</td></tr>
<tr><td>ChaCha (20 rounds)</td><td align="right">14.87us</td><td align="right">14.88us</td><td align="right">43.74us</td><td align="right">132</td></tr>
<tr><td>ChaCha (12 rounds)</td><td align="right">10.38us</td><td align="right">10.38us</td><td align="right">43.74us</td><td align="right">132</td></tr>
<tr><td>ChaCha (8 rounds)</td><td align="right">8.13us</td><td align="right">8.14us</td><td align="right">43.74us</td><td align="right">132</td></tr>
<tr><td>Speck (128-bit key, ECB mode)</td><td align="right">10.72us</td><td align="right">11.09us</td><td align="right">287.02us</td><td align="right">275</td></tr>
<tr><td>Speck (192-bit key, ECB mode)</td><td align="right">11.03us</td><td align="right">11.42us</td><td align="right">298.21us</td><td align="right">275</td></tr>
<tr><td>Speck (256-bit key, ECB mode)</td><td align="right">11.35us</td><td align="right">11.74us</td><td align="right">309.66us</td><td align="right">275</td></tr>
<tr><td>SpeckLowMemory (128-bit key, ECB mode)</td><td align="right">35.25us</td><td align="right"> </td><td align="right">10.22us</td><td align="right">35</td></tr>
<tr><td>SpeckLowMemory (192-bit key, ECB mode)</td><td align="right">36.56us</td><td align="right"> </td><td align="right">13.62us</td><td align="right">35</td></tr>
<tr><td>SpeckLowMemory (256-bit key, ECB mode)</td><td align="right">37.87us</td><td align="right"> </td><td align="right">16.89us</td><td align="right">35</td></tr>
<tr><td colspan="5"> </td></tr>
<tr><td>AEAD Algorithm</td><td align="right">Encryption (per byte)</td><td align="right">Decryption (per byte)</td><td>Key Setup</td><td>State Size (bytes)</td></tr>
<tr><td>ChaChaPoly</td><td align="right">41.23us</td><td align="right">41.23us</td><td align="right">902.55us</td><td align="right">255</td></tr>
<tr><td>GCM&lt;AES128&gt;</td><td align="right">186.47us</td><td align="right">186.42us</td><td align="right">1388.43us</td><td align="right">316</td></tr>
<tr><td>GCM&lt;AES192&gt;</td><td align="right">194.17us</td><td align="right">193.72us</td><td align="right">1628.67us</td><td align="right">348</td></tr>
<tr><td>GCM&lt;AES256&gt;</td><td align="right">201.47us</td><td align="right">201.02us</td><td align="right">1923.78us</td><td align="right">380</td></tr>
<tr><td>EAX&lt;AES128&gt;</td><td align="right">78.37us</td><td align="right">78.37us</td><td align="right">1445.15us</td><td align="right">300</td></tr>
<tr><td>EAX&lt;Speck&gt; (128-bit key)</td><td align="right">26.01us</td><td align="right">26.01us</td><td align="right">735.46us</td><td align="right">362</td></tr>
<tr><td>EAX&lt;SpeckLowMemory&gt; (128-bit key)</td><td align="right">75.08us</td><td align="right">75.07us</td><td align="right">1243.66us</td><td align="right">122</td></tr>
<tr><td colspan="5"> </td></tr>
<tr><td>Hash Algorithm</td><td align="right">Hashing (per byte)</td><td align="right">Finalization</td><td> </td><td>State Size (bytes)</td></tr>
<tr><td>SHA1</td><td align="right">21.90us</td><td align="right">1423.28us</td><td align="right"> </td><td align="right">95</td></tr>
<tr><td>SHA256</td><td align="right">43.85us</td><td align="right">2841.04us</td><td align="right"> </td><td align="right">107</td></tr>
<tr><td>SHA512</td><td align="right">122.82us</td><td align="right">15953.42us</td><td align="right"> </td><td align="right">211</td></tr>
<tr><td>SHA3_256</td><td align="right">61.78us</td><td align="right">8328.70us</td><td align="right"> </td><td align="right">405</td></tr>
<tr><td>SHA3_512</td><td align="right">115.94us</td><td align="right">8344.80us</td><td align="right"> </td><td align="right">405</td></tr>
<tr><td>BLAKE2s</td><td align="right">18.54us</td><td align="right">1200.06us</td><td align="right"> </td><td align="right">171</td></tr>
<tr><td>BLAKE2b</td><td align="right">50.70us</td><td align="right">6515.87us</td><td align="right"> </td><td align="right">339</td></tr>
<tr><td colspan="5"> </td></tr>
<tr><td>Authentication Algorithm</td><td align="right">Hashing (per byte)</td><td align="right">Finalization</td><td>Key Setup</td><td>State Size (bytes)</td></tr>
<tr><td>SHA1 (HMAC mode)</td><td align="right">21.90us</td><td align="right">4296.33us</td><td align="right">1420.24us</td><td align="right">95</td></tr>
<tr><td>SHA256 (HMAC mode)</td><td align="right">43.85us</td><td align="right">8552.61us</td><td align="right">2836.49us</td><td align="right">107</td></tr>
<tr><td>BLAKE2s (HMAC mode)</td><td align="right">18.54us</td><td align="right">3649.98us</td><td align="right">1214.81us</td><td align="right">171</td></tr>
<tr><td>Poly1305</td><td align="right">26.29us</td><td align="right">486.15us</td><td align="right">17.26us</td><td align="right">87</td></tr>
<tr><td>GHASH</td><td align="right">148.14us</td><td align="right">17.09us</td><td align="right">21.87us</td><td align="right">33</td></tr>
<tr><td colspan="5"> </td></tr>
<tr><td>Public Key Operation</td><td align="right">Time (per operation)</td><td colspan="3">Comment</td></tr>
<tr><td>Curve25519::eval()</td><td align="right">3119ms</td><td colspan="3">Raw curve evaluation</td></tr>
<tr><td>Curve25519::dh1()</td><td align="right">3121ms</td><td colspan="3">First half of Diffie-Hellman key agreement</td></tr>
<tr><td>Curve25519::dh2()</td><td align="right">3120ms</td><td colspan="3">Second half of Diffie-Hellman key agreement</td></tr>
<tr><td>Ed25519::sign()</td><td align="right">5688ms</td><td colspan="3">Digital signature generation</td></tr>
<tr><td>Ed25519::verify()</td><td align="right">9030ms</td><td colspan="3">Digital signature verification</td></tr>
<tr><td>Ed25519::derivePublicKey()</td><td align="right">5642ms</td><td colspan="3">Derive a public key from a private key</td></tr>
</table>

Where a cipher supports more than one key size (such as ChaCha), the values
are typically almost identical for 128-bit and 256-bit keys so only the
maximum is shown above.

\subsection crypto_performance_arm Performance on ARM

All figures are for the Arduino Due running at 84 MHz:

<table>
<tr><td>Encryption Algorithm</td><td align="right">Encryption (per byte)</td><td align="right">Decryption (per byte)</td><td>Key Setup</td><td>State Size (bytes)</td></tr>
<tr><td>AES128 (ECB mode)</td><td align="right">6.65us</td><td align="right">11.00us</td><td align="right">35.15us</td><td align="right">220</td></tr>
<tr><td>AES192 (ECB mode)</td><td align="right">8.02us</td><td align="right">13.31us</td><td align="right">36.59us</td><td align="right">252</td></tr>
<tr><td>AES256 (ECB mode)</td><td align="right">9.39us</td><td align="right">15.63</td><td align="right">50.19us</td><td align="right">284</td></tr>
<tr><td>ChaCha (20 rounds)</td><td align="right">0.87us</td><td align="right">0.88us</td><td align="right">4.96us</td><td align="right">136</td></tr>
<tr><td>ChaCha (12 rounds)</td><td align="right">0.70us</td><td align="right">0.71us</td><td align="right">4.96us</td><td align="right">136</td></tr>
<tr><td>ChaCha (8 rounds)</td><td align="right">0.62us</td><td align="right">0.62us</td><td align="right">4.96us</td><td align="right">136</td></tr>
<tr><td>Speck (128-bit key, ECB mode)</td><td align="right">0.97us</td><td align="right">0.96us</td><td align="right">36.80us</td><td align="right">288</td></tr>
<tr><td>Speck (192-bit key, ECB mode)</td><td align="right">1.00us</td><td align="right">0.98us</td><td align="right">38.14us</td><td align="right">288</td></tr>
<tr><td>Speck (256-bit key, ECB mode)</td><td align="right">1.03us</td><td align="right">1.01us</td><td align="right">39.31us</td><td align="right">288</td></tr>
<tr><td>SpeckLowMemory (128-bit key, ECB mode)</td><td align="right">2.72us</td><td align="right"> </td><td align="right">1.47us</td><td align="right">48</td></tr>
<tr><td>SpeckLowMemory (192-bit key, ECB mode)</td><td align="right">2.81us</td><td align="right"> </td><td align="right">1.54us</td><td align="right">48</td></tr>
<tr><td>SpeckLowMemory (256-bit key, ECB mode)</td><td align="right">2.90us</td><td align="right"> </td><td align="right">1.83us</td><td align="right">48</td></tr>
<tr><td colspan="5"> </td></tr>
<tr><td>AEAD Algorithm</td><td align="right">Encryption (per byte)</td><td align="right">Decryption (per byte)</td><td>Key Setup</td><td>State Size (bytes)</td></tr>
<tr><td>ChaChaPoly</td><td align="right">1.66us</td><td align="right">1.66us</td><td align="right">45.02us</td><td align="right">280</td></tr>
<tr><td>GCM&lt;AES128&gt;</td><td align="right">11.01us</td><td align="right">10.92us</td><td align="right">247.90us</td><td align="right">344</td></tr>
<tr><td>GCM&lt;AES192&gt;</td><td align="right">12.40us</td><td align="right">12.31us</td><td align="right">294.07us</td><td align="right">376</td></tr>
<tr><td>GCM&lt;AES256&gt;</td><td align="right">13.73us</td><td align="right">13.64us</td><td align="right">347.40us</td><td align="right">408</td></tr>
<tr><td>EAX&lt;AES128&gt;</td><td align="right">14.17us</td><td align="right">14.17us</td><td align="right">266.56us</td><td align="right">312</td></tr>
<tr><td>EAX&lt;Speck&gt; (128-bit key)</td><td align="right">2.65us</td><td align="right">2.65us</td><td align="right">79.38us</td><td align="right">384</td></tr>
<tr><td>EAX&lt;SpeckLowMemory&gt; (128-bit key)</td><td align="right">6.40us</td><td align="right">6.39us</td><td align="right">108.25us</td><td align="right">122</td></tr>
<tr><td colspan="5"> </td></tr>
<tr><td>Hash Algorithm</td><td align="right">Hashing (per byte)</td><td align="right">Finalization</td><td> </td><td>State Size (bytes)</td></tr>
<tr><td>SHA1</td><td align="right">0.94us</td><td align="right">62.55us</td><td align="right"> </td><td align="right">112</td></tr>
<tr><td>SHA256</td><td align="right">1.15us</td><td align="right">76.60us</td><td align="right"> </td><td align="right">120</td></tr>
<tr><td>SHA512</td><td align="right">2.87us</td><td align="right">370.37us</td><td align="right"> </td><td align="right">224</td></tr>
<tr><td>SHA3_256</td><td align="right">5.36us</td><td align="right">697.65us</td><td align="right"> </td><td align="right">424</td></tr>
<tr><td>SHA3_512</td><td align="right">9.89us</td><td align="right">697.81us</td><td align="right"> </td><td align="right">424</td></tr>
<tr><td>BLAKE2s</td><td align="right">0.76us</td><td align="right">50.88us</td><td align="right"> </td><td align="right">184</td></tr>
<tr><td>BLAKE2b</td><td align="right">1.33us</td><td align="right">170.93us</td><td align="right"> </td><td align="right">352</td></tr>
<tr><td colspan="5"> </td></tr>
<tr><td>Authentication Algorithm</td><td align="right">Hashing (per byte)</td><td align="right">Finalization</td><td>Key Setup</td><td>State Size (bytes)</td></tr>
<tr><td>SHA1 (HMAC mode)</td><td align="right">0.94us</td><td align="right">193.92us</td><td align="right">65.09us</td><td align="right">112</td></tr>
<tr><td>SHA256 (HMAC mode)</td><td align="right">1.15us</td><td align="right">238.98us</td><td align="right">80.44us</td><td align="right">120</td></tr>
<tr><td>BLAKE2s (HMAC mode)</td><td align="right">0.76us</td><td align="right">165.64us</td><td align="right">59.92us</td><td align="right">184</td></tr>
<tr><td>Poly1305</td><td align="right">0.85us</td><td align="right">19.25us</td><td align="right">2.35us</td><td align="right">96</td></tr>
<tr><td>GHASH</td><td align="right">4.37us</td><td align="right">1.50us</td><td align="right">4.37us</td><td align="right">36</td></tr>
<tr><td colspan="5"> </td></tr>
<tr><td>Public Key Operation</td><td align="right">Time (per operation)</td><td colspan="3">Comment</td></tr>
<tr><td>Curve25519::eval()</td><td align="right">103ms</td><td colspan="3">Raw curve evaluation</td></tr>
<tr><td>Curve25519::dh1()</td><td align="right">103ms</td><td colspan="3">First half of Diffie-Hellman key agreement</td></tr>
<tr><td>Curve25519::dh2()</td><td align="right">104ms</td><td colspan="3">Second half of Diffie-Hellman key agreement</td></tr>
<tr><td>Ed25519::sign()</td><td align="right">195ms</td><td colspan="3">Digital signature generation</td></tr>
<tr><td>Ed25519::verify()</td><td align="right">306ms</td><td colspan="3">Digital signature verification</td></tr>
<tr><td>Ed25519::derivePublicKey()</td><td align="right">194ms</td><td colspan="3">Derive a public key from a private key</td></tr>
</table>
*/