应用安全支撑平台签名、验签函数接口及使用方法.docx

《应用安全支撑平台签名、验签函数接口及使用方法.docx》由会员分享，可在线阅读，更多相关《应用安全支撑平台签名、验签函数接口及使用方法.docx（31页珍藏版）》请在得力文库 - 分享文档赚钱的网站上搜索。

1、SW/T XXXX2013ICS 35.240 L76 备案号：SW中华人民共和国税务行业标准税务系统数字证书应用接口规范TechnicalTechnical specificationspecification forfor digitaldigital certificatecertificate applicationapplication interfaceinterface toto taxtax systemsystem2013-11-XX 发布2013-11-XX 实施国国家家税税务务总总局局 发 布SW 72013SW 72013I目 次目 次 .I前 言 .III引 言 .I

2、V1范围 .12规范性引用文件 .13术语和定义 .13.1数字证书.13.2X.509.1 3.3用户密钥对.1 3.4容器.1 3.5签名及认证服务器.14符号和缩略语 .15接口概述 .25.1接口类型.2 5.2接口功能.2 5.3接口对应的密码设备.2 5.3.1 密码设备类型.2 5.3.2 密码设备标识.2 5.3.3 密钥容器名字.2 5.4接口采用的标准.2 5.5数据格式和接口标准.3 5.5.1 数据类型.3 5.5.2 身份认证.3 5.5.3 信息摘要.4 5.5.4 SHA-1 摘要算法 .4 5.5.5 SM3 摘要算法 .4 5.5.6 数字签名与验证.4 5.

3、5.7 数字信封.6 5.6算法名字说明.7附件 A （规范性附录） 服务器端接口 .9SW 72013IIA.1接口描述.9 A.2接口属性.9 A.3接口函数.9 A.3.1 打开密码设备.9 A.3.2 关闭密码设备.10 A.3.3 消息摘要.10 A.3.4 数字签名.10 A.3.5 验证签名.11 A.3.6 制作数字信封.12 A.3.7 解数字信封.13 A.3.8 生成服务器响应数据包.13 A.3.9 验证客户身份.13 A.3.10 读取证书.14 A.3.11 获取证书指定内容.14附件 B （规范性附录） 客户端接口 .15B.1接口描述.15 B.2接口属性.15

4、 B.3接口方法.15 B.3.1 打开密码设备.16 B.3.2 关闭密码设备.16 B.3.3 消息摘要函数.16 B.3.4 PKCS#1 格式数字签名 .17 B.3.5 验证 PKCS#1 格式数字签名.17 B.3.6 PKCS#7 格式数字签名 .18 B.3.7 验证 PKCS#7 格式数字签名.19 B.3.8 制作数字信封函数.19 B.3.9 解数字信封函数.20 B.3.10 生成客户认证请求 .20 B.3.11 生成客户认证凭据 .21 B.3.12 读取证书函数 .21 B.3.13 取证书序列号 .21 B.3.14 取证书信息 .21 B.3.15 检测设备

5、.22 B.3.16 验证口令 .22 B.3.17 验证并修改口令 .22附件 C （规范性附录） 返回错误代码说明 .23参考文献 .25SW 72013III前 言本规范规定了税务系统数字证书应用接口，包括客户端调用用户密码设备（如 USBKEY）接口和应 用服务器端调用签名及认证服务器接口，为完整实现税务系统数字证书身份认证、签名验签、数字信 封加解密等应用功能提供接口。 本规范是税务身份认证系统建设、运行管理、应用服务序列标准规范之一，定义了面向各级税务 部门、税务系统工作人员和纳税人服务的税务信息系统所需要的税务证书应用接口，作为税务系统推 广数字证书应用的技术开发规范。SW 72

6、013IV引 言目前，国内各类电子政务系统在应用数字证书服务中，各自采取不同的方法、函数等实现数字证 书应用功能，在调用方法、函数接口、服务功能等方面存在较大差异，使得同一数字证书在不同的应 用系统中无法兼容使用，增加了用户使用数字证书的复杂度和成本。对于税务系统身份认证系统证书 的推广应用，各省也存在不同的证书应用方式，所以迫切需要从税务行业角度，对税务身份认证系统 的证书应用接口进行规范和统一。因此，国家税务总局组织编写了税务系统数字证书应用接口规范 ，它是税务身份认证系统建设、运行管理和应用服务序列标准规范之一。 为了规范税务系统数字证书应用，提升数字证书的应用价值，本规范定义了证书应用

