甘肃省公共资源交易数字证书CA互认共享标准规范

甘肃省公共资源交易数字证书（CA）

互认共享标准规范

目录

1.数字证书介质(USBKey)兼容互认接口技术标准错误！未

定义书签。

1.1.简介......................错误!未定义书签。

1.2.算法标识..................错误!未定义书签。

1.3.数据交换结构..............错误!未定义书签。

1.4.SM2签名时计算Z值的操作流程和相关扩展错误!

未定义书签。

2.数字证书兼容互认接口技术标准…•….错误!未定义书签。

2.1.范围......................错误!未定义书签。

2.2.应用集成目标..............错误!未定义书签。

2.3.应用集成要求..............错误!未定义书签。

2.4.应用集成内容..............错误!未定义书签。

2.5.数字证书兼容互认应用接口规范错误!未定义书签。

2.5.1.B/S客户端接口.......错误!未定义书签。

2.5.2.C/S客户端接口.......错误!未定义书签。

2.53服务端接口.........错误!未定义书签。

2.6.交易系统接入CA互联互通流程错误!未定义书签。

2.7.CA机构接入CA互联互通流程错误!未定义书签。

3.电子签章兼容互认动态链接库....错误!未定义书签。

3.1.电子签章验证结果规范......错误!未定义书签。

3.2.电子签章互通标准接口定义.….错误!未定义书签。

3.2.1.读取标准印章数据....错误!未定义书签。

3.2.2.读取标准印章列表....错误!未定义书签。

3.2.3.读取具体标准印章数据..错误!未定义书签。

3.3.电子印章数据格式..........错误!未定义书签。

3.3.1.电子印章数据.........错误!未定义书签。

3.3.2.印章信息.............错误!未定义书签。

3.3.3.印章头信息...........错误!未定义书签。

3.3.4.印章属性信息.........错误!未定义书签。

3.3.5.印章图片信息.........错误:未定义书签。

3.3.6.印章签名信息.........错误!未定义书签。

1.数字证书介质（USBKey）兼容互认接口技术标准

1.1.简介

本规范是为同时兼容存量旧介质和新介质而基于CSP规范

扩展，主要针对USBKey在国密系列（SM系列）算法上的相

关接口标准规范进行说明，国际系列（RSA相关）算法上的相

关标准规范完全按照国际CSP及相关标准，本文不再赘述。

1.2.算法标识

（一）SM1算法

标识符值

ALG_SID_SM1IF

CALG_SM1(ALG_CLASS_DATA_ENCRYPT|ALG_TYPE_BLOCK|

ALG_SID_SM1)

（二）SM2算法

标识符值

ALG_TYPE_E(10«9)

CC

ALG_SID_ECC0

_ANY

ALG_SID_ECC1

_SM2

CALG.SM2(ALG_CLASS_ANY|ALG_TYPE_ECC|

ALG_SID_ECC_SM2)

CALG_SM2_SI(ALG_CLASS_SIGNATURE|ALG_TYPE_ECC|

GNATUREALG_SID_ECC_SM2)

CALG_SM2_E(ALG_CLASS_KEY_EXCHANGE|ALG_TYPE_ECC|

XCHANGEALG_SID_ECC_SM2)

CALG_SM2_E(ALG_CLASS_DATA_ENCRYPT|ALG_TYPE_ECC|

NCRYPTALG_SID_ECC_SM2)

（三）SM3算法

标识符值

ALG_SID_SM30x41

CALG_SM3(ALG_CLASS_HASH|ALG_TYPE_ANY|

ALG_SID_SM3)

（四）SM4

标识符值

ALG_SID_SM420

CALG_SM4(ALG_CLASS_DATA_ENCRYPT|ALG_TYPE_BLOCK|

ALG_SID_SM4)

13数据交换结构

所有SM2算法相关数据均使用大端序，包括公钥、签名值、

密文。

（一）预定义宏

标识符值

ECC_MAX_MODULUS_BITS256

_LEN

ECC_MAX_XCOORDINATE_256

BITS_LEN

ECC_MAX_YCOORDINATE_256

BITS_LEN

（二）SM2私钥结构

typedefstructStruct_ECCPRIVATEKEYBLOB

（

ULONGAlgID;

ULONGBitLen;

BYTE

PrivateKey[ECC_MAX_MODULUS_BITS_LEN/8];

JECCPRIVATEKEYBLOB,*PECCPRIVATEKEYBLOB;

该结构的字段具有如下含义：

AlgID算法标识号

值为

CALG_SM2_EXCHANGE

CALG_SM2_ENCRYPT

CALG_SM2_SIGNATURE

之一

BitLen模数的实际长度

PrivateKey[]私钥256位数据

（三）SM2公钥结构

typedefstructStruct_ECCPUBLICKEYBLOB

