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 CERT_MGR_H 17 #define CERT_MGR_H 18 19 #include <stdint.h> 20 #include "hitls_type.h" 21 #include "hitls_cert_type.h" 22 #include "hitls_cert_reg.h" 23 #include "hitls_cert.h" 24 #include "tls_config.h" 25 #include "bsl_hash.h" 26 27 #ifdef __cplusplus 28 extern "C" { 29 #endif 30 31 /* Used to transfer certificates, private keys, and certificate chains. */ 32 typedef struct CertPairInner CERT_Pair; 33 34 /** 35 * @brief Obtain the certificate 36 * 37 * @param certPair [IN] Certificate resource struct 38 * 39 * @return Certificate 40 */ 41 HITLS_CERT_X509 *SAL_CERT_PairGetX509(CERT_Pair *certPair); 42 43 /** 44 * @ingroup hitls_cert_reg 45 * @brief Obtain the encryption certificate 46 * 47 * @param certPair [IN] Certificate resource struct 48 * 49 * @return Encryption certificate 50 */ 51 HITLS_CERT_X509 *SAL_CERT_GetTlcpEncCert(CERT_Pair *certPair); 52 53 HITLS_CERT_Chain *SAL_CERT_PairGetChain(CERT_Pair *certPair); 54 55 CERT_Pair *SAL_CERT_PairDup(CERT_MgrCtx *mgrCtx, CERT_Pair *srcCertPair); 56 57 /** 58 * @brief Uninstall the certificate resource but not release the struct 59 * 60 * @param mgrCtx [IN] Certificate management struct 61 * @param certPair [IN] Certificate resource struct 62 * 63 * @return void 64 */ 65 void SAL_CERT_PairClear(CERT_MgrCtx *mgrCtx, CERT_Pair *certPair); 66 67 /** 68 * @brief Release the certificate resource struct 69 * 70 * @param mgrCtx [IN] Certificate management struct 71 * @param certPair [IN] Certificate resource struct. The certPair is set NULL by the invoker. 72 * 73 * @return void 74 */ 75 void SAL_CERT_PairFree(CERT_MgrCtx *mgrCtx, CERT_Pair *certPair); 76 77 /** 78 * @brief Copy certificate hash table 79 * 80 * @param destMgrCtx [OUT] Certificate management struct 81 * @param srcMgrCtx [IN] Certificate management struct 82 * 83 * @retval HITLS_SUCCESS succeeded. 84 */ 85 int32_t SAL_CERT_HashDup(CERT_MgrCtx *destMgrCtx, CERT_MgrCtx *srcMgrCtx); 86 87 /** 88 * @brief Indicates whether to enable the certificate management module. 89 * 90 * @param void 91 * 92 * @retval true yes 93 * @retval false no 94 */ 95 bool SAL_CERT_MgrIsEnable(void); 96 97 /** 98 * @brief Callback for obtaining a certificate 99 * 100 * @param NA 101 * 102 * @return Certificate callback 103 */ 104 HITLS_CERT_MgrMethod *SAL_CERT_GetMgrMethod(void); 105 106 /** 107 * @brief Create a certificate management struct 108 * 109 * @param void 110 * 111 * @return Certificate management struct 112 */ 113 CERT_MgrCtx *SAL_CERT_MgrCtxNew(void); 114 115 /** 116 * @brief Create a certificate management struct with provider 117 * 118 * @param libCtx [IN] Provider library context 119 * @param attrName [IN] Provider attrName 120 * 121 * @return Certificate management struct 122 */ 123 CERT_MgrCtx *SAL_CERT_MgrCtxProviderNew(HITLS_Lib_Ctx *libCtx, const char *attrName); 124 125 /** 126 * @brief Copy the certificate management struct 127 * 128 * @param mgrCtx [IN] Certificate management struct 129 * 130 * @return Certificate management struct 131 */ 132 CERT_MgrCtx *SAL_CERT_MgrCtxDup(CERT_MgrCtx *mgrCtx); 133 134 /** 135 * @brief Release the certificate management struct 136 * 137 * @param mgrCtx [IN] Certificate management struct. mgrCtx is set NULL by the invoker. 138 * 139 * @return void 140 */ 141 void SAL_CERT_MgrCtxFree(CERT_MgrCtx *mgrCtx); 142 143 /** 144 * @brief Set the cert store 145 * 146 * @param mgrCtx [IN] Certificate management struct 147 * @param store [IN] cert store 148 * 149 * @retval HITLS_SUCCESS succeeded. 150 */ 151 int32_t SAL_CERT_SetCertStore(CERT_MgrCtx *mgrCtx, HITLS_CERT_Store *store); 152 153 /** 154 * @brief Obtain the cert store 155 * 156 * @param mgrCtx [IN] Certificate management struct 157 * 158 * @return cert store 159 */ 160 HITLS_CERT_Store *SAL_CERT_GetCertStore(CERT_MgrCtx *mgrCtx); 161 162 /** 163 * @brief Set the chain store 164 * 165 * @param mgrCtx [IN] Certificate management struct 166 * @param store [IN] chain store 167 * 168 * @retval HITLS_SUCCESS succeeded. 169 */ 170 int32_t SAL_CERT_SetChainStore(CERT_MgrCtx *mgrCtx, HITLS_CERT_Store *store); 171 172 /** 173 * @brief Obtain the chain store 174 * 175 * @param mgrCtx [IN] Certificate management struct 176 * 177 * @return chain store 178 */ 179 HITLS_CERT_Store *SAL_CERT_GetChainStore(CERT_MgrCtx *mgrCtx); 180 181 /** 182 * @brief Set the verify store 183 * 184 * @param mgrCtx [IN] Certificate management struct 185 * @param store [IN] verify store 186 * 187 * @retval HITLS_SUCCESS succeeded. 188 */ 189 int32_t SAL_CERT_SetVerifyStore(CERT_MgrCtx *mgrCtx, HITLS_CERT_Store *store); 190 191 /** 192 * @brief Obtain the verify store 193 * 194 * @param mgrCtx [IN] Certificate management struct 195 * 196 * @return verify store 197 */ 198 HITLS_CERT_Store *SAL_CERT_GetVerifyStore(CERT_MgrCtx *mgrCtx); 199 200 /** 201 * @brief Add a device certificate and set it to the current. Only one certificate of each type can be added. 202 * If the certificate is added repeatedly, the certificate will be overwritten. 203 * 204 * @param config [IN] Certificate management struct 205 * @param cert [IN] Device certificate 206 * @param isGmEncCert [IN] Indicates whether the certificate is encrypted using the TLCP. 207 * 208 * @retval HITLS_SUCCESS succeeded. 209 */ 210 int32_t SAL_CERT_SetCurrentCert(HITLS_Config *config, HITLS_CERT_X509 *cert, bool isTlcpEncCert); 211 212 /** 213 * @brief Obtain the current device certificate 214 * 215 * @param mgrCtx [IN] Certificate management struct 216 * 217 * @return Device certificate 218 */ 219 HITLS_CERT_X509 *SAL_CERT_GetCurrentCert(CERT_MgrCtx *mgrCtx); 220 221 /** 222 * @brief Obtain the certificate of the specified type. 223 * 224 * @param mgrCtx [IN] Certificate management struct 225 * @param keyType [IN] Certificate public key type 226 * 227 * @return Device certificate 228 */ 229 HITLS_CERT_X509 *SAL_CERT_GetCert(CERT_MgrCtx *mgrCtx, HITLS_CERT_KeyType keyType); 230 231 /** 232 * @brief Add a private key and set it to the current key. 233 * Only one private key can be added for each type of certificate. 234 * If a private key is added repeatedly, it will be overwritten. 235 * 236 * @param config [IN] Certificate management struct 237 * @param key [IN] Private key 238 * @param isGmEncCertPriKey [IN] Indicates whether the private key of the certificate encrypted 239 * using the TLCP. 240 * 241 * @retval HITLS_SUCCESS succeeded. 242 */ 243 int32_t SAL_CERT_SetCurrentPrivateKey(HITLS_Config *config, HITLS_CERT_Key *key, bool isTlcpEncCertPriKey); 244 245 /** 246 * @brief Obtain the current private key 247 * 248 * @param mgrCtx [IN] Certificate management struct 249 * @param isGmEncCertPriKey [IN] Indicates whether the private key of the certificate encrypted 250 * using the TLCP. 251 * 252 * @return Private key 253 */ 254 HITLS_CERT_Key *SAL_CERT_GetCurrentPrivateKey(CERT_MgrCtx *mgrCtx, bool isTlcpEncCert); 255 256 /** 257 * @brief Obtain the private key of a specified type. 258 * 259 * @param mgrCtx [IN] Certificate management struct 260 * @param keyType [IN] Private key type 261 * 262 * @return Private key 263 */ 264 HITLS_CERT_Key *SAL_CERT_GetPrivateKey(CERT_MgrCtx *mgrCtx, HITLS_CERT_KeyType keyType); 265 266 int32_t SAL_CERT_AddChainCert(CERT_MgrCtx *mgrCtx, HITLS_CERT_X509 *cert); 267 268 HITLS_CERT_Chain *SAL_CERT_GetCurrentChainCerts(CERT_MgrCtx *mgrCtx); 269 270 void SAL_CERT_ClearCurrentChainCerts(CERT_MgrCtx *mgrCtx); 271 272 /** 273 * @brief Delete all certificate resources, including the device certificate, private key, and certificate chain. 274 * 275 * @param mgrCtx [IN] Certificate management struct 276 * 277 * @return void 278 */ 279 void SAL_CERT_ClearCertAndKey(CERT_MgrCtx *mgrCtx); 280 281 int32_t SAL_CERT_AddExtraChainCert(CERT_MgrCtx *mgrCtx, HITLS_CERT_X509 *cert); 282 283 HITLS_CERT_Chain *SAL_CERT_GetExtraChainCerts(CERT_MgrCtx *mgrCtx); 284 285 void SAL_CERT_ClearExtraChainCerts(CERT_MgrCtx *mgrCtx); 286 287 /** 288 * @brief Set the verification depth 289 * 290 * @param mgrCtx [IN] Certificate management struct 291 * @param depth [IN] Verification depth 292 * 293 * @retval HITLS_SUCCESS succeeded. 294 */ 295 int32_t SAL_CERT_SetVerifyDepth(CERT_MgrCtx *mgrCtx, uint32_t depth); 296 297 /** 298 * @brief Obtain the verification depth 299 * 300 * @param mgrCtx [IN] Certificate management struct 301 * @param depth [IN] Verification depth 302 * 303 * @retval HITLS_SUCCESS succeeded. 304 */ 305 int32_t SAL_CERT_GetVerifyDepth(CERT_MgrCtx *mgrCtx, uint32_t *depth); 306 307 /** 308 * @brief Set the default passwd callback. 309 * 310 * @param mgrCtx [IN] Certificate management struct 311 * @param cb [IN] Callback function 312 * 313 * @retval HITLS_SUCCESS succeeded. 314 */ 315 int32_t SAL_CERT_SetDefaultPasswordCb(CERT_MgrCtx *mgrCtx, HITLS_PasswordCb cb); 316 317 /** 318 * @brief Obtain the default passwd callback. 319 * 320 * @param mgrCtx [IN] Certificate management struct 321 * 322 * @return Callback function 323 */ 324 HITLS_PasswordCb SAL_CERT_GetDefaultPasswordCb(CERT_MgrCtx *mgrCtx); 325 326 /** 327 * @brief Set the user data used in the default passwd callback. 328 * 329 * @param mgrCtx [IN] Certificate management struct 330 * @param userdata [IN] User data 331 * 332 * @retval HITLS_SUCCESS succeeded. 333 */ 334 int32_t SAL_CERT_SetDefaultPasswordCbUserdata(CERT_MgrCtx *mgrCtx, void *userdata); 335 336 /** 337 * @brief Obtain the user data used in the default passwd callback. 338 * 339 * @param mgrCtx [IN] Certificate management struct 340 * 341 * @return User data 342 */ 343 void *SAL_CERT_GetDefaultPasswordCbUserdata(CERT_MgrCtx *mgrCtx); 344 345 /** 346 * @brief Set the verify callback function, which is used during certificate verification. 347 * 348 * @param mgrCtx [IN] Certificate management struct 349 * @param cb [IN] User data 350 * 351 * @retval HITLS_SUCCESS succeeded. 352 */ 353 int32_t SAL_CERT_SetVerifyCb(CERT_MgrCtx *mgrCtx, HITLS_VerifyCb cb); 354 355 /** 356 * @brief Obtain the verify callback function. 357 * 358 * @param mgrCtx [IN] Certificate management struct 359 * 360 * @return Callback function 361 */ 362 HITLS_VerifyCb SAL_CERT_GetVerifyCb(CERT_MgrCtx *mgrCtx); 363 364 #ifdef __cplusplus 365 } 366 #endif 367 #endif