191 lines
6.9 KiB
ReStructuredText
191 lines
6.9 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, you can select
|
|
in the Makefile only the primitives required by your application.
|
|
|
|
|
|
Limitations
|
|
************
|
|
|
|
The TinyCrypt library has some known limitations. Some of them are inherent to
|
|
the cryptographic primitives, but others are specific to TinyCrypt in order 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 (i.e., increasing the overall code size),
|
|
TinyCrypt only implements certain generic timing-attack countermeasures.
|
|
|
|
*Specific Limitations:*
|
|
|
|
* SHA-256:
|
|
|
|
* The state buffer 'leftover' is left in memory after processing. If your
|
|
application intends to have sensitive data in this buffer, remind to
|
|
erase it after the data has been processed.
|
|
|
|
* 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:
|
|
|
|
* The HMAC state is left 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.
|
|
This process boils down to compare the computed tag with some given tag.
|
|
Note that memcmp methods might be vulnerable to timing attacks, thus 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.
|
|
|
|
* NIST SP 800-90A requires during the initialization step 3 items as seed
|
|
material: entropy seed, personalization, and a nonce (optional). For
|
|
achieving small code size, TinyCrypts only requires the
|
|
personalization (which is always available to the user) and indirectly
|
|
requires the entropy seed requiring a mandatory call of the reseed
|
|
function).
|
|
|
|
* AES-128:
|
|
|
|
* The state is left 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 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
|
|
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 '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).
|
|
|
|
References
|
|
***********
|
|
* `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) <http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf>`_
|
|
|
|
* `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) <http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf>`_
|
|
|
|
* `NIST Statistical Test Suite <http://csrc.nist.gov/groups/ST/toolkit/rng/documentation_software.html>`_
|
|
|
|
* `RFC 2104 (HMAC-SHA256) <https://www.ietf.org/rfc/rfc2104.txt>`_
|