1 /* 2 * This file is part of the openHiTLS project. 3 * 4 * openHiTLS is licensed under the Mulan PSL v2. 5 * You can use this software according to the terms and conditions of the Mulan PSL v2. 6 * You may obtain a copy of Mulan PSL v2 at: 7 * 8 * http://license.coscl.org.cn/MulanPSL2 9 * 10 * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, 11 * EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, 12 * MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE. 13 * See the Mulan PSL v2 for more details. 14 */ 15 16 #ifndef HITLS_PKI_CERT_H 17 #define HITLS_PKI_CERT_H 18 19 #include "hitls_pki_types.h" 20 #include "crypt_eal_pkey.h" 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 typedef struct _HITLS_X509_Cert HITLS_X509_Cert; 27 28 /** 29 * @ingroup pki 30 * @brief Allocate a certificate. 31 * 32 * @retval HITLS_X509_Cert * 33 */ 34 HITLS_X509_Cert *HITLS_X509_CertNew(void); 35 36 /** 37 * @brief Create a new X509 certificate object using the provider mechanism 38 * 39 * @param libCtx [IN] Library context from CRYPT_EAL_LibCtx 40 * @param attrName [IN] Provider attribute name for capability matching 41 * 42 * @return HITLS_X509_Cert* Certificate object or NULL on failure 43 */ 44 HITLS_X509_Cert *HITLS_X509_ProviderCertNew(HITLS_PKI_LibCtx *libCtx, const char *attrName); 45 46 /** 47 * @ingroup pki 48 * @brief Unallocate a certificate. 49 * 50 * @param cert [IN] The certificate. 51 */ 52 void HITLS_X509_CertFree(HITLS_X509_Cert *cert); 53 54 /** 55 * @ingroup pki 56 * @brief Duplicate a certificate. 57 * 58 * @param src [IN] Source certificate. 59 * @retval HITLS_X509_Cert *, success. 60 * NULL, fail. 61 */ 62 HITLS_X509_Cert *HITLS_X509_CertDup(HITLS_X509_Cert *src); 63 64 /** 65 * @ingroup pki 66 * @brief Sign a certificate. 67 * 68 * @attention 1. This function can only be used when generating a new certificate. 69 * 2. You need to first call interfaces HITLS_X509_CertCtrl to set cert information. 70 * 71 * @param mdId [IN] The message digest algorithm ID. 72 * @param prvKey [IN] The private key context used for signing. 73 * @param algParam [IN] The signature algorithm parameters. 74 * @param cert [IN] The certificate to be signed. 75 * @retval #HITLS_PKI_SUCCESS, success. 76 * Error codes can be found in hitls_pki_errno.h 77 */ 78 int32_t HITLS_X509_CertSign(int32_t mdId, const CRYPT_EAL_PkeyCtx *prvKey, const HITLS_X509_SignAlgParam *algParam, 79 HITLS_X509_Cert *cert); 80 81 /** 82 * @ingroup pki 83 * @brief Compute the digest of the certificate. 84 * 85 * @attention This function must be called after generating or parsing a certificate. 86 * 87 * @param cert [IN] The certificate. 88 * @param mdId [IN] Digest algorithm. 89 * @param data [IN/OUT] The digest result. 90 * @param dataLen [IN/OUT] The length of the digest. 91 * @retval #HITLS_PKI_SUCCESS, success. 92 * Error codes can be found in hitls_pki_errno.h 93 */ 94 int32_t HITLS_X509_CertDigest(HITLS_X509_Cert *cert, CRYPT_MD_AlgId mdId, uint8_t *data, uint32_t *dataLen); 95 96 /** 97 * @ingroup pki 98 * @brief Generic function to process certificate. 99 * 100 * @param cert [IN] The certificate. 101 * @param cmd [IN] HITLS_X509_Cmd 102 * @param val [IN/OUT] input and output value 103 * @param valLen [In] value length 104 * @retval #HITLS_PKI_SUCCESS, success. 105 * Error codes can be found in hitls_pki_errno.h 106 */ 107 int32_t HITLS_X509_CertCtrl(HITLS_X509_Cert *cert, int32_t cmd, void *val, uint32_t valLen); 108 109 /** 110 * @ingroup pki 111 * @brief Parse the CERT in the buffer. 112 * @par Description: Parse the CERT in the buffer. 113 * If the encoding is successful, the memory for the crl is requested from within the function, 114 * and the user needs to free it after using it. When the parameter is BSL_FORMAT_PEM and 115 * BSL_FORMAT_UNKNOWN, the buff of encode needs to end with '\0' 116 * @attention None 117 * @param format [IN] Encoding format: BSL_FORMAT_PEM/BSL_FORMAT_ASN1/BSL_FORMAT_UNKNOWN. 118 * @param encode [IN] CERT data. 119 * @param cert [OUT] CERT after parse. 120 * @return #HITLS_PKI_SUCCESS, success. 121 * Error codes can be found in hitls_pki_errno.h 122 */ 123 int32_t HITLS_X509_CertParseBuff(int32_t format, const BSL_Buffer *encode, HITLS_X509_Cert **cert); 124 125 /** 126 * @ingroup pki 127 * @brief Parse a certificate buffer using the provider mechanism 128 * @par Description: Parse the certificate data using a specific provider implementation. 129 * If parsing is successful, memory for the certificate is allocated internally, 130 * and the user needs to free it after use. 131 * 132 * @param libCtx [IN] Library context from CRYPT_EAL_LibCtx 133 * @param attrName [IN] Provider attribute name for capability matching 134 * @param format [IN] Encoding format: BSL_FORMAT_PEM/BSL_FORMAT_ASN1/BSL_FORMAT_UNKNOWN 135 * @param encode [IN] Certificate data buffer 136 * @param cert [OUT] Parsed certificate object 137 * @return #HITLS_PKI_SUCCESS, success. 138 * Error codes can be found in hitls_pki_errno.h 139 */ 140 int32_t HITLS_X509_ProviderCertParseBuff(HITLS_PKI_LibCtx *libCtx, const char *attrName, const char *format, 141 const BSL_Buffer *encode, HITLS_X509_Cert **cert); 142 143 /** 144 * @ingroup pki 145 * @brief Parse the CERT in the file. 146 * @par Description: Parse the CERT in the file. 147 * If the encoding is successful, the memory for the crl is requested from within the function, 148 * and the user needs to free it after using it. 149 * @attention None 150 * @param format [IN] Encoding format: BSL_FORMAT_PEM/BSL_FORMAT_ASN1/BSL_FORMAT_UNKNOWN. 151 * @param path [IN] CERT file path. 152 * @param cert [OUT] CERT after parse. 153 * @return #HITLS_PKI_SUCCESS, success. 154 * Error codes can be found in hitls_pki_errno.h 155 */ 156 int32_t HITLS_X509_CertParseFile(int32_t format, const char *path, HITLS_X509_Cert **cert); 157 158 /** 159 * @ingroup pki 160 * @brief Parse a certificate file using the provider mechanism 161 * @par Description: Parse the certificate from a file using a specific provider implementation. 162 * If parsing is successful, memory for the certificate is allocated internally, 163 * and the user needs to free it after use. 164 * 165 * @param libCtx [IN] Library context from CRYPT_EAL_LibCtx 166 * @param attrName [IN] Provider attribute name for capability matching 167 * @param format [IN] Encoding format: PEM/ASN1/NULL 168 * @param path [IN] Certificate file path 169 * @param cert [OUT] Parsed certificate object 170 * @return #HITLS_PKI_SUCCESS, success. 171 * Error codes can be found in hitls_pki_errno.h 172 */ 173 int32_t HITLS_X509_ProviderCertParseFile(HITLS_PKI_LibCtx *libCtx, const char *attrName, const char *format, 174 const char *path, HITLS_X509_Cert **cert); 175 176 /** 177 * @ingroup pki 178 * @brief Parse the CERTs in the file. 179 * @par Description: Parse multiple CERTs in the file. 180 * If the encoding is successful, the memory for the certlist is requested from within the function, 181 * and the user needs to free it after using it. 182 * @attention None 183 * @param format [IN] Encoding format: BSL_FORMAT_PEM/BSL_FORMAT_ASN1/BSL_FORMAT_UNKNOWN. 184 * @param path [IN] CRL file path. 185 * @param crllist [OUT] CRL list after parse. 186 * @return #HITLS_PKI_SUCCESS, success. 187 * Error codes can be found in hitls_pki_errno.h 188 */ 189 int32_t HITLS_X509_CertParseBundleFile(int32_t format, const char *path, HITLS_X509_List **certlist); 190 191 /** 192 * @ingroup pki 193 * @brief Parse multiple certificates from a bundle file using the provider mechanism 194 * @par Description: Parse multiple certificates from a file using a specific provider implementation. 195 * If parsing is successful, memory for the certificate list is allocated internally, 196 * and the user needs to free it after use. 197 * 198 * @param libCtx [IN] Library context from CRYPT_EAL_LibCtx 199 * @param attrName [IN] Provider attribute name for capability matching 200 * @param format [IN] Encoding format: PEM/ASN1/NULL 201 * @param path [IN] Certificate bundle file path 202 * @param certlist [OUT] List of parsed certificate objects 203 * @return #HITLS_PKI_SUCCESS, success. 204 * Error codes can be found in hitls_pki_errno.h 205 */ 206 int32_t HITLS_X509_ProviderCertParseBundleFile(HITLS_PKI_LibCtx *libCtx, const char *attrName, const char *format, 207 const char *path, HITLS_X509_List **certlist); 208 209 /** 210 * @ingroup pki 211 * @brief Generates an encoded certificate. 212 * 213 * @attention This function is used after parsing the certificate or after signing. 214 * 215 * @param format [IN] Encoding format: BSL_FORMAT_ASN1 or BSL_FORMAT_PEM 216 * @param cert [IN] cert 217 * @param buff [OUT] encode result 218 * @retval #HITLS_PKI_SUCCESS, success. 219 * Error codes can be found in hitls_pki_errno.h 220 */ 221 int32_t HITLS_X509_CertGenBuff(int32_t format, HITLS_X509_Cert *cert, BSL_Buffer *buff); 222 223 /** 224 * @ingroup pki 225 * @brief Generate a certificate file. 226 * 227 * @attention This function is used after parsing the certificate or after signing. 228 * 229 * @param format [IN] Encoding format: BSL_FORMAT_ASN1 or BSL_FORMAT_PEM 230 * @param cert [IN] cert 231 * @param path [IN] file path 232 * @retval #HITLS_PKI_SUCCESS, success. 233 * Error codes can be found in hitls_pki_errno.h 234 */ 235 int32_t HITLS_X509_CertGenFile(int32_t format, HITLS_X509_Cert *cert, const char *path); 236 237 #ifdef __cplusplus 238 } 239 #endif 240 241 #endif // HITLS_PKI_CERT_H 242