7、的环境函数、 证书解析函数、身份认证函数、签名验签函数、数字信封加解密函数等。通过以上函数的定义，可以 提供完善的证书应用服务功能，方便税务系统数字证书应用的推广，有利于提升税务信息业务系统的 安全等级，实现用户一证多用、一证通用。 税务系统数字证书应用接口的产品形态可包括：动态链接库（Windows 和 Linux）、ActiveX 控件、 Java 组件包等各种形态。本规范遵循国家密码管理局发布的密码技术标准和国家标准，本规范将随以上标准的变化进行修订。SW 720131税务系统数字证书应用接口规范税务系统数字证书应用接口规范1范围本规范规定了税务系统数字证书应用接口的类型、功能、数据格式

8、、接口协议标准、接口定义等 内容。 本规范适用于基于接口调用证书应用模式的税务应用系统开发与集成，包括通过签名及认证服务 器或安全应用支撑平台实现数字证书身份认证、签名验签、数字信封加解密等证书应用功能。2规范性引用文件下列标准所包含的条文，通过在本规范中引用而构成本规范的条文。 税务系统数字证书格式标准国家税务总局3术语和定义下列术语和定义适用于本规范。 3.1 数字证书 由认证机构签名的包含公开密钥拥有者信息、公开密钥、签发者信息、有效期以及一些扩展信息 的数字文件，简称证书。本规范中是指由税务身份认证系统所签发的税务系统数字证书。3.2 X.509 被广泛使用的数字证书标准，由国际电联电

9、信委员会（ITU-T）制定的 PKI 标准。X.509 定义了 （但不仅限于）公钥证书、证书吊销列表、属性证书和证书路径验证算法等证书标准。 3.3 用户密钥对 存储在设备内部的应用于密码运算的非对称密钥对，包括签名密钥对和加密密钥对。 3.4 容器 密码设备中用于保存密钥所划分的存储空间的唯一性编号。 3.5 签名及认证服务器 签名及认证服务器作为密钥、证书存储和密码运算设备，进行证书、密钥和设备管理及高速密码 运算。签名及认证服务器采用安全中间件技术，为应用开发提供统一的、透明的证书应用开发接口， 把复杂的 PKI 技术转换为简单的调用接口或系统安全插件，为应用系统安全提供强有力的保证。签

10、名 及认证服务器的主要功能是提供数字证书身份认证、数字信封加解密和签名验签服务。4符号和缩略语下列符号和缩略语适用于本标准。API应用程序接口（Application Program Interface），简称应用接口CRL证书吊销列表（Certificate Revocation List）PEM私有加强邮件（Privacy Enhanced Mail）DER可区分编码规则（Distinguished Encoding Rules）LDAP轻量级目录访问协议（Lightweight Directory Access Protocol）OCSP在线证书状态协议（Online Certifica

11、te Status Protocol）OID对象标识符（Object Identifier）CSP加密服务提供者（Cryptographic Service Provider）SW 720132PKCS公钥密码标准（the Public-Key Cryptography Standards）ECC椭圆曲线算法（Elliptic Curve Cryptography）RSA一种公钥加密算法5接口概述5.1 接口类型 安全接口驻留在应用系统服务器端或客户端内部，由应用系统调用，实现读写加密设备信息、身 份认证、信息摘要、数字签名/验证、数字信封制作与解析等等。安全接口分为以下两个大类： 1）服务器

12、端接口 服务器端接口通过 TCP/IP 网络与签名及认证服务器进行联接，签名及认证服务器的功能通过安全 接口来实现，将复杂的密码运算转化为简单的接口调用来完成。 2）客户端接口 安全客户端接口，通过与系统客户端集成，分别为 B/S 结构和 C/S 结构系统的客户端提供身份认 证、数字签名/验证和安全通信的功能。 5.2 接口功能 安全接口实现的功能为： 1）身份认证，使用密码技术对通信双方实行基于证书的身份认证。 2）信息摘要和验证，对数据作摘要运算和对摘要结果进行验证。 3）数字签名和验签，实现数字签名和验证。 4）数字信封制作与解开，实现基于数字信封的数据加密和解密。 5）对证书的读取和解