{

ULONGAlgID;

ULONGBitLen;

BYTE

XCoordinate[ECC_MAX_XCOORDINATE_BITS_L

EN/8];

BYTE

YCoordinate[ECC_MAX_YCOORDINATE_BITS_L

EN/8];

JECCPUBLICKEYBLOB,*PECCPUBLICKEYBLOB;

该结构的字段具有如下含义：

AlgID算法标识号

值为

CALG_SM2_EXCHANGE

CALG_SM2_ENCRYPT

CALG_SM2_SIGNATURE

之一

BitLen模数的实际长度

XCoordinate[]公钥曲线X坐标

YCoordinate[]公钥曲线Y坐标

（四）SM2签名传出传入结构

typedefstructStruct_ECCSIGNATUREBLOB

{

BYTEr[ECC_MAX_XC00RDINATE_BITS_LEN/8];

BYTEs[ECC_MAX_YCOORDINATE_BITS_LEN/8];

}ECCSIGNATUREBLOB,*PECCSIGNATUREBLOB;

该结构的字段具有如下含义：

r[]签名值第一部分，参见SM2签名算法

规范

s[]签名值第二部分，参见SM2签名算法

规范

（五）SM2密文传出传入结构

typedefstructStruct_ECCCIPHERBLOB

（

BYTE

XCoordinate[ECC_MAX_XCOORDINATE_BITS_L

EN/8];

BYTE

YCoordinate[ECC_MAX_XCOORDINATE_BITS_L

EN/8];

BYTEHASH[32];

BYTECipher[l];

}ECCCIPHERBLOB,*PECCCIPHERBLOB;

该结构的字段具有如下含义：

XCoordinate加密曲线X坐标，参见SM2加密算法

规范

^Coordinate加密曲线Y坐标，参见SM2加密算法

规范

HASH口SM3（X坐标|原文|Y坐标），参见SM2

加密算法规范

Cipher[]密文数据，参见SM2加密算法规范

（六）SM2私钥导出导入结构

struct_ERHeader

（

BLOBHEADERblobheader;

ECCPUBLICKEYBLOBsm2PubKey;

ECCPRIVATEKEYBLOBsm2PriKey;

）；

该结构的字段具有如下含义：

blobheaderPRIVATEKEYBLOB该结构的

aiKeyAlg的值为CALG.SM2

sm2PubKey该结构的AligID的值：

如果是签名密钥对则为

CALG_SM2_SIGNATURE

如果密钥交换的则为

CALG_SM2_EXCHANGE

sm2PriKey该结构的AligID的值：

如果是签名密钥对则为

CALG_SM2_SIGNATURE

如果密钥交换的则为

CALG_SM2_EXCHANGE

(七)SM2公钥导出导入结构

struct_PHeader

(

BLOBHEADERblobheader;

ECCPUBLICKEYBLOBsm2PubKey;

)；

该结构的字段具有如下含义：

blobheaderPUBLICKEYBLOB该结构aiKeyAlg

的值为CALG_SM2

sm2PubKey该结构的AligID的值：

如果是签名密钥对则为

CALG_SM2_SIGNATURE

如果密钥交换的则为

CALG_SM2_EXCHANGE

（A）密文导入SM私钥方法：

首先，导入用非对称密钥（通常是签名密钥对）加密的对

称密钥，采用SIMPLEBLOB

BLOBHEADERblobheader;〃参考下边的BLOGHEADER

ALGIDalg;〃如果该对称密钥是被SM2公钥

加密，则此处的alg为CALG_SM2_EXCHANGE,如果是被RSA

公钥加密，则alg为CALG_RSA_KEYX；

BYTEencryptedKey[];〃如果该对称密钥是被SM2公钥

加密,则参考本文SM2密文结构；如果是被RSA公钥加密，

则为微软RSA密文结构

ion=CUR_BLOB_VERSION;

=SIMPLEBLOB;

ved=0;

Alg=algid;//对称密钥的算法SM1标识为

CALG.SM1,SM4标识为CALG_SM4其他采用微软默认标识

然后用上一步导入的对称密钥，导入密文的SM2密钥，采

用PRIVATEKEYBLOB

如果导入的是SM2密钥对，参考定义的（六）中SM2密

钥导入结构，具体如下：

typedefstruct_ERHeader〃用于导出导入SM2的私钥

BLOBHEADERblobheader;//PRIVATEKEYBLOB

ECCPUBLICKEYBLOBsm2PubKey;

ECCPRIVATEKEYBLOBsm2PriKey;

}ECCPRIKEYHEADER,*PECCPRIKEYHEADER;

其中：

(0)blobheader

=PRIVATEKEYBLOB;

ion=CUR_BLOB_VERSION;

ved=0;

Alg=CALG_SM2_EXCHANGE;

//CALG_SM2_EXCHANGE为加密密钥对；

CALG_SM2_SIGNATURE为签名密钥对(很少用)

(1)ECCPRIVATEKEYBLOB

typedefstructStruct_ECCPRIVATEKEYBLOB

{

ULONGAlgID;〃算法标识号

CALG_SM2_EXCHANGE/CALG_SM2_SIGNATURE

ULONGBitLen;〃模数的实际位长度

BYTE

PrivateKeyLECC_MAX_MODULUS_BlTS_LEN/8J;〃该结

构的私钥部分为被对称密钥加密的32字节密文

}ECCPRIVATEKEYBLOB,

*PECCPRIVATEKEYBLOB;

