doc/crypto/tinycrypt.rst - third_party/github/zephyrproject-rtos/zephyr - Git at Google

 .. _tinycrypt:

 TinyCrypt Cryptographic Library v1.0
 ####################################
 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.

 * 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: Mode of operation.
   * Standard Specification: NIST SP 800-38A.
   * Requires: AES-128.

 * AES-CTR mode:

   * Type of primitive: Mode of operation.
   * Standard Specification: NIST SP 800-38A.
   * Requires: AES-128.


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


 Limitations
 ***********

 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.

 General Limitations
 ===================

 * 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,
   TinyCrypt only implements certain generic timing-attack countermeasures.

 Specific Limitations
 ====================

 * 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
     2^64 bits, which is an extremely large window.

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

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

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

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


 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)

  * Encrypt data and keys (AES-128 encrypt + AES-CTR + HMAC-SHA256)

  * Decrypt data and keys (AES-128 encrypt + AES-CTR + HMAC-SHA256)


 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.

 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 Statistical Test Suite`_

 .. _NIST Statistical Test Suite:
    http://csrc.nist.gov/groups/ST/toolkit/rng/documentation_software.html

 * `RFC 2104 (HMAC-SHA256)`_

 .. _RFC 2104 (HMAC-SHA256):
    https://www.ietf.org/rfc/rfc2104.txt
	.. _tinycrypt:

	TinyCrypt Cryptographic Library v1.0
	####################################
	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.

	* 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: Mode of operation.
	* Standard Specification: NIST SP 800-38A.
	* Requires: AES-128.

	* AES-CTR mode:

	* Type of primitive: Mode of operation.
	* Standard Specification: NIST SP 800-38A.
	* Requires: AES-128.


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


	Limitations
	***********

	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.

	General Limitations
	===================

	* 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,
	TinyCrypt only implements certain generic timing-attack countermeasures.

	Specific Limitations
	====================

	* 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
	2^64 bits, which is an extremely large window.

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

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

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

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


	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)

	* Encrypt data and keys (AES-128 encrypt + AES-CTR + HMAC-SHA256)

	* Decrypt data and keys (AES-128 encrypt + AES-CTR + HMAC-SHA256)


	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.

	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 Statistical Test Suite`_

	.. _NIST Statistical Test Suite:
	http://csrc.nist.gov/groups/ST/toolkit/rng/documentation_software.html

	* `RFC 2104 (HMAC-SHA256)`_

	.. _RFC 2104 (HMAC-SHA256):
	https://www.ietf.org/rfc/rfc2104.txt