From 4c8f28bb37e33f7a341d0c865c725a7c78b10feb Mon Sep 17 00:00:00 2001 From: Constanza Heath Date: Tue, 9 Feb 2016 14:16:19 -0800 Subject: [PATCH] Updating TinyCrypt v2.0 documentation. Change-Id: I53ffef8a799a41442c636509a67cca80bb375787 Signed-off-by: Constanza Heath --- doc/crypto/tinycrypt.rst | 272 ++++++++++++++++++++++++++++----------- 1 file changed, 194 insertions(+), 78 deletions(-) diff --git a/doc/crypto/tinycrypt.rst b/doc/crypto/tinycrypt.rst index 8aa366e1f1b..cb2d7847657 100644 --- a/doc/crypto/tinycrypt.rst +++ b/doc/crypto/tinycrypt.rst @@ -1,17 +1,21 @@ .. _tinycrypt: -TinyCrypt Cryptographic Library v1.0 -#################################### +TinyCrypt Cryptographic Library +############################### Copyright (C) 2015 by Intel Corporation, All Rights Reserved. Overview ******** -The TinyCrypt Library provides an implementation for constrained devices of a -minimal set of standard cryptography primitives, as listed below. TinyCrypt's -implementation differs in some aspects from the standard specifications for -better serving applications targeting constrained devices. See the Limitations -section for these differences. Note that some primitives depend on the -availability of other primitives. +The TinyCrypt Library provides an implementation for targeting constrained devices +with a minimal set of standard cryptography primitives, as listed below. To better +serve applications targeting constrained devices, TinyCrypt implementations differ +from the standard specifications (see the Important Remarks section for some +important differences). Certain cryptographic primitives depend on other +primitives, as mentioned in the list below. + +Aside from the Important Remarks section below, valuable information on the usage, +security and technicalities of each cryptographic primitive are found in the +corresponding header file. * SHA-256: @@ -39,99 +43,113 @@ availability of other primitives. * AES-CBC mode: - * Type of primitive: Mode of operation. + * Type of primitive: Encryption mode of operation. * Standard Specification: NIST SP 800-38A. * Requires: AES-128. * AES-CTR mode: - * Type of primitive: Mode of operation. + * Type of primitive: Encryption mode of operation. * Standard Specification: NIST SP 800-38A. * Requires: AES-128. +* AES-CMAC mode: + + * Type of primitive: Message authentication code. + * Standard Specification: NIST SP 800-38B. + * Requires: AES-128. + +* AES-CCM mode: + + * Type of primitive: Authenticated encryption. + * Standard Specification: NIST SP 800-38C. + * Requires: AES-128. + +* ECC-DH: + + * Type of primitive: Key exchange. + * Standard Specification: RFC 6090. + * Requires: ECC auxiliary functions (ecc.h/c). + +* ECC-DSA: + + * Type of primitive: Digital signature. + * Standard Specification: RFC 6090. + * Requires: ECC auxiliary functions (ecc.h/c). Design Goals ************ -* Minimize the code size of each primitive. This means minimize the size of - the generic code. Various usages may require further features, optimizations - and treatments for specific threats that would increase the overall code size. +* Minimize the code size of each cryptographic primitive. This means minimize + the size of a platform-independent implementation, as presented in TinyCrypt. + Note that various applications may require further features, optimizations with + respect to other metrics and countermeasures for particular threats. These + peculiarities would increase the code size and thus are not considered here. -* Minimize the dependencies among primitive implementations. This means that - it is unnecessary to build and allocate object code for more primitives - than the ones strictly required by the usage. In other words, - in the Makefile you can select only the primitives that your application requires. +* Minimize the dependencies among the cryptographic primitives. This means + that it is unnecessary to build and allocate object code for more primitives + than the ones strictly required by the intended application. In other words, + one can select and compile only the primitives required by the application. -Limitations -*********** +Important Remarks +***************** -The TinyCrypt library has some known limitations. Some are inherent to -the cryptographic primitives; others are specific to TinyCrypt, to -meet the design goals (in special, minimal code size) and better serving -applications targeting constrained devices in general. +The cryptographic implementations in TinyCrypt library have some limitations. +Some of these limitations are inherent to the cryptographic primitives +themselves, while others are specific to TinyCrypt. Some of these limitations +are discussed in-depth below. -General Limitations -=================== +General Remarks +*************** -* TinyCrypt does **not** intend to be fully side-channel resistant. There is a huge - variety of side-channel attacks, many of them only relevant to certain - platforms. In this sense, instead of penalizing all library users with +* TinyCrypt does **not** intend to be fully side-channel resistant. Due to the + variety of side-channel attacks, many of them making certain platforms + vulnerable. In this sense, instead of penalizing all library users with side-channel countermeasures such as increasing the overall code size, TinyCrypt only implements certain generic timing-attack countermeasures. -Specific Limitations -==================== +Specific Remarks +**************** * SHA-256: - * The state buffer 'leftover' stays in memory after processing. If your - application intends to have sensitive data in this buffer, remember to - erase it after the data has been processed. - - * The number of bits_hashed in the state is not checked for overflow. - This will only be a problem if you intend to hash more than + * The number of bits_hashed in the state is not checked for overflow. Note + however that this will only be a problem if you intend to hash more than 2^64 bits, which is an extremely large window. * HMAC: - * The HMAC state stays in memory after processing. If your application - intends to have sensitive data in this buffer, remind to erase it after - the data is processed. - * The HMAC verification process is assumed to be performed by the application. - In essence, this process compares the computed tag with some given tag. - Note that memcmp methods might be vulnerable to timing attacks; be - sure to use a safe memory comparison function for this purpose. + This compares the computed tag with some given tag. + Note that conventional memory-comparison methods (such as memcmp function) + might be vulnerable to timing attacks; thus be sure to use a constant-time + memory comparison function (such as compare_constant_time + function provided in lib/utils.c). * HMAC-PRNG: - * Before using HMAC-PRNG, you **must** find an entropy source to produce a seed. - PRNGs only stretch the seed into a seemingly random output of fairly - arbitrary length. The security of the output is exactly equal to the + * Before using HMAC-PRNG, you *must* find an entropy source to produce a seed. + PRNGs only stretch the seed into a seemingly random output of arbitrary + length. The security of the output is exactly equal to the unpredictability of the seed. - * During the initialization step, NIST SP 800-90A requires two items as seed - material: entropy material and personalization material. A nonce material is optional. - For achieving small code size, TinyCrypt only requires the personalization, - which is always available to the user, and indirectly requires the entropy seed, - which requires a mandatory call of the reseed function. + * NIST SP 800-90A requires three items as seed material in the initialization + step: entropy seed, personalization and a nonce (which is not implemented). + TinyCrypt requires the personalization byte array and automatically creates + the entropy seed using a mandatory call to the re-seed function. * AES-128: - * The state stays in memory after processing. If your application intends to - have sensitive data in this buffer, remember to erase it after the data is - processed. - - * The current implementation does not support other key-lengths (such as 256 bits). - If you need AES-256, it is likely that your application is running in a - constrained environment. AES-256 requires keys twice the size as for AES-128, - and the key schedule is 40% larger. + * The current implementation does not support other key-lengths (such as 256 + bits). Note that if you need AES-256, it doesn't sound as though your + application is running in a constrained environment. AES-256 requires keys + twice the size as for AES-128, and the key schedule is 40% larger. * CTR mode: - * The AES-CTR mode limits the size of a data message they encrypt to 2^32 blocks. - If you need to encrypt larger data sets, your application would + * The AES-CTR mode limits the size of a data message they encrypt to 2^32 + blocks. If you need to encrypt larger data sets, your application would need to replace the key after 2^32 block encryptions. * CBC mode: @@ -140,41 +158,119 @@ Specific Limitations contiguous (as produced by TinyCrypt CBC encryption). This allows for a very efficient decryption algorithm that would not otherwise be possible. +* CMAC mode: + + * AES128-CMAC mode of operation offers 64 bits of security against collision + attacks. Note however that an external attacker cannot generate the tags + him/herself without knowing the MAC key. In this sense, to attack the + collision property of AES128-CMAC, an external attacker would need the + cooperation of the legal user to produce an exponentially high number of + tags (e.g. 2^64) to finally be able to look for collisions and benefit + from them. As an extra precaution, the current implementation allows to at + most 2^48 calls to tc_cmac_update function before re-calling tc_cmac_setup + (allowing a new key to be set), as suggested in Appendix B of SP 800-38B. + +* CCM mode: + + * There are a few tradeoffs for the selection of the parameters of CCM mode. + In special, there is a tradeoff between the maximum number of invocations + of CCM under a given key and the maximum payload length for those + invocations. Both things are related to the parameter 'q' of CCM mode. The + maximum number of invocations of CCM under a given key is determined by + the nonce size, which is: 15-q bytes. The maximum payload length for those + invocations is defined as 2^(8q) bytes. + + To achieve minimal code size, TinyCrypt CCM implementation fixes q = 2, + which is a quite reasonable choice for constrained applications. The + implications of this choice are: + + The nonce size is: 13 bytes. + + The maximum payload length is: 2^16 bytes = 65 KB. + + The mac size parameter is an important parameter to estimate the security + against collision attacks (that aim at finding different messages that + produce the same authentication tag). TinyCrypt CCM implementation + accepts any even integer between 4 and 16, as suggested in SP 800-38C. + + * TinyCrypt CCM implementation accepts associated data of any length between + 0 and (2^16 - 2^8) = 65280 bytes. + + * TinyCrypt CCM implementation accepts: + + * Both non-empty payload and associated data (it encrypts and + authenticates the payload and only authenticates the associated data); + + * Non-empty payload and empty associated data (it encrypts and + authenticates the payload); + + * Non-empty associated data and empty payload (it degenerates to an + authentication-only mode on the associated data). + + * RFC-3610, which also specifies CCM, presents a few relevant security + suggestions, such as: it is recommended for most applications to use a + mac size greater than 8. Besides, it is emphasized that the usage of the + same nonce for two different messages which are encrypted with the same + key obviously destroys the security properties of CCM mode. + +* ECC-DH and ECC-DSA: + + * TinyCrypt ECC implementation is based on nano-ecc (see + https://github.com/iSECPartners/nano-ecc) which in turn is based on + mciro-ecc (see https://github.com/kmackay/micro-ecc). In the original + nano and micro-ecc documentation, there is an important remark about the + way integers are represented: + + "Integer representation: To reduce code size, all large integers are + represented using little-endian words - so the least significant word is + first. You can use the 'ecc_bytes2native()' and 'ecc_native2bytes()' + functions to convert between the native integer representation and the + standardized octet representation." Examples of Applications ************************ -It is possible to do useful cryptography with only the given small set of primitives. -With this list of primitives it becomes feasible to support a range of cryptography usages: +It is possible to do useful cryptography with only the given small set of +primitives. With this list of primitives it becomes feasible to support a range +of cryptography usages: - * Measurement of code, data structures, and other digital artifacts (SHA256) + * Measurement of code, data structures, and other digital artifacts (SHA256); - * Generate commitments (SHA256) + * Generate commitments (SHA256); - * Construct keys (HMAC-SHA256) + * Construct keys (HMAC-SHA256); - * Extract entropy from strings containing some randomness (HMAC-SHA256) + * Extract entropy from strings containing some randomness (HMAC-SHA256); - * Construct random mappings (HMAC-SHA256) + * Construct random mappings (HMAC-SHA256); - * Construct nonces and challenges (HMAC-PRNG) + * Construct nonces and challenges (HMAC-PRNG); - * Authenticate using a shared secret (HMAC-SHA256) + * Authenticate using a shared secret (HMAC-SHA256); - * Create an authenticated, replay-protected session (HMAC-SHA256 + HMAC-PRNG) + * Create an authenticated, replay-protected session (HMAC-SHA256 + HMAC-PRNG); - * Encrypt data and keys (AES-128 encrypt + AES-CTR + HMAC-SHA256) + * Authenticated encryption (AES-128 + AES-CCM); - * Decrypt data and keys (AES-128 encrypt + AES-CTR + HMAC-SHA256) + * Key-exchange (EC-DH); + * Digital signature (EC-DSA); Test Vectors ************ -The library includes a test program for each primitive. The tests are available -in the :file:`samples/crypto/` folder. Each test illustrates how to use the corresponding -TinyCrypt primitives and also evaluates its correct behavior according to -well-known test-vectors (except for HMAC-PRNG). To evaluate the unpredictability -of the HMAC-PRNG, we suggest the NIST Statistical Test Suite. See References below. +The library provides a test program for each cryptographic primitive (see 'test' +folder). Besides illustrating how to use the primitives, these tests evaluate +the correctness of the implementations by checking the results against +well-known publicly validated test vectors. + +For the case of the HMAC-PRNG, due to the necessity of performing an extensive +battery test to produce meaningful conclusions, we suggest the user to evaluate +the unpredictability of the implementation by using the NIST Statistical Test +Suite (see References). + +For the case of the EC-DH and EC-DSA implementations, most of the test vectors +were obtained from the site of the NIST Cryptographic Algorithm Validation +Program (CAVP), see References. References ********** @@ -199,12 +295,32 @@ References .. _NIST SP 800-38A (AES-CBC and AES-CTR): http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf +* `NIST SP 800-38B (AES-CMAC)`_ + +.. _NIST SP 800-38B (AES-CMAC): + http://csrc.nist.gov/publications/nistpubs/800-38B/SP_800-38B.pdf + +* `NIST SP 800-38C (AES-CCM)`_ + +.. _NIST SP 800-38C (AES-CCM): + http://csrc.nist.gov/publications/nistpubs/800-38C/SP800-38C_updated-July20_2007.pdf + * `NIST Statistical Test Suite`_ .. _NIST Statistical Test Suite: http://csrc.nist.gov/groups/ST/toolkit/rng/documentation_software.html +* `NIST Cryptographic Algorithm Validation Program (CAVP) site`_ + +.. _NIST Cryptographic Algorithm Validation Program (CAVP) site: + http://csrc.nist.gov/groups/STM/cavp/ + * `RFC 2104 (HMAC-SHA256)`_ .. _RFC 2104 (HMAC-SHA256): https://www.ietf.org/rfc/rfc2104.txt + +* `RFC 6090 (ECC-DH and ECC-DSA)`_ + +.. _RFC 6090 (ECC-DH and ECC-DSA): + https://www.ietf.org/rfc/rfc6090.txt