(2)ECCPUBLICKEYBLOB

typedefstructStruct_ECCPUBLICKEYBLOB

{

ULONGAlgID;〃算法标识号

CALG_SM2_EXCHANGE/CALG_SM2_SIGNATURE

ULONGBitLen;〃模数的实际位长度

BYTE

XCoordinate[ECC_MAX_XCOORDINATE_BITS_LEN/8];//

曲线上点的X坐标

BYTE

YCoordinate[ECC_MAX_YCOORDINATE_BITS_LEN/8];//

曲线上点的Y坐标

}ECCPUBLICKEYBLOB,*PECCPUBLICKEYBLOB;

1.4.SM2签名时计算Z值的操作流程和相关扩展

CSP在进行SM2签名时，如果未设置与Z值计算有关的

UserID和公钥时，签名不计算Z值。

以下部分可选择实现。

1.通过CryptSetHashParam方法实现三个扩展

1)使用HP_USERID0x101设置UserID。

例:

CryptSetHashParam(hHash,HP_USERID,

(PBYTE)pbUserlD,0);

//pbUserlD为16字节长的UserID

2)使用HP_SM2_PUBLICKEY0x102设置公钥，通过传

入ECCPUBLICKEYBLOB结构实现。

例：

CryptSetHashParam(hHash,HP_SM2_PUBLICKEY_H,(PB

YTE)&EccPubLickeyBlob,0);

//EccPubLickeyBlob为ECCPUBLICKEYBLOB结构

3)使用HP_SM2_PUBLICKEY_H0x104设置公钥，通过

传入HCRYPTKEY句柄的实现。

例：

CryptSetHashParam(hHash,HP_SM2_PUBLICKEY_H,(PB

YTE)&hKey,0);

//hKey为HCRYPTKEY句柄

2.通过句柄设置公钥时，句柄可以是其他容器中的密钥，

且不管是签名密钥或加密密钥，都可用于计算。

3.如果既通过结构设置了公钥，又通过句柄设置了公钥，

则使用句柄设置的公钥进行计算。

4.如果未通过HP_SM2_PUBLICKEY或HP_SM2_PUB

LICKEY.H设置公钥，不计算Z值。

5.如果这样调用CryptSetHashParam(hHash,HP_SM2_PU

BLICKEY,NULL,0),则视为没有设置。如果先前设置过，则

取消设置。

6.如果这样调用CryptSe田ashParam(hHash,HP_SM2_PU

BLICKEY_H,NULL,0),则视为没有设置。如果先前设置过，

则取消设置。

7.在已设置公钥但未设置UserID的情况下，使用默认Us

erlD“5678”计算。在设置了UserID的情况下，使用设置的Us

erlD计算Z值。

8.设置UserID时传入NULL,应报错。

2.数字证书兼容互认接口技术标准

2.1.范围

本规范参照国家密码管理局“公钥密码基础设施应用技术体

系''系列技术规范，结合系统业务特点，提出系统数字证书应

用集成目标、集成要求、集成内容，定义统一的证书应用接口，

并提供证书应用接口的典型部署示例、登录认证流程示例和签

名验证流程示例等。

2.2.应用集成目标

1)遵循本规范要求新建或者修改的信息系统，使用不同

CA机构颁发的数字证书，实现数字证书的互通互认，并确保系

统访问控制的高安全性和高可靠性；

2)对信息系统的重要操作环节和重要数据实现基于多CA

数字证书的数字签名功能，保护数据的完整性，并为后期纠纷

处理及责任认定提供合法电子证据;

3）对信息系统的敏感信息实现支持多CA的数字证书的数

据加密功能，确保敏感信息在传输和存储阶段的安全性及多CA

支持。

2.3.应用集成要求

在证书应用集成时，应根据应用系统本身的业务特点和业

务需求，确定需要使用数字证书认证的用户及范围、确定需要

加密、签名的重要操作环节和数据，具体集成要求如下：

1）对于具有操作行为责任认定、证据保存需求的应用系

统，应集成基于数字证书的数字签名的功能；

2）对于具有数据加密和解密需求的信息系统，应集成基于

数字证书的信息加密、信息解密功能；

2.4.应用集成内容

应用系统数字证书应用集成内容如下：

1）数字签名和验证

信息系统中关键业务数据和操作的数字签名，应满足《电

子签名法》以及其他相关政策法规规定的书面形式、原件形式

及文件保存等要求，至少应包括数据原文、电子签名、可信时

间等内容，并可在需要时查询、阅读、下载、验证，具备作为

电子证据的真实性、可靠性和可验证性。

2）数据加密和解密

数据加密时应采用对称算法和非对称算法相结合的方式，

既保障加密机制的安全性、密钥分发的方便性，同时又提高了

加解密操作的效率。根据业务需求，可使用单个数字证书加密,

也可使用多个数字证书对数据共同加密，形成密文数据。

密文数据应安全存储在数据库或磁盘上，待解密时间达到

后方可解密。数据解密时，须使用数字证书对应的密码设备或

证书介质解密。如果证书介质损坏或丢失，电子认证服务机构

