GM/T 0019-2012 English PDF (GMT0019-2012)
GM/T 0019-2012 English PDF (GMT0019-2012)
GM/T 0019-2012: Universal cryptography service interface specification
CRYPTOGRAPHY INDUSTRY STANDARD
OF THE PEOPLE REPUBLIC OF CHINA
File No.. 38317-2013
Universal cryptography service interface specification
ISSUED ON. NOVEMBER 22, 2012
IMPLEMENTED ON. NOVEMBER 22, 2012
Issued by. State Cryptography Administration
Table of Contents
Foreword ... 3
1 Scope .. 5
2 Normative references ... 5
3 Terms and definitions ... 5
4 Symbols and abbreviations ... 6
5 Algorithm identification and data structure... 6
5.1 Algorithm identifier and constant definition .. 6
5.2 Cryptographic service interface data structure definition and description ... 7 6 Cryptography service interface ... 9
6.1 Location of universal cryptography service interface in the framework of public key cryptography infrastructure application technology system ... 9 6.2 Cryptographic service interface composition and function description ... 10 7 Cryptography service interface function definition ... 12
7.1 Environment class function ... 12
7.2 Certificate class function .. 15
7.3 Cryptography operation class function ... 22
7.4 Message class function ... 43
Appendix A (Normative) Cryptography service interface error code definition 53 References ... 55
This Standard was drafted in accordance with the rules given in GB/T 1.1-2009. Attention is drawn to the possibility that some of the elements of this Standard may be the subject of patent rights. The issuing authority shall not be held responsible for identifying any or all such patent rights.
Appendix A of this standard is normative Appendix.
This Standard was proposed by and shall be under the jurisdiction of Code Industry Standardization Technical Committee.
Main drafting organizations of this Standard. Beijing Digital Certification Co., Ltd., Shanghai Geer Software Co., Ltd., Beijing Haitai Fangyuan Technology Co., Ltd., Wuxi Jiangnan Information Security Engineering Technology Center, Shanghai Digital Certificate Certification Center Co., Ltd., Guardian Information Industry Co., Ltd., Shandong De'an Information Technology Co., Ltd., National Information Security Engineering Technology Research Center.
Main drafters of this Standard. Liu Ping, Li Shusheng, Tan Wuzheng, Liu Zengshou, Xu Qiang, Liu Cheng, Li Yuanzheng, Gao Zhiquan, Kong Fanyu,
This standard involves cryptographic algorithms related content, which is implemented in accordance with the relevant state laws and regulations. Universal cryptography service interface specification
This standard specifies a unified universal cryptography service interface. This standard applies to the cryptography application service development under the public key application technology system, the R and D and detection of the cryptography application support platform, and to guide the development of the application system by direct use of the cryptography device.
2 Normative references
The following documents are essential to the application of this document. For the dated documents, only the versions with the dates indicated are applicable to this document; for the undated documents, only the latest version (including all the amendments) are applicable to this standard.
GM/T 0006 Cryptographic application identifier criterion specification
GM/T 0015 Digital certificate format based on SM2 algorithm
GM/T 0018 Interface specifications of cryptography device application
GM/T 0016 Smart token cryptography application interface specification
GM/T 0010 SM2 cryptography message syntax specification
GM/T 0009 SM2 Cryptography Algorithm Application Specification
PKCS #7. Cryptographic Message Syntax
3 Terms and definitions
The following terms and definitions apply to this document.
Digital file signed by the authentication authority number, including public key owner information, public key, signer information, validation date, and some extension information.
An asymmetric key pair stored in the device that is used for application cryptographic operations, including a signature key pair and an encryption key pair.
It is used in the cryptographic device to store the unique storage space divided by the key.
4 Symbols and abbreviations
The following abbreviations apply to this document.
API. Application Program Interface, referred to as application interface CA. Certification Authority
CN. Common Name
CRL. Certificate Revocation List
DER. Distinguished Encoding Rules
DN. Distinguished Name
ECC. Elliptic Curve Cryptography
LDAP. Lightweight Directory Access Protocol
OlD. Object IDentifier
PKCS. the Public-Key Cryptography Standard
5 Algorithm identification and data structure
5.1 Algorithm identifier and constant definition
The constant definitions used in this specification, the specific definitions of operations are carried out in a safe and trusted program space. Environment class functions are also responsible for creating and managing the security access token between the user and the cryptographic devices. There are two types of user secure access tokens that can be created, one for normal users, this type of secure access token identifies that this user is a normal user, who can only access his/her own information and data in the cryptographic device; the other is for administrator, this type of secure access token identifies that this user is administrator, who can manage the security token of the normal user. When the application uses the cryptography service interface, it must first call the initialization environment function (SAF_Initialize) to create and initialize the secure application space, to complete the connection and initialization with the cryptography device. Before aborting the application, it shall call the clear environment function (SAF_Finalize), to abort the connection to the
cryptography device, destroy the security program space created, and prevent the security risk caused by memory residue. Application shall first call the user login function (SAF_Login) to establish the secure access token before
performing any cryptography operation by calling any cryptography service function. After establishing the secure access token, it can call any
cryptography service function. When no more cryptography service function is called, it shall call the logout function (SAF_Logout) to logout the secure access token, to avoid the cryptography device from illegal access.
6.2.3 Certificate class functions
Certificate class functions set various types of digital certificates to the application interface session environment to verify user certificates and get digital certificates or CRL, to provide a series of specific functions including certificate acquisition, CRL acquisition, CA root certificate setting, user certificate verification, and user certificate information acquisition. The application achieves digital certificate-based identity authentication through calling the certificate function, acquires relevant information from certificate, achieves authorization management, access control, and other security
mechanism. The digital certificate formats covered in this standard shall follow GM/T 0015.
6.2.4 Cryptography operation class functions
The cryptography class function is responsible for interacting with the cryptography device to achieve a specific cryptographic operation, and
returning the result of the cryptography operation back to the application, which is the foundation for the applications to achieve security mechanisms such as data confidentiality, integrity, and non-repudiation.
Cryptography operation class functions provide including base64 codec,
7.2 Certificate class function
Certificate class functions include the following specific functions, the return value of each function is as shown in the Appendix A. Error code definition. a) Add root CA certificate. SAF_AddTrustedRootCaCertificate
b) Get number of root CA certificates. SAF_GetRootCaCertificateCount
c) Get root CA certificate. SAF_GetRootCaCertificate
d) Remove root CA certificate. SAF_RemoveRootCaCertificate
e) Add CA Certificate. SAF_AddCaCertificate
f) Get number of CA certificates. SAF_GetCaCertificateCount
g) Get the CA certificate. SAF_GetCaCertificate
h) Remove CA certificate. SAF_RemoveCaCertificate
i) Add CRL. SAF_AddCrl
j) Verify user certificate. SAF_VerifyCertificate
k) Get user certificate logout status by CRL file. SAF_VerifyCertificateByCrl l) Get certificate status by OCSP. SAF_GetCertificateStateByOCSP
m) Get certificate from LDAP. SAF_GetCertificateFromLdap
n) Get CRL corresponding to the certificate from LDAP.
o) Get certificate information. SAF_GetCertificatelnfo