DB11 T 254.2-2004 政务数字证书规范第2部分：应用接口.pdf

1、 ICS 35.240.30L 70备案号：16484-2005DB北京市地方标准DB11/T 254.2-2004政务数字证书规范第2 部分：应用接口Specification of digital certificate for government affair Part 2: Application programming interface 2004-12-20北京市质量技术监督局发布 2005-02-01实施发布DB11/T 254.2-2004目 次前 言. II 引 言.III 1 范围. 1 2 规范性引用文件. 1 3 术语和定义、缩略语. 1 3.1 术语和定义. 1 3

2、.2 缩略语. 2 4 政务数字证书应用接口. 2 4.1 数字证书应用接口体系结构. 2 4.2 数字证书应用接口组成和功能说明. 3 5 政务数字证书应用接口函数定义. 5 5.1 环境函数. 5 5.2 设备管理函数. 6 5.3 证书函数. 7 5.4 密码服务函数. 12 5.5 消息函数. 30 附 录 A (规范性附录) 政务数字证书应用接口宏定义和说明. 34 A.1 类型宏定义. 34 A.2 常量宏定义. 34 A.3 全局参数. 34 附 录 B (规范性附录) 政务数字证书应用接口数据结构定义和说明. 36 附 录 C (规范性附录) 政务数字证书应用接口错误代码定义和

3、说明. 37 附 录 D (资料性附录) 政务数字证书典型应用框架图. 38 D.1 典型应用框架图. 38 D.2 典型业务流程分析. 39 附 录 E (资料性附录) 政务数字证书典型应用示例. 40 E.1 程序基本流程. 40 E.2 程序示例说明. 41 I DB11/T 254.2-2004前 言DB11/T 254-2004政务数字证书规范分为二个部分：第1部分：格式；第2部分：应用接口。本部分为DB11/T 254-2004的第2部分。本部分从总体 结 定。本部分的附录A、附录B和附录C 规范性附录 附录D和附录E 资料性附录。本部分 息 口。本部分currency1： 数字证

4、书“证、 fifl fl 息全 、 密局、 密 。本部分：、”全、 、能、 、 。II DB11/T 254.2-2004引 言息术和 术 的 、文 、 和管理 个 的 的 息全 。 政务 程的 和 的 环境 个 、的 体 “政务参 的 自 彼此间的 系以及 证 息的 密性、完整性和可用性。以PKI为核的 “证体系和 息加密术已成为业界广泛“ 的 种构造 体 的 式 成为 息全 障体系其的组成部分之。数字证书应用接口 PKI术应用的 键和核 政务应用系统使用和应用PKI术的桥梁。为 政务数字证书政务 息的应用能够通用 现 息系统互联互通 统 数字证书应用接口规范 更好形成统 的 体系。III

5、DB11/T 254.2-2004政务数字证书规范 第2部分：应用接口1 范围本部分规定 政务数字证书应用接口体系结构 个接口函数的函数名称、参数和返回值以及政务数字证书应用接口所 的宏定义、数据结构和错误代码。本部分适用于数字证书“证机构、数字证书“证系统的 商、政务应用部门以及基于数字证书的全应用 商 行 息系统 设。应用于商务领域的数字证书应用接口 也可参照本部分。本部分 涉及 何具体的密码运算 所密码运算均符 法规的密码设备 行。本部分凡涉及密码 内容 按 法规 施。2 规范性引用文件列文件的条款通过DB11/T 254的本部分的引用 成为本部分的条款。凡 注日期的引用文件 其后所的修

6、改currency1（ 包括勘误的内容）或修订版均 适用于本部分 然 鼓励根据本部分达成协议的 否可使用这些文件的最新版本。凡 注日期的引用文件 其最新版本适用于本部分。ISO/IEC 8825-1：1998 息术-ASN.1编码规则：基本编码规则（BER）的规范 正规编码规则（CER）和可 分编码规则（DER）IETF RFC 3280 Internet X.509 Public Key Infrastructure Certificate and CertificateRevocation List (CRL) Profile X.509 密 基 设施证书 证书 列 PKCS1: RSA