13、析，对证书项信息进行解析。 5.3 接口对应的密码设备5.3.1密码设备类型安全接口支持的密码设备类型有： 1）USBKEY（电子钥匙，USB 接口） ； USBKEY 在客户端使用，具有通用的 PKCS#11 接口、微软 CSP 接口和符合国家标准的底层接口。 2）签名及认证服务器（网络接口） 。 签名及认证服务器在服务器端提供各种密码服务，在签名及认证服务器上实现各种密码运算。 为了内部处理的需要，每种密码设备有一个内部的设备类型编码： 1）具有 CSP 接口的 USBKEY、IC 卡等，按微软指定的类型进行编码，一般为 1； 2）签名及认证服务器的设备类型编码为 0x604。5.3.2密

14、码设备标识应用系统使用密码设备时，应指定密码设备的名字。按下述规则为每种密码设备指定一个名字: 具有 CSP 接口的 USBKEY，为注册的 CSP 名字。 对于签名及认证服务器，为接口模块的名字。一般在 Windows 下，为动态链接库的名字。在 Linux/Unix 下，为共享库的名字。5.3.3密钥容器名字在一个密码设备中，一般都可以容纳多对公私钥和多个证书，因此需要使用密钥容器的名字来标 识所使用的密钥和证书。 5.4 接口采用的标准 1）数字证书采用 X.509v3 标准； 2）数字签名、数字信封、数据摘要采用 PKCS#1 和 PKCS#7 标准； 3）服务器端接口符合 J2EE

15、规范；SW 7201334）密码设备接口采用国家标准、PKCS#11 或 CSP 标准； 5）数据编码格式采用 DER 和 PEM 标准。 5.5 数据格式和接口标准 下面描述接口采用的各种数据格式和接口标准。5.5.1数据类型使用以下几种类型数据格式（具体的类型定义与开发平台有关）： 1)4 字节整数和无符号整数 2)8 位二进制字节数组 3)普通字符串 4)16 进制字符串 5)Base64 编码字符串 Base64 编码格式将二进制字节数组每 3 个字节一组转换为 4 个字符（俗称 3 变 4） ，较之 16 进制 字符串更节省存储空间，但转换要稍复杂一些。 首先将 3 个字节共 24

16、个 bit 分成 4 段，每个分段 6 个 bit，6 个 bit 组成 063 之间的一个数， 然后按下表映射为一个字符(0A ，1B ，63/)：ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/ 如果原字节数组长度不是 3 的倍数，则先在原字节数组后补 1 到 2 个 0x0 字节，待转换完成后， 再将转换结果的最后 1 到 2 个字符替换为=号（替换的个数与补 0 的个数相同） 。例如，字节数组 b 转换为 Base64 格式时为：“EjShsg=“5.5.2身份认证每个用户都持有可唯一标识用户身份的私钥和由

17、 CA 签发的公钥证书，用户私有信息保存在电子钥 匙(USBKEY)或其它安全载体中。在访问应用系统时，用户出示自已的身份证明（签名和证书） ，实现基 于证书的身份认证过程。 身份认证分为单向或双向认证方式，在一般情况下采用服务器认证客户的单向认证方式，在必要 时可采用双向认证方式。 应用系统中，应用服务程序直接通过安全接口调用认证服务器对用户进行身份认证，用户身份信 息由应用系统自身进行维护和管理。 应用系统服务器端和客户端各需要执行两次调用，才能完成对一个用户的身份认证。下面对认证 流程进行较详细描述。 1）客户端请求(ClientHello) 客户插入 USBKEY，进行 USBKEY

