TinyCrypt Cryptographic Library
Overview
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:
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: Encryption mode of operation.
Standard Specification: NIST SP 800-38A.
Requires: AES-128.
AES-CTR mode:
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 cryptographic primitive. This means minimize the size of a board-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 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.
Important Remarks
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 Remarks
TinyCrypt does not intend to be fully side-channel resistant. Due to the variety of side-channel attacks, many of them making certain boards 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 Remarks
SHA-256:
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 verification process is assumed to be performed by the application. 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 arbitrary length. The security of the output is exactly equal to the unpredictability of the seed.
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 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 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.
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 micro-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:
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);
Authenticated encryption (AES-128 + AES-CCM);
Key-exchange (EC-DH);
Digital signature (EC-DSA);
Test Vectors
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.