全球平台TEE内部API规范v1.0

需积分: 9 144 浏览量更新于2024-07-09 收藏 1.27MB PDF 举报

"GPD_TEE_Internal_API_Specification_v1.0.pdf" 本文档是Global Platform（全球平台）发布的TEE（Trusted Execution Environment）内部API规范的版本1.0，适用于智能卡开发，特别是SIM卡相关的智能卡技术。全球平台是一家专注于制定安全设备和应用程序接口标准的组织，其目标是提供一个开放且可扩展的框架，以确保各种设备和服务的安全运行。 TEE是一种在通用计算环境中（如操作系统）提供安全执行环境的技术。它与通常的Rich Execution Environment（REE）并存，用于处理敏感数据和执行安全应用。在SIM卡开发中，TEE可以确保移动通信和支付等敏感操作的安全性，防止未授权访问和攻击。 TEE内部API规范定义了TEE与REE之间的交互方式，以及安全应用程序如何在TEE内运行和通信。这个规范的使用者被鼓励提交任何他们可能知道的相关专利权或其他知识产权，以防在实施该规范时可能侵犯到这些权利，并提供支持文档。文档的主要内容可能包括： 1. TEE架构：解释了TEE的基本结构、组件及其与REE的关系。 2. API接口：详细描述了开发者可以使用的接口函数，用于在TEE内创建和管理安全对象、进行安全通信、加密解密等操作。 3. 安全机制：涵盖了TEE提供的安全特性，如权限管理、身份验证、完整性保护和隐私保护等。 4. 事件和通知：说明了如何在TEE和REE之间传递事件和通知，以协调它们的交互。 5. 错误处理：定义了在API调用失败时的错误代码和处理机制。 6. 兼容性和移植性：讨论了如何确保实现的兼容性，以便在不同平台上部署和迁移安全应用。该规范的使用受到Global Platform的许可协议约束，任何违反协议的使用都是严格禁止的。随着技术的发展，Global Platform可能会对这个规范进行更新、修订和扩展。智能卡开发者需要理解并遵循这个规范，以确保他们的SIM卡应用能够与TEE正确、安全地交互，同时遵守所有相关的知识产权法律。这个文档对于理解和实施安全、高效且符合行业标准的SIM卡解决方案至关重要。

16/202 TEE Internal API Specification – Public Release v1.0

The technology provided or described herein is subject to updates, revisions, and extensions by GlobalPlatform. Use of this

information is governed by the GlobalPlatform license agreement and any use inconsistent with that agreement is strictly

prohibited.

2 Overview of the TEE Internal API

This specification defines a set of C APIs for the development of Trusted Applications (TAs) running inside

a Trusted Execution Environment (TEE). For the purposes of this document a TEE is expected to meet

the requirements defined in the GlobalPlatform TEE System Architecture [2] specification, i.e., it is accessible

from a Rich Execution Environment (REE) through the GlobalPlatform TEE Client API [1] but is specifically

protected against malicious attacks and runs only code trusted in integrity and authenticity.

A TEE provides the Trusted Applications an execution environment with defined security boundaries, a set of

security enabling capabilities, and means to communicate with Client Applications running in the Rich

Execution Environment. This document specifies how to use these capabilities and communication means

for Trusted Applications developed using the C programming language. It does not cover how Trusted

Applications are installed or managed and does not cover other language bindings.

2.1 Trusted Applications

A Trusted Application (TA) is a program that runs in a Trusted Execution Environment (TEE) and exposes

security services to its Clients.

A Trusted Application is command-oriented. Clients access a Trusted Application by opening a session with

the Trusted Application and invoking commands within the session. When a Trusted Application receives a

command, it parses the messages associated with the command, performs any required processing, and

then sends a response back to the client.

A Client typically runs in the Rich Execution Environment and communicates with a Trusted Application using

the TEE Client API [1]. It is then called a “Client Application”. It is also possible for a Trusted Application to

act as a client of another Trusted Application, using the Internal Client API (see section 4.9). The term

“Client” covers both cases.

18/202 TEE Internal API Specification – Public Release v1.0

The technology provided or described herein is subject to updates, revisions, and extensions by GlobalPlatform. Use of this

information is governed by the GlobalPlatform license agreement and any use inconsistent with that agreement is strictly