7、Cryptography Standard PKCS1：RSA密码 PKCS7: Cryptographic Message Syntax Standard PKCS7：密码消息语法 3 术语和定义、缩略语列术语、定义和缩略语适用于 DB11/T 254 的本部分。3.1 术语和定义3.1.1证书认证机构（CA） certification authority (CA)用 和分 证书的 机构。3.1.2证书验证 certificate validation“证书 定间的过程 可能包 个证书“证 的构造和 理 的所证书 定间（ 证书 或 过期）。3.1.3证书撤销列表（黑名单） certific

8、ate revocation list (CRL)个已 的列 定 系列证书 “为 的证书。3.1.4数字证书（证书） digital certificate“可的、 CA 行数字 名的 个可 的数字 文件。数字证书包 密 的 息、 密 、 名算法和CA的数字 名。3.1.5政务数字证书 government affair digital certificate1 DB11/T 254.2-2004用 政务参 的数字证书。根据参 的 类分为政务证书“证机构证书、政务个证书、政务机构证书、政务设备证书、政务代码 名证书。3.1.6私有密钥 （私钥）private key（ 密码体 ）用 密 为 用

9、 所的密 。3.1.7公开密钥（公钥）public key（ 密码体 ）用 密 的密 。3.1.8公开密钥基础设施（PKI） public key infrastructure 管理体 的基 设施 currency1、加密、完整性和 可否“性服务。3.1.9信任 trust通常 “ 个 体设 个 体完全按照前 的期行fi 则称前 “ ”后 。这种“ ”可能fl适用于 些 定功能。本部分“ ”的 键 用 体和 机构之间的 系；体应 能够“ ” 机构 可的证书。3.2 缩略语列缩略语适用于本部分：API 应用程序接口（Application Programming Interface） 称应用接口

10、 CA 证书“证机构（Certification Authority）CN 通用名（Common Name）CRL 证书 列 （ 名currency1）（Certificate Revocation List）CSP 加密服务currency1 （Cryptographic Service Provider）DER 可 分编码规则（Distinguished Encoding Rules）DN 可名（Distinguished Name）LDAP 量录”协议（Lightweight Directory Access Protocol）OID 符（Object Identifier）PKCS 密

11、码使用 (the Public-Key Cryptography Standard)4 政务数字证书应用接口4.1 数字证书应用接口体系结构证书数字证书应用接口体系结构 图1所示：2 DB11/T 254.2-2004可否“性完整性 密性 “证应 用 程 序政 务 数 字 证 书 应 用 接 口设备管理函数环境函数 证书函数 消息函数密 码 服 务 函 数密码设备（加密机、加密 、能IC 和USB KEY ）密 应用 接口 设备 图1 政务数字证书应用接口体系结构政务数字证书应用接口于应用系统和密码设备之间 应用程序通过用政务数字证书应用接口 现 “证、 现 息的 密性、完整性和 可否“性；政

12、务数字证书应用接口通过 接口 密码设备 现具体的密码运算和密 使用。政务数字证书应用接口通过 PKCS11和CSP接口 式 类密码设备（加密机、加密 、能IC 和能USB KEY ）的设备性 类密码设备的密码应用接口的性 现应用程序密码设备 性。政务数字证书应用接口currency1的消息函数符 PKCS7格式。政务数字证书应用接口证书格式按DB11/T XXXX.1-2004行 证书码按ISO/IEC 8825-1行 名currency1（CRL）码按IETF RFC 3280行 加密体系按PKCS1和PKCS7行。本部分证书和CRL LDAP 式。本部分所引用的MD2、MD5、SHA-1和

13、RSA密码算法均为例说明。4.2 数字证书应用接口组成和功能说明数字证书应用接口 以部分组成： 环境函数 设备管理函数 证书函数 密码服务函数 消息函数4.2.1 环境函数3 DB11/T 254.2-2004环境函数 和管理全程序 间 和管理全程序 间所 的 种资、 全程序 间应用程序运行期间 法” 造成 息 。环境函数 完成 密码设备的全 接 后 的全 全、可 的程序 间 行。应用程序使用政务数字证书应用接口 用 环境函数（PKI_Initialize） 和全的应用程序 间 完成 密码设备 接和 。 应用程序之前 应用 环境函数（PKI_Finalize） 密码设备的 接 所 的全程序 间

