diff --git a/README.md b/README.md index ebea8b8b..7f4b19f2 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,8 @@ Recent significant changes to the library Apr 2018: * Acorn128 authenticated cipher (finalist in the CAESAR AEAD competition). +* Split the library into Crypto (core), CryptoLW (light-weight), and + CryptoLegacy (deprecated algorithms). * Tiny and small versions of AES for reducing memory requirements. * Port the library to ESP8266 and ESP32. * Make the RNG class more robust if the app doesn't call begin() or loop(). diff --git a/doc/Doxyfile b/doc/Doxyfile index 6d0ea40f..4c60b831 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -657,6 +657,7 @@ WARN_LOGFILE = INPUT = ../libraries/Crypto \ ../libraries/CryptoLW/src \ + ../libraries/CryptoLegacy/src \ ../libraries/NewHope \ ../libraries/RingOscillatorNoiseSource \ ../libraries/TransistorNoiseSource \ diff --git a/doc/crypto.dox b/doc/crypto.dox index 87bfad40..fa8fb5db 100644 --- a/doc/crypto.dox +++ b/doc/crypto.dox @@ -24,28 +24,73 @@ \file crypto.dox \page crypto Arduino Cryptography Library -\section crypto_algorithms Supported Algorithms +\section crypto_algorithms Supported algorithms -\li Block ciphers: AES128, AES192, AES256, Speck -\li Block cipher modes: CTR, CFB, CBC, OFB, EAX, GCM, XTS +The library is split into four main sections: core, light-weight, legacy, +and other. + +\subsection crypto_core_algorithms Core algorithms + +Core algorithms are found within the "libraries/Crypto" directory +in the repository: + +\li Authenticated encryption with associated data (AEAD): ChaChaPoly, EAX, GCM +\li Block ciphers: AES128, AES192, AES256 +\li Block cipher modes: CTR, EAX, GCM, XTS \li Stream ciphers: ChaCha -\li Authenticated encryption with associated data (AEAD): ChaChaPoly, EAX, GCM, Acorn128 \li Hash algorithms: SHA256, SHA512, SHA3_256, SHA3_512, BLAKE2s, BLAKE2b (regular and HMAC modes) \li Extendable output functions (XOF's): SHAKE128, SHAKE256 \li Message authenticators: Poly1305, GHASH, OMAC \li Public key algorithms: Curve25519, Ed25519, P521 -\li Post-quantum algorithms: NewHope -\li Random number generation: \link RNGClass RNG\endlink, TransistorNoiseSource, RingOscillatorNoiseSource +\li Random number generation: \link RNGClass RNG\endlink Reduced memory versions of some algorithms (encryption is slower, but the RAM required for the key schedule is less): \li AESTiny128, AESSmall128, AESTiny256, AESSmall256 -\li SpeckTiny, SpeckSmall The "tiny" versions only support encryption which makes them suitable for the CTR, CFB, OFB, EAX, and GCM block cipher modes but not CBC. The "small" -versions use a little more memory but support both encryptionm and decryption. +versions use a little more memory but support both encryption and decryption. + +\subsection crpto_lw_algorithms Light-weight algorithms + +The algorithms in the "libraries/CryptoLW" directory are new algorithms +that have been designed for "light-weight" environments where memory and +CPU resources are constrained: + +\li Authenticated encryption with associated data (AEAD): Acorn128 +\li Block ciphers: Speck, SpeckSmall, SpeckTiny + +These algorithms are fairly new, but they are ideal for Arduino devices. +They don't yet appear in any internationally adopted standards yet but any +algorithms that are adopted into standards later will be moved to the +core library. Maybe you'll be the one to create that new standard! + +\subsection crypto_legacy_algorithms Legacy algorithms + +Legacy algorithms in the "libraries/CryptoLegacy" are those that should +probably not be used in new protocol designs, but may be required for +backwards-compatibility with older protocols: + +\li Block cipher modes: CFB, CBC, OFB + +CBC is included in the legacy list because cryptography experts no longer +recommend it for use in newer designs. It was an important mode in the past +but newer designs should be using authenticated encryption with associated +data (AEAD) instead. If you were looking to use CBC in your project, +then please consider transitioning to one of the AEAD schemes listed above. + +Over time, other algorithms may be moved from the core library to legacy. + +\subsection crypto_other_algorithms Other algorithms + +Other algorithms are provided in the remaining directories under "libraries", +and consist of algorithms that are either too big for the main library, +or are dedicated to a special purpose that only some applications will need: + +\li Post-quantum algorithms: NewHope +\li Random number generation: TransistorNoiseSource, RingOscillatorNoiseSource \section crypto_optimizations Optimizations diff --git a/host/Crypto/Makefile b/host/Crypto/Makefile index e2ebb306..e854c64b 100644 --- a/host/Crypto/Makefile +++ b/host/Crypto/Makefile @@ -5,15 +5,18 @@ TOPDIR = ../.. SRCDIR = $(TOPDIR)/libraries/Crypto SRCDIR2 = $(TOPDIR)/libraries/NewHope SRCDIR3 = $(TOPDIR)/libraries/CryptoLW +SRCDIR4 = $(TOPDIR)/libraries/CryptoLegacy #VPATH = $(SRCDIR) vpath %.cpp $(SRCDIR) vpath %.cpp $(SRCDIR2) vpath %.cpp $(SRCDIR3)/src +vpath %.cpp $(SRCDIR4)/src vpath %.o . vpath %.ino $(SRCDIR)/examples vpath %.ino $(SRCDIR2)/examples vpath %.ino $(SRCDIR3)/examples +vpath %.ino $(SRCDIR4)/examples vpath %.sketch . LIBRARY = libCrypto.a @@ -22,6 +25,7 @@ CPPFLAGS = \ -I$(TOPDIR)/host/emulation \ -I$(TOPDIR)/libraries/Crypto \ -I$(TOPDIR)/libraries/CryptoLW/src \ + -I$(TOPDIR)/libraries/CryptoLegacy/src \ -I$(TOPDIR)/libraries/NewHope \ -DHOST_BUILD diff --git a/libraries/Crypto/examples/TestCBC/TestCBC.ino b/libraries/CryptoLegacy/examples/TestCBC/TestCBC.ino similarity index 99% rename from libraries/Crypto/examples/TestCBC/TestCBC.ino rename to libraries/CryptoLegacy/examples/TestCBC/TestCBC.ino index 3225735b..346e7000 100644 --- a/libraries/Crypto/examples/TestCBC/TestCBC.ino +++ b/libraries/CryptoLegacy/examples/TestCBC/TestCBC.ino @@ -25,6 +25,7 @@ This example runs tests on the CBC implementation to verify correct behaviour. */ #include +#include #include #include #include diff --git a/libraries/Crypto/examples/TestCFB/TestCFB.ino b/libraries/CryptoLegacy/examples/TestCFB/TestCFB.ino similarity index 99% rename from libraries/Crypto/examples/TestCFB/TestCFB.ino rename to libraries/CryptoLegacy/examples/TestCFB/TestCFB.ino index c1390a97..a3169ebd 100644 --- a/libraries/Crypto/examples/TestCFB/TestCFB.ino +++ b/libraries/CryptoLegacy/examples/TestCFB/TestCFB.ino @@ -25,6 +25,7 @@ This example runs tests on the CFB implementation to verify correct behaviour. */ #include +#include #include #include #include diff --git a/libraries/Crypto/examples/TestOFB/TestOFB.ino b/libraries/CryptoLegacy/examples/TestOFB/TestOFB.ino similarity index 99% rename from libraries/Crypto/examples/TestOFB/TestOFB.ino rename to libraries/CryptoLegacy/examples/TestOFB/TestOFB.ino index 2918c9e7..1cedd9e8 100644 --- a/libraries/Crypto/examples/TestOFB/TestOFB.ino +++ b/libraries/CryptoLegacy/examples/TestOFB/TestOFB.ino @@ -25,6 +25,7 @@ This example runs tests on the OFB implementation to verify correct behaviour. */ #include +#include #include #include #include diff --git a/libraries/CryptoLegacy/keywords.txt b/libraries/CryptoLegacy/keywords.txt new file mode 100644 index 00000000..0568b84f --- /dev/null +++ b/libraries/CryptoLegacy/keywords.txt @@ -0,0 +1,3 @@ +CBC KEYWORD1 +CFB KEYWORD1 +OFB KEYWORD1 diff --git a/libraries/CryptoLegacy/library.json b/libraries/CryptoLegacy/library.json new file mode 100644 index 00000000..6f6a95e4 --- /dev/null +++ b/libraries/CryptoLegacy/library.json @@ -0,0 +1,22 @@ +{ + "name": "CryptoLegacy", + "version": "0.1.6", + "keywords": "CBC,CFB,OFB", + "description": "Legacy ciphers for the Arduino Cryptography Library", + "authors": + { + "name": "Rhys Weatherley", + "email": "rhys.weatherley@gmail.com", + "url": "https://rweather.github.io/arduinolibs/crypto.html" + }, + "export": { + "include": "libraries/CryptoLegacy" + }, + "repository": + { + "type": "git", + "url": "https://github.com/rweather/arduinolibs.git" + }, + "frameworks": "arduino", + "platforms": "*" +} diff --git a/libraries/CryptoLegacy/library.properties b/libraries/CryptoLegacy/library.properties new file mode 100644 index 00000000..3d635550 --- /dev/null +++ b/libraries/CryptoLegacy/library.properties @@ -0,0 +1,10 @@ +name=CryptoLegacy +version=1.0.0 +author=Rhys Weatherley +maintainer=Rhys Weatherley +sentence=Legacy algorithms in the Arduino Cryptography Library +paragraph=This library provides implementations of various legacy cryptography algorithms which should not be used for new protocols but which may be needed when implementing older protocols. +category=Communication +url=https://github.com/rweather/arduinolibs +architectures=* +includes=CryptoLegacy.h diff --git a/libraries/Crypto/CBC.cpp b/libraries/CryptoLegacy/src/CBC.cpp similarity index 100% rename from libraries/Crypto/CBC.cpp rename to libraries/CryptoLegacy/src/CBC.cpp diff --git a/libraries/Crypto/CBC.h b/libraries/CryptoLegacy/src/CBC.h similarity index 100% rename from libraries/Crypto/CBC.h rename to libraries/CryptoLegacy/src/CBC.h diff --git a/libraries/Crypto/CFB.cpp b/libraries/CryptoLegacy/src/CFB.cpp similarity index 100% rename from libraries/Crypto/CFB.cpp rename to libraries/CryptoLegacy/src/CFB.cpp diff --git a/libraries/Crypto/CFB.h b/libraries/CryptoLegacy/src/CFB.h similarity index 100% rename from libraries/Crypto/CFB.h rename to libraries/CryptoLegacy/src/CFB.h diff --git a/libraries/CryptoLegacy/src/CryptoLegacy.h b/libraries/CryptoLegacy/src/CryptoLegacy.h new file mode 100644 index 00000000..fe020629 --- /dev/null +++ b/libraries/CryptoLegacy/src/CryptoLegacy.h @@ -0,0 +1,29 @@ +/* + * Copyright (C) 2018 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. + */ + +#ifndef CRYPTO_LEGACY_H +#define CRYPTO_LEGACY_H + +// This header exists to make the Arudino IDE add the library to the +// include and link paths when the sketch includes . + +#endif diff --git a/libraries/Crypto/OFB.cpp b/libraries/CryptoLegacy/src/OFB.cpp similarity index 100% rename from libraries/Crypto/OFB.cpp rename to libraries/CryptoLegacy/src/OFB.cpp diff --git a/libraries/Crypto/OFB.h b/libraries/CryptoLegacy/src/OFB.h similarity index 100% rename from libraries/Crypto/OFB.h rename to libraries/CryptoLegacy/src/OFB.h