prohibited.

2.1.2 Instances, Sessions, Tasks, and Commands

When a Client creates a session with a Trusted Application, it connects to an Instance of that Trusted

Application. A Trusted Application instance has physical memory space which is separated from the physical

memory space of all other Trusted Application instances. The Trusted Application instance memory space

holds the Trusted Application instance heap and writable global and static data.

All code executed in a Trusted Application is said to be executed by Tasks. A Task keeps a record of its

execution history (typically realized with a stack) and current execution state. This record is collectively called

a Task context. A Task MUST be created each time the Trusted OS calls an entry point of the Trusted

Application. Once the entry point has returned, an Implementation may recycle a Task to call another entry

point but this MUST appear like a completely new Task was created to call the new entry point.

A Session is used to logically connect multiple commands invoked in a Trusted Application. Each session

has its own state, which typically contains the session context and the context(s) of the Task(s) executing the

session.

A Command is issued within the context of a session and contains a Command Identifier, which is a 32-bit

integer, and four Operation Parameters, which can contain integer values or references to client-owned

shared memory blocks.

It is up to the Trusted Application to define the combinations of commands and their parameters that are

valid to execute. This is outside the scope of this specification.

2.1.3 Sequential Execution of Entry Points

All entry point calls within a given Trusted Application instance are called in sequence, i.e., no more than one

entry point is executed at any point in time. The Trusted Core Framework implementation MUST guarantee

that a commenced entry point call is completed before any new entry point call is allowed to begin execution.

If there is more than one entry point call to complete at any point in time, all but one call MUST be queued by

the Framework. The order in which the Framework queues and picks enqueued calls for execution is

implementation-defined.

It is not possible to execute multiple concurrent commands within a session. The TEE guarantees that a

pending command has completed before a new command is executed.

Since all entry points of a given Trusted Application instance are called in sequence, there is no need to use

any dedicated synchronization mechanisms to maintain consistency of any Trusted Application instance

memory. The sequential execution of entry points inherently guarantees this consistency.

2.1.4 Cancellations

Clients can request the cancellation of open-session and invoke-command operations at any time.

If an operation is requested to be cancelled and has not reached the Trusted Application yet but has been

queued, then the operation is simply retired from the queue.

If the operation has already been transmitted to the Trusted Application, then the task running the operation

is put in the cancelled state. This has an effect on a few “cancellable” functions, such as TEE_Wait, but this

effect may also be masked by the Trusted Application if it does not want to be affected by client

cancellations. See section 4.10 for more details on how a Trusted Application can handle cancellation

requests and mask their effect.

TEE Internal API Specification – Public Release v1.0 19/202

The technology provided or described herein is subject to updates, revisions, and extensions by GlobalPlatform. Use of this

information is governed by the GlobalPlatform license agreement and any use inconsistent with that agreement is strictly

prohibited.

2.1.5 Unexpected Client Termination

When the client of a Trusted Application dies or exits abruptly and when it can be properly detected, then this

must appear to the Trusted Application as if the client requests cancellation of all pending operations and

gracefully closes all its client sessions. It must be indistinguishable from a clean session closing.

More precisely, the REE SHOULD detect when a Client Application dies or exits. When this happens, the

REE MUST initiate a termination process that MUST result in the following sequence of events for all Trusted

Application instances that are serving a session with the terminating client:

• If an operation is pending in the closing session, it must appear as if the client had requested its

cancellation.

• When no operation remains pending in the session, the session must be closed.

If a TA client is a TA itself, this sequence of events MUST happen when the client TA panics.

2.1.6 Instance Types

At least two Trusted Application instance types MUST be supported: Multi Instance and Single Instance.

Whether a Trusted Application is Multi Instance or Single Instance is part of its configuration properties and

MUST be enforced by the Trusted OS. See section 4.5 for more information on configuration properties.

• For a Multi Instance Trusted Application, each session opened by a client is directed to a separate

Trusted Application instance, created on demand when the session is opened and destroyed when the

session closes. By definition, every instance of such a Trusted Application accepts and handles one

and only one session at a given time.

• For a Single Instance Trusted Application, all sessions opened by the clients are directed to a

single Trusted Application instance. From the Trusted Application point of view, all sessions share the

same Trusted Application instance memory space, which means for example that memory dynamically