18、保护口令验证。 客户生成随机数，将该随机数及用户 ID 上传至服务器，请求登录系统。 2）服务器应答(ServerHello) 认证服务器用私钥对客户随机数签名，并生成服务器随机数，将数字签名、服务器随机数和认证 服务器证书回送给客户。 3）客户认证服务器，生成并上传客户端认证信息 客户端在收到应答后，检验认证服务器证书的有效性，再验证认证服务器的签名。若签名验证不 正确，则本次认证过程中止，否则用客户私钥对服务器随机数签名，连同用户证书组成认证信息上传 至服务器。 4）服务器认证客户 认证服务器先验证用户证书的有效性，再验证客户的签名。签名正确，客户身份认证成功，允许SW 720134客户进

19、行正常的业务操作，否则，客户被拒绝。5.5.3信息摘要信息摘要（即 HASH 运算）对一串数据流进行反复的迭加运算，生成一个摘要结果，用于对数据的 完整性验证。签名及认证服务器使用的 HASH 算法为 SHA-1 算法和 SM3 算法。5.5.4SHA-1 摘要算法用 DATA 记需要进行 HASH 运算的数据，数据长度不限，用 SHA()记 SHA-1 算法，用 H 记运算结 果，则 SHA-1 运算记为：H = SHA(DATA) SHA 运算结果 H 为 20 字节(160bit)长度数据。5.5.5SM3 摘要算法SM3 是国家标准 HASH 算法。用 DATA 记需要进行 HASH

20、运算的数据，数据长度不限，用 SM3()记 SM3 算法，用 H 记运算结果，则 SM3 运算记为：H = SM3(DATA) SM3 运算结果 H 为 32 字节(256bit)长度数据。5.5.6数字签名与验证5.5.6.1签名算法 RSA 签名算法：1024 位/2048 位 SM2(ECC)签名算法：256 位 5.5.6.2PKCS#1 标准格式签名 5.5.6.2.1PKCS#1 签名格式 被签名的数据为字节数组。 对给出的被签名原数据进行 HASH 运算，HASH 结果按 PKCS#1 标准进行填充： B = 00 01 ff ff ff 00 30 H00，H01，H13 其中

21、 H00，H13为 HASH 结果。 再使用用户的私钥对填充后的数据块作 RSA 运算，得到的结果即为 PKCS#1 格式签名值。当使用 1024 位的 RSA 算法进行签名时，签名结果长度为 128 字节（与密钥长度相同） 。 5.5.6.2.2PKCS#1 签名 1) 用 SHA-1 摘要算法对需要签名的数据（DATA）进行 HASH 运算，生成 20 字节 HASH 结果： H = SHA（DATA）H 为 20 字节 2) 按 PKCS#1 标准对 HASH 结果作填充；B = 00 01 ff ff ff 00 30 21 30 09 06 05 2B 0E 03 02 1A 05

22、00 04 14 H00，H01，H13 3) 使用私钥(记作 pvk)对填充后的数据块作 RSA 运算，生成 128 字节签名结果： SIGN = RSApvk(B)SIGN 为 128 字节 5.5.6.2.3PKCS#1 验签 从接收签名结果记为 SIGN，签名原数据为 DATA，验签公钥为 pbk，则验证签名的流程为: 1) 使用公钥对签名结果作 RSA 公钥解密运算并去掉填充:H = RSApbk(SIGN) 2) 对签名原数据作 HASH 运算：H = SHA(DATA) 3) 比较 H 与 H ，如相等，则验证正确，否则验证错误。SW 7201355.5.6.3PKCS#7 标准

23、格式签名 5.5.6.3.1PKCS#7 签名格式 PKCS#7 签名是在 PKCS#1 签名的基础上增加了签名者信息等内容后，并进行 DER 编码后的数据结 构。其结构如表 1 所示： 表 1 PKCS#7 数字签名格式表PKCS#7 数 字 签 名 格 式版本号1信息摘要算法标识数据类型被签名内容信息被签名内容(可选)证书签名者证书和签发者证书(可选)CRLs证书作废链(可选)版本号(1)证书序列号信息摘要算法标识签名时间(可选)签名算法标识签名者信息签名值在数字签名结果中可以包含被签名数据(称为 Attach 方式)或不包含被签名数据(称为 Detach 方式) ；在数字签名结果中可以包

