pigweed / third_party / github / zephyrproject-rtos / zephyr / 57c150af0cc5350f1f83365377f6674745cbb3ab / . / doc / services / crypto / tinycrypt.rst

.. _tinycrypt: | |

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. | |

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 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 |