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 * @defgroup hitls_cert_reg 17 * @ingroup hitls 18 * @brief Certificate related interfaces to be registered 19 */ 20 21 #ifndef HITLS_CERT_REG_H 22 #define HITLS_CERT_REG_H 23 24 #include <stdint.h> 25 #include "hitls_crypt_type.h" 26 #include "hitls_cert_type.h" 27 #include "hitls_type.h" 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 /** 34 * @ingroup hitls_cert_reg 35 * @brief Create a certificate store 36 * 37 * @param void 38 * 39 * @retval Certificate store 40 */ 41 typedef HITLS_CERT_Store *(*CERT_StoreNewCallBack)(void); 42 43 /** 44 * @ingroup hitls_cert_reg 45 * @brief Duplicate the certificate store. 46 * 47 * @param store [IN] Certificate store. 48 * 49 * @retval New certificate store. 50 */ 51 typedef HITLS_CERT_Store *(*CERT_StoreDupCallBack)(HITLS_CERT_Store *store); 52 53 /** 54 * @ingroup hitls_cert_reg 55 * @brief Release the certificate store. 56 * 57 * @param store [IN] Certificate store. 58 * 59 * @retval void 60 */ 61 typedef void (*CERT_StoreFreeCallBack)(HITLS_CERT_Store *store); 62 63 /** 64 * @ingroup hitls_cert_reg 65 * @brief ctrl interface 66 * 67 * @param config [IN] TLS link configuration. 68 * @param store [IN] Certificate store. 69 * @param cmd [IN] Ctrl option. 70 * @param input [IN] Input. 71 * @param output [IN] Output. 72 * 73 * @retval HITLS_SUCCESS indicates success. Other values are considered as failure. 74 */ 75 typedef int32_t (*CERT_StoreCtrlCallBack)(HITLS_Config *config, HITLS_CERT_Store *store, HITLS_CERT_CtrlCmd cmd, 76 void *input, void *output); 77 78 /** 79 * @ingroup hitls_cert_reg 80 * @brief Create a certificate chain based on the device certificate in use. 81 * 82 * @attention If the function is successful, the certificate in the certificate chain is managed by the HiTLS, 83 * and the user does not need to release the memory. Otherwise, the certificate chain is an empty pointer 84 * array. 85 * @param config [IN] TLS link configuration 86 * @param store [IN] Certificate store 87 * @param cert [IN] Device certificate 88 * @param certList [OUT] Certificate chain, which is a pointer array. Each element indicates a certificate. 89 * The first element is the device certificate. 90 * @param num [IN/OUT] IN: maximum length of the certificate chain OUT: length of the certificate chain 91 * 92 * @retval HITLS_SUCCESS indicates success. Other values are considered as failure. 93 */ 94 typedef int32_t (*CERT_BuildCertChainCallBack)(HITLS_Config *config, HITLS_CERT_Store *store, HITLS_CERT_X509 *cert, 95 HITLS_CERT_X509 **certList, uint32_t *num); 96 97 /** 98 * @ingroup hitls_cert_reg 99 * @brief Verify the certificate chain 100 * 101 * @param ctx [IN] TLS link object 102 * @param store [IN] Certificate store. 103 * @param certList [IN] Certificate chain, a pointer array, each element indicates a certificate. 104 * The first element indicates the device certificate. 105 * @param num [IN] Certificate chain length. 106 * 107 * @retval HITLS_SUCCESS indicates success. Other values are considered as failure. 108 */ 109 typedef int32_t (*CERT_VerifyCertChainCallBack)(HITLS_Ctx *ctx, HITLS_CERT_Store *store, 110 HITLS_CERT_X509 **certList, uint32_t num); 111 112 /** 113 * @ingroup hitls_cert_reg 114 * @brief Encode the certificate in ASN.1 DER format. 115 * 116 * @param ctx [IN] TLS link object. 117 * @param cert [IN] Certificate. 118 * @param buf [OUT] Certificate encoding data. 119 * @param len [IN] Maximum encoding length. 120 * @param usedLen [OUT] Actual encoding length. 121 * 122 * @retval HITLS_SUCCESS indicates success. Other values are considered as failure. 123 */ 124 typedef int32_t (*CERT_CertEncodeCallBack)(HITLS_Ctx *ctx, HITLS_CERT_X509 *cert, uint8_t *buf, uint32_t len, 125 uint32_t *usedLen); 126 127 /** 128 * @ingroup hitls_cert_reg 129 * @brief Read the certificate. 130 * 131 * @attention If the data is loaded to config, config points to the TLS configuration. 132 * If the data is loaded to the TLS object, the config command is used only for a single link. 133 * 134 * @param config [IN] TLS link configuration, which can be used to obtain the passwd callback. 135 * @param buf [IN] Certificate data. 136 * @param len [IN] Certificate data length. 137 * @param type [IN] Parsing type. 138 * @param format [IN] Data format. 139 * 140 * @retval Certificate 141 */ 142 typedef HITLS_CERT_X509 *(*CERT_CertParseCallBack)(HITLS_Config *config, const uint8_t *buf, uint32_t len, 143 HITLS_ParseType type, HITLS_ParseFormat format); 144 145 /** 146 * @ingroup hitls_cert_reg 147 * @brief Duplicate the certificate. 148 * 149 * @param cert [IN] Certificate 150 * 151 * @retval New certificate 152 */ 153 typedef HITLS_CERT_X509 *(*CERT_CertDupCallBack)(HITLS_CERT_X509 *cert); 154 155 /** 156 * @ingroup hitls_cert_reg 157 * @brief Certificate reference counting plus one. 158 * 159 * @param cert [IN] Certificate 160 * 161 * @retval certificate 162 */ 163 typedef HITLS_CERT_X509 *(*CERT_CertRefCallBack)(HITLS_CERT_X509 *cert); 164 165 /** 166 * @ingroup hitls_cert_reg 167 * @brief Release the certificate. 168 * 169 * @param cert [IN] Certificate 170 * 171 * @retval void 172 */ 173 typedef void (*CERT_CertFreeCallBack)(HITLS_CERT_X509 *cert); 174 175 /** 176 * @ingroup hitls_cert_reg 177 * @brief Ctrl interface 178 * 179 * @param config [IN] TLS link configuration 180 * @param cert [IN] Certificate 181 * @param cmd [IN] Ctrl option 182 * @param input [IN] Input 183 * @param output [IN] Output 184 * 185 * @retval HITLS_SUCCESS indicates success. Other values are considered as failure. 186 */ 187 typedef int32_t (*CERT_CertCtrlCallBack)(HITLS_Config *config, HITLS_CERT_X509 *cert, HITLS_CERT_CtrlCmd cmd, 188 void *input, void *output); 189 190 /** 191 * @ingroup hitls_cert_reg 192 * @brief Read the certificate key. 193 * @attention If the data is loaded to config, config points to the TLS configuration. 194 * If the data is loaded to the TLS object, the config command applies only to a single link. 195 * 196 * @param config [IN] LTS link configuration, which can be used to obtain the passwd callback. 197 * @param buf [IN] Private key data 198 * @param len [IN] Data length 199 * @param type [IN] Parsing type 200 * @param format [IN] Data format 201 * 202 * @retval Certificate key 203 */ 204 typedef HITLS_CERT_Key *(*CERT_KeyParseCallBack)(HITLS_Config *config, const uint8_t *buf, uint32_t len, 205 HITLS_ParseType type, HITLS_ParseFormat format); 206 207 /** 208 * @ingroup hitls_cert_reg 209 * @brief Duplicate the certificate key. 210 * 211 * @param key [IN] Certificate key 212 * 213 * @retval New certificate key 214 */ 215 typedef HITLS_CERT_Key *(*CERT_KeyDupCallBack)(HITLS_CERT_Key *key); 216 217 /** 218 * @ingroup hitls_cert_reg 219 * @brief Release the certificate key. 220 * 221 * @param key [IN] Certificate key 222 * 223 * @retval void 224 */ 225 typedef void (*CERT_KeyFreeCallBack)(HITLS_CERT_Key *key); 226 227 /** 228 * @ingroup hitls_cert_reg 229 * @brief Ctrl interface 230 * 231 * @param config [IN] TLS link configuration. 232 * @param key [IN] Certificate key. 233 * @param cmd [IN] Ctrl option. 234 * @param input [IN] Input. 235 * @param output [IN] Output. 236 * 237 * @retval HITLS_SUCCESS indicates success. Other values are considered as failure. 238 */ 239 typedef int32_t (*CERT_KeyCtrlCallBack)(HITLS_Config *config, HITLS_CERT_Key *key, HITLS_CERT_CtrlCmd cmd, 240 void *input, void *output); 241 242 /** 243 * @ingroup hitls_cert_reg 244 * @brief Signature 245 * 246 * @param ctx [IN] TLS link object 247 * @param key [IN] Certificate private key 248 * @param signAlgo [IN] Signature algorithm 249 * @param hashAlgo [IN] Hash algorithm 250 * @param data [IN] Data to be signed 251 * @param dataLen [IN] Data length 252 * @param sign [OUT] Signature 253 * @param signLen [IN/OUT] IN: maximum signature length OUT: actual signature length 254 * 255 * @retval HITLS_SUCCESS indicates success. Other values are considered as failure. 256 */ 257 typedef int32_t (*CERT_CreateSignCallBack)(HITLS_Ctx *ctx, HITLS_CERT_Key *key, HITLS_SignAlgo signAlgo, 258 HITLS_HashAlgo hashAlgo, const uint8_t *data, uint32_t dataLen, uint8_t *sign, uint32_t *signLen); 259 260 /** 261 * @ingroup hitls_cert_reg 262 * @brief Signature verification 263 * 264 * @param ctx [IN] TLS link object 265 * @param key [IN] Certificate public key 266 * @param signAlgo [IN] Signature algorithm 267 * @param hashAlgo [IN] Hash algorithm 268 * @param data [IN] Data to be signed 269 * @param dataLen [IN] Data length 270 * @param sign [IN] Signature 271 * @param signLen [IN] Signature length 272 * 273 * @retval HITLS_SUCCESS indicates success. Other values are considered as failure. 274 */ 275 typedef int32_t (*CERT_VerifySignCallBack)(HITLS_Ctx *ctx, HITLS_CERT_Key *key, HITLS_SignAlgo signAlgo, 276 HITLS_HashAlgo hashAlgo, const uint8_t *data, uint32_t dataLen, const uint8_t *sign, uint32_t signLen); 277 278 /** 279 * @ingroup hitls_cert_reg 280 * @brief Encrypted by the certificate public key. 281 * 282 * @param ctx [IN] TLS link object. 283 * @param key [IN] Certificate public key. 284 * @param in [IN] Plaintext. 285 * @param inLen [IN] Plaintext length. 286 * @param out [OUT] Ciphertext. 287 * @param outLen [IN/OUT] IN: maximum ciphertext length OUT: actual ciphertext length. 288 * 289 * @retval HITLS_SUCCESS indicates success. Other values are considered as failure. 290 */ 291 typedef int32_t (*CERT_EncryptCallBack)(HITLS_Ctx *ctx, HITLS_CERT_Key *key, const uint8_t *in, uint32_t inLen, 292 uint8_t *out, uint32_t *outLen); 293 294 /** 295 * @ingroup hitls_cert_reg 296 * @brief Use the certificate private key to decrypt the data. 297 * 298 * @param ctx [IN] TLS link object. 299 * @param key [IN] Certificate private key. 300 * @param in [IN] Ciphertext. 301 * @param inLen [IN] Ciphertext length. 302 * @param out [OUT] Plaintext. 303 * @param outLen [IN/OUT] IN: maximum plaintext length OUT: actual plaintext length. 304 * 305 * @retval HITLS_SUCCESS indicates success. Other values are considered as failure. 306 */ 307 typedef int32_t (*CERT_DecryptCallBack)(HITLS_Ctx *ctx, HITLS_CERT_Key *key, const uint8_t *in, uint32_t inLen, 308 uint8_t *out, uint32_t *outLen); 309 310 /** 311 * @ingroup hitls_cert_reg 312 * @brief Check whether the private key matches the certificate. 313 * 314 * @param config [IN] TLS link configuration. 315 * @param cert [IN] Certificate. 316 * @param key [IN] Private key. 317 * 318 * @retval HITLS_SUCCESS indicates success. Other values are considered as failure. 319 */ 320 typedef int32_t (*CERT_CheckPrivateKeyCallBack)(const HITLS_Config *config, HITLS_CERT_X509 *cert, HITLS_CERT_Key *key); 321 322 typedef struct { 323 CERT_StoreNewCallBack certStoreNew; /**< REQUIRED, Creating a certificate store. */ 324 CERT_StoreDupCallBack certStoreDup; /**< REQUIRED, duplicate certificate store. */ 325 CERT_StoreFreeCallBack certStoreFree; /**< REQUIRED, release the certificate store. */ 326 CERT_StoreCtrlCallBack certStoreCtrl; /**< REQUIRED, certificate interface store ctrl. */ 327 CERT_BuildCertChainCallBack buildCertChain; /**< REQUIRED, construct a certificate chain. */ 328 CERT_VerifyCertChainCallBack verifyCertChain; /**< REQUIRED, verify certificate chain. */ 329 330 CERT_CertEncodeCallBack certEncode; /**< REQUIRED, certificate encode. */ 331 CERT_CertParseCallBack certParse; /**< REQUIRED, certificate decoding. */ 332 CERT_CertDupCallBack certDup; /**< REQUIRED, duplicate the certificate. */ 333 CERT_CertRefCallBack certRef; /**< OPTIONAL, Certificate reference counting plus one. */ 334 CERT_CertFreeCallBack certFree; /**< REQUIRED, release certificate. */ 335 CERT_CertCtrlCallBack certCtrl; /**< REQUIRED, certificate interface ctrl. */ 336 337 CERT_KeyParseCallBack keyParse; /**< REQUIRED, loading key. */ 338 CERT_KeyDupCallBack keyDup; /**< REQUIRED, duplicate key. */ 339 CERT_KeyFreeCallBack keyFree; /**< REQUIRED, Release the key. */ 340 CERT_KeyCtrlCallBack keyCtrl; /**< REQUIRED, key ctrl interface. */ 341 CERT_CreateSignCallBack createSign; /**< REQUIRED, signature. */ 342 CERT_VerifySignCallBack verifySign; /**< REQUIRED, verification. */ 343 CERT_EncryptCallBack encrypt; /**< OPTIONAL, RSA key exchange REQUIRED, RSA encryption. */ 344 CERT_DecryptCallBack decrypt; /**< OPTIONAL, RSA key exchange REQUIRED, RSA decryption. */ 345 346 CERT_CheckPrivateKeyCallBack checkPrivateKey; /**< REQUIRED, Check whether the certificate matches the key. */ 347 } HITLS_CERT_MgrMethod; 348 349 /** 350 * @ingroup hitls_cert_reg 351 * @brief Callback function related to certificate registration 352 * 353 * @param method [IN] Callback function 354 * 355 * @retval HITLS_SUCCESS, succeeded. 356 * @retval HITLS_NULL_INPUT, the callback function is NULL. 357 */ 358 int32_t HITLS_CERT_RegisterMgrMethod(HITLS_CERT_MgrMethod *method); 359 360 /** 361 * @ingroup hitls_cert_reg 362 * @brief Certificate deregistration callback function 363 * 364 * @param method [IN] Callback function 365 * 366 * @retval 367 */ 368 void HITLS_CERT_DeinitMgrMethod(void); 369 370 /** 371 * @ingroup hitls_cert_reg 372 * @brief Register the private key with the config file and certificate matching Check Interface. 373 * 374 * @param config [IN/OUT] Config context 375 * @param checkPrivateKey API registration 376 * @retval HITLS_SUCCESS. 377 * @retval For other error codes, see hitls_error.h. 378 */ 379 int32_t HITLS_CFG_SetCheckPriKeyCb(HITLS_Config *config, CERT_CheckPrivateKeyCallBack checkPrivateKey); 380 381 /** 382 * @ingroup hitls_cert_reg 383 * @brief Interface for obtaining the registered private key and certificate matching check 384 * 385 * @param config [IN] Config context 386 * 387 * @retval The interface for checking whether the registered private key matches the certificate is returned. 388 * If the registered private key does not match the certificate, NULL is returned. 389 */ 390 CERT_CheckPrivateKeyCallBack HITLS_CFG_GetCheckPriKeyCb(HITLS_Config *config); 391 392 /** 393 * @ingroup hitls_cert_reg 394 * @brief Get certificate callback function 395 * 396 * @retval Cert callback function 397 */ 398 HITLS_CERT_MgrMethod *HITLS_CERT_GetMgrMethod(void); 399 400 #ifdef __cplusplus 401 } 402 #endif 403 404 #endif /* HITLS_CERT_REG_H */ 405