PEARL IoT v2 - IDEMIA€¦ · 7 Integration Guide PEARL IoT v2.2 2 / System 2.1 > Overview PEARL...

PEARL IoT v2.2 Integration Guide (Public version)

May 2019

2 Integration Guide PEARL IoT v2.2

Table of content

1 / Documents 4

1.1 > History 4

1.2 > Document Overview 4

1.3 > Abbreviations 5

1.4 > Referenced documents 6

2 / System 7

2.1 > Overview 7

3 / Device Architecture 8

3.1 > Overall Architecture Block Diagram 8

3.2 > Role and Component 8

3.3 > IDEMIA deliverables and functionalities 8

4 / MiddleWare 9

4.1 > A companion software 9

5 / PEARL IoT Hardware 10

5.1 > DFN6 Pin List 10

5.2 > DFN6 Drawing 11

5.3 > Electrical characteristics 12 5.3.1 > Typical Electrical Application 13 5.3.2 > Secure Element General Architecture 14

6 / API Descriptions 16

6.1 > Generalities 16 6.1.1 > Commands availability 16 6.1.2 > BIST process 16

6.2 > System 17 6.2.1 > Put Data 17 6.2.2 > Get Data 17 6.2.3 > Get Random 17 6.2.4 > Message Level Security (MLS) 17

6.3 > Nano HSM 20 6.3.1 > Calculate SHA-256 20 6.3.2 > Data Management (Safety box) 20

6.4 > Sigfox 20

6.5 > LoRaWAN 21 6.5.1 > LoRaWAN frame 21 6.5.2 > LoRaWan security keys 22 6.5.3 > Join Request 22 6.5.4 > ReJoin Request 23


6.5.5 > Join Accept 23 6.5.6 > Secure Uplink 23 6.5.7 > Verify Downlink 24

7 / Data Objects 25

7.1 > Data object structure 25

7.2 > System 26

7.3 > Safety Box 27

7.4 > LoRaWAN profiles and management 27

Re

f. 2

00

26

05 I

SS

UE

1


1 / Documents

1.1 > History

Version Date Revision

1.0 24/05/2019 First release

1.2 > Document Overview

The objective is to provide various details from the ecosystem to the low-level algorithms using the commands supported by the PEARL IoT Secure Element. The description is static one. However, in order to ease the understanding, some message Sequence Charts were added. Targeted audience is developers of the business application software that will communicate with PEARL IoT Secure Element. Skills prerequisite should include knowledge of security basics (cryptography, authentication mechanisms …) and I2C bus interface.


1.3 > Abbreviations

An abbreviation is a shortened form of a word or phrase and used widely to represent it. The following table includes all the abbreviations that are used in the current specification:

Abbreviation Description End Use

ABP Activation By Personalization LoRaWAN

ADR Adaptive Data Rate LoRaWAN

AES Advanced Encryption Standard Generic

AES128 CBC AES Cipher Block Chaining Generic

AK Administration Key Generic

API Application Programmable Interface Generic

AppKey Application Key LoRaWAN

AppSKey Application Session Key LoRaWAN LoRaWAN

ASP Application Service Provider Generic

CBC Cipher Block Chaining Generic

CIN Card Identification Number Generic

CMAC Cipher based Message Authentication Code Generic

HSM Hardware Security Module Generic

IoT Internet of Things Generic

KMS Key Management System Generic

MAC Message Authentication Code Generic

MCU Multipoint Control Unit Generic

MHDR Message Header LoRaWAN

MIC Message Integrity Code LoRaWAN

MW MiddleWare Generic

NwkSKey Network Session Key LoRaWAN

O/S Operating System Generic

OTAA Over The Air Activation LoRaWAN

RoT Root of Trust Generic

SE Secure Element (PEARL IoT) Generic

SHA 1/256/512 Secure Hash Algorithm Generic

Table 1: Abbreviations


1.4 > Referenced documents

Abbreviation Reference Date

[LORAWAN_SPEC] LoRaWAN Specifications version V1.0.3 & 1.1