allocated for one session is accessible in all other sessions. It is also configurable whether a Single

Instance Trusted Application accepts multiple concurrent sessions or not.

2.1.7 Configuration, Development, and Management

Trusted Applications as discussed in this document are developed using the C language. The way Trusted

Applications are compiled and linked is implementation-dependent.

The way Trusted Applications are configured and installed in a TEE is also implementation-dependent. The

scope of this specification does not include configuration, installation, de-installation, signing, verification, or

any other life-cycle or deployment aspects.

Panics are discussed in section 2.2.3.

20/202 TEE Internal API Specification – Public Release v1.0

The technology provided or described herein is subject to updates, revisions, and extensions by GlobalPlatform. Use of this

information is governed by the GlobalPlatform license agreement and any use inconsistent with that agreement is strictly

prohibited.

2.2 Error Handling

2.2.1 Normal Errors

The TEE Internal API functions usually return an error code of type TEE_Result to indicate errors to the

caller. This is used to denote “normal” run-time errors that the TA code is expected to catch and handle, such

as out-of-memory conditions or short buffers.

2.2.2 Programmer Errors

There are a number of conditions in this specification that can only occur as a result of Programmer Error,

i.e., they are triggered by incorrect use of the API by a Trusted Application, such as wrong parameters,

wrong state, invalid pointers, etc., rather than by run-time errors such as out-of-memory conditions.

Some Programmer Errors are explicitly tagged as “Panic Reasons” and MUST be reliably detected by an

Implementation. These errors make it impossible to produce the result of the function and require that the

API panic the calling TA instance, which kills the instance. If such a Panic Reason occurs, it MUST NOT go

undetected and, e.g., produce incorrect results or corrupt TA data.

However, it is accepted that some Programmer Errors cannot be realistically detected at all times and that

precise behavior cannot be specified without putting too much of a burden on the implementation. In case of

such a Programmer Error, an Implementation is therefore not required to gracefully handle the error or even

to behave consistently, but the Implementation SHOULD still make a best effort to detect the error and panic

the calling TA. In any case, a Trusted Application MUST NOT be able to use a Programmer Error on purpose

to circumvent the security boundaries enforced by an Implementation.

In general, incorrect handles—i.e., handles not returned by the API, already closed, with the wrong owner,

type, or state—are definite Panic Reasons while incorrect pointers are imprecise Programmer Errors.

2.2.3 Panics

A Panic is an instance-wide uncatchable exception that kills a whole TA instance as a result of calling one of

the API functions. It happens when the Implementation can detect a Programmer Error and also when the

Trusted Application itself requests to panic by calling the function TEE_Panic.

When a Panic occurs, the Trusted Core Framework kills the panicking TA instance and does the following:

• It discards all client entry point calls queued on the TA instance and closes all sessions opened by

Clients.

• It closes all resources that the TA instance opened, including all handles and all memory, and

destroys the instance. Note that multiple instances can reference a common resource, for example an

object. If an instance sharing a resource is destroyed, the Framework does not destroy the shared

resource immediately, but will wait until no other instances reference the resource before reclaiming it.

After a Panic, no TA function of the instance is ever called again, not even TA_DestroyEntryPoint.

From the client’s point of view, when a Trusted Application panics, the client commands must return the error

TEE_ERROR_TARGET_DEAD with the origin TEE_ORIGIN_TEE until the session is closed. (For details about

return origins, see the function TEE_InvokeTACommand in section 4.9.3 or the function

TEEC_InvokeCommand in the TEE Client API Specification [1], §4.5.9.)

When a Panic occurs, an Implementation in a non-production environment, such as in a development or

pre-production state, is encouraged to issue precise diagnostic information to help the developer understand

the Programmer Error. Diagnostic information SHOULD NOT be exposed outside of a secure development

environment.

剩余201页未读，继续阅读

sinat_27589407

粉丝: 0
资源: 5

全球平台TEE内部API规范v1.0

TEE_Client_API_Specification-V1.0_c_watermark.pdf

GP TEE Internal API v1.1

GPD_TEE_Internal_Core_API_Specification_v1.3_PublicRelease.pdf

gpd_tee_protectionprofile_v1.3

gpd.fiscale(y) Error in gpd.fiscale(y) : Use only with 'pot' objects

最新资源