14、 于内 所 的全 。4.2.2 设备管理函数设备管理函数 用 密码设备之间 和管理全” 。设备管理函数 种类型的用 全” 种 通用 类型的全” 用 通用 fl能”密码设备 于 的 息和数据； 类 用 （或全） 类型的全” 用用 （全） 可以”密码设备的 息 设和修改 通用 的PIN。应用程序用 何密码服务函数 行 何密码运算之前 用设备管理函数的用 录函数（PKI_Login） 全” 。 全” 后 则可以用 何密码服务函数。 用 何密码服务函数 应用注 录函数（PKI_Logout）注 全” 密码设备法”。 用 可以定期通过用修改PIN函数（PKI_ChangePin） 修改 全” 所 cur

15、rency1的PIN 密码设备 法使用。4.2.3 证书函数证书函数 设 类数字证书应用接口 环境、 证用 证书和 数字证书或 名currency1 currency1 包括证书 、 名currency1（CRL） 、可 根CA证书设、用 证书 证和用 证书 息系列具体函数。应用程序通过用证书函数 可以 现基于数字证书的 “证 从证书 息 现 管理、” 全机 。证书函数具体使用 通过用证书和CRL 函数或其 证书和 名currency1（CRL）,然后用 的证书设函数：加 的CA根证书、加CA证书、设用 证书 设证书应用环境。此基 用 函数 行证书 证 现用 “证；用 证书 息和 证书息 证书

16、 息 现 管理和” 全机 。4.2.4 密码服务函数密码服务函数 具体 密码设备互 现具体 密码运算 密码运算后 结 返回 应用程序 应用程序 现数据 密性、完整性和 可否“性 全机 的基 。密码服务函数currency1包括BASE64编码、机数成、数字 以及 种称和称密码运算 39个具体的函数。密码服务函数 定长数据和 定长数据的密码运算 于定长数据可以直接用 函数 行 理；于 定长数据 应的密码运算 然后用 应的函数数据 行理。“数据 理完 用 应的函数 示数据 理完 最后用 应函数 应的密码运算。密码服务函数整个政务数字证书应用接口 于底 函数 所的密码服务函数 应用程序使用。4.2.

17、5 消 函数消息函数 数据按照PKCS7格式 行封装 现数据封装格式 应用系统 性 现应用系统互联互通和 息 享。4 DB11/T 254.2-2004消息函数currency1 PKCS7格式的数据编码、PKCS7格式的 名数据编码和PKCS7格式的数字 封编码 能够常 应用程序 现 “证、 密性、完整性和 可否“性 全措施。5 政务数字证书应用接口函数定义以所定义的函数 明 说明 其接口参数 能为 。5.1 环境函数环境函数包括以具体函数： 环境：PKI_Initialize 环境：PKI_Finalize 接口版本 息：PKI_GetVersion5.1.1 环境PKI_Initiali

18、ze函数名称 PKI_RVPKI_Initialize(unsigned long providerType,char *providerParameter,unsigned long pinSilentFlag,char *devMngApi);功能介 全应用程序 间参数说明 providerType IN: 密码服务模块类型“providerType = PKI_PROVIDER_CSPproviderParameter: CSP的名称devMngApi：设备管理接口库 “providerType = PKI_PROVIDER_PKCS11providerParameter: PKCS11

19、库的 devMngApi：设备管理接口库 pinSilentFlag 为口输 静态静态 返回值 RV_OK：成功其 ：失败5.1.2 环境：PKI_Finalize函数名称 PKI_RVPKI_Finalize(void);功能介 应用程序 间参数说明 返回值 RV_OK：成功其 ：失败5 DB11/T 254.2-20045.1.3 接口 信 ：PKI_GetVersion函数名称 PKI_RVPKI_GetVersion(unsigned long *versoin)功能介 接口版本参数说明 version OUT: 版本version的2字节 示版本 低2字节 示次版本返回值 RV_OK

