michaelh/zephyr
1
0
Fork 0
Code Releases Activity

Updating TinyCrypt v2.0 documentation.

Browse source 
Change-Id: I53ffef8a799a41442c636509a67cca80bb375787
Signed-off-by: Constanza Heath <constanza.m.heath@intel.com>
This commit is contained in:
Constanza Heath 2016-02-09 14:16:19 -08:00 • committed by Anas Nashif
commit 4c8f28bb37
1 changed files with 194 additions and 78 deletions
Download patch file Download diff file Expand all files Collapse all files

272
doc/crypto/tinycrypt.rst
View file

@ -1,17 +1,21 @@
.. _tinycrypt: .. _tinycrypt:
TinyCrypt Cryptographic Library v1.0 TinyCrypt Cryptographic Library
#################################### ###############################
Copyright (C) 2015 by Intel Corporation, All Rights Reserved. Copyright (C) 2015 by Intel Corporation, All Rights Reserved.
Overview Overview
******** ********
The TinyCrypt Library provides an implementation for constrained devices of a The TinyCrypt Library provides an implementation for targeting constrained devices
minimal set of standard cryptography primitives, as listed below. TinyCrypt's with a minimal set of standard cryptography primitives, as listed below. To better
implementation differs in some aspects from the standard specifications for serve applications targeting constrained devices, TinyCrypt implementations differ
better serving applications targeting constrained devices. See the Limitations from the standard specifications (see the Important Remarks section for some
section for these differences. Note that some primitives depend on the important differences). Certain cryptographic primitives depend on other
availability of other primitives. 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: * SHA-256:
@ -39,99 +43,113 @@ availability of other primitives.
* AES-CBC mode: * AES-CBC mode:
* Type of primitive: Mode of operation. * Type of primitive: Encryption mode of operation.
* Standard Specification: NIST SP 800-38A. * Standard Specification: NIST SP 800-38A.
* Requires: AES-128. * Requires: AES-128.
* AES-CTR mode: * AES-CTR mode:
* Type of primitive: Mode of operation. * Type of primitive: Encryption mode of operation.
* Standard Specification: NIST SP 800-38A. * Standard Specification: NIST SP 800-38A.
* Requires: AES-128. * 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 Design Goals
************ ************
* Minimize the code size of each primitive. This means minimize the size of * Minimize the code size of each cryptographic primitive. This means minimize
the generic code. Various usages may require further features, optimizations the size of a platform-independent implementation, as presented in TinyCrypt.
and treatments for specific threats that would increase the overall code size. 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 * Minimize the dependencies among the cryptographic primitives. This means
it is unnecessary to build and allocate object code for more primitives that it is unnecessary to build and allocate object code for more primitives
than the ones strictly required by the usage. In other words, than the ones strictly required by the intended application. In other words,
in the Makefile you can select only the primitives that your application requires. 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 implementations in TinyCrypt library have some limitations.
the cryptographic primitives; others are specific to TinyCrypt, to Some of these limitations are inherent to the cryptographic primitives
meet the design goals (in special, minimal code size) and better serving themselves, while others are specific to TinyCrypt. Some of these limitations
applications targeting constrained devices in general. are discussed in-depth below.
General Limitations General Remarks
=================== ***************
* TinyCrypt does **not** intend to be fully side-channel resistant. There is a huge * TinyCrypt does **not** intend to be fully side-channel resistant. Due to the
variety of side-channel attacks, many of them only relevant to certain variety of side-channel attacks, many of them making certain platforms
platforms. In this sense, instead of penalizing all library users with vulnerable. In this sense, instead of penalizing all library users with
side-channel countermeasures such as increasing the overall code size, side-channel countermeasures such as increasing the overall code size,
TinyCrypt only implements certain generic timing-attack countermeasures. TinyCrypt only implements certain generic timing-attack countermeasures.
Specific Limitations Specific Remarks
==================== ****************
* SHA-256: * SHA-256:
* The state buffer 'leftover' stays in memory after processing. If your * The number of bits_hashed in the state is not checked for overflow. Note
application intends to have sensitive data in this buffer, remember to however that this will only be a problem if you intend to hash more than
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. 2^64 bits, which is an extremely large window.
* HMAC: * 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. * The HMAC verification process is assumed to be performed by the application.
In essence, this process compares the computed tag with some given tag. This compares the computed tag with some given tag.
Note that memcmp methods might be vulnerable to timing attacks; be Note that conventional memory-comparison methods (such as memcmp function)
sure to use a safe memory comparison function for this purpose. 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: * HMAC-PRNG:
* Before using HMAC-PRNG, you **must** find an entropy source to produce a seed. * 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 PRNGs only stretch the seed into a seemingly random output of arbitrary
arbitrary length. The security of the output is exactly equal to the length. The security of the output is exactly equal to the
unpredictability of the seed. unpredictability of the seed.
* During the initialization step, NIST SP 800-90A requires two items as seed * NIST SP 800-90A requires three items as seed material in the initialization
material: entropy material and personalization material. A nonce material is optional. step: entropy seed, personalization and a nonce (which is not implemented).
For achieving small code size, TinyCrypt only requires the personalization, TinyCrypt requires the personalization byte array and automatically creates
which is always available to the user, and indirectly requires the entropy seed, the entropy seed using a mandatory call to the re-seed function.
which requires a mandatory call of the reseed function.
* AES-128: * AES-128:
* The state stays in memory after processing. If your application intends to * The current implementation does not support other key-lengths (such as 256
have sensitive data in this buffer, remember to erase it after the data is bits). Note that if you need AES-256, it doesn't sound as though your
processed. 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).
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: * CTR mode:
* The AES-CTR mode limits the size of a data message they encrypt to 2^32 blocks. * The AES-CTR mode limits the size of a data message they encrypt to 2^32
If you need to encrypt larger data sets, your application would blocks. If you need to encrypt larger data sets, your application would
need to replace the key after 2^32 block encryptions. need to replace the key after 2^32 block encryptions.
* CBC mode: * CBC mode:
@ -140,41 +158,119 @@ Specific Limitations
contiguous (as produced by TinyCrypt CBC encryption). This allows for a contiguous (as produced by TinyCrypt CBC encryption). This allows for a
very efficient decryption algorithm that would not otherwise be possible. 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 Examples of Applications
************************ ************************
It is possible to do useful cryptography with only the given small set of primitives. It is possible to do useful cryptography with only the given small set of
With this list of primitives it becomes feasible to support a range of cryptography usages: 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 Test Vectors
************ ************
The library includes a test program for each primitive. The tests are available The library provides a test program for each cryptographic primitive (see 'test'
in the :file:`samples/crypto/` folder. Each test illustrates how to use the corresponding folder). Besides illustrating how to use the primitives, these tests evaluate
TinyCrypt primitives and also evaluates its correct behavior according to the correctness of the implementations by checking the results against
well-known test-vectors (except for HMAC-PRNG). To evaluate the unpredictability well-known publicly validated test vectors.
of the HMAC-PRNG, we suggest the NIST Statistical Test Suite. See References below.
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 References
********** **********
@ -199,12 +295,32 @@ References
.. _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 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`_
.. _NIST Statistical Test Suite: .. _NIST Statistical Test Suite:
http://csrc.nist.gov/groups/ST/toolkit/rng/documentation_software.html 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)`_
.. _RFC 2104 (HMAC-SHA256): .. _RFC 2104 (HMAC-SHA256):
https://www.ietf.org/rfc/rfc2104.txt 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