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_PKCS12_H 17 #define HITLS_PKI_PKCS12_H 18 19 #include "hitls_pki_types.h" 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 typedef struct _HITLS_PKCS12 HITLS_PKCS12; 26 27 typedef struct _HITLS_PKCS12_Bag HITLS_PKCS12_Bag; 28 29 /** 30 * @ingroup pkcs12 31 * @brief Allocate a pkcs12 struct. 32 * 33 * @retval HITLS_PKCS12 * 34 */ 35 HITLS_PKCS12 *HITLS_PKCS12_New(void); 36 37 /** 38 * @ingroup pkcs12 39 * @brief Allocate a pkcs12 struct. 40 * 41 * @param libCtx [IN] lib context 42 * @param attrName [IN] attribute name 43 * @retval HITLS_PKCS12 * 44 */ 45 HITLS_PKCS12 *HITLS_PKCS12_ProviderNew(HITLS_PKI_LibCtx *libCtx, const char *attrName); 46 47 /** 48 * @ingroup pkcs12 49 * @brief Release the pkcs12 context. 50 * 51 * @param csr [IN] p12 context. 52 * @retval void 53 */ 54 void HITLS_PKCS12_Free(HITLS_PKCS12 *p12); 55 56 /** 57 * @ingroup pkcs12 58 * @brief Allocate a bag struct, which could store a cert or key and its attributes. 59 * 60 * @param bagId [IN] BagId, BSL_CID_PKCS8SHROUDEDKEYBAG/BSL_CID_CERTBAG/BSL_CID_SECRETBAG 61 * @param bagType [IN] BagType, for example, BSL_CID_X509CERTIFICATE is a bagType of BSL_CID_CERTBAG. 62 * @param bagValue [IN] bagValue, the bagValue must match the bag-type. Each Bag only holds one piece of 63 * information -- a key or a certificate... 64 * @retval HITLS_PKCS12_Bag * 65 */ 66 HITLS_PKCS12_Bag *HITLS_PKCS12_BagNew(uint32_t bagId, uint32_t bagType, void *bagValue); 67 68 /** 69 * @ingroup pkcs12 70 * @brief Release the bag context. 71 * 72 * @param bag [IN] bag context. 73 * @retval void 74 */ 75 void HITLS_PKCS12_BagFree(HITLS_PKCS12_Bag *bag); 76 77 /** 78 * @ingroup pkcs12 79 * @brief Generic function to set a p12 context. 80 * 81 * @param bag [IN] bag context. 82 * @param cmd [IN] HITLS_PKCS12_XXX 83 * @param val [IN/OUT] input and output value 84 * @param valLen [In] value length 85 * @retval #HITLS_PKI_SUCCESS, success. 86 * Error codes can be found in hitls_pki_errno.h 87 */ 88 int32_t HITLS_PKCS12_BagCtrl(HITLS_PKCS12_Bag *bag, int32_t cmd, void *val, uint32_t valType); 89 90 /** 91 * @ingroup pkcs12 92 * @brief Generic function to set a p12 context. 93 * 94 * @param p12 [IN] p12 context. 95 * @param cmd [IN] HITLS_PKCS12_XXX 96 * cmd val type 97 * HITLS_PKCS12_GEN_LOCALKEYID AlgId of MD 98 * HITLS_PKCS12_SET_ENTITY_KEYBAG a pkey bag 99 * HITLS_PKCS12_SET_ENTITY_CERTBAG a cert bag 100 * HITLS_PKCS12_ADD_CERTBAG a cert bag 101 * HITLS_PKCS12_GET_ENTITY_CERT HITLS_X509_Cert** 102 * HITLS_PKCS12_GET_ENTITY_KEY CRYPT_EAL_PkeyCtx** 103 * @param val [IN/OUT] input and output value 104 * @param valLen [In] value length 105 * @retval #HITLS_PKI_SUCCESS, success. 106 * Error codes can be found in hitls_pki_errno.h 107 */ 108 int32_t HITLS_PKCS12_Ctrl(HITLS_PKCS12 *p12, int32_t cmd, void *val, uint32_t valLen); 109 110 /** 111 * @ingroup pkcs12 112 * @brief pkcs12 parse 113 * @par Description: parse p12 buffer, and set the p12 struct. When the parameter is 114 * BSL_FORMAT_PEM and BSL_FORMAT_UNKNOWN, the buff of encode needs to end with '\0' 115 * 116 * @attention Only support to parse p12 buffer in key-integrity and key-privacy protection mode. 117 * @param format [IN] Decoding format: BSL_FORMAT_ASN1/BSL_FORMAT_UNKNOWN. 118 * @param encode [IN] encode data 119 * @param pwdParam [IN] include MAC-pwd, enc-pwd, they can be different. 120 * @param p12 [OUT] the p12 struct. 121 * @param needMacVerify [IN] true, need verify mac; false, skip mac check. 122 * @retval #HITLS_PKI_SUCCESS, success. 123 * Error codes can be found in hitls_pki_errno.h 124 */ 125 int32_t HITLS_PKCS12_ParseBuff(int32_t format, const BSL_Buffer *encode, const HITLS_PKCS12_PwdParam *pwdParam, 126 HITLS_PKCS12 **p12, bool needMacVerify); 127 128 /** 129 * @ingroup pkcs12 130 * @brief pkcs12 parse 131 * @par Description: parse p12 buffer, and set the p12 struct. 132 * 133 * @attention Only support to parse p12 buffer in key-integrity and key-privacy protection mode. 134 * @param libCtx [IN] lib context 135 * @param attrName [IN] attribute name 136 * @param format [IN] Encoding format: PEM/ASN1/NULL 137 * @param encode [IN] encode data 138 * @param pwdParam [IN] include MAC-pwd, enc-pwd, they can be different. 139 * @param p12 [OUT] the p12 struct. 140 * @param needMacVerify [IN] true, need verify mac; false, skip mac check. 141 * @retval #HITLS_PKI_SUCCESS, success. 142 * Error codes can be found in hitls_pki_errno.h 143 */ 144 int32_t HITLS_PKCS12_ProviderParseBuff(HITLS_PKI_LibCtx *libCtx, const char *attrName, const char *format, 145 const BSL_Buffer *encode, const HITLS_PKCS12_PwdParam *pwdParam, HITLS_PKCS12 **p12, bool needMacVerify); 146 /** 147 * @ingroup pkcs12 148 * @par Description: parse p12 file, and set the p12 struct. 149 * 150 * @attention Only support to parse p12 files in key-integrity and key-privacy protection mode. 151 * @param format [IN] Encoding format: BSL_FORMAT_PEM/BSL_FORMAT_ASN1 152 * @param path [IN] p12 file path. 153 * @param pwdParam [IN] include MAC-pwd, enc-pwd, they can be different. 154 * @param p12 [OUT] the p12 struct. 155 * @param needMacVerify [IN] true, need verify mac; false, skip mac check. 156 * @retval #HITLS_PKI_SUCCESS, success. 157 * Error codes can be found in hitls_pki_errno.h 158 */ 159 int32_t HITLS_PKCS12_ParseFile(int32_t format, const char *path, const HITLS_PKCS12_PwdParam *pwdParam, 160 HITLS_PKCS12 **p12, bool needMacVerify); 161 162 /** 163 * @ingroup pkcs12 164 * @brief pkcs12 parse file 165 * @par Description: parse p12 file, and set the p12 struct. 166 * 167 * @attention Only support to parse p12 files in key-integrity and key-privacy protection mode. 168 * @param libCtx [IN] lib context 169 * @param attrName [IN] attribute name 170 * @param format [IN] Encoding format: PEM/ASN1/NULL 171 * @param path [IN] p12 file path. 172 * @param pwdParam [IN] include MAC-pwd, enc-pwd, they can be different. 173 * @param p12 [OUT] the p12 struct. 174 * @param needMacVerify [IN] true, need verify mac; false, skip mac check. 175 * @retval #HITLS_PKI_SUCCESS, success. 176 * Error codes can be found in hitls_pki_errno.h 177 */ 178 int32_t HITLS_PKCS12_ProviderParseFile(HITLS_PKI_LibCtx *libCtx, const char *attrName, const char *format, 179 const char *path, const HITLS_PKCS12_PwdParam *pwdParam, HITLS_PKCS12 **p12, bool needMacVerify); 180 /** 181 * @ingroup pkcs12 182 * @brief pkcs12 gen 183 * @par Description: gen p12 buffer. 184 * 185 * @attention Generate a p12 buffer based on the existing information. 186 * @param format [IN] Encoding format: BSL_FORMAT_ASN1/BSL_FORMAT_UNKNOWN. 187 * @param p12 [IN] p12 struct, including entityCert, CA-cert, prvkey, and so on. 188 * @param encodeParam [IN] encode data 189 * @param isNeedMac [IN] Identifies whether macData is required. 190 * @param encode [OUT] result. 191 * @retval #HITLS_PKI_SUCCESS, success. 192 * Error codes can be found in hitls_pki_errno.h 193 */ 194 int32_t HITLS_PKCS12_GenBuff(int32_t format, HITLS_PKCS12 *p12, const HITLS_PKCS12_EncodeParam *encodeParam, 195 bool isNeedMac, BSL_Buffer *encode); 196 197 /** 198 * @ingroup pkcs12 199 * @par Description: Generate p12 to store in file 200 * 201 * @attention Generate a .p12 file based on the existing information. 202 * @param format [IN] Encoding format: BSL_FORMAT_ASN1/BSL_FORMAT_UNKNOWN. 203 * @param p12 [IN] p12 struct, including entityCert, CA-cert, prvkey, and so on. 204 * @param encodeParam [IN] encode data 205 * @param isNeedMac [IN] Identifies whether macData is required. 206 * @param path [IN] The path of the generated p12-file. 207 * @retval #HITLS_PKI_SUCCESS, success. 208 * Error codes can be found in hitls_pki_errno.h 209 */ 210 int32_t HITLS_PKCS12_GenFile(int32_t format, HITLS_PKCS12 *p12, const HITLS_PKCS12_EncodeParam *encodeParam, 211 bool isNeedMac, const char *path); 212 213 #ifdef __cplusplus 214 } 215 #endif 216 217 #endif // HITLS_PKI_PKCS12_H 218