/* * 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:

Encryption Algorithm	Encryption (per byte)	Decryption (per byte)	Key Setup	State Size (bytes)
AES128 (ECB mode)	33.28us	63.18us	160.00us	181
AES192 (ECB mode)	39.94us	76.48us	166.54us	213
AES256 (ECB mode)	46.61us	89.78us	227.97us	245
ChaCha (20 rounds)	14.87us	14.88us	43.74us	132
ChaCha (12 rounds)	10.38us	10.38us	43.74us	132
ChaCha (8 rounds)	8.13us	8.14us	43.74us	132
Speck (128-bit key, ECB mode)	10.72us	11.09us	287.02us	275
Speck (192-bit key, ECB mode)	11.03us	11.42us	298.21us	275
Speck (256-bit key, ECB mode)	11.35us	11.74us	309.66us	275
SpeckLowMemory (128-bit key, ECB mode)	35.25us		10.22us	35
SpeckLowMemory (192-bit key, ECB mode)	36.56us		13.62us	35
SpeckLowMemory (256-bit key, ECB mode)	37.87us		16.89us	35

AEAD Algorithm	Encryption (per byte)	Decryption (per byte)	Key Setup	State Size (bytes)
ChaChaPoly	41.23us	41.23us	902.55us	255
GCM<AES128>	183.25us	182.80us	1272.73us	284
GCM<AES192>	189.92us	189.47us	1492.60us	316
GCM<AES256>	196.59us	196.13us	1767.33us	348
EAX<AES128>	71.14us	71.14us	1329.44us	268
EAX<Speck> (128-bit key)	26.01us	26.01us	735.46us	362
EAX<SpeckLowMemory> (128-bit key)	75.08us	75.07us	1243.66us	122

Hash Algorithm	Hashing (per byte)	Finalization		State Size (bytes)
SHA1	21.90us	1423.28us		95
SHA256	43.85us	2841.04us		107
SHA512	122.82us	15953.42us		211
SHA3_256	60.69us	8180.24us		205
SHA3_512	113.88us	8196.34us		205
BLAKE2s	20.65us	1335.25us		107
BLAKE2b	65.22us	8375.36us		211

Authentication Algorithm	Hashing (per byte)	Finalization	Key Setup	State Size (bytes)
SHA1 (HMAC mode)	21.90us	4296.33us	1420.24us	95
SHA256 (HMAC mode)	43.85us	8552.61us	2836.49us	107
BLAKE2s (HMAC mode)	20.65us	4055.56us	1350.00us	107
Poly1305	26.29us	486.15us	17.26us	87
GHASH	148.14us	17.09us	21.87us	33

Public Key Operation	Time (per operation)	Comment
Curve25519::eval()	3119ms	Raw curve evaluation
Curve25519::dh1()	3121ms	First half of Diffie-Hellman key agreement
Curve25519::dh2()	3120ms	Second half of Diffie-Hellman key agreement
Ed25519::sign()	5688ms	Digital signature generation
Ed25519::verify()	9030ms	Digital signature verification
Ed25519::derivePublicKey()	5642ms	Derive a public key from a private key

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:

Encryption Algorithm	Encryption (per byte)	Decryption (per byte)	Key Setup	State Size (bytes)
AES128 (ECB mode)	5.71us	10.41us	34.73us	188
AES192 (ECB mode)	6.87us	12.57us	36.51us	220
AES256 (ECB mode)	8.04us	14.72	49.96us	252
ChaCha (20 rounds)	0.87us	0.88us	4.96us	136
ChaCha (12 rounds)	0.70us	0.71us	4.96us	136
ChaCha (8 rounds)	0.62us	0.62us	4.96us	136
Speck (128-bit key, ECB mode)	0.97us	0.96us	36.80us	288
Speck (192-bit key, ECB mode)	1.00us	0.98us	38.14us	288
Speck (256-bit key, ECB mode)	1.03us	1.01us	39.31us	288
SpeckLowMemory (128-bit key, ECB mode)	2.72us		1.47us	48
SpeckLowMemory (192-bit key, ECB mode)	2.81us		1.54us	48
SpeckLowMemory (256-bit key, ECB mode)	2.90us		1.83us	48

AEAD Algorithm	Encryption (per byte)	Decryption (per byte)	Key Setup	State Size (bytes)
ChaChaPoly	1.66us	1.66us	45.02us	280
GCM<AES128>	10.29us	10.29us	223.82us	312
GCM<AES192>	11.50us	11.51us	265.62us	344
GCM<AES256>	12.67us	12.67us	313.06us	376
EAX<AES128>	12.29us	12.29us	236.47us	280
EAX<Speck> (128-bit key)	2.65us	2.65us	79.46us	384
EAX<SpeckLowMemory> (128-bit key)	6.29us	6.29us	106.60us	144

Hash Algorithm	Hashing (per byte)	Finalization		State Size (bytes)
SHA1	0.94us	62.55us		112
SHA256	1.15us	76.60us		120
SHA512	2.87us	370.37us		224
SHA3_256	5.64us	735.29us		224
SHA3_512	10.42us	735.49us		224
BLAKE2s	0.72us	48.24us		120
BLAKE2b	1.29us	165.28us		224

Authentication Algorithm	Hashing (per byte)	Finalization	Key Setup	State Size (bytes)
SHA1 (HMAC mode)	0.94us	193.92us	65.09us	112
SHA256 (HMAC mode)	1.15us	238.98us	80.44us	120
BLAKE2s (HMAC mode)	0.72us	157.75us	57.18us	120
Poly1305	0.85us	19.25us	2.35us	96
GHASH	4.37us	1.50us	4.37us	36

Public Key Operation	Time (per operation)	Comment
Curve25519::eval()	103ms	Raw curve evaluation
Curve25519::dh1()	103ms	First half of Diffie-Hellman key agreement
Curve25519::dh2()	104ms	Second half of Diffie-Hellman key agreement
Ed25519::sign()	195ms	Digital signature generation
Ed25519::verify()	306ms	Digital signature verification
Ed25519::derivePublicKey()	194ms	Derive a public key from a private key