diff options
| -rw-r--r-- | LICENSE | 28 | ||||
| -rw-r--r-- | Makefile | 2 | ||||
| -rw-r--r-- | README | 8 | ||||
| -rw-r--r-- | VERSION | 2 | ||||
| -rw-r--r-- | config.mk (renamed from Makefile.conf) | 13 | ||||
| -rw-r--r-- | documentation/tinycrypt.rst | 261 |
6 files changed, 230 insertions, 84 deletions
@@ -1,7 +1,7 @@ ================================================================================ - TinyCrypt Cryptographic Library v1.0 + TinyCrypt Cryptographic Library ================================================================================ @@ -34,3 +34,29 @@ ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ================================================================================ + +Copyright (c) 2013, Kenneth MacKay +All rights reserved. + +https://github.com/kmackay/micro-ecc + +Redistribution and use in source and binary forms, with or without modification, +are permitted provided that the following conditions are met: + * Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR +ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON +ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +================================================================================ @@ -6,7 +6,7 @@ # See lib/Makefile and tests/Makefile for further configuration. # ################################################################################ -include Makefile.conf +include config.mk all: $(MAKE) -C lib @@ -41,15 +41,17 @@ The TinyCrypt Library provides an implementation for constrained devices of a minimal set of standard cryptography primitives. Please, ***SEE THE DOCUMENTATION*** folder for more information on the supported -cryptographic primitives and the limitations of TinyCrypt library. +cryptographic primitives and the limitations of TinyCrypt library. For usage, +security and technicalities, please see the corresponding header file of each +cryptographic primitive. ================================================================================ Organization: -/lib: Cryptographic primitives source code. +/lib: C source code of the cryptographic primitives. /tests: Test vectors of the cryptographic primitives. -/documentation: Documentation of TinyCrypt. +/doc: Documentation of TinyCrypt. ================================================================================ @@ -1 +1 @@ -0.1.5
\ No newline at end of file +0.2.0
\ No newline at end of file diff --git a/Makefile.conf b/config.mk index bd7a71e..282c270 100644 --- a/Makefile.conf +++ b/config.mk @@ -6,15 +6,12 @@ # ################################################################################ -CFLAGS = -Os -std=c99 -Wall -Wextra -I../lib -v -I../tests/include +CC=gcc +CFLAGS = -Os -std=c99 -Wall -Wextra -I../include -I../lib +VPATH = ../include ../lib -ifdef ComSpec - RM=del /F /Q -else - RM=rm -f -endif - -export RM +export CC export CFLAGS +export VPATH ################################################################################ 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 |