Refer to : https://lora-alliance.org/resource-hub

July 2018 & October 2017

[I2C_PROT] I2C protocol NXP Rev 6 UM10204 4 Apr. 2014

[Sigfox_SPEC] Sigfox connected objects Radio specifications rev1.3

https://build.sigfox.com/sigfox-device-radio-specifications 13th February 2019

https://lora-alliance.org/resource-hub

http://cache.nxp.com/documents/user_manual/UM10204.pdf

https://build.sigfox.com/sigfox-device-radio-specifications



2 / System

2.1 > Overview

PEARL IoT is a tiny Secure Element based on a secure tamper-proof chip, the IDEMIA StarChip SCO256I and the PEARL IoT O/S. The PEARL IoT is a managed Secure Element. It is delivered pre-loaded with security credentials used to establish a root of trust from a device point of view. The M-TRUST is the corresponding security server, which manages and remotely updates the PEARL IoT credentials. The PEARL IoT is a versatile Secure Element (SE) and can be adapted to any network backend. It can be directly soldered onto the end device board without any specific initialization. PEARL IoT is a slave Secure Element companion connected to the IoT end device through an I2C bus and is capable of providing high level of cryptography to connected device and storing all secure credentials and keys of device applications. Moreover, PEARL IoT integrates advanced security functionality to support the LoRaWAN and Sigfox environment.

Figure 1: PEARL IoT & M-TRUST in IoT System


3 / Device Architecture

3.1 > Overall Architecture Block Diagram

3.2 > Role and Component

Main CPU Environment + device Applicative Hardware (sensor, actuator, connectivity…)

PEARL IoT (or SE): Tamper resistant chip connected to the communication module through I2C interface

Target I2C layer, timer management, Memory: Software implementing resources required by the MiddleWare

MiddleWare (or Wrapper): a software library provided by IDEMIA to easily integrate the PEARL IoT hardware. The MiddleWare defines some native APIs to communicate with the PEARL IoT.

3.3 > IDEMIA deliverables and functionalities

PEARL IoT hardware component: Perform following functionalities:

o Implement the security layer for LoRaWAN communication

o Implement the security layer for Sigfox communication

o Additional set of security services can be enabled for specific applications

MiddleWare: Software companion delivered as a reference implementation to ease the integration of PEARL IoT hardware component.

Figure 2: Device General Architecture


4 / MiddleWare

4.1 > A companion software

To facilitate the integration of the PEARL IoT secure element, a companion software can be used (MiddleWare). The role of this companion is to offer some APIs (SE API) usable by the end device’s software.

API for SE system (must be used to connect the SE, initiate the communication between the main device and the SE)

API for LoRaWAN™ usage (must be used through a LoRaWAN™ stack)

API for Sigfox™ usage (must be used through a Sigfox™ stack)

This companion needs to use some of the end device resources (Memory access, I2C I/O, timer, etc…). To be independent of one target, the companion defines some Resources API to be implemented by the end device’s business application software.

Figure 3: Typical Software Integration


5 / PEARL IoT Hardware

Secure Element PEARL IoT in form factor DFN6

Communication protocol:

o I2C

o SE address on I2C: ‘5Ch’

5.1 > DFN6 Pin List

Pin Name Supply Role

Vcc -- Power Supply from 1.62V to 5.5V

SDA Vcc I2C Serial Data

SCL Vcc I2C Serial Clock

GPIO Vcc General Purpose Input Output

Gnd -- Ground

Table 2: DFN6 Pin List

Figure 4: DFN6 Bottom View


5.2 > DFN6 Drawing

Figure 5: DFN6 drawing


5.3 > Electrical characteristics

Stresses beyond those listed under “Absolute Maximum Ratings” may cause permanent damage to the device. Those are stress rating only, and functional operation of the device of these or other conditions beyond those indicated in the operational sections of the specification is not implied. Exposure to the absolute maximum rating conditions for extended periods may affect device reliability.

Limits

Symbol Parameter Condition Min Typical Max Unit

Vcc Supply Voltage -0.3 7.5 V