20、：成功其 ：失败5.2 设备管理函数设备管理函数包括以具体函数： 用 录：PKI_Login 修改PIN：PKI_ChangePin 注 录：PKI_Logout5.2.1 用 ：PKI_Login函数名称 PKI_RVPKI_Login (unsigned char *pin,unsigned long pinLen)功能介 用 录密码设备 全 。参数说明 pin IN：设备口pinLen IN：设备口长度返回值 RV_OK：成功其 ：失败5.2.2 PIN：PKI_ChangePin函数名称 PKI_RVPKI_ChangePin (unsigned char *oldPin,unsign

21、ed long oldPinLen,unsigned char *newPin,unsigned long newPinLen);功能介 修改设备PIN参数说明 usrType IN:用 类型/ 0: SUPER_LOGIN 1: USR_LOGINoldPin IN：设备“前口6 DB11/T 254.2-2004oldPinLen IN：设备“前口长度newPin IN：设备新口newPinLen IN：设备新口长度返回值 RV_OK：成功其 ：失败5.2.3 销 ：PKI_Logout函数名称 PKI_RVPKI_ Logout (unsigned long usrType)功能介 设备

22、注 录 参数说明 usrType IN:用 类型 / 0: SUPER_LOGIN 1: USR_LOGIN返回值 RV_OK：成功其 ：失败5.3 证书函数证书函数包括以具体函数： 加 的CA根证书：PKI_AddTrustedRootCaCertificate 加CA证书：PKI_AddCaCertificate 加 名currency1：PKI_AddCrl 设用 证书：PKI_SetUsrCertificate 用 证书：PKI_GetUsrCertificate 证用 证书：PKI_VerifyUsrCertificate 根据CRL文件 证用 证书 否 注 ：PKI_VerifyU

23、srCertificateByCrl OCSP线证书状态查询：PKI_OcspVerifyCertificate 通过LDAP 式 证书：PKI_GetCertFromLdap 通过LDAP 式根据证书 CRL：PKI_GetCrlFromLdap 证书 息：PKI_GetCertificateInfo 证书 息：PKI_GetExtTypeInfo5.3.1 信任 CA 证书：PKI_AddTrustedRootCaCertificate函数名称 PKI_RVPKI_AddTrustedRootCaCertificate(unsigned char *certificate,unsigned

24、 long certificateLen);功能介 加 的CA根证书参数说明 certificate IN: DER编码的证书certificateLen IN: DER编码的证书长度返回值 RV_OK：成功其 ：失败7 DB11/T 254.2-20045.3.2 CA证书：PKI_AddCaCertificate函数名称 PKI_RVPKI_AddCaCertificate(unsigned char *certificate,unsigned long certificateLen);功能介 加CA证书参数说明 certificate IN: DER编码的证书certificateLen

25、 IN: DER编码的证书长度返回值 RV_OK：成功其 ：失败5.3.3 黑名单：PKI_AddCrl函数名称 PKI_RVPKI_AddCrl(unsigned char *derCrl,unsigned long derCrlLen);功能介 加 名currency1参数说明 derCrl IN: DER编码的CRLderCrlLen IN: DER编码的CRL长度返回值 RV_OK：成功其 ：失败5.3.4 设 用 证书：PKI_SetUsrCertificate函数名称 PKI_RVPKI_SetUsrCertificate(unsigned char *containerName,

26、unsigned long containerLen,unsigned long keyUsage,unsigned char *certificate,unsigned long certificateLen);功能介 设用 证书参数说明 containerName IN: 密 的容器名containerNameLen IN: 密 的容器名长度keyUsage IN: 密 用certificate IN: DER编码的证书8 DB11/T 254.2-2004certificateLen IN: DER编码的证书长度返回值 RV_OK：成功其 ：失败5.3.5 用 证书：PKI_GetUsr

