Overview documentation for the Crypto library

doc/crypto.dox

@@ -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.
+
+*/

doc/mainpage.dox

@@ -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

libraries/Crypto/examples/TestChaCha/TestChaCha.ino

@@ -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()