/alios-things-optiga-trust-m

AliOS with hardware-based security powered by OPTIGA Trust M2 ID2

EN | 中文

Alibaba cloud IoT with OPTIGA™ Trust M2 ID2

Introduction

This document describes how to setup the environment to demonstrate mqttapp using AliOS-Things software package with the OPTIGA™ Trust M2 ID2 ESP32-DevKitC V4.

References

Definition Source
[1] ESP32-DevKitC V4_usermanual espressif
[2] Infineon_I2C_Protocol Infineon

Abbreviations

Abbreviation Definition
API Application Programming Interface
ESP32 ESP32-DevKitC V4
I2C Inter Integrated Circuit
IoT Internet of Things
OS Operating System
PAL Platform Abstraction Layer
RSA Rivest-Shamir-Adleman
PC Personal Computer
RST Reset
SCL Serial Clock
SDA Serial Data
SW Software
TTL Transistor Transistor Logic
USB Universal Serial Bus

OPTIGA™ Trust M2 ID2

OPTIGA™ Trust M2 ID2 is a security solution with a pre-programmed security controller with wide range of security features. It supports secure data, key and metadata object update, hibernate and cryptographic toolbox functionalities, secure communication, platform integrity, data store protection and lifecycle management for Connected Device Security. This document describe the porting guide of OPTIGA™ host library for other platforms supported by AliOS-Things.

OPTIGA™ Trust M2 ID2 with ESP32-DevKitC V4

OPTIGA™ Trust M2 ID2 ESP32-DevKitC V4 is designed to provide all the components required to setup the environment to demonstrate the features of the OPTIGA™ Trust M2 ID2.

Evaluation Kit Components

No. Item Description
1 ESP32-DevKitC V4 Hardware Evaluation board for ESP32 microcontroller.
2 ESP32 DevKitC Adapter for Shield2Go ESP32-DevKitC V4 compatible connector to add Shield2Go board on ESP32-DevKitC V4.
3 OPTIGA™ Trust M2 ID2 Security Shield2Go Shield2Go board contains OPTIGA™ Trust M2 ID2 chip. It is compatible with Infineon’s ESP32 DevKitC Adapter for Shield2Go.
4 Micro USB to USB cable The cable provides DC supply to ESP32-DevKitC V4 and to flash software.

System Setup

This section explains the basic components required for system setup.

System Overview

System Overview

This system consists of the following components:

  1. ESP32-DevKitC V4
    • The ESP32-DevKitC V4 is an evaluation board with ESP32 Microcontroller from espressif. For more information refer document [1].
    • It is used as a reference platform to simulate the Host.
    • It interacts via I2C.
  2. ESP32 DevKitC Adapter for Shield2Go
    • It acts as a gateway to add Shield2Go boards onto ESP32-DevKitC V4.
  3. OPTIGA™ Trust M2 ID2 Security Shield2Go
    • Shield2Go board contains OPTIGA™ Trust M2 ID2 chip.
      The following interface/connection is done among the above components:
    • Micro USB data cable (with Data line) from PC is connected to ESP32-DevKitC V4 to supply power.

Hardware Setup

The hardware required to run OPTIGA™ Trust M2 ID2 setup is described in this section.

ESP32-DevKitC V4

ESP32 DevKitC V4

Connector supports I2C, reset pin and power supply interfaces among others.

ESP32-DevKitC V4 Pin Information
No. Description Pin
1 I2C SCL GPIO 22
2 I2C SDA GPIO 21
3 RST GPIO 25
4 VCC GPIO 26
5 GND GND

For more information about the ESP32 Specification, Architecture and Design/Schematic, refer document [1]

ESP32 DevKitC Adapter for Shield2Go

The ESP32 DevKitC adapter is an evaluation board that allows users to easily combine different Shield2Go boards to ESP compliant ecosystem, for fast evaluation of IoT systems. With its solderless connectors, it allows users to easily stack Shield2Go boards instead of soldering it. The adapter design is derived from ESP32-DevKitC V4 evaluation board.

ESP32 DevKitC Adapter for Shield2Go

ESP32 DevKitC adapter features are as follows:

  • Provide power supply and connectivity for Shield2Go boards.
    • Level shifting handling capabilities between CMOS 3.3V and TTL 5V.
      • Solder bridges to selectively deactivate level shifting.
      • Additional pins enable setting the reference voltages for level shifting.
    • Separate power control switches for Socket.

More information is available at Infineon website.

Shield2Go Security OPTIGA™ Trust M2 ID2

Shield2Go boards are equipped with featured Infineon ICs and provide a standardized form factor and pin layout, allowing a ‘plug and play’ approach for easy prototyping.

OPTIGA™ Trust M2 ID2 Shield2Go

The OPTIGA™ Trust M2 ID2 Shield2Go is equipped with OPTIGA™ Trust M2 ID2 security chip. It allows users to develop system solutions by combining Shield2Go with ESP32 DevKitC Adapter for Shield2Go and ESP32.

Note: Ensure no voltage supplied to any of the pins exceeds the absolute maximum rating of Vcc + 0.3 V.

