Adding TinyCrypt 2.0 Documentation.

Signed-off-by: Constanza Heath <[email protected]>

1 files changed, 191 insertions, 70 deletions

diff --git a/documentation/tinycrypt.rst b/documentation/tinycrypt.rst
index a474395..c9324e5 100644
--- a/documentation/tinycrypt.rst
+++ b/documentation/tinycrypt.rst
@@ -6,12 +6,16 @@ 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.
+The TinyCrypt Library provides an implementation targeting constrained devices
+of a minimal set of standard cryptography primitives, as listed below. TinyCrypt
+implementations differ in many aspects from the standard specifications in
+in the hope to better serve applications targeting constrained devices (see the
+Important Remarks section for some important differences). Certain cryptographic
+primitives depend on other primitives, as mentioned in the list below.
+
+Besides the Important Remarks section below, valuable information on the usage,
+security and technicalities of each cryptographic primitive can be found in the
+corresponding header file.
 
 * SHA-256:
 
@@ -39,58 +43,81 @@ availability of other primitives.
 
 * AES-CBC mode:
 
-  * Type of primitive: Mode of operation.
+  * Type of primitive: Encryption mode of operation.
   * Standard Specification: NIST SP 800-38A.
   * Requires: AES-128.
 
 * AES-CTR mode:
 
-  * Type of primitive: Mode of operation.
+  * 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 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 code size of each cryptographic primitive. This means minimize
+ 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 
+ pecularities would increase the code size and thus are not considered here.
 
-* 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.
+* 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.
 
 
-Limitations
+Important Remarks
 ***********
 
-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.
+The cryptographic implementations in TinyCrypt library have some limitations. 
+Some of these limitations are inherent to the cryptographic primitives 
+themselves, but others are specific to TinyCrypt in order to meet its design 
+goals (in special, minimal code size) and to better serve applications targeting 
+constrained devices in general. Below, some of these limitations are discussed.
 
-General Limitations
+General Remarks
 ===================
 
 * 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,
+  side-channel countermeasures (i.e., increasing the overall code size),
   TinyCrypt only implements certain generic timing-attack countermeasures.
 
-Specific Limitations
+Specific Remarks
 ====================
 
 * 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
+  * 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:
@@ -100,38 +127,36 @@ Specific Limitations
     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.
+    This process boils down to compare 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 for this purpose (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 fairly
-    arbitrary length. The security of the output is exactly equal to the
+  * 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.
-
-  * 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.
+    
+  * NIST SP 800-90A requires three items as seed material in the initialization 
+    step: entropy seed, personalization and a nonce (which is optional). To 
+    achieve small code size, TinyCrypts only requires the personalization 
+    (which is always available to the user) and indirectly requires the 
+    entropy seed by requiring a mandatory call to the re-seed 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.
+  * 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
+  * 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:
@@ -140,41 +165,119 @@ Specific Limitations
     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
+    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
 ************************
-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)
+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:
 
- * Construct keys (HMAC-SHA256)
+ * Measurement of code, data structures, and other digital artifacts (SHA256);
 
- * Extract entropy from strings containing some randomness (HMAC-SHA256)
+ * Generate commitments (SHA256);
 
- * Construct random mappings (HMAC-SHA256)
+ * Construct keys (HMAC-SHA256);
 
- * Construct nonces and challenges (HMAC-PRNG)
+ * Extract entropy from strings containing some randomness (HMAC-SHA256);
 
- * Authenticate using a shared secret (HMAC-SHA256)
+ * Construct random mappings (HMAC-SHA256);
 
- * Create an authenticated, replay-protected session (HMAC-SHA256 + HMAC-PRNG)
+ * Construct nonces and challenges (HMAC-PRNG);
 
- * Encrypt data and keys (AES-128 encrypt + AES-CTR + HMAC-SHA256)
+ * Authenticate using a shared secret (HMAC-SHA256);
 
- * Decrypt data and keys (AES-128 encrypt + AES-CTR + 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 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.
+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
 **********
@@ -199,12 +302,30 @@ References
 .. _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)`_
+    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