24、含签名者证书也可以不包含签名者证书。 “签名值”是通过私钥对“被签名内容”和其它可认证属性进行签名运算的结果。因此，在上述 签名格式中的证书、CLRs、被签名内容等可以从已生成的签名结果中删除或重新插入。一般情况下， 签名格式根据下面的需要进行选择： 1) 需要保存在数据库中的数字签名与被签名原数据采用分离的方式进行存放，即在“被签名内容 信息”内不含实际的“被签名内容” ，被签名内容存放在数据库其它地方。 2) 不包含签名者证书，可以减少签名数据大小，但在验证时需要查找证书。 3) 需要在网络上传输（例如与其它系统交换数据）的数字签名，在签名包中可以包含被签名数据 和签名者证书。 5.5.6

25、.3.2PKCS#7 签名 数字签名前要对数据使用 SHA-1 或 SM3 数据摘要算法作 HASH 运算，再用用户的签名私钥作 RSA 运 算，结果即为对数据的“数字签名” 。下面的 DATA 为待签名数据，HASH()为 HASH 函数，SIGN()为 签名运算函数，DS 为签名结果。数字签名过程为： 1)对数据作 HASH 运算： H = SHA（DATA）H 为 20 字节 2)按 PKCS#1 标准对 HASH 结果作填充； B = 00 01 00 ff ff ff 00 30 H00，H01，H13 3)使用用户的私钥(pvk)对填充后的数据块作 RSA 运算。 DS = RSA

26、pvk(B)DS 为 128 字节 4)按 PKCS#7 标准格式对签名进行编码，得到的结果记为 signedData。SW 7201365.5.6.3.3PKCS#7 验签 设待验证的签名为 signedData，签名原数据为 DATA，则验证签名的流程为: 1）从 signedData 中提取签名者证书序列号等信息，按证书序列号获取签名者证书并检验证书的 有效性(在签名中提取证书或通过 LDAP 下载证书)； 2）从证书中提取签名者公钥(pbk)，使用公钥对签名结果作 RSA 公钥解密运算并去掉填充:H = RSApbk(DS) 3）对签名原数据作 HASH 运算：H = SHA(DATA

27、) 4）比较 H 与 H ，如相等，则验证正确，否则验证错误。5.5.7数字信封数字信封用于通信双方交换数据。发送方生成一个随机的报文密钥，使用报文密钥对发送内容进 行加密(对称算法)，再用接收方的公钥对报文密钥加密，最后将加密的报文密钥和加密的发送内容按 PKCS#7 标准，编码组成一个“数字信封” 。发送方还可以为发送内容附加签名。 5.5.7.1数字信封格式 数字信封的格式，见表 2、表 3： 表 2 数字信封格式（不带签名）数 字 信 封 格 式 (不带签名)版本号0版本号证书序列号对密钥的加密算法标识接收者信息加密的报文密钥数据类型数据加密算法标识加密内容信息加密的内容表 3 数字信

28、封格式（带签名）数 字 信 封 格 式 (带签名)版本号0版本号证书序列号对密钥的加密算法标识接收者信息加密的报文密钥信息摘要算法算法标识数据类型数据加密算法标识加密内容信息加密的内容(使用报文密钥加密)SW 720137证书签名者证书和签发者证书(可选)版本号(1)签名者证书序列号签名时间签名算法加密的签名值(使用报文密钥加密)签名者信息其它属性5.5.7.2制作数字信封 数字信封制作过程： 1）随机生成报文密钥 mk； 2）用接收方公钥对 mk 加密(按 PKCS#1 标准)； 3）使用 mk 对发送内容加密； 4）如果需要签名，则执行如下步骤： a) 对发送内容作数字签名(见数字签名过程

29、，但不作编码)； b) 使用 mk 为密钥对签名进行加密； 5）按格式编码构成数字信封。 5.5.7.3解数字信封 接收方从数字信封中解出所需的内容，并验证发送方的签名(如果有的话)。 解数字信封的过程： 1）使用接收者自已的私钥解出 mk； 2）使用 mk 为密钥解密传送的内容； 3）如果存在签名，则执行： a) 使用 mk 为密钥解出签名值； b) 验证签名。 5.6 算法名字说明 目前用到的算法名字和标识见表 4： 表 4 算法名字和表示名字名字算法算法 IDID说明说明摘要算法“SHA1“CRYPT_ALGID_SHA1SHA-1 摘要算法“GBSM3“CRYPT_ALGID_GB_S