应在安全可控的前提下，为用户及时提供密钥恢复服务。

25数字证书兼容互认应用接口规范

数字证书兼容互认应用接口规范是应用系统可直接调用的

应用接口，分为B/S客户端接口、C/S客户端接口和服务端接口。

2.5.1.B/S客户端接口

B/S客户端接口是B/S客户端应用程序直接调用的接口，支

持主流操作系统，支持IE、Chrome>Firefox等主流浏览器。支

持使用符合《数字证书介质（USBKey）兼容互认接口接口技术

标准》的数字证书介质。支持符合国际RSA算法和国家密码管

理局制定的SM2算法的数字证书。

2.5.1.L功能介绍

CertKitWinClient是一套用于Windows平台下B/S客户端的

证书应用套件。由一组JS接口和客户端组件组成。

CertKit支持的功能和特性如下：

1.证书应用。如：基于证书的加密解密、签名验签。

2.JS接口和客户端组件支持多种浏览器，如：IE32/64位、

Chrome、Firefoxo

3.CertKit提供的功能均支持RSA和SM2证书。

CertKitWinClient提供了以下JS对象：

l.TCAo用于对CertKitWinClient提供配置，并提供了多个

常量值。

2.CertStoreo提供列举证书的多种证书管理功能。

3.Certificateo证书对象，可用于获取证书信息和部分证书操

作。

4.CertSeto证书集合，由一组证书对象组成的证书集合，包

含多个过滤方法，并提供了部分证书操作。

5.PKCS7o用于操作PKI体系中的PKCS7结构，同时作为

部分接口的返回值。

2.5.L2.接口说明

2.5J.2.1.TCA

2.5.L2.1.L概述

TCA对象用于配置CertKitWinClient,并提供了多个PKI相

关常量值。

2.5.1.2.L2,构造方法

无

2.5.1.2.L3.成员方法

无

.1.4.常量

TCA提供多个常量值，可作为一些接口的参数使用。

用于表示算法的常量

1

2

4

3

1024

2048

用于表示密钥用法的常量

alSignature

pudiation

cipherment

ncipherment

reement

rtSign

gn

herOnly

herOnly

ntCommitment

用于表示扩展密钥用法的常量

rAuth

tAuth

igning

Protection

EndSystem

Tunnel

User

tamping

igning

ertAAServerAuth

esponder

erPPP

erLAN

erver

lient

IKE

pAC

pWTP

cardlogon

.1.5.静态方法

.1.5.1.TopESAConfigO

描述

此方法用于配置CertKitWinCliento

这个方法必须在调用其他对象和方法之前调用。

参数

无

返回值

true/false

.2.CertStore

.2.1.概述

CertStore提供了列举证书的功能。

.2.2.构造方法：

无

2.5・1・2・2.3.静态方法：

.2.3.1.listAHCerts()

描述

用于列举当前系统中“个人”存储区下的所有证书。

CertStore不会主动从“个人”存储区以外读取证书。

对于UKey或其他密码设备中的证书，需要由厂商将

证书注册到“个人”存储区下。

参数

无。

返回值

CertSet类型。

.2.3.2.byName(name)

描述

获取指定名字的CertStore对象

参数

nameString类型

返回值

CertStore类型。

2・5・1.2・2・3.3.byCertificate(cert)

描述

获取指定证书所在的CertStore对象

参数

certCertificate类型

返回值

CertStore类型

.2.4.成员方法：

.2A.1.listCerts()

描述

获取当前CertStore下的证书

参数

无

返回值

CertSet对象

.3.CertSet

2.5.L2.3.1.概述

CertSet用于储存一组Certificate对象，并提供了数个过滤

方法。

2.5.1.23.2.构造方法

.3.2.1.CertSet(pkcs7)

描述

读取PKCS7中的证书，并用其中的证书构造CertSet

对象。

参数

pkcs7Base64编码的PKCS7

2.5.1・2・3・2.2.CertSet(b64Certs)

描述

使用一个字符串数组构造CertSet对象。

参数

b64Certs字符串数组，每一项都是Base64编码后的证

书数据。

2.5・L.CertSet(certs)

描述

使用一个Certificate对象数组构造CertSet对象。

参数

certs证书对象数组

.3.3.静态方法

无

3.4.成员方法

2・5・L2・3.4.Lsize()

描述

获取当前CertSet对象中的证书数量。

参数

无

返回值

当前CertSet对象中的证书数量。

3.4.2.get(idx)

描述

使用索引获取证书

参数

idx指定索引

返回值

Certificate类型

2・5・1・2・3・4・3・encryptMessage(origin)

描述

使用当前CertSet对象中的证书进行加密

参数

origin字符串类型。原文。

返回值

字符串类型。加密后的密文。

3.4.4.forSign()

描述

过滤含有签名用法的证书集合

参数

无

返回值

CertSet类型。其中的证书是当前CertSet中含有签名用

法的所有证书。

.3・4.5.forEncrypt()

描述

过滤含有加密用法的证书集合。

参数

无

返回值

CertSet类型。其中的证书是当前CertSet中含有加密用

法的所有证书。

2.5・L.byKeyUsage(intKeyUsage)

