Crypto

Module scope

This module is responsible for:

• Encryption/decryption algorithms:
  • AES-CTR.
  • AES-ECB.
  • AES-CCM.
• Deterministic random byte generator: AES CTR-DRBG.
• Hash function: SHA256.
• Message authentication codes: CMAC.
• Message Digest functionality for supported Message Digest types.
• Public key signature verification.
• Elliptic curve (EC) keys functionality:
  • Generate EC key pair.
  • Verify EC keys.
  • Parse private and public keys from DER format.
  • Write private and public keys to DER format.
  • Elliptic curve key exchange: ECDHC (compute key).
  • Elliptic curve ECDSA sign and verify.
  • Create group.
• Exporting ASN1 tags.
• X509 certificate functionality:
  • Parsing.
  • Verification.
  • Getting certificate attributes.
• Certificate signing request (CSR) functionality:
  • Set subject.
  • Set message digest algorithm.
  • Set key and key usage.
  • Set extensions.
  • Write CSR to DER format.

The pal_plat_Crypto.h header declares the cryptographic APIs.

Prerequisites for this porting stage

For a successful port, a platform needs to support:

• RTOS module (successfully ported).
• AES-CTR.
• AES-CCM.
• AES-ECB.
• SHA256.
• CMAC.
• Message digest. See palMDType_t in the pal_Crypto.h header.
• EC functionalities: parsing and writing EC keys in DER, generating keys and getting a key’s curve.
• ECDHC compute key.
• ECDSA sign and verify.
• X509 parsing, verification and field extraction.
• CSR functionalities: setting the subject, MD, Key, KeyUsage and Extensions fields, and writing CSR in DER.
• Deterministic random bit generator: AES CTR-DRBG connected to a strong entropy source.

Porting result

After successfully porting the Crypto module, all PAL Crypto tests need to pass. Please see the Tests section for more information.

Porting notes

This section covers non-trivial functionality that the platform needs for a successful port.

General notes

• To set the encryption/decryption key for CTR, call pal_setAesKey() with PAL_KEY_TARGET_ENCRYPTION.

• For the Mbed Client related certificates the X509 certificate verification must enforce certificates use:

  • Message Digest type: MD_SHA256.
  • Public key type: PK_ECKEY or PK_ECDSA.
  • Curve: SECP256R1.
  • Certificate verification must fail otherwise.

• If an X509 certificate verification returns multiple error values, the error order must be:

  1. PAL_ERR_X509_BADCERT_EXPIRED.
  2. PAL_ERR_X509_BADCERT_FUTURE.
  3. PAL_ERR_X509_BADCERT_BAD_MD.
  4. PAL_ERR_X509_BADCERT_BAD_PK.
  5. PAL_ERR_X509_BADCERT_BAD_KEY.
  6. PAL_ERR_X509_BADCERT_NOT_TRUSTED.

• While porting the specific cryptographic library to the target platform, make sure it is connected to a strong entropy source. When using Mbed TLS, please make sure that you use Mbed TLS with hardware entropy source. See the Mbed TLS Porting Guide for instructions.

  For example, see pal_plat_entropySource() in pal_plat_Crypto.c (located in the folder Source/Port/Reference-Impl/Lib_Specific/mbedTLS/Crypto).

Reference implementations

PAL provides reference implementations for the Mbed TLS library: pal_plat_Crypto.c located in the folder Source/Port/Reference-Impl/Lib_Specific/mbedTLS/Crypto.