V All pins -0.3 Vcc+0.3 V

Tstg Storage temperature -40 105 °C

ESD Electrostatic discharge resistance

Human Body model[1]

6 kV

[1]: Equivalent to discharging a 100pF capacitor through 1.5kΩ

Table 3: Absolute Maximum Ratings

All the table gives electrical characteristics of SCO256i under typical conditions of temperature and Vcc.

Limits

Symbol Parameter Condition Min Typical Max Unit

Vcc Operating Voltage 1.62 5.5 V

Top Operating Temperature -40 105 °C

Icc Power supply Current Run: 20MHz 2.6 mA

fvfo CPU clock frequency VFO @20MHz 20 MHz

Table 4: Operating Conditions


5.3.1 > Typical Electrical Application

Figure 6: Typical Electrical Application

The PEARL IoT Secure Element needs between 2 and 3 mA to operate, so it is directly powered from an MCU I/O port (Vcc_control I/O). The I2C pull-up resistors (Rpull : typical 10 KΩ) are connected to the same MCU I/O port. When the PEARL IoT functions are needed, the I/O port is set to 1, as a result the PEARL IoT and the pull-up resistors are activated. Once the security function is finished, the I/O port is pulled down and there is no residual power consumption. The PEARL IoT power supply has to be between 1.62V and 5.5V. The device will not start if the power supply is not in the proper range. A decoupling capacitor of 100nf is needed between the Gnd and the Vcc of the chip. PIN 6 can be left unconnected. PIN 5 (GPIO) can be left unconnected or drive an external component via PEARL IoT software dedicated function (actioner use case).


5.3.2 > Secure Element General Architecture

Figure 7: Secure Element General Architecture


Layer Module Hard/Soft Descriptions

Comm

I2C H I2C physical layer

ISO low layer S Low layer protocol

I2C low layer S Low layer protocol

I/O layer S Layer protocol

Define I/O buffer and manage APDU format

Dispatcher S Dispatch command to application according to instruction

Memory

NVM H Non Volatile Memory area

RAM H Random Access Memory area

Memory driver S Implement basic function to memory management

Wear Levelling S Implement anti-stress mechanism according to variable to be recorded

Memory Management

S Implement high level function according to variable to be recorded (key, data, etc….)

Crypto

AES HW

accelerator H Basic hardware function usable for AES calculation

MUL32 H Basic hardware mathematical function

TRNG generator H Hardware Random Generator

RNG driver S Software API for Random Generator

AES 128 S AES 128 implementation

SHA 256 S SHA 256 implementation

Applicative Crypto Algorithms

S Implement high level service for encryption.

e.g. AES_CBC, AES-CMAC, etc…

Application

System S Implement global service for SE.

e.g. Life Cycle State, Root of Trust, etc…

LoRaWAN S

Implement LoRaWAN service.

e.g. Secure Uplink, Check Downlink, Join process, etc…

Sigfox S Implement SIGFOX service.

e.g. Secure Uplink, Check Downlink, etc…

Table 5: Component description


6 / API Descriptions This chapter describes all commands supported by PEARL IoT according to targeted Application and Life Cycle State.

6.1 > Generalities

6.1.1 > Commands availability

Tag Name Content

System

'04' Put Data Data object to store/update in the SE memory

'0D' Get Data Return Data object value

'10' Get Random Return a random value according to the length required

'20' MLS UnWrap UnWrap MLS frame received by the MCU

'21' MLS Wrap Wrap Applicative data in MLS format.

Nano HSM

'52' Compute SHA-256 Compute a SHA256 on input data

LoRaWAN

'60' Secure Uplink (LoRaWAN Wrap)

Build Applicative data field in LoRaWAN format

'61' Verify Downlink LoRa UnWrap Verify a downlink LoRaWAN frame

'62' LoRa JoinRequest Build a Join Request

'63' LoRa RejoinRequest Build a Rejoin Request

'64' LoRa JoinAccept Verify a Join Accept frame

Sigfox

'70' SIGFOX Secure Uplink Build a Secure Uplink