描述

过滤含有指定密钥用法的证书集合

参数

intKeyUsageint类型，用于指定密钥用法。

取值可使用TCA中的密钥用法常量组合得

出。

请参见TCA中的密钥用法常量

返回值

CertSet类型。其中的证书是当前CertSet中含有指定密

钥用法的所有证书。

.3.4.7.byKeyUsage(strarrKeyUsage)

描述

过滤含有指定密钥用法的证书集合

参数

strarrKeyUsage字符串数组，用于指定密钥用法。

返回值

CertSet类型。其中的证书是当前CertSet中含有指定密

钥用法的所有证书。

3.4.8.byValidity()

描述

过滤在当天有效的证书。

日期取自客户端。

参数

无

返回值

CertSet类型。其中的证书是当前CertSet中在当天有效

的所有证书。

2・5・L2・3.4.9.byValidity(date)

描述

过滤在制定日期有效的证书。

日期由调用者传入。

参数

datajs中的Date对象

返回值

CertSet类型。其中的证书是当前CertSet中在指定日期

有效的所有证书。

.3.4.10.bylssuer(issuer)

描述

使用指定关键字，通过颁发者过滤证书。

参数

issuer字符串类型。

返回值

CertSet类型。其中的证书是当前CertSet中使用指定关

键字过滤后的所有证书。

.3.4.11.bySubject(subject)

描述

使用指定关键字。通过主题过滤证书。

参数

subject字符串类型

返回值

CertSet类型。其中的证书是当前CertSet中使用指定关

键字过滤后的所有证书。

.3.4.12.bySerialnumber(serial)

描述

使用指定关键字。通过序列号过滤证书。

请注意，此接口为精确匹配。

参数

serial字符串类型

返回值

CertSet类型。其中的证书是当前CertSet中使用序列号

过滤后的证书。

2・5・L2.4.Certificate

2・5・L2・4.1.概述

Certificate用于表示一张证书，提供了多个方法用于获取

证书信息，并提供了一些证书应用的接口。

.4.2.构造方法：

.4.2.1.Certificate(b64str)

描述

使用Base64证书数据构造Certificate对象

参数

b64str字符串类型。Base64编码后的证书数据

静态方法

无

.4.3.用于获取证书信息的成员方法

Certificate提供了多个用于获取证书信息接口，这些接口均

无参数。

这些接口如下：

serialNumber()

issuer()

subject()

notBefore()

notAfter()

keyUsage()

extededKeyUsage()

crlUrl()

.4.4.用于证书应用的成员方法

.4.4.1.signMessage(plaintext)

描述

使用证书对消息进行签名。

需要注意的是，签名实际使用的是证书所对应的私钥。

如果你仅持有证书而没有私钥，此方法会报错。

签名结果为P7,包含原文。

参数

plaintext字符串类型。原文。

返回值

String类型，Base64编码后的P7数据，包含原文。

.4.4.2.signLogondata(plaintext)

描述

使用证书对消息进行登录的签名，签名时会在消息原

文前追加LOGONDATA:字符，验签时需要注意同步追加。

需要注意的是，签名实际使用的是证书所对应的私钥。

如果你仅持有证书而没有私钥，此方法会报错。

签名结果为P7,包含原文。

参数

plaintext字符串类型。原文。

返回值

String类型，Base64编码后的P7数据，包含原文。

2.5・L.signMessage(plaintext,b)

描述

使用证书对消息进行签名。

需要注意的是，签名实际使用的是证书所对应的私钥。

如果你仅持有证书而没有私钥，此方法会报错。

签名结果为P7,由调用者决定是否原文。

参数

plaintext字符串类型。原文。

bbool类型。true时，会输出包含原文的P7签名。

false时，会输出不包含原文的P7签名。

返回值

String类型，Base64编码后的P7数据。

2.5.1・2.4・4.4.encryptMessage(origin)

描述

使用证书对消息进行加密。

参数

origin

返回值

String类型，Base64编码后的P7数据

2・5・1・2.4・4.5.toBase64()

描述

导出证书的Base64字符串

参数

无

返回值

证书的Base64字符串

.5.PKCS7

.5.1.概述

PKCS7用于操作PKI体系中的PKCS7数据结构。

2.5A.2.5.2.构造方法

.5.2.1.PKCS7(cms)

描述

使用Base64编码后的P7数据构造PKCS7对象

参数

cms字符串类型。Base64编码后的数据结构。

2・5・.静态方法

无

.5.4.成员方法

2・5・1・2・5・4.LcontentMessage()

描述

获取P7签名中的原文信息。

请注意，如果当前的PKCS7对象不是签名P7,此方法

会报错。

参数

无

返回值

字符串类型，P7签名中的原文数据。

.5.4.2.verify()

描述

验证P7签名。

请注意，如果当前的PKCS7对象不是签名P7或P7中

不包含原文，此方法会报错。

参数

无

返回值

如果验证通过，则返回Certificate对象。

.5.43.toBase64()

描述

返回base64编码的p7

参数

无

返回值

base64编码的p7

.5.4.4.verify(plaintext)

描述

