DOCSEARCHbyAlgolia
Submit Docs

CryptoAuthLib

repository·main·Indexed 19 days ago

https://github.com/microchiptech/cryptoauthlib

A portable C library for communicating with Microchip Security devices, such as the ATECC608 and SHA10x series. It provides a standardized API for cryptographic operations across various hardware platforms and protocols, including PKCS11 support for Linux, symmetric authentication for IP protection, and secure boot implementations for ATECC608.

Tokens
7K
Snippets
14
Records
40
Agent score
66%

What's inside CryptoAuthLib

  1. Integrate OpenSSL as the software crypto library

    main
    The lib/openssl directory provides the interfacing and wrapper functions required to use OpenSSL as the underlying software cryptographic library for CryptoAuthLib. Use the functions within this directory to bridge CryptoAuthLib operations with OpenSSL implementations.

  3. Implementation considerations for Secure Boot

    main

    When implementing secure boot with ATECC608, keep the following requirements in mind:

    • SHA256 Calculation: The host must perform SHA256 calculations on the firmware. If your host lacks hardware acceleration, use the software implementation provided in lib/crypto/atca_crypto_sw_sha2.c.
    • Nonce Generation: When using wire protection, the host must generate a nonce (NumIn parameter for the Nonce command) sent before the SecureBoot command. This must come from a high-quality random or non-repeating source on the host.
    • Key Storage: The IO protection key should be stored in the host's protected internal memory if available.
    • Boot Loader Security: Secure boot is only effective if the boot loader itself is protected. The boot loader should ideally reside in immutable memory (e.g., Boot ROM or write-protected flash) to prevent an attacker from skipping the verification process.
    • Provisioning: These APIs do not perform provisioning. The ATECC608 must already be configured and provisioned with the necessary keys for secure boot to function.

  4. Understand the CryptoAuthLib directory structure

    main

    The library is organized into several functional directories:

    • lib: Primary library source code.
    • lib/atcacert: Certificate data and I/O methods.
    • lib/calib: The Basic Cryptoauth API.
    • lib/crypto: Software crypto implementations (primarily SHA1 and SHA2).
    • lib/hal: Hardware Abstraction Layer (HAL) code for platform support.
    • lib/host: Support functions for common host-side calculations.
    • lib/jwt: JSON Web Token functions.
    • test: Integration tests and examples.

    Note: For production code, exclude the test directory to avoid adding unnecessary bulk to your application.

  5. Use ATCA_NO_POLL and ATCA_NO_HEAP compiler defines

    main

    Two major compiler defines can modify the library's behavior:

    1. ATCA_NO_POLL: Reverts the library to a non-polling mechanism. Instead of polling for device responses (which provides quicker response times), the library will simply delay for the maximum execution time of a command before reading the response.
    2. ATCA_NO_HEAP: Removes the use of malloc/free from the main library. This is useful for small MCUs without a heap. When using the basic API, no code changes are required. However, for the lower-level API, you must use init/release functions directly as new/delete will no longer be used.

  6. Understand the CryptoAuthLib HAL Architecture

    main

    CryptoAuthLib uses a layered architecture to separate high-level cryptographic logic from physical hardware communication. When integrating the library, you interact with these layers:

    1. atcab_ API Layer: The highest level. These are general-purpose, consistent functions used by your application to perform cryptographic operations regardless of the underlying hardware.
    2. calib_ and talib_ API Layer: The internal library functions that generate command packets and process responses. This layer handles device-specific logic.
    3. HAL (Hardware Abstraction Layer): Performs the transmit/receive of data for a specific interface.
      • Native HAL: If you are using a native driver (like a standard I2C driver), the HAL layer is sufficient.
      • PHY Layer: If the interface requires protocol interpretation or additional logic (e.g., bit-banging GPIO to simulate I2C), the HAL performs the protocol interpretation and the PHY layer performs the actual physical communication.

    Note: You should only include the HAL files required for your specific platform to minimize footprint.

  7. Use the `cal_buffer` structure for atcacert APIs

    main

    Starting with version 3.7.7, the atcacert module APIs have been modified to support TA Compressed certificates. Instead of passing raw buffers, APIs now accept the cal_buffer structure. This structure ensures that the length of the data is bundled with the buffer, which is particularly useful for resource-constrained devices and multipart buffers.

    To initialize a cal_buffer, use the provided convenience macros:

    • CAL_BUF_INIT(length, pointer): Standard initialization for a single buffer.
    • CAL_BUF_INIT_LINK: Used only when multipart buffers are enabled (rare).
    uint8_t signer_ca_public_key[64] = { 0 };
cal_buffer signer_ca_public_key_buf = CAL_BUF_INIT(sizeof(signer_ca_public_key), signer_ca_public_key);

status = atcacert_read_cert(&cert_def, &signer_ca_public_key_buf, cert, &cert_size);

  9. Security considerations for Symmetric Authentication

    main

    When using the symmetric authentication IP protection feature, developers must address the following security responsibilities:

    • Master Key Storage: The user is responsible for determining how the master key is securely stored on the MCU side.
    • Provisioning: The library APIs do not perform chip provisioning. The user must handle the provisioning of the cryptoauthentication device independently.

  10. Integrate mbedtls for software crypto and ECC hardware acceleration

    main
    The lib/mbedtls directory provides interfacing and wrapper functions designed to integrate mbedtls as the primary software cryptography library within CryptoAuthLib. Additionally, this layer provides support for Elliptic Curve Cryptography (ECC) hardware acceleration, allowing the library to offload specific cryptographic operations to compatible hardware.

  11. Migrate atcacert APIs from v3.7.6 to v3.7.7

    main

    When migrating from atcacert version 3.7.6 to 3.7.7, you must update function signatures to accommodate the new cal_buffer structure and additional context parameters. The following functions require signature changes:

    | Function | Change Type | | :--- | : | | atcacert_get_response | Buffers | | atcacert_read_cert | Public key Buffer | | atcacert_read_cert_ext | Public key Buffer | | atcacert_merge_device_loc | Added device context | | atcacert_cert_build_start | Buffers | | atcacert_set_subj_public_key | Public key Buffer | | atcacert_set_signature | Signature Buffer | | atcacert_get_signature | Signature Buffer | | atcacert_generate_sn | Public key Buffer | | atcacert_set_auth_key_id | Public key Buffer | | atcacert_get_tbs_digest | Digest key Buffer | | atcacert_get_key_id | Public key Buffer | | atcacert_der_enc_ecdsa_sig_value | Signature Buffer | | atcacert_der_dec_ecdsa_sig_value | Signature Buffer | | atcacert_verify_cert_hw | Public key Buffer | | atcacert_gen_challenge_hw | Buffers | | atcacert_verify_response_hw | Buffers | | atcacert_gen_challenge_sw | Buffers | | atcacert_verify_cert_sw | Public key Buffer | | atcacert_verify_response_sw | Buffers |

  12. Use TNG convenience functions for ATECC608A-MAHTN-T devices

    main
    The tng folder contains convenience functions specifically designed for working with TNG devices, currently supporting the ATECC608A-MAHTN-T model. These functions simplify interactions with devices that use standard certificates. For reading standard certificates from these devices, use the functions provided in tng_atcacert_client.h.