123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352 |
- TinyCrypt Cryptographic Library
- ###############################
- Copyright (C) 2017 by Intel Corporation, All Rights Reserved.
- 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.
-
- Design Goals
- 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.
- 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. These limitations were accepted
- in order to meet its design goals (in special, minimal code size) and to better
- serve applications targeting constrained devices in general. Some of these
- limitations are discussed in-depth below.
- General Remarks
- 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 Remarks
- however that this will only be a problem if you intend to hash more than
- 2^64 bits, which is an extremely large window.
- 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).
- cleans the state context before exiting. Thus, applications do not need to
- clean the TCHmacState_t ctx after calling tc_hmac_final. This should not
- be changed in future versions of the library as there are applications
- currently relying on this good-practice/feature of TinyCrypt.
- 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.
- 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.
- 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.
- blocks. If you need to encrypt larger data sets, your application would
- need to replace the key after 2^32 block encryptions.
- 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.
- contiguous (as produced by TinyCrypt CBC encryption). This allows for a
- very efficient decryption algorithm that would not otherwise be possible.
- 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.
- 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.
- 0 and (2^16 - 2^8) = 65280 bytes.
- authenticates the payload and only authenticates the associated data);
- authenticates the payload);
- authentication-only mode on the associated data).
- 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.
- https:
- 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."
- Note that the assumed bit layout is: {31, 30, ..., 0}, {63, 62, ..., 32},
- {95, 94, ..., 64}, {127, 126, ..., 96} for a very-long-integer (vli)
- consisting of 4 unsigned integers (as an example).
- before calling uECC_make_key() or uECC_sign().
- 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:
- 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):
- http:
- .. _NIST FIPS PUB 197 (AES-128):
- http:
- .. _NIST SP800-90A (HMAC-PRNG):
- http:
- .. _NIST SP 800-38A (AES-CBC and AES-CTR):
- http:
- .. _NIST SP 800-38B (AES-CMAC):
- http:
- .. _NIST SP 800-38C (AES-CCM):
- http:
- .. _NIST Statistical Test Suite (useful for testing HMAC-PRNG):
- http:
- .. _NIST Cryptographic Algorithm Validation Program (CAVP) site:
- http:
- .. _RFC 2104 (HMAC-SHA256):
- https:
- .. _RFC 6090 (ECC-DH and ECC-DSA):
- https:
|