验证P7签名。原文信息由调用者指定

请注意，如果当前的PKCS7对象不是签名P7,此方法

会报错。

参数

plaintext字符串类型。原文。

返回值

如果验证通过，则返回Certificate对象

2・5・1・2.5・4.5.decryptMessage()

描述

解密数据。

请注意，如果当前的PKCS7对象不是加密P7,此方法

会报错。

参数

无

返回值

String类型。解密后的原文

2.5.2.C/S客户端接口

2.5.2.1.功能介绍

iTrusPTA是应用于Windows平台下C/S客户端的的证书应

用套件，采用com技术，产品形态为dll动态库。

iTrusPTA依托于微软CSP密码体系规范，基于微软

CryptoAPI开发和扩展，同时支持符合国际RSA算法体系和国

家密码管理局制定的SM2算法体系的数字证书。

iTrusPTA组■件层次结构图如下：

iTni^PTA

IVfirrnQnftCrvntnAPT

MicrcscftThirdSoft|INRKev

图2.1

iTrusPTA基于CSP密码体系规范，借助MicrosoftCryptoAPI

实现，通过不同加密服务提供者，对各种证书软硬件需求提供

灵活地支持。

2.5・22数据结构说明

2.5.22L密钥用法类型

说明：用于证书扩展项〈密钥用法〉的表述。

类型：枚举

定义：

typedefenum_MIDLMIDL_itfLPTA_0000_0001

{KEY_USAGE_CRL_SIGN=0x2,

KEY_USAGE_CERT_SIGN=0x4,

KEY_USAGE_KEY_AGREEMENT=0x8,

KEY_USAGE_DATA_ENCIPHERMENT=0x10,

KEY_USAGE_KEY_ENCIPHERMENT=0x20,

KEY_USAGE_NON_REPUDIATION=0x40,

KEY_USAGE_DIGITAL_SIGNATURE=0x80

}KEY_USAGE_TYPE;

具体含义可参见RFC5280。

2・522・2.消息指示类型

说明：用于指示输入/输出消息编码类型和内容选项。

类型：枚举

定义：

typedefenum_MIDLMIDL_itLPTA_0000_0002

{INPUT_BASE64=0x1,

INPUT_HEX=0x2,

OUTPUT_BASE64=0x4,

OUTPUT_HEX=0x8,

INNER.CONTENT=0x10,

PLAINTEXT_UTF8=0x20,

MIN.CERTSTORE=0x40,

MSG_BASE64=0x4,

MSG_HEX=0x8

}OPTION;

具体含义如下：

INPUT_BASE64：指示输入的消息为base64编码

INPUTHEX：指示输入的消息为16进制编码

OUTPUT_BASE64：指示输出的消息为base64编码

OUTPUT.HEX：指示输出的消息为16进制编码

INNER.CONTENT：指示PKCS7签名结果需要包含明

文

PLAINTEXT.UTF8:指示明文为UTF8编码格式字符串

MIN.CERTSTORE：指示消息的PKCS7签名结果不含

证书链

MSG_BASE64:指示验证签名时输入的明文为base64

编码

MSG.HEX：指示验证签名时输入的明文为16进

制编码

2・5・2・2.3.证书编码类型

说明：用于指示证书的编码类型。

类型：枚举

定义：

typedefenum_MIDLMIDL_itf_PTA_0000_0003

{CERT_ENCODE_DER=0,

CERT_ENCODE_PEM=1,

CERT_ENCODE_BASE64=2

}CERT_ENCODING;

具体含义如下：

CERT_ENCODE_DER：指示证书为二进制编码

CERT_ENCODE_PEM：指示证书为pem编码

CERT_ENCODE_BASE64：指示证书为base64编码

2.5.23.接口说明

.1.ICertFilter

ICertFilter是证书过滤条件的设置接口，其本身不独立工

作，它作为liltrusPTA的证书过滤属性影响liltrusPTA的证书集

合属性。

2.5.23.1.1.属性

2・5・2・3・1.1.LSubject

类型：BSTR

说明：证书过滤的主题条件，支持正则表达式。

.1.1.2.Issuer

类型：BSTR

说明：证书过滤的颁发者条件，支持正则表达式。

2.5.2・3.1・1.3.SerialNumber

类型：BSTR

说明：证书过滤的序列号条件。

.1.4.CSP

类型：BSTR

说明：证书过滤的CSP条件。

2・5.2・3・L1.5.UseLocalMachineCertStore

类型：BOOL

说明：标识是使用本机证书store还是使用当前用户证书

store的标记。TRUE表示使用本机证书store,FALSE表示使用

当前用户证书storeo

.1.2.方法

.2.1.Clear

原型：HRESULTClear（）

说明：用于清除已经设置的过滤属性条件，清除范围包含

如下属性：Subject、Issuer>SerialNumber和CSP。

输入参数：无

输出参数：无

返回值：无

.liltrusPTA

.1.liltrusPTA属性

.1.1.Filter

类型：ICertFilter*

说明：证书过滤器。用于设置过滤证书的条件，只读属性

（本身不可改变，但其内容可变）。