27、Certificate函数名称 PKI_RVPKI_GetUsrCertificate(unsigned char *containerName,unsigned long containerLen,unsigned long keyUsage,unsigned char *certificate,unsigned long *certificateLen);功能介 用 证书参数说明 containerName IN: 容器名containerNameLen IN: 容器名长度keyUsage IN: 密 用certificate OUT: DER编码的证书certificateLen OUT

28、: DER编码的证书长度返回值 RV_OK：成功其 ：失败5.3.6 验证用 证书：PKI_VerifyUsrCertificate函数名称 PKI_RVPKI_VerifyUsrCertificate(unsigned char *usrCertificate,unsigned long usrCertificateLen);功能介 证用 证书参数说明 usrCertificate IN: DER编码的证书usrCertificateLen IN: DER编码的证书长度返回值 RV_OK：成功其 ：失败5.3.7 CRL文件验证用 证书 销：PKI_VerifyUsrCertificateB

29、yCrl函数名称 PKI_RVPKI_VerifyUsrCertificateByCrl (unsigned char *usrCertificate,9 DB11/T 254.2-2004unsigned long usrCertificateLen,unsigned char *derCrl, unsigned long derCrlLen);功能介 根据CRL文件 证用 证书 否 注 参数说明 usrCertificate IN: DER编码的证书usrCertificateLen IN: DER编码的证书长度derCrlIN:DER编码的 名currency1derCrlLen:DER

30、编码的 名currency1长度返回值 RV_OK：成功其 ：失败5.3.8 OCSP 证书 ：PKI_OcspVerifyCertificate函数名称 PKI_RVPKI_OcspVerifyCertificate (char *ocspServerIpAddress,unsigned long ocspServerPort,unsigned char *derRequestCert,unsigned long derRequestCertLen,unsigned char needVerifedCert,unsigned long needVerifedCertLen,unsigned

31、long *certStatus);功能介 通过OCSP 证证书的“前状态参数说明 ocspServerIpAddressIN: OCSP Server IPocspServerPortIN: OCSP Server PortderRequestCertIN: OCSP申请的用 证书derRequestCertLenIN: OCSP申请的用 证书长度needVerifedCertIN: 证的证书needVerifedCertLenIN: 证的证书长度certStatusOUT:返回的证书状态返回值 RV_OK：成功其 ：失败5.3.9 LDAP方 证书：PKI_GetCertFromLdap函

32、数名称PKI_RVPKI_GetCertFromLdap (Char * ldapHostIp,unsigned long ldapPort,10 DB11/T 254.2-2004unsigned char *SubDN,unsigned long SubDNLen,unsigned char *outCert,unsigned long *outCertLen);功能介 通过LDAP 式 证书参数说明ldapHostIp IN: ldap服务器IP 址ldapPortIN: ldap服务器端口SubDNIN: 查找的证书的DNSubDNLen IN: 查找的证书的DN长度outCert O

33、UT:找的DER编码的证书outCertLen OUT: 找的DER编码的证书长度返回值 RV_OK：成功其 ：失败5.3.10 LDAP方 证书 CRL：PKI_GetCrlFromLdap函数名称 PKI_RVPKI_GetCrlFromLdap (char * ldapHostIp,unsigned long ldapPort,unsigned char * Certificate,unsigned long CertificateLen,unsigned char * crlData,unsigned long * crlDataLen);功能介 通过LDAP 式根据证书 CRL参数说

34、明 ldapHostIp IN: ldap服务器IP 址ldapPortIN: ldap服务器端口Certificate IN: 证书CertificateLen IN: 证书长度crlData OUT:找的DER编码的证书crlDataLen OUT: 找的DER编码的证书长度返回值 RV_OK：成功其 ：失败5.3.11 证书信 ：PKI_GetCertificateInfo函数名称 PKI_RVPKI_GetCertificateInfo(unsigned char *certificate,unsigned long certificateLen,11 DB11/T 254.2-2004unsigned long infoType,void *info1,void *info2);功能介 析证书 证书的 息参数说明 certificate IN: DER编码的证书certificateLen IN: DER编码的证书长度infoType IN: 证书域的 息类型info1 OUT: 息1 根据