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