Software Setup

This section describes the software used in ESP32 to run the AliOS-Things OPTIGA™ Trust M2 ID2 setup.

Software Components

All the software components required on AliOS-Things for ESP32 are explained in the following sections.

ESP32-DevKitC V4
  1. OPTIGA™ Trust M2 ID2 Host Library consists of the following:
    • Service Layer
      The layers (Util and Crypt) provide APIs to interact with OPTIGA™ for various use-case functionalities.
    • Access Layer
      This layer manages the access to the command interface of OPTIGA™ security chip. It also provides the communication interface to the OPTIGA™.
    • Platform Abstraction Layer
      This layer provides platform agnostic interfaces for the underlying HW and SW platform functionalities used by OPTIGA™ libraries.
    • Platform Layer
      This layer provides the platform specific components and libraries for the supported platforms.
  2. IFX I2C Protocol
    This is an implementation as per document [2].
  3. ESP32 I2C Driver
    These are low level I2C device driver for I2C communication from ESP32 to OPTIGA™ Trust M2 ID2 Security chip.

PC Requirements and Configurations

PC Requirement

A 32-bit or 64-bit PC with Windows 7/10 Operating System with the below requirements need to be used for setting up ESP32 to run the AliOS-Things using OPTIGA™ Trust M2 ID2 setup:

  1. One USB port.

  2. Python 2.7.14 version to install AliOS-Thing dependency packages
    Link to download Python 2.7.14: Download link.

  3. Visual Studio Code for development environment.
    Link to download Visual Studio Code: Download link

  4. Git for downloading source code.
    Link to download git: Download link

  5. FTD driver to access ESP32 via COM port.
    Link to download FTD driver: Download link

  6. ASN1 editor require to extract OPTIGA™ supported RSA fields from key provided by Ali key distribution center user is free to use any editor which supports ASN format.
    Link to download ASN1 editor: Download link

    Note: Add C:\Python27 and C:\Python27\Scripts path to environment variable in the beginning of the environment variable list.

AliOS-Things environment setup Using OPTIGA™ Trust M2 ID2

Quick Setup

  1. Setup Visual Studio Code as describe from the link
  2. Create a folder in < workspace > (here "workspace" is the folder where AliOS-Things repository will be cloned, for example %USERPROFILE%/Documents)
  3. Open command prompt and go to the directory < workspace >
  4. Download aos-2.1-esp32-with-optiga-se.patch file from the link (Refer section for the patch contain).
  5. Execute below commands to download AliOS-Things source package
  git clone https://github.com/alibaba/AliOS-Things.git
  cd AliOS-Things
  git checkout rel_2.1.0
  git pull origin rel_2.1.0
  git apply aos-2.1-esp32-with-optiga-se.patch

Note: Ignore below warnings while applying the patch

Warning while applying patch
  1. Add project to Visual studio code (e.g. Go to File->add folder to workspace->select top level directory of AliOS-Things repository).
  2. Open new Terminal in visual studio code (go to Terminal ->New Terminal)
  3. To upgrade aos-cube, follow the below steps in Visual Studio Code Terminal
  pip install --upgrade setuptools
  pip install --upgrade wheel
  pip install --upgrade aos-cube

Configure and build mqttapp use case for ESP32-DevKitC V4

This section describes how to configure and build mqttapp example in AliOS-Things source code for ESP32.
Note: To use customize Device name and secret please refer this section.

Configuration
  1. Execute below command to configure the mqttapp example (make sure you run the terminal in the root of the AliOS-Things repository)
  aos make mqttapp@esp32devkitc -c config

Note: while execution above step if below error occurs

Error while configuring the setup

Execute below command in the terminal

  git clone https://gitee.com/alios-things/kconfig-frontends-win32.git ./build/kconfig/Win32/

Repeat from step 1

  1. Open < workspace >\AliOS-Things\build\build_rules\toolchain\ aos_toolchain_xtensa.mk file and check the variable assigned with the below specified value.
  COMPILER_SPECIFIC_OPTIMIZED_CFLAGS    := -O0
  1. Execute below command to enable OPTIGA™ host library and iTLS
  aos make menuconfig
  1. Below options need to be selected for ID2
  Security -> Link Security ID2
  Security -> Root of trust, SE-KM
  Security -> Root of trust, OPTIGA
  Security -> Lightweight TLS Support by ID2
Menuconfig option to Security section
Menuconfig option to select ID2, SE-KM, OPTIGA
  1. Change below options to change TLS to iTLS
  Deselect  Middleware -> Linkkit Configuration -> Linkkit HAL Config ->support TLS
  Select Middleware -> Linkkit Configuration -> Linkkit HAL Config ->support ITLS
Menuconfig option to Middleware
Menuconfig option to Linkkit Configuration
Menuconfig option to Linkkit HAL config
Menuconfig option to deselect support TLS
Menuconfig option to select support ITLS
  1. Save and exit from menuconfig
Build source code
  1. To build source code execute below command (make sure you are running python2.7 "python -V")
  aos make

