diff options
Diffstat (limited to 'documentation/se_api_design.md')
| -rw-r--r-- | documentation/se_api_design.md | 145 |
1 files changed, 145 insertions, 0 deletions
diff --git a/documentation/se_api_design.md b/documentation/se_api_design.md new file mode 100644 index 0000000..83023a8 --- /dev/null +++ b/documentation/se_api_design.md @@ -0,0 +1,145 @@ +# 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 0~19. 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 + 1~19) 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 +- [ISO7816-4] +- [GP Secure Element API] +- [PC/SC Lite] +- [PC/SC Passthru Reader] + +### How to verify +To test SE API, you need [Modified QEMU] and enhanced [JavaCard simulator]. +Please use this [setup script] to setup test environment. + +[Modified QEMU]:https://github.com/m943040028/qemu/tree/smart_card_emul +[JavaCard simulator]:https://github.com/m943040028/jcardsim/tree/se_api +[PC/SC Passthru Reader]:https://github.com/m943040028/pcsc_passthru_driver +[PC/SC Lite]:https://pcsclite.alioth.debian.org/ +[GlobalPlatform Card Specification]:http://www.globalplatform.org/specificationscard.asp +[GP Secure Element API]: http://www.globalplatform.org/specificationsdevice.asp +[TZC 400]: +http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0504c/index.html +[ISO7816-4]: +http://www.embedx.com/pdfs/ISO_STD_7816/info_isoiec7816-4%7Bed2.0%7Den.pdf +[setup script]: +https://raw.githubusercontent.com/m943040028/optee_os/48fe3bf418bda0047784327cbf72e6613ff547b2/scripts/setup_seapi_optee.sh + |