【国家标准】 识别卡 集成电路卡编程接口 第4部分：应用编程接口（API）管理

ICS 35.240.15 L64 中华人民共和国国家标准 GB/T 29271.4—2019 识别卡 集成电路卡编程接口 应用编程接口（API）管理 第4部分： Identification cards — Integrated circuit card programming interfaces — Part 4: Application programming interface (API) administration (ISO/IEC 24727-4:2008, MOD) 2019-08-30 发布 2020-03-01 实施 国家市场监督管理总局 中国国家标准化管理委员会 前言 GB/T 29271《识别卡 集成电路卡编程接口》分为以下六个部分： 第1部分：体系结构； 第2部分：通用卡接口； 第3部分：应用接口； 第4部分：应用编程接口（API）管理； 第5部分：测试规程； 第6部分：实现互操作的鉴别协议的注册管理规程。 本部分为GB/T 29271的第4部分。本部分按照GB/T 1.1—2009给出的规则起草。 本部分使用重新起草法修改采用ISO/IEC 24727-4:2008《识别卡 集成电路卡编程接口 第4部分：应用编程接口（API）管理》。 本部分与ISO/IEC 24727-4:2008的技术性差异及其原因如下： 关于规范性引用文件，本部分做了具有技术性差异的调整，以适应我国的技术条件，调整的情况集中反映在第2章“规范性引用文件”中，具体调整如下： ● 增加引用了GB/T 16649.15（GB/T 16649.15—2010, ISO/IEC 7816-15:2004, IDT）（见5.8，7.5和第8章）； ● 用等同采用国际标准的GB/T 29271.1代替了ISO/IEC 24727-1（见5.1、第7章和8.1）； ● 用等同采用国际标准的GB/T 29271.2代替了ISO/IEC 24727-2（见第5章、第6章、第8章、附录A和附录F）； ● 用修改采用国际标准的GB/T 29271.3代替了ISO/IEC 24727-3（见第5章、第6章、第7章、第8章、附录A、附录F、附录H、附录I和附录L）； ● 将参考文献ISO/IEC 19784-1:2006移至规范性引用文件，并用等同采用国际标准的GB/T 30267.1—2013代替（见7.5）； ● 增加引用了ISO/IEC 24727-2:2008/Amd1:2014（见5.8）； ● 增加引用了ISO/IEC 7816-15:2004/Amd2:2008（见8.1、G.2.16和G.4.1）； ● 将国际标准中出现的ISO/IEC 24727-5移至规范性引用文件（见5.1和图1）。 增加缩略语ACD、ACR、AR、DID、GCI、ICC、IFD、Kenc、Kmac、PCD和SAL。 本部分还做了下列编辑性修改： ● 纳入国际标准技术勘误ISO/IEC 24727-4 COR 1:2011的内容（见附录B的B.1、B.2、B.3、附录C的C.1、C.2、附录D和附录E）； ● 纳入国际标准修正单ISO/IEC 24727-4/Amd1:2014的内容（见5.8、第8章、附录F~附录L）； ● 图统一从图1开始编号，不再采用原图标序号； ● 表统一从表1开始编号，不再采用原表序号； ● 调整了缩略语顺序； ● 将国际标准中出现的悬置段编号并加标题，并依序调整下文的条标题编号； ● 附录D的第一句“ISO 24727-4-IFDAPI (iso(1) standard(0) iso24727(24727) part4(4) ifdapi(74))”，改为“GB/T 29271.4-IFDAPI (1.2.156.5006.29271.4.74)”； ● 附录D的第8行“ISO 24727-COMMON (iso(1) standard(0) iso24727(24727))”，改为“GB/T 29271-COMMON (1.2.156.5006.29271)”； ● 附录D的第11、12行中的“revMajISO24727-4-IFDAPI”、“revMinISO24727-4-IFDAPI”，改为相应的新版本标识。 引言 1 范围 GB/T 29271的本部分规定了识别卡集成电路卡编程接口中应用编程接口（API）的管理规范。 2 规范性引用文件 下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅注日期的版本适用于本文件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。 GB/T 16649.15—2010 识别卡 集成电路卡 第15部分：对象标识和编码规则（ISO/IEC 7816-15:2004, IDT） GB/T 29271.1—2012 识别卡 集成电路卡编程接口 第1部分：体系结构（ISO/IEC 24727-1:2006, IDT） GB/T 29271.2—2012 识别卡 集成电路卡编程接口 第2部分：通用卡接口（ISO/IEC 24727-2:2006, IDT） GB/T 29271.3—2012 识别卡 集成电路卡编程接口 第3部分：应用接口（ISO/IEC 24727-3:2008, MOD） GB/T 30267.1—2013 信息技术 安全 认证策略 第1部分：通用模型（ISO/IEC 19784-1:2006, IDT） ISO/IEC 24727-4:2008 识别卡 集成电路卡编程接口 第4部分：应用编程接口（API）管理 3 术语和定义 GB/T 29271.1、GB/T 29271.2和GB/T 29271.3中确立的以及下列术语和定义适用于本文件。 4 缩略语 下列缩略语适用于本文件。 ACD: Application Control Domain（应用控制域） ACR: Access Control Rule（访问控制规则） AR: Access Rule（访问规则） DID: Data Identification（数据标识） GCI: Global Card Identifier（全局卡标识符） ICC: Integrated Circuit Card（集成电路卡） IFD: Interface Device（接口设备） Kenc: Encryption Key（加密密钥） Kmac: Message Authentication Code Key（消息认证码密钥） PCD: Physical Contact Device（物理接触设备） SAL: Service Access Layer（服务访问层） 5 体系结构规范 5.1 概述 本部分定义了GB/T 29271体系结构中API管理的规范。图1展示了GB/T 29271的总体体系结构。 5.2 全网络栈 全网络栈（Full Network Stack）提供了完整的通信服务，包括物理层、数据链路层、网络层、传输层和应用层。图2展示了全网络栈的通用元素。 5.3 忠诚栈 忠诚栈（Loyal Stack）是一种简化的栈结构，主要用于支持特定的安全服务。 5.4 不透明ICC栈 不透明ICC栈（Opaque ICC Stack）隐藏了ICC的内部实现细节，仅通过定义好的接口与外部交互。图6展示了不透明ICC栈的结构。 5.5 远程忠诚栈 远程忠诚栈（Remote Loyal Stack）允许通过远程方式访问忠诚栈提供的服务。图7展示了远程忠诚栈的结构。 5.6 ICC本地栈 ICC本地栈（ICC Local Stack）位于ICC内部，处理本地的命令和数据传输。图8展示了ICC本地栈的结构。 5.7 远程ICC栈 远程ICC栈（Remote ICC Stack）通过远程接口访问ICC栈的服务。图9展示了远程ICC栈的配置。 5.8 服务访问层扩展 服务访问层（SAL）的扩展提供了更丰富的服务接口，支持更多类型的API操作。 6 安全体系结构 6.1 路径保护政策 路径保护政策定义了数据在传输过程中的保护机制，包括加密、认证和完整性保护。 6.2 访问控制列表-访问控制规则（ACL-ACR）映射 ACL-ACR映射定义了如何将访问控制列表转换为具体的访问控制规则，以确保只有授权的主体才能访问特定的资源。 6.3 安全报文传输 安全报文传输（Secure Message Transmission）确保报文在传输过程中的机密性和完整性。图A.1展示了带安全报文传输和不带安全报文传输的通信差异。 6.4 可信信道密钥管理 可信信道密钥管理负责生成、分发、存储和销毁可信信道使用的密钥，确保密钥的安全性和有效性。 7 连接组件 7.1 概述 连接组件定义了API管理所需的连接结构和接口。 7.2 操作请求和响应语义 操作请求和响应语义定义了API调用时请求和响应的格式、含义和处理流程。 7.3 委托-代理（Proxy-Agent）体系结构 委托-代理体系结构允许一个实体（代理）代表另一个实体（委托人）执行操作。图11展示了委托-代理机制。 7.4 可信信道接口（TC_API） 可信信道接口（TC_API）提供了建立和维护可信信道的API，支持安全的数据传输。 7.5 接口设备API（IFD_API） 接口设备API（IFD_API）提供了与接口设备交互的API，支持设备管理、命令发送和数据接收等功能。 8 GB/T 16649.15 注册实施 8.1 概述 本章规定了如何基于GB/T 16649.15对API进行注册和实施，确保不同系统之间的互操作性。 8.2 GB/T 29271.3 数据结构映射 GB/T 29271.3中定义的数据结构需要映射到GB/T 16649.15定义的对象标识和编码规则中。 8.3 SAL API 操作映射到 GB/T 16649.15 属性 SAL API的操作需要映射到GB/T 16649.15的属性，以便进行标准化的数据处理。表10展示了SAL API操作映射到GB/T 16649.15属性的示例。 8.4 特定卡 APDU 映射到 GB/T 16649.15 属性 特定卡的APDU（Application Protocol Data Unit）需要映射到GB/T 16649.15的属性，以便进行标准化的命令执行。表11展示了DataContainerObject的属性（GB/T 16649.15 DO）。 8.5 GB/T 29271.3 数据结构存储在卡上 GB/T 29271.3中定义的数据结构在存储到卡上时，需要遵循GB/T 16649.15的编码规则。表12展示了EF或DO识别，表13展示了EF文件内容示例。 附录 A（规范性附录） 路径保护机制 A.1 安全报文传输机制 A.1.1 带安全报文传输和不带安全报文传输的通信 图A.1展示了带安全报文传输和不带安全报文传输的通信差异。 A.1.2 命令头转换 图A.2展示了命令头的转换过程。 A.2 加密数据处理 A.2.1 在INS为奇数值时创建包含加密数据的DO 图A.3展示了在INS为奇数值时创建包含加密数据的DO的过程。 A.2.2 创建包含密码校验和的DO 图A.4展示了创建包含密码校验和的DO的过程。 A.2.3 创建包含Le字段的DO 图A.5展示了创建包含Le字段的DO的过程。 A.3 MAC运算 图A.6展示了MAC运算的过程。 A.4 状态字节处理 A.4.1 创建包含状态字节的DO 图A.7展示了创建包含状态字节的DO的过程。 A.4.2 保护CASE 4命令 APDU 图A.8展示了保护CASE 4命令APDU的过程。 A.4.3 保护带数据字段的响应 APDU 图A.9展示了保护带数据字段的响应APDU的过程。 附录 B（资料性附录） IFD-API：Web服务绑定 B.1 IFD-API Web服务绑定概述 B.2 服务接口定义 B.3 消息格式 附录 C（资料性附录） IFD-Callback-API：Web服务绑定 C.1 IFD-Callback-API Web服务绑定概述 C.2 回调服务接口定义 C.3 回调消息格式 附录 D（资料性附录） GB/T 29271.4-IFD API 模块 D.1 模块定义 D.2 接口定义 D.3 数据结构定义 附录 E（资料性附录） GB/T 29271.4-TC API 模块 E.1 模块定义 E.2 接口定义 E.3 数据结构定义 附录 F（资料性附录） 程序元素的增强使用 F.1 程序元素功能 图F.1展示了程序元素功能。 F.2 完整互操作网络栈 图F.2展示了完整互操作网络栈。 F.3 当前全网络栈 图F.3展示了当前全网络栈。 F.4 建议配置 图F.4展示了建议配置。 F.5 当前忠诚栈 图F.5展示了当前忠诚栈。 F.6 建议忠诚栈 图F.6展示了建议忠诚栈。 F.7 当前不透明 ICC 栈 图F.7展示了当前不透明ICC栈。 F.8 建议不透明 ICC 栈 图F.8展示了建议不透明ICC栈。 F.9 当前远程忠诚栈 图F.9展示了当前远程忠诚栈。 F.10 建议远程忠诚栈 图F.10展示了建议远程忠诚栈。 F.11 当前远程 ICC 栈 图F.11展示了当前远程ICC栈。 F.12 建议远程 ICC 栈 图F.12展示了建议远程ICC栈。 附录 G（资料性附录） 用于 GB/T 16649.15 数据结构处理的 API G.1 API概述 G.2 数据结构处理接口 G.3 错误处理 附录 H（资料性附录） 轻量级服务访问层（SAL API LITE） H.1 SAL API LITE概述 H.2 接口定义 H.3 使用示例 附录 I（资料性附录） 密码信息应用示例 I.1 基于UML的eService计算模型 图I.1展示了基于UML的eService计算模型（基于GB/T 29271对象）。 I.2 用于卡端应用和DataSet对象的GB/T 16649.15数据对象封装 表I.1展示了基于对象的“myservice”数据集。 表I.2展示了用于卡端应用和DataSet对象的GB/T 16649.15数据对象封装。 附录 J（资料性附录） 转换 ASN.1 模块 J.1 ASN.1转换概述 J.2 转换规则 J.3 转换示例 附录 K（资料性附录） 可互操作访问存储库 K.1 存储库概述 K.2 访问接口 K.3 存储结构 附录 L（资料性附录） Crypto API（CAPI）通过程序元素访问 L.1 CAPI访问概述 图L.1展示了启用CAPI的程序元素。 L.2 PKCS#11的加密服务 图L.2展示了PKCS#11的加密服务。 L.3 接口定义 L.4 使用示例 图列表 图1 GB/T 29271 体系结构 图2 GB/T 29271 栈的通用元素 图3 后续数据的图例 图4 卡端应用和客户端应用之间的网络连接 图5 GB/T 29271.2 和 GB/T 29271.3 层的专有实现 图6 不透明 ICC 栈 图7 远程忠诚栈 图8 ICC 本地栈 图9 远程 ICC 栈配置 图10 网络栈 图11 委托-代理机制 图12 发现鉴别协议值 图13 GB/T 16649.15 信息对象和 GB/T 29271.3 数据结构之间的关系 图A.1 带安全报文传输和不带安全报文传输的通信 图A.2 命令头转换 图A.3 在 INS 为奇数值时创建包含加密数据的 DO 图A.4 创建包含密码校验和的 DO 图A.5 创建包含 Le 字段的 DO 图A.6 MAC 运算 图A.7 创建包含状态字节的 DO 图A.8 保护 CASE 4 命令 APDU 图A.9 保护带数据字段的响应 APDU 图F.1 程序元素功能 图F.2 完整互操作网络栈 图F.3 当前全网络栈 图F.4 建议配置 图F.5 当前忠诚栈 图F.6 建议忠诚栈 图F.7 当前不透明 ICC 栈 图F.8 建议不透明 ICC 栈 图F.9 当前远程忠诚栈 图F.10 建议远程忠诚栈 图F.11 当前远程 ICC 栈 图F.12 建议远程 ICC 栈 图I.1 基于 UML 的 eService 计算模型（基于 GB/T 29271 对象） 图L.1 启用 CAPI 的程序元素 图L.2 PKCS#11 的加密服务 表列表 表1 命令进程 表2 每个栈配置的每个类别的路径保护策略类 表3 可信信道 API 表4 DataSet 映射到 ACL 表5 CardApplication 映射到 DataContainerObjectChoice 表6 Service 映射到 ACL 表7 authObject 映射到 DID 表8 Secret Key 映射到 DID 表9 privateKey 映射到 DID 表10 SAL API 操作映射到 GB/T 16649.15 属性 表11 DataContainerObject 的属性（GB/T 16649.15 DO） 表12 EF 或 DO 识别 表13 EF 文件内容示例 表A.1 安全报文传输中各字段使用的值 表I.1 基于对象的“myservice”数据集 表I.2 用于卡端应用和 DataSet 对象的 GB/T 16649.15 数据对象封装