1 简介

本文档中指定的 API 使移动应用程序能够访问移动设备中的不同 SE，例如 SIM 或嵌入式 SE。本规范提供了接口定义和 UML 图，以允许在各种移动平台和不同的编程语言中实现。如果编程语言支持命名空间，则它应为 org.simalliance.openmobileapi，除非在平台绑定文档中明确更改。对于过程接口，使用前缀“OMAPI_”代替

编者注：GlobalPlatform 打算在本规范的未来版本中拆分本文档，以便提供具有一组平台/语言绑定的高级功能 API 描述，作为解决围绕平台绑定出现的歧义的一种方法在过去。特别是，计划将现有的 TEE SE API 和用于访问 SE 的 WebAPI 将来成为 OMAPI 的平台绑定，并有一个新的单独文档描述广泛部署的 Java/Android 绑定。本文档中的一些文本——尤其是在事件处理程序方面——旨在为这种拆分铺平道路。本文无意在未来用于证明对已部署在市场上的 Open Mobile API 的平台绑定的向后不兼容更改的合理性。

2 Architecture

图 2-1 提供了 Open Mobile API 架构的概览。
该架构分为以下功能层：

• 当通过传输API 访问时，传输层为应用程序提供对SE 的一般访问。传输层使用 APDU 与 SE 通信（详见第 4 节）。在传输层之下是插件，它们在开放移动 API 的核心功能和用于与安全元素通信的低级机制之间提供接口抽象。

o Open Mobile API 与特定编程语言或软件平台的具体绑定可能会提供有关插件实现的特定指南。
o 每个 Reader 有一个插件实例。
o 某些插件可能会提供与相关安全元件的直接和无中介通信。但是，其他插件可以通过中间子系统（例如调制解调器或 RIL）进行通信。
o 插件行为的某些方面可能超出了本文档的范围；例如：错误处理、电源管理和恢复策略。插件开发人员负责确保此类策略不会影响使用 Open Mobile API 的应用程序。
o 插件功能和行为将在第 7 节中进一步讨论。

• 服务层为SE 上的各种功能提供更抽象的接口。它们可能比通用传输 API 更容易被应用程序开发人员使用。一个示例可能是使用加密 API 的 sign() 函数并让加密 API 与 SE 交换所有 APDU 的电子邮件应用程序（而不是直接在电子邮件应用程序中处理所有必需的 APDU）

注意：本文档中的服务层已弃用

• 应用层代表使用开放移动API 的各种应用程序。

图 2-1 显示了在移动设备上实现 Open Mobile API 的可能架构。由于给定设备上的 Open Mobile API 实现的各个方面依赖于 REE 和硬件，因此此体系结构的某些方面可能看起来因 REE 而异。 API 的描述使用抽象的面向对象的执行环境，支持聚合、异常处理、并发、回调和内部类。针对不支持部分或全部这些功能的环境的映射提供了一些指导。在图 2-1 中，我们展示了启用与安全元件连接的插件可以与托管 Open Mobile API 的执行环境以外的执行环境进行通信：

• 安全元件可以通过插件连接到传输API，该插件使用由REE 托管和控制的物理接口。此类接口的示例包括 I2C、SPI 或由支持 CLF 的 REE 服务托管的 APDU 门。

• 安全元件（通常支持 UICC 功能）可以通过使用物理接口的插件连接到传输 API，例如 ISO/IEC 7816 中定义的接口，由调制解调器托管和控制。在图中，无线电接口层为 REE 和调制解调器之间的通信提供代理。

• 安全元件可以通过插件连接到传输API，该插件使用由TEE 拥有和控制的物理接口，例如I2C 或SPI。所呈现的安排展示了一种允许使用 TEE 安全元件 API 规范 [TEE SE API] 的受信任应用程序和使用服务 API 或传输 API 的移动应用程序访问安全元件的方法。请注意，在这种情况下，REE 应用程序还可以通过本身使用 TEE SE API（例如使用 TEE 客户端 API）的受信任应用程序与安全元件间接通信。此类通信超出了本文档的范围。

来自 REE 或其他执行环境的安全元件连接的其他安排是有效的。安全元件以多种形式存在，包括嵌入式安全元件、smartSD、智能 microSD、UICC、eUICC 和集成安全元件。当我们在图 2-1 中提及安全元件时，我们指的是任何外形规格的符合 GlobalPlatform 标准的安全元件。 Transport API 包括一个访问控制执行器的实现。结合连接的安全元素中的 ARA 小程序和/或 ARF，这使开放移动 API 能够使用 GlobalPlatform 安全元素访问控制规范 ([SEAC]) 来确保执行环境托管提供的安全级别 Access Control Enforcer，只有 SE 发行者或授权 SD 所有者授权的应用程序才能与 SE 上的小程序通信。

3 API Description

一般而言，本规范中描述的 API 定义了一个抽象接口，该接口使支持面向对象概念（例如异常或对象和实例）的软件平台能够访问 SE。接口和数据类型不受特定软件平台或编程语言的约束。相反，它们是通过可以相应地映射到相应平台表示的逻辑类型来定义的。方法描述如下： <返回值类型> <方法名称> ( <parameter1 type> <parameter1 name> …) 可以定义本规范针对特定软件平台的具体绑定，例如： • The Open Mobile API – Android 绑定规范【Android Binding】定义了该规范在Android平台上的具体绑定。 • [TEE SE API] 定义了此规范在GlobalPlatform TEE 上的具体绑定。以下类型用于描述返回值、参数和错误。如果平台支持，错误可能会映射到异常。

3.1 Programming Language vs. ISO 7816-4 Language Conventions

本文档描述了一个 API，可用于实现涉及设备和 SE 的用例。在本文档中，API 定义使用类似 Java 的语言约定。与 SE 的交互使用 ISO/IEC 7816-4 [ISO 7816-4] 中的约定。应特别注意以下约定：

• 使用“XX”或“xx”表示一个字节，表示为一对十六进制数字，其中每个 x 可以取以下值之一：“0”..“9”表示十进制值 0 到 9； ‘A’..‘F’代表十进制值 10 到 15； “X”表示 0 到 15 之间的任何十进制值。
• 为了保证到字节的明确映射，此语法只能用于偶数个十六进制数字（例如，'A34' 是非法的）。
• 一对直单引号内可以连接无限数量的字节。