| .. _tinycrypt: |
| |
| TinyCrypt Cryptographic Library v1.0 |
| #################################### |
| 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. |
| |
| * SHA-256: |
| |
| * Type of primitive: Hash function. |
| * Standard Specification: NIST FIPS PUB 180-4. |
| * Requires: -- |
| |
| * HMAC-SHA256: |
| |
| * Type of primitive: Message authentication code. |
| * Standard Specification: RFC 2104. |
| * Requires: SHA-256 |
| |
| * HMAC-PRNG: |
| |
| * Type of primitive: Pseudo-random number generator. |
| * Standard Specification: NIST SP 800-90A. |
| * Requires: SHA-256 and HMAC-SHA256. |
| |
| * AES-128: |
| |
| * Type of primitive: Block cipher. |
| * Standard Specification: NIST FIPS PUB 197. |
| * Requires: -- |
| |
| * AES-CBC mode: |
| |
| * Type of primitive: Mode of operation. |
| * Standard Specification: NIST SP 800-38A. |
| * Requires: AES-128. |
| |
| * AES-CTR mode: |
| |
| * Type of primitive: Mode of operation. |
| * Standard Specification: NIST SP 800-38A. |
| * Requires: AES-128. |
| |
| |
| 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 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. |
| |
| |
| Limitations |
| *********** |
| |
| 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. |
| |
| General Limitations |
| =================== |
| |
| * 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 |
| side-channel countermeasures such as increasing the overall code size, |
| TinyCrypt only implements certain generic timing-attack countermeasures. |
| |
| Specific Limitations |
| ==================== |
| |
| * 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 |
| 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. |
| |
| * 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 |
| 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. |
| |
| * 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. |
| |
| * 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 |
| need to replace the key after 2^32 block encryptions. |
| |
| * CBC mode: |
| |
| * TinyCrypt CBC decryption assumes that the iv and the ciphertext are |
| contiguous (as produced by TinyCrypt CBC encryption). This allows for a |
| very efficient decryption algorithm that would not otherwise be possible. |
| |
| |
| 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: |
| |
| * Measurement of code, data structures, and other digital artifacts (SHA256) |
| |
| * Generate commitments (SHA256) |
| |
| * Construct keys (HMAC-SHA256) |
| |
| * Extract entropy from strings containing some randomness (HMAC-SHA256) |
| |
| * Construct random mappings (HMAC-SHA256) |
| |
| * Construct nonces and challenges (HMAC-PRNG) |
| |
| * Authenticate using a shared secret (HMAC-SHA256) |
| |
| * Create an authenticated, replay-protected session (HMAC-SHA256 + HMAC-PRNG) |
| |
| * Encrypt data and keys (AES-128 encrypt + AES-CTR + HMAC-SHA256) |
| |
| * Decrypt data and keys (AES-128 encrypt + AES-CTR + HMAC-SHA256) |
| |
| |
| 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. |
| |
| References |
| ********** |
| |
| * `NIST FIPS PUB 180-4 (SHA-256)`_ |
| |
| .. _NIST FIPS PUB 180-4 (SHA-256): |
| http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf |
| |
| * `NIST FIPS PUB 197 (AES-128)`_ |
| |
| .. _NIST FIPS PUB 197 (AES-128): |
| http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf |
| |
| * `NIST SP800-90A (HMAC-PRNG)`_ |
| |
| .. _NIST SP800-90A (HMAC-PRNG): |
| http://csrc.nist.gov/publications/nistpubs/800-90A/SP800-90A.pdf |
| |
| * `NIST SP 800-38A (AES-CBC and AES-CTR)`_ |
| |
| .. _NIST SP 800-38A (AES-CBC and AES-CTR): |
| http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf |
| |
| * `NIST Statistical Test Suite`_ |
| |
| .. _NIST Statistical Test Suite: |
| http://csrc.nist.gov/groups/ST/toolkit/rng/documentation_software.html |
| |
| * `RFC 2104 (HMAC-SHA256)`_ |
| |
| .. _RFC 2104 (HMAC-SHA256): |
| https://www.ietf.org/rfc/rfc2104.txt |