全球平台TEE内部API规范

需积分: 10 139 浏览量更新于2024-07-09 收藏 1.71MB PDF 举报

"GPD_TEE_Internal_API_Specification_v1.0.pdf 是一份由GlobalPlatform Inc.发布的关于TEE GP接口的详细说明文档，旨在定义并规范可信执行环境(Trusted Execution Environment, TEE)的内部API接口。该文档是版本1.0的公共发布版，日期为2011年12月。" 全球平台(GlobalPlatform)是一个专注于制定安全设备技术标准的组织，其目标是促进和管理设备上敏感数据的安全处理。TEE是一种在设备上创建的安全区域，它与通常的操作系统（通常称为富客户端环境或REE，Rich Execution Environment）并存，但提供了更高的安全性和隐私保护。 TEE内部API规格说明书详细描述了开发者如何与TEE进行交互，定义了一系列API接口，这些接口允许安全应用程序（通常称为可信应用，TA）在TEE内执行安全操作。这些接口可能包括但不限于密钥管理、安全对象存储、加密操作、权限控制以及与REE之间的安全通信。文档中提到，接收者可以提交与文档相关的专利权或其他知识产权的通知，并提供支持性文档。这表明GlobalPlatform鼓励开放和透明的讨论，以确保实现此规格的兼容性和互操作性，同时尊重所有者的知识产权。文档的技术内容可能涵盖以下几个方面： 1. **安全上下文管理**：定义如何创建、管理和销毁在TEE内的安全上下文，这些上下文通常关联到可信应用实例。 2. **对象管理**：描述如何在TEE内创建、存储和管理安全对象，如证书、密钥和其他敏感数据。 3. **通信协议**：定义了TEE与REE之间的通信协议，确保数据在两者之间安全传输。 4. **权限和访问控制**：规定了访问TEE服务和资源的权限模型，以防止未经授权的访问。 5. **加密和哈希操作**：详述了在TEE内执行加密和哈希运算的API，以支持数据的保密性和完整性。 6. **事件和通知机制**：说明了如何在TEE内触发和处理事件，以及如何向REE报告关键事件。 7. **错误处理**：定义了当API调用失败时的错误代码和处理流程。由于技术会不断更新、修订和扩展，用户必须遵循GlobalPlatform的许可协议来使用这份信息，任何违反协议的使用都是被严格禁止的。GlobalPlatform商标属于GlobalPlatform Inc. 这份文档对于理解和开发在TEE环境中运行的安全软件至关重要，它为开发者提供了一套标准化的接口，有助于提高跨平台的安全应用开发的效率和一致性。

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页未读，继续阅读

vir_king

粉丝: 0
资源: 8

全球平台TEE内部API规范

GPD_TEE_SystemArch_1.2.zip

GPD_TEE_TA_Debug_Spec_v1.0

TEE相关文档合集（GlobalPaltform组织）

gpd_tee_protectionprofile_v1.3

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

最新资源