2・5・2・3・2・L2.MyCertificates

类型：ICerti行cates*

说明：当前系统容器中个人证书集合，只读属性（本身不

可改变，但其内容可变）。

.2.1.3.OtherCertificates

类型：ICertificates*

说明：当前系统容器中其他人证书集合，只读属性（本身

不可改变，但其内容可变）。

.2.1.4.CaCertificates

类型：ICertificates*

说明：当前系统容器中中间证书颁发机构证书集合，只读

属性（本身不可改变，但其内容可变）。

2.5・2・3.2・1.5.RootCertificates

类型：ICerti仔cates*

说明：当前系统容器中受信任根证书颁发机构证书集合，

只读属性（本身不可改变，但其内容可变）。

.2.1.6.Version

类型:BSTR

说明：文件版本号，只读属性。

2.5.2・3・2.1.7.LangCode

类型:BSTR

说明：语言代码JEN”表示英语，其他表示中文。

.2.liltrusPTA方法

2・5.2・3.2.2.LDecryptMessage

原型：HRESULTDecryptMessage（[in]BSTRp7msg,

[in,defaultvalue(1)]OPTIONopt,[out,retval]BSTR*m

Sg)；

说明：解密PKCS7信封消息。

输入参数：p7msg待解密的消息

opt指示密文消息和输出的明文消息的编码格式，下述

值可联合使用：

INPUT_BASE64表示密文消息为Base64编码,

TNPUT_HEX表示密文消息为16进制字符串，

OUTPUT_BASE64指示输出的明文消息为Base64编码，

OUTPUT_HEX指示输出的明文消息为16进制字符串

输出参数：无

返回值：明文消息。

2.S..2.VerifySignature

原型：HRESULTVerifySignature([in]BSTRmsg,[in]BSTR

sign,[in,defaultvalue(l)]OPTIONopt,[out,retval]ICertificate**

signer);

说明：验证PKCS7签名消息。

输入参数：msg消息明文，可选，当PKCS7签名消息内

含明文，可不提供。

signPKCS7签名消息

opt指示明文消息和P7签名消息的编码格式，下述值可联

合使用：

MSG_BASE64表示明文消息为Base64编码,

MSG_HEX表示明文消息为16进制字符串，

PLAINTEXT_UTF8表示明文消息为UTF8编码字符串,

INPUT_BASE64表示P7签名消息为Base64编码，

INPUT.HEX表示P7签名消息为16进制字符串

输出参数：无

返回值：签名者证书。

2・5.2・3.3.【Certificate

2.5.2.33.1.属性

2・5・2・3・3・1・1・CommonName

类型：BSTR

说明：证书的cn串，只读属性。

2・5・2・3.3・1.2.Subject

类型：BSTR

说明：证书主题名称dn,只读属性。

2.5.2・.Issuer

类型：BSTR

说明：证书颁发者dn,只读属性。

2.5・2・3.3・1.4.SerialNumber

类型：BSTR

说明：证书序列号，只读属性。

3.1.5.ValidFrom

类型：DATE

说明：证书有效期开始时间，只读属性。

・3.L6.ValidTo

类型：DATE

说明：证书有效期结束时间，只读属性。

.3.1.7.keyUsage

类型：KEY_USAGE_TYPE

说明：证书密钥用法，只读属性。

3.1.8.CSP

类型：BSTR

说明：证书所属csp名称，只读属性。

.3.1.9.KeyContainer

类型：BSTR

说明：证书密钥容器名称，只读属性。

2.5.2.33.2.方法

2.5.2・.CreateFromStream

原型：HRESULTCreateFromStream([in]BSTRstream);

说明：从流创建证书对象。

输入参数：stream证书字节流。

输出参数：无

返回值：无

3.2.2.GetEncodedCert

原型：HRESULTGetEncodedCert([in,defaultvalue(l)]CER

T_ENCODINGenc,[out,retval]BSTR*certEnc);

说明：获取证书内容串。

输入参数：enc证书内容串编码格式标识

输出参数：无

返回值：证书内容串。

3.2.3.SignMessage

原型：HRESULTSignMessage([in]BSTRmsg,[in,defaultva

lue(4)]OPTIONopt,[out,retval]BSTR*signout);

说明:PKCS7消息签名。

输入参数：

msg待签名消息

opt指示待签名消息和签名消息的编码格式，下述值可联

合使用：

INPUT_BASE64表示待签名消息为Base64编码，

INPUT_HEX表示待签名消息为16进制字符串，

PLAINTEXT_UTF8表示待签名消息为UTF8编码格式字符

串，

OUTPUT.BASE64指示签名消息为Base64编码，

OUTPUT_HEX指示签名消息为16进制字符串

输出参数：无

返回值：PKCS7消息

.4.Icertificates

.4.1.属性

无自身属性，继承属性参见微软【Collection接口。

23.2.3.4.2.方法

.4.2.1.EncryptMessage

原型：HRESULTEncryptMessage([in]BSTRmsg,[in,defau

ltvalue(4)]OPTIONopt,[out,retval]BSTR*val);

说明：消息加密

输入参数：msg待加密消息

