PortingGuide.md

mbedTLS porting guide for OPTIGA™ Trust M

This document guides to port the mbedTLS software crypto library functions to use OPTIGA™ Trust M hardware secure element based cryptographic functionalities.

Table of contents

• About this document
• OPTIGA™ Trust M integration to mbedTLS
  
  • Platform Abstraction Layer
    
  • Initialization API's
    
  • Cryptographic API's
    

About this document

The aim of this document is to describe the porting details of OPTIGA™ Trust M into mbedTLS software crypto library on any hardware platform (e.g. microcontroller,single board computer etc...) and porting of platform abstraction layer.
mbedTLS is a crypto library to perform TLS Handshke (secure channel establishment). This library uses an interface, which allows to substitute some of it's functionality by third-party crypto implemementations.For example mbedTLS used in FreeRTOS, where OPTIGA™ Trust M can be used to substitute the standard software crypto implemementation functions of ECDSA, ECDH and RSA.

OPTIGA™ Trust M integration to mbedTLS

The functions that are needed to be integrated into mbedTLS are defined below.

Platform Abstraction Layer

Platform abstraction layer for platform low level drivers like I2C, Timer, GPIO, socket and other platform dependencies. Modify the files based on the target platform. Generic steps are described here.

Initialization API's

These are the API's which initializes the OPTIGA™ Trust M chip. Define these API's in the file “optiga_trust.c” and update corresponding header file. Copy these files under folder utilities

• static volatile optiga_lib_status_t optiga_lib_status
  Call back status is stored in this variable.
• optiga_util_callback
  This is used as call back function to return the API execution status after the operation is completed asynchronously.
• read_certificate_from_optiga
  This API reads DER encoded device certificate stored in OPTIGA™ security chip and converts to PEM encoding format.
• read_trust_anchor_from_optiga
  This API reads the data from trust anchor oid.
• write_optiga_trust_anchor
  This API writes the trust anchor to OPTIGA™ trust anchor OID.
• write_data_object
  This API writes the device certificate gives as an input to the specified oid in the OPTIGA™ security chip.
• optiga_trust_init
  This API initializes the OPTIGA™ security chip by calling the open application. It also writes the device certificate to the Security chip.

For more information refer to the example_optiga_util_read_data.c and example_optiga_util_write_data.c

Cryptographic API's

• ECDH

  This section explains about porting of ECDH key pair generation and shared secret computation API's. Entire “trustm_ecdh.c” file must be guarded under macro MBEDTLS_ECDH_C
  

  • #define OPTIGA_TRUSTM_KEYID_TO_STORE_PRIVATE_KEY 0xE103
    This macro defines the session oid used to store shared secret generated

  • static void optiga_lib_status_crypt_event_completed_status;
    This static variable will be used to store call back status.

  • optiga_crypt_event_completed
    The above function used as a call back function to return the API execution status after the operation is completed asynchronously.

  • mbedtls_ecdh_gen_public
    

    • This API generates ECC key pair using OPTIGA™ Security chip, stores the private key in the security chip and returns only the public key. The returned public key need to be stored into the mbedtls structure.
      
    • This API need to be defined under the macro MBEDTLS_ECDH_GEN_PUBLIC_ALT.

  • mbedtls_ecdh_compute_shared

    • This API computes shared secret using OPTIGA™ Security chip and returns the shared. This returned shared secret need to be stored into the mbedtls structure.
    • This API need to be defined under the macro MBEDTLS_ECDH_COMPUTE_SHARED_ALT.
  
  

  For more information about OPTIGA™ Trust M Key generation and shared secret operation refer example_optiga_crypt_ecdh.c

• ECDSA
  

  This section explains about porting of ECDSA sign and ECDSA verify API's. Entire “trustm_ecdsa.c” file must be guarded under macro MBEDTLS_ECDSA_C
  

  • static void optiga_lib_status_t crypt_event_completed_status;
    This static variable will be used to store call back status.

  • optiga_crypt_event_completed
    This is used as callback function to return the API execution status after the operation is completed asynchronously.

  • mbedtls_ecdsa_sign
    

    • This API generates ECC Signature using ECC private key stored in OPTIGA™ Security chip for the given input and returns the generated signature. This generated signature need to be stored into the mbedtls structure.
    • This API need to be defined under the macro MBEDTLS_ECDSA_SIGN_ALT

  • mbedtls_ecdsa_verify
    

    • This API verifies ECC Signature using OPTIGA™ Security chip for the given input public key, input data and signature.This API need to be defined under the macro MBEDTLS_ECDSA_VERIFY_ALT.
    
    

  For more information about OPTIGA™ Trust M Key generation and shared secret operation refer example_optiga_crypt_ecdsa_sign.c and example_optiga_crypt_ecdsa_verify.c

• RSA
  

  This section explains about porting of RSA sign,verify,encrypt,decrypt API's. Entire “trustm_rsa.c” file must be guarded under macro MBEDTLS_RSA_ALT
  Once the macro "MBEDTLS_RSA_ALT" is enabled, mbedTLS expects rsa_alt.h header file. Create this file if not present already and file should have mbedtls_rsa_context

  • define TRUSTM_RSA_PRIVATE_KEY_OID (0xE0FC)
    This macro defines the RSA private key inOPTIGA™ Trust M used during RSA sign and RSA decrypt.
  • static volatile optiga_lib_status_t crypt_event_completed_status;
    This static variable will be used to store call back status.
  • optiga_crypt_event_completed
    This is used as call back function to return the API execution status after the operation is completed asynchronously.
  • mbedtls_rsa_create_public_key_bit_string_format
    This function forms the public key in DER BIT STRING format.
  • mbedtls_rsa_get_sig_scheme_digest_len)
    This function used to get signature algorithm and digest length based on the hash algorithm.
  • mbedtls_rsa_get_sig_len_key_type
    This function used to get signature length and key type based on modulus length.
  • mbedtls_rsa_rsassa_pkcs1_v15_verify
    This API verifies the signature using OPTIGA™ security chip using the public key.
  • mbedtls_rsa_rsassa_pkcs1_v15_sign
    This API generates signature for the given digest using the RSA private key stored in OPTIGA™ security chip and the signature generated need to be stored in the mbedTLS signature structure.
  • mbedtls_rsa_rsaes_pkcs1_v15_encrypt
    This API encrypts the input message using OPTIGA™ security chip.
  • mbedtls_rsa_rsaes_pkcs1_v15_decrypt
    This API decrypts the message using the RSA private key stored in OPTIGA™ security chip.
    

  For more information refer example_optiga_crypt_rsa_sign.c , example_optiga_crypt_rsa_verify.c , example_optiga_crypt_rsa_encrypt_message.c , example_optiga_crypt_rsa_decrypt.c .