Steps to download example hex file to ESP32-DevKitC V4

  1. Execute below command to flash the generated HEX file (Check the COM port number from device manager which is connected with your ESP32-DevKitC V4)
  aos upload mqttapp@esp32devkitc
Selecting COM port

Steps to execute mqttapp

  1. Execute below command to run mqttapp (Check the COM port number from device manager which is connected with your ESP32-DevKitC V4)
  aos monitor COMn 115200(‘n’ is the port number assigned to ESP32-DevKitC V4)
  1. Press reset button
  2. To configure Wi-Fi execute below command (after restart press enter in serial port console)
  netmgr connect wifi_name wifi_password
  1. Below is the example log of successful cloud connection
Successful client server authentication log of mqttapp
Server side hosted log

FAQs

How to check connectivity in Ali cloud

  1. Access the website : https://www.alibabacloud.com/ , and push the button of "Free Account".
Ali Free Account
  1. Fill in your registration information, and push the "Confirm" button.
Register Ali Free Account
  1. Finish the Verification process by your Email or by your Phone.
Ali Free Account Verification
  1. Now you have an individual account. And please finish the "Basic Information" & "Payment Information" registration.
Ali Free Account
  1. Use this account to login the "IoT Platform", in order to create a new Ali IoT device
Login IoT Platform
  1. Select the Tab of "Documentation".
Ali IoT Platform Documentation
  1. Click Quick Start -> Use IoT Platform -> Create products and devices, here is a detail manual to guide you how to create an Ali IoT Device.
Create a new Product
  1. Note: Please select the "ID2" in the "Authentication Mode" list. But so far it's not aviable for oversea customers.
Select ID2 for Authentication Mode
  1. When you create product successfully, you can view it in Device Management Panel. Push the "View" button to get the "ProductKey" & "ProductSecret“
Get "ProductKey"&"ProductSecret"
  1. Replace the "ProductKey" & "ProductSecret" in the .\app.\example\mqttapp\mqtt_example.c, and make a new for "#define DEVICE_NAME", ignore the "DEVICE_SECRET"
Update mqtt_example.c

  1. Compile your project.

  2. After download the new image and power on you device, then you will see the device status on the panel of : IoT Platform Console -> Maintenance -> Real-time Monitoring

Monitoring your device status

How to change the crypto configuration in AliOS-Things source code

This section describes the modification require to use key type as per needs.

RSA

  1. Below Modification is required in AliOS-Things\security\irot\se\chipset\chip_template\chip_config.h
#define CHIP_CRYPTO_TYPE_CONFIG   CHIP_CRYPTO_TYPE_RSA
  1. Below Modification is required in AliOS-Things\security\id2\aos.mk
ifeq ($(CONFIG_LS_KM_SE), y)
  $(NAME)_DEFINES     += ID2_CRYPTO_TYPE_CONFIG=ID2_CRYPTO_TYPE_RSA

AES

  1. Below Modification is required in AliOS-Things\security\irot\se\chipset\chip_template\chip_config.h
#define CHIP_CRYPTO_TYPE_CONFIG   CHIP_CRYPTO_TYPE_AES
  1. Below Modification is required in AliOS-Things\security\id2\aos.mk
ifeq ($(CONFIG_LS_KM_SE), y)
  $(NAME)_DEFINES     += ID2_CRYPTO_TYPE_CONFIG=ID2_CRYPTO_TYPE_AES

How to create and update new ID2 device node

  1. Create an ID2 device node in https://cn.aliyun.com/
  2. Replace the device name and device secret in the below section present in AliOS-Things\app\example\mqttapp\mqtt_example.c file
#define DEVICE_NAME      "your device name"
#define DEVICE_SECRET   "your device secret"
#define PRODUCT_KEY      "your product key"
#define PRODUCT_SECRET   "your product secret"

How to enable power off option to OPTIGA™ chip

  1. Before doing an OPTIGA™ chip power off, it is recommended to wait until the security event counter on OPTIGA™ reaches zero. This can lead to certain time delays which leads to connection timeout on the server side.
  2. The above code flow is implemented in irot_hal_cleanup but it is disabled by default using macro OPTIGA_SE_ENABLE_POWER_DOWN.
  3. To enable the code flow, uncomment the macro definition present in AliOS-Things\security\irot\se\src\core\optiga_se_adapter.c file
#define OPTIGA_SE_ENABLE_POWER_DOWN

How to port OPTIGA™ host library to different platform

The host library present in AliOS-Things\3rdparty\experimental\optiga location can be port to different platform supported by the AliOS-Things framework.

  1. Platform abstraction layer for platform low level drivers like I2C, Timer located in AliOS-Things\3rdparty\experimental\optiga\pal can be modified as described here.
  2. User need to use platform specific libitls.a library which should be present in AliOS-Things\security\itls\lib<platform specific folder>.

What Infineon patch file contain

Below are the modification present in the patch.

  1. OPTIGA™ host library including platform dependent file for ESP32 specific.
  2. Modified i2c driver to support read and write operation for maximum 20bytes of data
  3. Shielded connection option is disabled due to the limitation of the i2c driver.
  4. ESP32 platform supported libitls.a library.