mirror of
https://github.com/taigrr/arduinolibs
synced 2025-01-18 04:33:12 -08:00
Overview documentation for the Crypto library
This commit is contained in:
Rhys Weatherley
parent
ad858d7419
commit
9fe7854d0f
69
doc/crypto.dox
Normal file
69
doc/crypto.dox
Normal file
@ -0,0 +1,69 @@
|
||||
/*
|
||||
* 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
|
||||
\li Block cipher modes: CTR, CFB, CBC, OFB
|
||||
\li Stream ciphers: ChaCha, Arcfour
|
||||
\li Hash algorithms: SHA1, SHA256
|
||||
|
||||
All cryptographic algorithms have been optimized for 8-bit Arduino platforms
|
||||
like the Uno. Memory usage is also reduced, particularly for SHA1 and SHA256
|
||||
which save 256 and 192 bytes respectively over traditional implementations.
|
||||
|
||||
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, AES256, and Arcfour
|
||||
are provided for use in applications where compatibility with other systems
|
||||
is desirable.
|
||||
|
||||
\section crypto_examples Examples
|
||||
|
||||
TBD
|
||||
|
||||
\section crypto_performance Performance
|
||||
|
||||
All figures are for the Arduino Uno running at 16 MHz:
|
||||
|
||||
<table>
|
||||
<tr><td>Algorithm</td><td>Encryption / Hashing (per byte)</td><td>Decryption (per byte)</td><td>Key Setup</td><td>State Size (bytes)</td></tr>
|
||||
<tr><td>AES128 (ECB mode)</td><td align="right">32.27us</td><td align="right">65.85us</td><td align="right">158.74us</td><td align="right">208</td></tr>
|
||||
<tr><td>AES192 (ECB mode)</td><td align="right">43.44us</td><td align="right">79.59us</td><td align="right">165.53us</td><td align="right">240</td></tr>
|
||||
<tr><td>AES256 (ECB mode)</td><td align="right">50.62us</td><td align="right">92.34us</td><td align="right">225.58us</td><td align="right">272</td></tr>
|
||||
<tr><td>Arcfour</td><td align="right">2.98us</td><td align="right">2.98us</td><td align="right">601.34us</td><td align="right">258</td></tr>
|
||||
<tr><td>ChaCha (20 rounds)</td><td align="right">14.87us</td><td align="right">14.88us</td><td align="right">39.88us</td><td align="right">130</td></tr>
|
||||
<tr><td>ChaCha (12 rounds)</td><td align="right">10.38us</td><td align="right">10.38us</td><td align="right">39.88us</td><td align="right">130</td></tr>
|
||||
<tr><td>ChaCha (8 rounds)</td><td align="right">8.13us</td><td align="right">8.14us</td><td align="right">39.88us</td><td align="right">130</td></tr>
|
||||
<tr><td>SHA1</td><td align="right">21.90us</td><td> </td><td align="right"> </td><td align="right">94</td></tr>
|
||||
<tr><td>SHA256</td><td align="right">42.89us</td><td> </td><td align="right"> </td><td align="right">106</td></tr>
|
||||
</table>
|
||||
|
||||
Where a cipher supports more than one key size (such as ChaCha and Arcfour),
|
||||
the values are typically almost identical for 128-bit and 256-bit keys so only
|
||||
the maximum is shown above.
|
||||
|
||||
*/
|
||||
@ -88,6 +88,15 @@ The default implementation simulates the time and date based on the value of
|
||||
\li \ref alarm_clock "Alarm Clock" example that uses the DS1307 or DS3232
|
||||
realtime clock and the LCD library to implement an alarm clock.
|
||||
|
||||
\section main_Crypto Cryptographic Library
|
||||
|
||||
\li Block ciphers: AES128, AES192, AES256
|
||||
\li Block cipher modes: CTR, CFB, CBC, OFB
|
||||
\li Stream ciphers: ChaCha, Arcfour
|
||||
\li Hash algorithms: SHA1, SHA256
|
||||
|
||||
More information can be found on the \ref crypto "Cryptographic Library" page.
|
||||
|
||||
\section main_IR Infrared Control Library
|
||||
|
||||
\li IRreceiver class that receives incoming RC-5 commands from an
|
||||
|
||||
@ -291,6 +291,39 @@ void testCipher(ChaCha *cipher, const struct TestVector *test)
|
||||
Serial.println("Failed");
|
||||
}
|
||||
|
||||
// The data space of this sketch is too big if we try to test the
|
||||
// performance of all of setKey(), encrypt(), and decrypt().
|
||||
// Since decryption is almost identical to encryption, only test
|
||||
// that if the PERF_DECRYPT option is enabled, suppressing setKey().
|
||||
//#define PERF_DECRYPT 1
|
||||
|
||||
#if !defined(PERF_DECRYPT)
|
||||
|
||||
void perfCipherSetKey(ChaCha *cipher, const struct TestVector *test)
|
||||
{
|
||||
unsigned long start;
|
||||
unsigned long elapsed;
|
||||
int count;
|
||||
|
||||
Serial.print(test->name);
|
||||
Serial.print(" SetKey ... ");
|
||||
|
||||
cipher->setNumRounds(test->rounds);
|
||||
start = micros();
|
||||
for (count = 0; count < 1000; ++count) {
|
||||
cipher->setKey(test->key, test->keySize);
|
||||
cipher->setIV(test->iv, 8);
|
||||
}
|
||||
elapsed = micros() - start;
|
||||
|
||||
Serial.print(elapsed / 1000.0);
|
||||
Serial.print("us per operation, ");
|
||||
Serial.print((1000.0 * 1000000.0) / elapsed);
|
||||
Serial.println(" per second");
|
||||
}
|
||||
|
||||
#endif
|
||||
|
||||
void perfCipherEncrypt(ChaCha *cipher, const struct TestVector *test)
|
||||
{
|
||||
unsigned long start;
|
||||
@ -315,6 +348,8 @@ void perfCipherEncrypt(ChaCha *cipher, const struct TestVector *test)
|
||||
Serial.println(" bytes per second");
|
||||
}
|
||||
|
||||
#if defined(PERF_DECRYPT)
|
||||
|
||||
void perfCipherDecrypt(ChaCha *cipher, const struct TestVector *test)
|
||||
{
|
||||
unsigned long start;
|
||||
@ -339,10 +374,17 @@ void perfCipherDecrypt(ChaCha *cipher, const struct TestVector *test)
|
||||
Serial.println(" bytes per second");
|
||||
}
|
||||
|
||||
#endif
|
||||
|
||||
void perfCipher(ChaCha *cipher, const struct TestVector *test)
|
||||
{
|
||||
#if !defined(PERF_DECRYPT)
|
||||
perfCipherSetKey(cipher, test);
|
||||
perfCipherEncrypt(cipher, test);
|
||||
#else
|
||||
perfCipherEncrypt(cipher, test);
|
||||
perfCipherDecrypt(cipher, test);
|
||||
#endif
|
||||
}
|
||||
|
||||
void setup()
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user