'71' SIGFOX Verify downlink Verify a Secure Downlink Sigfox frame

GPIO

'E0' Read GPIO Read the GPIO line state.

'E1' Write GPIO Set the GPIO line state

Table 6: Command list

6.1.2 > BIST process The goal of this process is to check PEARL IoT component usability. The component will be declared ready to use when the status of following commands are successful.

getData to retrieve the Serial Number.

getData to retrieve the CIN.

getRandom to return a random value. See the following section (6.2) to build these commands.


6.2 > System

6.2.1 > Put Data This command allows to put all type of data to record in PEARL IoT. For detail of data and format refer to Section 7

6.2.2 > Get Data This command allows to get all type of data to record in PEARL IoT. For detail of data and format refer to Section 7

6.2.3 > Get Random Use this command to return a random with a required length. For detail of data and format refer to Section 7

6.2.4 > Message Level Security (MLS) Introduction

MLS is a secure channel protocol optimized for IoT applications. It has been designed to provide an Authenticated Encryption of the plain messages that is bearer independent. MLS can be used to:

Provide a basic encryption / decryption functionality for end device

Enable the device to use M-TRUST security services MLS protocol provides multiple channels (up to 8) for administration and service. Its manageable fields are identified by generic tags. Complete MLS specification is available on request and subject to non-disclosure agreement. Ask your IDEMIA sales representative.

MLS – Wrap data

This command will be used to format input data in MLS format according to a channel. The channel to use must be configured as a “Service channel” The channel to use to wrap applicative date must be in range [2..7] as defined in default configuration. In case of “Remote response ready to send”, the command will return the response recorded whatever the input parameters (channel and data)

Figure 8: Wrap applicative Data


MLS – UnWrap data

This command will be used to unwrap a MLS formatted message. If the message is a “Service message”, the payload in plain text will be return with the channel ID If the message is a “Command message”, the payload will be processed internally. A status of Unwrap execution will be return with additional info:

Reset SE requested

LoRaWAN join request requested

MLS response “ready to send”

Figure 9: Service Message - UnWrap Applicative Data

Figure 10: UnWrap PEARL IoT Command without response


Figure 11: UnWrap PEARL IoT Command with response

Figure 12: UnWrap PEARL IoT Command with response “MW auto”


6.3 > Nano HSM

6.3.1 > Calculate SHA-256 Use this command to hash data with SHA-256 algorithm. Basic operations embedded in PEARL IoT are:

Calculate SHA-256 with chaining command Chaining cannot be continued after a reset.

6.3.2 > Data Management (Safety box) This functionality allows to record applicative data in PEARL IoT component. The device can set and retrieve data through two generic commands (refer to section 7 for detail):

Put Data

Get Data The type of data must be managed according to the number of update planned during the life of the device:

One set of data (16) with the number max of write is 1 million. (ID is 1 byte in range [‘00h’..’0Fh’])

One set of data (16) with a low number of write. (ID is 1 byte in range [‘80h’..’8Fh’]) The maximum size of data is 252 bytes.

6.4 > Sigfox

