211 lines
7.1 KiB
ReStructuredText
211 lines
7.1 KiB
ReStructuredText
.. _crypto:
|
|
|
|
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
|