opt指示待加密消息和密文消息的编码格式

输出参数：无

返回值：密文消息。

2.5.3.服务端接口

服务器端接口是供应用系统服务器端程序直接调用的高级

接口，支持所有主流操作系统，支持B/S和C/S等系统架构，

支持符合国际RSA算法和国家密码管理局制定的SM2算法的

数字证书，可通过添加证书信任列表的方式实现不同电子认证

服务机构证书之间的交叉认证和互信互认。服务端接口使用

HTTP/HTTPS作为通讯接口协议，所有的请求都使用POST方

法，请求参数保存在POST表单域内。

2.5.3.L互认平台API调用协议说明

2.5.3.L1.API调用协议详解

互联互通开放平台（UAP）的API是基于HTTP协议来调

用的，开发者可以直接使用UAP提供的官方SDK及dem。（支

持多种语言，包含了请求的封装，签名加密，响应解释，性能

优化等）来调用，也可以根据UAP的协议来自行封装HTTP请

求进行调用，以下主要是针对自行封装HTTP请求进行API调

用的原理进行详细解说。

2.5.3.L2,调用流程

使用官方SDK,Java和C#将自动完成以下封装和解析过

程。

应用系统可根据协议，按以下协议解析即可，根据UAP的

协议：填充参数>生成签名>拼装HTTP请求>发起HTTP

请求,得到HTTP响应>解释json结果，以下是大体的调用

过程示意图：

服务端

（UAP）

平台统一接口地址及公共参数

:82/uap/api/verify

公共参数：

参数类是否必

参数名称参数描述

型须

methodString是API接口名称。

UAP分配给应用的AppKeyo

这里要注意正式环境和沙箱

app_keyString是环境的AppKey是不同的（包

括AppSecret）,使用时要注意

区分；

时间戳，格式为yyyy-MM-dd

HH:mm:ss,时区为GMT+8,

例如：2016-01-0112:00:00o

timestampString是

UAPAPI服务端允许客户端

请求最大时间误差为10分

钟。

响应格式。默认为xml格式，

formatString否

可选值：xml,jsono

VString是API协议版本，可选值：1.0。

ign_metho签名的摘要算法，可选值为：

String是

dhmaco

API输入参数签名结果，签名

signString是

算法参照下面的介绍。

2・5・3.1.3.请求参数签名算法

为了防止API调用过程中被黑客恶意篡改，调用任何一个

API都需要携带签名，UAP服务端会根据请求参数，对签名进

行验证，签名不合法的请求将会被拒绝。TOP目前支持的签名

算法是HMAC：HMAC_MD5(sign_method=hmac),签名大体过

程如下：

1)对所有API请求参数(包括公共参数而业务参数，但

除去sign参数和byte口类型的参数)，根据参数名称的ASCII码

表的顺序排序。如:foo:1,bar:2,foo_bar:3,foobar:4排序后的顺

序是bar:2,foo:l,foo_bar:3,foobar:4o

2)将排序好的参数名和参数值拼装在一起，根据上面的

示例得到的结果为：bar2foo1foo_bar3foobar4。

3)把拼装好的字符串采用utf-8编码，使用签名算法对编

码后的字节流进行摘要。如果使用MD5算法，则需要在拼装的

字符串前后加上app的secret后，再进行摘要，如：

md5(secret+bar2foo1foo_bar3foobar4+secret)；如果使用

HMAC_MD5算法，则需要用app的secret初始化摘要算法后，

再进行摘要，如：hmac_md5(bar2foo1foo_bar3foobar4)o

4)将摘要得到的字节流结果使用十六进制表示，如：

hex(uhelloworldv.getBytes(uutf-8v))=

“68656c6c6F776F726c64”说明：HMAC_MD5是128位长

度的摘要算法，用16进制表示，一个十六进制的字符能表示4

个位，所以签名后的字符串长度固定为32个十六进制字符。

2.53.2.平台API接口

2.5.32L签名验证接口

请求的业务参数

所有参数均采用UTF-8方式进行

参数名称说明

method接口名称,指定为：y.verifypkcs7

to_sign签名原文字符串

signeddata签名值结果字符串

op_type操作内容，如登陆签名，标识解密等

requestid客户端请求流水号

返回值说明

返回值类Json格式数据

型

返回值(

“code":200,

“message":“操作成功”，

"requestid”:“2018-06-2913:16:470,

,'reponseidM:,"\

ndataH:{

“certCN":“企业证书”,

"entityName":”企业证书”，

ncaNumbern:n6043n,

nhexSerialNumbern:'781052dO52c13901

c5f4062d5c2491Of85a77b69”，

nnotAfter11:00,

,'notBcforc,':00,

unotAfterBjTimeStrn:"2019-10-15

15:51:33”，

MnotBeforeBjTimeStrn:n2018-10-15

15:51:33”，

McertBase64n:nMIID3zCCA4SgAwIBAg

IUeBBSOFLBOQHF9AYtXCSRD4Wne

2kwDAYIKoEczlUBg3UFADCBgzEL

MAkGA1UEBhMCQ04xQDA+BgNVB

AoMN1NpY2h1YW4gRGl