1 /** 2 * \file pkcs12.h 3 * 4 * \brief PKCS#12 Personal Information Exchange Syntax 5 */ 6 /* 7 * Copyright The Mbed TLS Contributors 8 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 9 */ 10 #ifndef MBEDTLS_PKCS12_H 11 #define MBEDTLS_PKCS12_H 12 13 #if !defined(MBEDTLS_CONFIG_FILE) 14 #include "mbedtls/config.h" 15 #else 16 #include MBEDTLS_CONFIG_FILE 17 #endif 18 19 #include "mbedtls/md.h" 20 #include "mbedtls/cipher.h" 21 #include "mbedtls/asn1.h" 22 23 #include <stddef.h> 24 25 /** Bad input parameters to function. */ 26 #define MBEDTLS_ERR_PKCS12_BAD_INPUT_DATA -0x1F80 27 /** Feature not available, e.g. unsupported encryption scheme. */ 28 #define MBEDTLS_ERR_PKCS12_FEATURE_UNAVAILABLE -0x1F00 29 /** PBE ASN.1 data not as expected. */ 30 #define MBEDTLS_ERR_PKCS12_PBE_INVALID_FORMAT -0x1E80 31 /** Given private key password does not allow for correct decryption. */ 32 #define MBEDTLS_ERR_PKCS12_PASSWORD_MISMATCH -0x1E00 33 34 #define MBEDTLS_PKCS12_DERIVE_KEY 1 /**< encryption/decryption key */ 35 #define MBEDTLS_PKCS12_DERIVE_IV 2 /**< initialization vector */ 36 #define MBEDTLS_PKCS12_DERIVE_MAC_KEY 3 /**< integrity / MAC key */ 37 38 #define MBEDTLS_PKCS12_PBE_DECRYPT 0 39 #define MBEDTLS_PKCS12_PBE_ENCRYPT 1 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 #if defined(MBEDTLS_ASN1_PARSE_C) 46 47 /** 48 * \brief PKCS12 Password Based function (encryption / decryption) 49 * for pbeWithSHAAnd128BitRC4 50 * 51 * \param pbe_params an ASN1 buffer containing the pkcs-12PbeParams structure 52 * \param mode either MBEDTLS_PKCS12_PBE_ENCRYPT or MBEDTLS_PKCS12_PBE_DECRYPT 53 * \param pwd the password used (may be NULL if no password is used) 54 * \param pwdlen length of the password (may be 0) 55 * \param input the input data 56 * \param len data length 57 * \param output the output buffer 58 * 59 * \return 0 if successful, or a MBEDTLS_ERR_XXX code 60 */ 61 int mbedtls_pkcs12_pbe_sha1_rc4_128(mbedtls_asn1_buf *pbe_params, int mode, 62 const unsigned char *pwd, size_t pwdlen, 63 const unsigned char *input, size_t len, 64 unsigned char *output); 65 66 /** 67 * \brief PKCS12 Password Based function (encryption / decryption) 68 * for cipher-based and mbedtls_md-based PBE's 69 * 70 * \note When encrypting, #MBEDTLS_CIPHER_PADDING_PKCS7 must 71 * be enabled at compile time. 72 * 73 * \warning When decrypting: 74 * - if #MBEDTLS_CIPHER_PADDING_PKCS7 is enabled at compile 75 * time, this function validates the CBC padding and returns 76 * #MBEDTLS_ERR_PKCS12_PASSWORD_MISMATCH if the padding is 77 * invalid. Note that this can help active adversaries 78 * attempting to brute-forcing the password. Note also that 79 * there is no guarantee that an invalid password will be 80 * detected (the chances of a valid padding with a random 81 * password are about 1/255). 82 * - if #MBEDTLS_CIPHER_PADDING_PKCS7 is disabled at compile 83 * time, this function does not validate the CBC padding. 84 * 85 * \param pbe_params an ASN1 buffer containing the pkcs-12 PbeParams structure 86 * \param mode either #MBEDTLS_PKCS12_PBE_ENCRYPT or 87 * #MBEDTLS_PKCS12_PBE_DECRYPT 88 * \param cipher_type the cipher used 89 * \param md_type the mbedtls_md used 90 * \param pwd Latin1-encoded password used. This may only be \c NULL when 91 * \p pwdlen is 0. No null terminator should be used. 92 * \param pwdlen length of the password (may be 0) 93 * \param data the input data 94 * \param len data length 95 * \param output Output buffer. 96 * On success, it contains the encrypted or decrypted data, 97 * possibly followed by the CBC padding. 98 * On failure, the content is indeterminate. 99 * For decryption, there must be enough room for \p len 100 * bytes. 101 * For encryption, there must be enough room for 102 * \p len + 1 bytes, rounded up to the block size of 103 * the block cipher identified by \p pbe_params. 104 * 105 * \return 0 if successful, or a MBEDTLS_ERR_XXX code 106 */ 107 int mbedtls_pkcs12_pbe(mbedtls_asn1_buf *pbe_params, int mode, 108 mbedtls_cipher_type_t cipher_type, mbedtls_md_type_t md_type, 109 const unsigned char *pwd, size_t pwdlen, 110 const unsigned char *data, size_t len, 111 unsigned char *output); 112 113 #if defined(MBEDTLS_CIPHER_PADDING_PKCS7) 114 115 /** 116 * \brief PKCS12 Password Based function (encryption / decryption) 117 * for cipher-based and mbedtls_md-based PBE's 118 * 119 * 120 * \warning When decrypting: 121 * - This function validates the CBC padding and returns 122 * #MBEDTLS_ERR_PKCS12_PASSWORD_MISMATCH if the padding is 123 * invalid. Note that this can help active adversaries 124 * attempting to brute-forcing the password. Note also that 125 * there is no guarantee that an invalid password will be 126 * detected (the chances of a valid padding with a random 127 * password are about 1/255). 128 * 129 * \param pbe_params an ASN1 buffer containing the pkcs-12 PbeParams structure 130 * \param mode either #MBEDTLS_PKCS12_PBE_ENCRYPT or 131 * #MBEDTLS_PKCS12_PBE_DECRYPT 132 * \param cipher_type the cipher used 133 * \param md_type the mbedtls_md used 134 * \param pwd Latin1-encoded password used. This may only be \c NULL when 135 * \p pwdlen is 0. No null terminator should be used. 136 * \param pwdlen length of the password (may be 0) 137 * \param data the input data 138 * \param len data length 139 * \param output Output buffer. 140 * On success, it contains the encrypted or decrypted data, 141 * possibly followed by the CBC padding. 142 * On failure, the content is indeterminate. 143 * For decryption, there must be enough room for \p len 144 * bytes. 145 * For encryption, there must be enough room for 146 * \p len + 1 bytes, rounded up to the block size of 147 * the block cipher identified by \p pbe_params. 148 * \param output_size size of output buffer. 149 * This must be big enough to accommodate for output plus 150 * padding data. 151 * \param output_len On success, length of actual data written to the output buffer. 152 * 153 * \return 0 if successful, or a MBEDTLS_ERR_XXX code 154 */ 155 int mbedtls_pkcs12_pbe_ext(mbedtls_asn1_buf *pbe_params, int mode, 156 mbedtls_cipher_type_t cipher_type, mbedtls_md_type_t md_type, 157 const unsigned char *pwd, size_t pwdlen, 158 const unsigned char *data, size_t len, 159 unsigned char *output, size_t output_size, 160 size_t *output_len); 161 162 #endif /* MBEDTLS_CIPHER_PADDING_PKCS7 */ 163 164 #endif /* MBEDTLS_ASN1_PARSE_C */ 165 166 /** 167 * \brief The PKCS#12 derivation function uses a password and a salt 168 * to produce pseudo-random bits for a particular "purpose". 169 * 170 * Depending on the given id, this function can produce an 171 * encryption/decryption key, an initialization vector or an 172 * integrity key. 173 * 174 * \param data buffer to store the derived data in 175 * \param datalen length of buffer to fill 176 * \param pwd The password to use. For compliance with PKCS#12 §B.1, this 177 * should be a BMPString, i.e. a Unicode string where each 178 * character is encoded as 2 bytes in big-endian order, with 179 * no byte order mark and with a null terminator (i.e. the 180 * last two bytes should be 0x00 0x00). 181 * \param pwdlen length of the password (may be 0). 182 * \param salt Salt buffer to use This may only be \c NULL when 183 * \p saltlen is 0. 184 * \param saltlen length of the salt (may be zero) 185 * \param mbedtls_md mbedtls_md type to use during the derivation 186 * \param id id that describes the purpose (can be 187 * #MBEDTLS_PKCS12_DERIVE_KEY, #MBEDTLS_PKCS12_DERIVE_IV or 188 * #MBEDTLS_PKCS12_DERIVE_MAC_KEY) 189 * \param iterations number of iterations 190 * 191 * \return 0 if successful, or a MD, BIGNUM type error. 192 */ 193 int mbedtls_pkcs12_derivation(unsigned char *data, size_t datalen, 194 const unsigned char *pwd, size_t pwdlen, 195 const unsigned char *salt, size_t saltlen, 196 mbedtls_md_type_t mbedtls_md, int id, int iterations); 197 198 #ifdef __cplusplus 199 } 200 #endif 201 202 #endif /* pkcs12.h */ 203