1.. _tinycrypt: 2 3TinyCrypt Cryptographic Library 4############################### 5 6Overview 7******** 8The TinyCrypt Library provides an implementation for targeting constrained devices 9with a minimal set of standard cryptography primitives, as listed below. To better 10serve applications targeting constrained devices, TinyCrypt implementations differ 11from the standard specifications (see the Important Remarks section for some 12important differences). Certain cryptographic primitives depend on other 13primitives, as mentioned in the list below. 14 15Aside from the Important Remarks section below, valuable information on the usage, 16security and technicalities of each cryptographic primitive are found in the 17corresponding header file. 18 19* SHA-256: 20 21 * Type of primitive: Hash function. 22 * Standard Specification: NIST FIPS PUB 180-4. 23 * Requires: -- 24 25* HMAC-SHA256: 26 27 * Type of primitive: Message authentication code. 28 * Standard Specification: RFC 2104. 29 * Requires: SHA-256 30 31* HMAC-PRNG: 32 33 * Type of primitive: Pseudo-random number generator. 34 * Standard Specification: NIST SP 800-90A. 35 * Requires: SHA-256 and HMAC-SHA256. 36 37* AES-128: 38 39 * Type of primitive: Block cipher. 40 * Standard Specification: NIST FIPS PUB 197. 41 * Requires: -- 42 43* AES-CBC mode: 44 45 * Type of primitive: Encryption mode of operation. 46 * Standard Specification: NIST SP 800-38A. 47 * Requires: AES-128. 48 49* AES-CTR mode: 50 51 * Type of primitive: Encryption mode of operation. 52 * Standard Specification: NIST SP 800-38A. 53 * Requires: AES-128. 54 55* AES-CMAC mode: 56 57 * Type of primitive: Message authentication code. 58 * Standard Specification: NIST SP 800-38B. 59 * Requires: AES-128. 60 61* AES-CCM mode: 62 63 * Type of primitive: Authenticated encryption. 64 * Standard Specification: NIST SP 800-38C. 65 * Requires: AES-128. 66 67* ECC-DH: 68 69 * Type of primitive: Key exchange. 70 * Standard Specification: RFC 6090. 71 * Requires: ECC auxiliary functions (ecc.h/c). 72 73* ECC-DSA: 74 75 * Type of primitive: Digital signature. 76 * Standard Specification: RFC 6090. 77 * Requires: ECC auxiliary functions (ecc.h/c). 78 79Design Goals 80************ 81 82* Minimize the code size of each cryptographic primitive. This means minimize 83 the size of a board-independent implementation, as presented in TinyCrypt. 84 Note that various applications may require further features, optimizations with 85 respect to other metrics and countermeasures for particular threats. These 86 peculiarities would increase the code size and thus are not considered here. 87 88* Minimize the dependencies among the cryptographic primitives. This means 89 that it is unnecessary to build and allocate object code for more primitives 90 than the ones strictly required by the intended application. In other words, 91 one can select and compile only the primitives required by the application. 92 93 94Important Remarks 95***************** 96 97The cryptographic implementations in TinyCrypt library have some limitations. 98Some of these limitations are inherent to the cryptographic primitives 99themselves, while others are specific to TinyCrypt. Some of these limitations 100are discussed in-depth below. 101 102General Remarks 103*************** 104 105* TinyCrypt does **not** intend to be fully side-channel resistant. Due to the 106 variety of side-channel attacks, many of them making certain boards 107 vulnerable. In this sense, instead of penalizing all library users with 108 side-channel countermeasures such as increasing the overall code size, 109 TinyCrypt only implements certain generic timing-attack countermeasures. 110 111Specific Remarks 112**************** 113 114* SHA-256: 115 116 * The number of bits_hashed in the state is not checked for overflow. Note 117 however that this will only be a problem if you intend to hash more than 118 2^64 bits, which is an extremely large window. 119 120* HMAC: 121 122 * The HMAC verification process is assumed to be performed by the application. 123 This compares the computed tag with some given tag. 124 Note that conventional memory-comparison methods (such as memcmp function) 125 might be vulnerable to timing attacks; thus be sure to use a constant-time 126 memory comparison function (such as compare_constant_time 127 function provided in lib/utils.c). 128 129* HMAC-PRNG: 130 131 * Before using HMAC-PRNG, you *must* find an entropy source to produce a seed. 132 PRNGs only stretch the seed into a seemingly random output of arbitrary 133 length. The security of the output is exactly equal to the 134 unpredictability of the seed. 135 136 * NIST SP 800-90A requires three items as seed material in the initialization 137 step: entropy seed, personalization and a nonce (which is not implemented). 138 TinyCrypt requires the personalization byte array and automatically creates 139 the entropy seed using a mandatory call to the re-seed function. 140 141* AES-128: 142 143 * The current implementation does not support other key-lengths (such as 256 144 bits). Note that if you need AES-256, it doesn't sound as though your 145 application is running in a constrained environment. AES-256 requires keys 146 twice the size as for AES-128, and the key schedule is 40% larger. 147 148* CTR mode: 149 150 * The AES-CTR mode limits the size of a data message they encrypt to 2^32 151 blocks. If you need to encrypt larger data sets, your application would 152 need to replace the key after 2^32 block encryptions. 153 154* CBC mode: 155 156 * TinyCrypt CBC decryption assumes that the iv and the ciphertext are 157 contiguous (as produced by TinyCrypt CBC encryption). This allows for a 158 very efficient decryption algorithm that would not otherwise be possible. 159 160* CMAC mode: 161 162 * AES128-CMAC mode of operation offers 64 bits of security against collision 163 attacks. Note however that an external attacker cannot generate the tags 164 him/herself without knowing the MAC key. In this sense, to attack the 165 collision property of AES128-CMAC, an external attacker would need the 166 cooperation of the legal user to produce an exponentially high number of 167 tags (e.g. 2^64) to finally be able to look for collisions and benefit 168 from them. As an extra precaution, the current implementation allows to at 169 most 2^48 calls to tc_cmac_update function before re-calling tc_cmac_setup 170 (allowing a new key to be set), as suggested in Appendix B of SP 800-38B. 171 172* CCM mode: 173 174 * There are a few tradeoffs for the selection of the parameters of CCM mode. 175 In special, there is a tradeoff between the maximum number of invocations 176 of CCM under a given key and the maximum payload length for those 177 invocations. Both things are related to the parameter 'q' of CCM mode. The 178 maximum number of invocations of CCM under a given key is determined by 179 the nonce size, which is: 15-q bytes. The maximum payload length for those 180 invocations is defined as 2^(8q) bytes. 181 182 To achieve minimal code size, TinyCrypt CCM implementation fixes q = 2, 183 which is a quite reasonable choice for constrained applications. The 184 implications of this choice are: 185 186 The nonce size is: 13 bytes. 187 188 The maximum payload length is: 2^16 bytes = 65 KB. 189 190 The mac size parameter is an important parameter to estimate the security 191 against collision attacks (that aim at finding different messages that 192 produce the same authentication tag). TinyCrypt CCM implementation 193 accepts any even integer between 4 and 16, as suggested in SP 800-38C. 194 195 * TinyCrypt CCM implementation accepts associated data of any length between 196 0 and (2^16 - 2^8) = 65280 bytes. 197 198 * TinyCrypt CCM implementation accepts: 199 200 * Both non-empty payload and associated data (it encrypts and 201 authenticates the payload and only authenticates the associated data); 202 203 * Non-empty payload and empty associated data (it encrypts and 204 authenticates the payload); 205 206 * Non-empty associated data and empty payload (it degenerates to an 207 authentication-only mode on the associated data). 208 209 * RFC-3610, which also specifies CCM, presents a few relevant security 210 suggestions, such as: it is recommended for most applications to use a 211 mac size greater than 8. Besides, it is emphasized that the usage of the 212 same nonce for two different messages which are encrypted with the same 213 key obviously destroys the security properties of CCM mode. 214 215* ECC-DH and ECC-DSA: 216 217 * TinyCrypt ECC implementation is based on nano-ecc (see 218 https://github.com/iSECPartners/nano-ecc) which in turn is based on 219 micro-ecc (see https://github.com/kmackay/micro-ecc). In the original 220 nano and micro-ecc documentation, there is an important remark about the 221 way integers are represented: 222 223 "Integer representation: To reduce code size, all large integers are 224 represented using little-endian words - so the least significant word is 225 first. You can use the 'ecc_bytes2native()' and 'ecc_native2bytes()' 226 functions to convert between the native integer representation and the 227 standardized octet representation." 228 229Examples of Applications 230************************ 231It is possible to do useful cryptography with only the given small set of 232primitives. With this list of primitives it becomes feasible to support a range 233of cryptography usages: 234 235 * Measurement of code, data structures, and other digital artifacts (SHA256); 236 237 * Generate commitments (SHA256); 238 239 * Construct keys (HMAC-SHA256); 240 241 * Extract entropy from strings containing some randomness (HMAC-SHA256); 242 243 * Construct random mappings (HMAC-SHA256); 244 245 * Construct nonces and challenges (HMAC-PRNG); 246 247 * Authenticate using a shared secret (HMAC-SHA256); 248 249 * Create an authenticated, replay-protected session (HMAC-SHA256 + HMAC-PRNG); 250 251 * Authenticated encryption (AES-128 + AES-CCM); 252 253 * Key-exchange (EC-DH); 254 255 * Digital signature (EC-DSA); 256 257Test Vectors 258************ 259 260The library provides a test program for each cryptographic primitive (see 'test' 261folder). Besides illustrating how to use the primitives, these tests evaluate 262the correctness of the implementations by checking the results against 263well-known publicly validated test vectors. 264 265For the case of the HMAC-PRNG, due to the necessity of performing an extensive 266battery test to produce meaningful conclusions, we suggest the user to evaluate 267the unpredictability of the implementation by using the NIST Statistical Test 268Suite (see References). 269 270For the case of the EC-DH and EC-DSA implementations, most of the test vectors 271were obtained from the site of the NIST Cryptographic Algorithm Validation 272Program (CAVP), see References. 273 274References 275********** 276 277* `NIST FIPS PUB 180-4 (SHA-256)`_ 278 279.. _NIST FIPS PUB 180-4 (SHA-256): 280 http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf 281 282* `NIST FIPS PUB 197 (AES-128)`_ 283 284.. _NIST FIPS PUB 197 (AES-128): 285 http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf 286 287* `NIST SP800-90A (HMAC-PRNG)`_ 288 289.. _NIST SP800-90A (HMAC-PRNG): 290 http://csrc.nist.gov/publications/nistpubs/800-90A/SP800-90A.pdf 291 292* `NIST SP 800-38A (AES-CBC and AES-CTR)`_ 293 294.. _NIST SP 800-38A (AES-CBC and AES-CTR): 295 http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf 296 297* `NIST SP 800-38B (AES-CMAC)`_ 298 299.. _NIST SP 800-38B (AES-CMAC): 300 http://csrc.nist.gov/publications/nistpubs/800-38B/SP_800-38B.pdf 301 302* `NIST SP 800-38C (AES-CCM)`_ 303 304.. _NIST SP 800-38C (AES-CCM): 305 http://csrc.nist.gov/publications/nistpubs/800-38C/SP800-38C_updated-July20_2007.pdf 306 307* `NIST Statistical Test Suite`_ 308 309.. _NIST Statistical Test Suite: 310 http://csrc.nist.gov/groups/ST/toolkit/rng/documentation_software.html 311 312* `NIST Cryptographic Algorithm Validation Program (CAVP) site`_ 313 314.. _NIST Cryptographic Algorithm Validation Program (CAVP) site: 315 http://csrc.nist.gov/groups/STM/cavp/ 316 317* `RFC 2104 (HMAC-SHA256)`_ 318 319.. _RFC 2104 (HMAC-SHA256): 320 https://www.ietf.org/rfc/rfc2104.txt 321 322* `RFC 6090 (ECC-DH and ECC-DSA)`_ 323 324.. _RFC 6090 (ECC-DH and ECC-DSA): 325 https://www.ietf.org/rfc/rfc6090.txt 326