On February 13th, 2019, Sigfox made public its radio specifications for connected devices. (Refer to https://build.sigfox.com/sigfox-device-radio-specifications) In the section 5.3 “Applicative payload encryption” of the specification (Sigfox connected objects Radio specifications rev1.3), it is explained that “the Payload encryption is a procedure that encrypts the payload of applicative messages over the air, in both uplink and downlink communication. It uses an AES128 algorithm in mode CTR with an encryption key (Ke), unique per end-point. The procedure is specified in a dedicated Sigfox specification document.” IDEMIA has fully implemented this dedicated specification. For more information on the PEARL IoT implementation, please contact your IDEMIA sales representative to get access to the full documentation which will be delivered after a Non-Disclosure Agreement has been signed.



6.5 > LoRaWAN

6.5.1 > LoRaWAN frame A LoRaWAN frame is structured as follow:

Figure 13: LoRaWAN Frame Structure


6.5.2 > LoRaWan security keys

What LoRaWan 1.0.x LoRaWan 1.1.x Description

Device root Keys AppKey NwkKey AppKey

AES-128 root keys unique per end device. Root keys are used to derive session keys

Join Server: to point to the targeted JS

AppEUI JoinEUI Uniquely identified the Join Server

Join Server keys JSIntKey JSEncKey

JSIntKey is used to MIC:

ReJoin-Request type1

Join Accept answers

JSEncKey is used to encrypt the Join Accept triggered by a Rejoin-Request

Network Uplink session key for MIC calculation

NwkSKey FNwkSIntKey These keys are derivated from the NwkKey root key

Network Downlink session key for MIC calculation

NwkSKey SNwkSIntKey

NwkSKey is derivated from AppKey root key SNwkSIntKey is derivated from NwkKey root key

Session key for encryption of the MAC payloads

AppSKey NwkSEncKey AppSKey and NwkSEncKey are derivated from AppKey root key

Table 7: LoRaWAN Security Keys

6.5.3 > Join Request The join procedure is always initiated from the end-device by sending a join-request message whose structure is:

MHDR Join-Request Data MIC

The message integrity code (MIC) value for a join-request message is calculated by using the AppKey (LoRaWAN 1.0.x) or by using the NwkKey (LoRaWAN 1.1.x) See LORAWAN_SPEC for more details. AppKey and/or NwkKey are retrieved using M-TRUST Key Management System and IDEMIA derivation algorithm.


6.5.4 > ReJoin Request Once activated a device MAY periodically transmit a ReJoin-request message on top of its normal applicative traffic. This ReJoin-request message periodically gives to the network the opportunity to initialize a new session context for the end-device. As for the Join Request command, the message structure is:

MHDR ReJoin-Request Data MIC

See LORAWAN_SPEC for more details about MIC generation. The session keys must be available:

AppSKey and NwkSKey for LoRaWAN 1.0.x

AppSkey, NwkSEncKey, FNwkSIntKey and SNwkSIntKey for LoRaWAN 1.1.x

6.5.5 > Join Accept This function allows to check the Join Accept message sent by the server when the end-device is allowed to join a network and then to derive the different session keys requested by the LoRaWAN protocol.

6.5.6 > Secure Uplink If a LoRaWAN data frame carries a payload (FRMPayload), it MUST be encrypted before the message integrity code (MIC) is calculated. Uplink messages structure is:

MHDR MACPayload MIC

With MACPayload:

FHDR FPort FRMPayload

The encryption scheme used is based on the generic algorithm described in IEEE 802.15.4/2006 using AES with a key length of 128 bits. Once encrypted, the message integrity code (MIC) is calculated over all the fields in the message. msg = MHDR | FHDR | FPort | Enc(FRMPayload) See LORAWAN_SPEC for more details.


6.5.7 > Verify Downlink This function verifies the downlink message integrity and signature. See LORAWAN_SPEC for more details. If downlink data encapsulate MLS command processed by the PEARL IoT, a secure Uplink is necessary to retrieve data to send to the server

Figure 14: UnWrap LoRaWAN MLS command


7 / Data Objects Data objects are used to handle and manage any kind of data and information of the secure element. Their purpose is to identify the data and to link them to the corresponding value. These values can be simple stream of bytes, secrets, identifiers, counters, configurations or security policy like access rights. The two main operations supported on the data objects are the following:

PutData command: The “Set” operation that is used to load and store such object into the secure element.

GetData command: The “Get” operation that is used to retrieve data from the secure element. Both operations are done under access control with different rights depending on the originator of the request, the operation nature and the type of data objects. Other variables and possibilities not described here could be modified on chip configuration in production. Please to ask IDEMIA for more information.

7.1 > Data object structure

The data are made up of the following

fields

Size (in bytes)

Description

Identifier 1-2

Data Object identifier. Value between 0 and 127 are coded on a single byte: '00'-'7F' Value between 128 and 32767: are coded on two bytes with the msb equal to 1: '8080'-'FFFF'

Data Variable Data Object value to store/update in the data structure in memory

Table 8: Data Object Structure

Depending on the identifier, the data field can be formatted. Data objects are grouped depending on their usage according to the following table.

Identifier range Targeted usage

'00' Reserved

‘01’ to ‘1F’ System and Security

‘8300’ to ‘834F’ Safety Boxes

‘8400’ to ‘84FF’ LoRaWAN Profiles

'8C00' to '8FFF' Target configuration

Table 9: Data Object Range ID


7.2 > System

The tables below described the data object dedicated to system configuration and traceability. Get operation

Name ID Length Returned value

SN ‘01’ In: 0 Out: 21

Chip serial number

CHIP UID ‘02’ In: 0 Out: 8

Chip short identifier

CIN ‘03’ In: 0 Out: 10

Card Identifier Number

SE-ID ‘04’ In: 0 Out: 8

Secure Element Identifier

Firmware ID & Software version

‘05’ In: 0 Out: 2

First byte for the Firmware ID ‘02’ for the PEARL IoT (PEARL IoT V2.2) Second byte for the software version ‘00’ for the PEARL IoT

Applications version '06' In: 0 Out: variable

List of pair [Id, version] (Version is coded on 1 byte).

SE Build Number '07' In: 0 Out: 32

The build number (String of 32 bytes) set during the SE compilation

Table 10: Get Operation - System


7.3 > Safety Box

32 variables can be address by the Safety box mechanism:

o 16 with a high level of update required (1 million max) with VariableId in range [0..15]

o 16 with a low level of update required (100 000 max) with VariableId in range [16..31]

The maximum size of each variable is 252 bytes.

Get operation

Name ID Length Value

Safety box ‘8300’+VariableId In: 0 Out: L

L bytes of value

Table 11: Get Operation

Set operation


Safety box ‘8300’+VariableId In: L L bytes of value (L<252)

Table 12: Set Operation

7.4 > LoRaWAN profiles and management

The tables below described the data object dedicated to LoRaWAN profile and management of them. The profile ID is coded on 2 bits. The Profile ID ‘00’ is reserved for the bootstrap profile (Profile active by default) 2 profiles are supported with id ‘00’ Get operation


Dev EUI '8400'+ProfileId In: 0 Out: 8

Device unique identifier

Table 13: Get Operation - LoRaWAN


The documentation has been prepared and is fully owned by Idemia. All intellectual property rights referred to herein, whether registered or not in specific countries, are the properties of their respective owners. No license, express or implied, by estoppal or otherwise, to any intellectual property rights is granted by this document. Implementation of certain elements of the documentation may require the use of third parties intellectual property rights. Thus, user has been informed that the execution of agreements with the respective owners of such intellectual property rights might be necessary. Idemia is not, and shall not be held responsible in any manner for identifying or failing to identify any or all such third party intellectual property rights. The documentation and any product, specifications, data or information described in the documentation are subject to change at any time without notice. The user acknowledges that the documentation is provided on an “as is,” “with all faults and error” basis and Idemia shall not be liable for any errors or omissions that may exist. Idemia makes no representations or warranties of any kind, express or implied, with respect to the documentation. Idemia specifically disclaims all representations and warranties, including the implied warranties of merchantability and fitness for a particular purpose. Idemia makes no representation or warranty regarding whether any part of the documentation or any implementation thereof, infringes upon intellectual property of a third party. Idemia makes no representations or warranties as to the accuracy, completeness, or compatibility of the documentation with user’s computer or other IT systems. Documentation is used at user own risks. All Idemia’s products are sold subject to Idemia current version of terms and conditions of sale. The Products and its information, including technical data, may be subject to export or import regulations in different countries. Any user of the Products agrees to comply strictly with all such regulations and acknowledges that it has the responsibility to obtain licenses to export, re-export, or import the Products.

Cop

yri

gh

t 2

01

9 -

Ph

oto

: G

ett

yIm

ag

es-6

56

16

49

14

Date post:	22-May-2020
Category:	Documents
Upload:	others
View:	5 times
Download:	0 times