DOCSEARCHbyAlgolia
Submit Docs

TinyCrypt Documentation

repository·master·Indexed 19 days ago

https://github.com/intel/tinycrypt

A lightweight, modular cryptographic library designed for constrained devices. It provides a minimal set of standard primitives, including SHA-256, HMAC-SHA256, AES-128 (CBC, CTR, CMAC, CCM), ECC-DH, and ECC-DSA. The library includes PRNGs (HMAC-PRNG and CTR-PRNG) and is optimized for minimal code size. Note: Intel has ceased development and maintenance of this project.

Tokens
1.5K
Snippets
1
Records
9
Agent score
18%

What's inside TinyCrypt

  1. Overview of TinyCrypt cryptographic primitives

    master

    TinyCrypt provides a minimal set of standard cryptographic primitives designed for constrained devices. The library is modular, allowing you to compile only the primitives required by your application to minimize code size and dependencies.

    Available primitives include:

    • Hashing & MACs:
      • SHA-256: Hash function (NIST FIPS PUB 180-4).
      • HMAC-SHA256: Message authentication code (RFC 2104). Requires SHA-256.
      • HMAC-PRNG: 256-bit strength Pseudo-random number generator (NIST SP 800-90A). Requires SHA-256 and HMAC-SHA256.
    • AES Block Cipher & Modes:
      • AES-128: Block cipher (NIST FIPS PUB 197).
      • AES-CBC: Encryption mode (NIST SP 800-38A). Requires AES-128.
      • AES-CTR: Encryption mode (NIST SP 800-38A). Requires AES-128.
      • AES-CMAC: Message authentication code (NIST SP 800-38B). Requires AES-128.
      • AES-CCM: Authenticated encryption (NIST SP 800-38C). Requires AES-128.
      • CTR-PRNG: 128-bit strength Pseudo-random number generator (NIST SP 800-90A). Requires AES-128.
    • Elliptic Curve Cryptography (ECC):
      • ECC-DH: Key exchange based on NIST p-256 curve (RFC 6090). Requires ecc.h/c.
      • ECC-DSA: Digital signature based on NIST p-256 curve (RFC 6090). Requires ecc.h/c.

  2. How to use HMAC-PRNG and CTR-PRNG safely

    master

    Pseudo-random number generators (PRNGs) only stretch an initial seed into a sequence of bits. The security of the output is entirely dependent on the unpredictability of the seed.

    Requirements:

    • You must provide an external entropy source to produce a seed.
    • HMAC-PRNG: Requires a personalization byte array. TinyCrypt automatically handles the entropy seed via a mandatory call to the re-seed function.
    • CTR-PRNG: Requires an entropy source to produce a seed before use.

  3. Security considerations and side-channel resistance

    master

    TinyCrypt is optimized for minimal code size and may not be fully side-channel resistant. While it implements certain generic timing-attack countermeasures, it does not provide exhaustive protection against all side-channel attacks.

    Key Security Requirements for Users:

    • HMAC Verification: The library does not perform the final comparison of the computed tag against the provided tag. You must implement this in your application. To prevent timing attacks, use a constant-time memory comparison function like compare_constant_time (provided in lib/utils.c) instead of standard memcmp.

  4. Verify implementations with test vectors

    master

    The library includes a test program for each cryptographic primitive located in the test folder. These tests validate the correctness of the implementations against publicly validated test vectors.

    • HMAC-PRNG: Because of the complexity of testing PRNGs, it is recommended to evaluate the unpredictability of your implementation using the NIST Statistical Test Suite.
    • ECC-DH and ECC-DSA: Test vectors are derived from the NIST Cryptographic Algorithm Validation Program (CAVP).

  5. Project structure and organization

    master

    The TinyCrypt repository is organized as follows:

    • /lib: C source code for the cryptographic primitives.
    • /lib/include/tinycrypt: C header files for the cryptographic primitives.
    • /tests: Test vectors for the cryptographic primitives.
    • /doc: General documentation for TinyCrypt.

  6. Configure AES-CCM parameters

    master

    TinyCrypt's AES-CCM implementation uses fixed parameters to minimize code size. When using CCM mode, be aware of the following constraints:

    • Fixed Parameter q: Set to 2.
    • Nonce Size: 13 bytes (calculated as 15 - q).
    • Maximum Payload Length: 65 KB ($2^{16}$ bytes).
    • Associated Data: Can be any length between 0 and 65,280 bytes ($2^{16} - 2^8$).
    • MAC Size: Accepts any even integer between 4 and 16.

    Usage Modes:

    • Encrypt and authenticate both payload and associated data.
    • Encrypt and authenticate payload only (empty associated data).
    • Authenticate associated data only (empty payload).

    Warning: Never use the same nonce with the same key for different messages, as this destroys the security properties of CCM mode.

  7. Build the TinyCrypt library

    master

    To build TinyCrypt, you must configure the build environment via Makefile.conf and select the specific cryptographic primitives you need in lib/Makefile.

    Follow these steps:

    1. Edit Makefile.conf to set CFLAGS (compiler flags), CC (compiler), and ENABLE_TESTS (true to enable tests, false to disable).
    2. Edit lib/Makefile to select the specific cryptographic primitives required for your project.
    3. Edit tests/Makefile to select the tests corresponding to your chosen primitives.
    4. Run make in the root directory.
    5. Run the generated tests located in the tests/ directory to verify the build.
    # 1. Configure Makefile.conf (CFLAGS, CC, ENABLE_TESTS)
# 2. Configure lib/Makefile (select primitives)
# 3. Configure tests/Makefile (select tests)
# 4. Build
make
# 5. Run tests
./tests/run_tests_script # (or equivalent command in tests/)

  8. Handle ECC integer representation and RNG

    master

    TinyCrypt's ECC implementation is based on micro-ecc.

    Integer Representation: To reduce code size, large integers are represented using little-endian words (least significant word first). Use the following functions to convert between native integer representation and standardized octet representation:

    • ecc_bytes2native()
    • ecc_native2bytes()

    RNG Requirement: You must set a cryptographically-secure PRNG function using uECC_set_rng() before calling uECC_make_key() or uECC_sign().

  9. Important notice regarding maintenance

    master

    Intel has ceased development of TinyCrypt.

    Intel no longer provides maintenance, bug fixes, new releases, or updates. Patches are no longer accepted. If you need to use this project or wish to maintain it, you must create your own fork of the repository.