Skip to content

Latest commit

 

History

History
145 lines (116 loc) · 7.42 KB

se_api_design.md

File metadata and controls

145 lines (116 loc) · 7.42 KB

GlobalPlatform Secure Element API Design Document

BACKGROUND

A Secure Element (SE) is a tamper-resistant platform (typically a one chip secure microcontroller) capable of securely hosting applications and their confidential and cryptographic data (e.g. key management) in accordance with the rules and security requirements set forth by a set of well-identified trusted authorities.

Simplified speaking, SE is a secure platform that can run application (called Applet) on it. In order to communicate with Applet, we need a transport interface.

SE can be implemented via one of the following technologies

  • Embedded SE (accessed via platform dependent interface, unremovable)
  • Universal Integrated Circuit Card (UICC, accessed via SIM interface)
  • Advanced secure MicroSD (accessed via sdio/mmc interface)

Which means the physical interface between application processor (AP) and SE can be quite different. GlobalPlatform tries to remove this gap and defined a standard transport API called Secure Element API to cover those different physical transport layer protocols.

SE can be accessed directly in TEE, or indirectly accessed via REE. In later case, a secure channel is needed to ensure the data stream is not hijacked in REE. (For secure channel, we may leverage TZC 400 to create a secure memory that is not accessible in REE)

To understand SE API, you need to understand the following terms

  • Trusted Application (TA): An application execute in Trust Execution Environment (TEE), which is the initiator of SE API.

  • Applet: Applications that run on smartcard OS. Secure Element API defines the method to communicate between host application (in our case, TA) and Applet.

  • Service: A service can be used to retrieve all SE readers available in the system, it also provides a service to create a session from TA to a specific Reader.

  • Session: It maintains the connection between TA and a specific Reader. Different TAs can have a session opened on the same reader. It is SE manager's responsibility to demux the request from different TAs. Upon a session is opened by a TA, the card is power-up and ready to accept commands.

  • Reader: It is an abstraction to describe the transport interface between the system and SEs. You can imagine that a SD card slot is a Reader connected with assd. A ril daemon can be another read to talk with UICC cards. Even embedded SE should have a (virtual) Reader attached to it.

  • Logical Channel: It is used by host application (in our case, a TA) to communicate with applets on the smartcard. GlobalPlatform Card Specification defines maximum 20 logical channels, numbered from 019. Channel number 0 is so-called Basic logical channel, or in short, Basic channel. A channel can be opened or closed by a host application. It is the smartcard OS's responsibility to manage the state of each logical channel. Basic channel is always open and cannot be closed. A channel must select an applet, which means the command passed through the channel will be processed by the selected applet. GlobalPlatform requires a default applet must be selected on basic channel after system reset. Host application can select different applet by issuing a SELECT command on basic channel. Other logical channels (numbered 119) can be opened with or without a given Application Identifier (AID). If AID is not given, the applet selected on basic channel will be selected on the just opened logical channel.

  • MultiSelectable or Non-MultiSelectable: An applet can be MultiSelectable or Non-MultiSelectable. For a Non-MultiSelectable applet, it can only be selected by one channel, further SELECT command on another channel that is targeting to the applet will fail. MultiSelectable applet can be selected by multiple channels, the applet can decide maximum number of channels it is willing to accept.

DESIGN

The following figure shows initial architecture of SE API.

  • Manager (core/include/tee/se/manager.h): This component manages all Readers on the system. It should provide reader interface for the Reader developers to register their own Reader instance. (In the case of JavaCard Simulator, we should have PC/SC Passthru Reader to talk with simulator) It also provides an interface for client to get reader handle on the system.

  • Reader (core/include/tee/se/reader.h): It provides the operations that can be applied on a reader handle. Just like get reader properties and create session to a reader. It’s also responsible for routing an operation(open, transmit...etc) to a specific Reader implementation.

  • Protocol (core/include/tee/se/{protocol.h,aid.h,apdu.h}): This module implements the ISO7816 transport layer protocol that is used to talk with smartcard. It relies on operations provided by Reader to transmit Application Protocol Data Unit (APDU, refer to ISO7816-4) to a specific SE.

  • Session (core/include/tee/se/session.h): It provides the operations that can be applied on a session. Just like open basic or logical channel, and transmit APDU on the session. It relies on protocol layer to create logical, basic channel and transmit APDU.

  • Channel (core/include/tee/se/channel.h): It provides the operations that can be applied on a channel. Like transmit an APDU on the channel, select next applet. It relies on protocol module to select AID, and session module to transport APDU.

  • Reader interface (core/include/tee/se/reader/interface.h): The abstract layer used to implement a specific Reader instance, a set of operations need to be implemented to support a new Reader.

    • open(): Triggered when the first session is connected, the Reader should be powered on and reset. Doing initialization. Detect SE is present or not.
    • close(): Triggered when the last session to the Reader has been closed. The Reader can be powered down in this method.
    • get_properties(): Get properties of the Reader. Something like the Reader is exclusive to TEE or not. SE is present...etc.
    • get_atr(): Get ATR message from the Reader. ATR is defined in ISO7816-3, and it is the message report by SE to describe the ability of SE.
    • transmit(): Transmit an APDU through the Reader which SE attached to.

Reference Documents

How to verify

To test SE API, you need Modified QEMU and enhanced JavaCard simulator. Please use this setup script to setup test environment.