30、M3SM3 摘要算法(软件算法)非对称加密算法“RSA“CRYPT_ALGID_RSA_PKCSRSA 公钥加密算法“GBECC“CRYPT_ALGID_GB_ECC国标 SM2 公钥加密算法签名算法“SHA1withRSA“CRYPT_ALGID_SHA1_RSA_PKCSPKCS1 RSA+SHA-1 签名算法“GBECSM3“CRYPT_ALGID_GB_ECDSA_SM3国标 SM2+SM3 签名算法对称加密算法“DES3_CBC“CRYPT_ALGID_DES3_CBC3DES CBC 对称加密算法(软件算法)SW 720138“GBSSF33“SGD_SSF33_ECBSSF33

31、ECB 对称加密算法(国密新接口)“GBSSF33_CBCSGD_SSF33_CBC SSF33 CBC 对称加密算法“GBSM1“SGD_SM1_ECBSM1 ECB 对称加密算法(即 SCB2)“GBSM1_CBC“SGD_SM1_CBC SM1 CBC 对称加密算法(即 SCB2)“GBSMS4“SGD_SMS4_ECB SMS4 ECB 对称加密算法(软件算法)“GBSMS4_CBC“SGD_SMS4_CBC SMS4 CBC 对称加密算法(软件算法)SW 720139附件 A （规范性附录） 服务器端接口A.1 接口描述 在应用系统服务器端，由认证服务器和签名服务器为系统提供安全服务

32、。签名及认证服务器与应 用系统的接口是与平台无关的 JAVA 接口，适用于所有操作系统。 本接口由一组 JAVA 函数构成，接口主要实现身份认证、数字签名、数字信封和其他相关功能。 A.2 接口属性 接口属性见表 5： 表 5 接口属性表interrCode 返回的错误码.StringerrMsg 返回对应错误码的错误信息StringstrResult 结果字符串.主要用于存放返回的字符串bytebResult 二进制结果数组，长度为 lenResult0IntlenResult 结果长度A.3 接口函数 函数列表见表 6: 表 6 接口函数表openDevice打开密码设备closeDevi

33、ce关闭密码设备digestData消息摘要sign数字签名(PKCS#1 格式)signData数字签名(PKCS#7 格式)verify验证 PKCS#1 格式签名verifySign验证 PKCS#7 格式签名envelopData制作数字信封unenvelopData验证并解数字信封serverHello生成服务器响应数据包serverAuth验证客户身份readCert读取证书getCertInfo获取证书指定内容A.3.1 打开密码设备public int openDevice(String strProvider, String strContainer, int nProvTy

34、pe, String strPassword)SW 7201310功能：打开签名及认证服务器。 输入： strProvider加密设备的名字。 strContainer加密设备对应的密钥容器。 nProvType加密设备的类型，固定为 1540(0x604)。 strPassword打开加密设备需要的口令字。 输出： errCode错误码，成功时为 0，其它为错误。 errMsg错误信息。 返回值：错误码，成功时为 0，其它为错误。 说明： 在调用任何其它与密码设备有关的方法前，必须先打开签名及认证服务器，否则操作将失败。在 不使用设备时，调用 closeDevice()方法关闭。 A.3.2

35、 关闭密码设备public int closeDevice() 功能：关闭打开的签名及认证服务器。 输入：无。 输出： errCode 错误码，成功时为 0，其它为错误。 errMsg错误信息。 返回值：错误码，成功时为 0，其它为错误。 消息摘要public int digestData(String strData) public int digestData(String strData, int lenData , String strAlgid, int dwFlags) 功能： 对数据作消息摘要(即 HASH 运算)。 输入： strData 被 HASH 数据，普通字符串。 lenData 被 HASH 数据长度。 strAlgidHASH 算法标识，见表 4 摘要算法说明。 dwFlags 指定输出格式，其值为以下值之一： 0x000000H