1 /** 2 * \file pkcs5.h 3 * 4 * \brief PKCS#5 functions 5 * 6 * \author Mathias Olsson <mathias@kompetensum.com> 7 */ 8 /* 9 * Copyright The Mbed TLS Contributors 10 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 11 */ 12 #ifndef MBEDTLS_PKCS5_H 13 #define MBEDTLS_PKCS5_H 14 15 #if !defined(MBEDTLS_CONFIG_FILE) 16 #include "mbedtls/config.h" 17 #else 18 #include MBEDTLS_CONFIG_FILE 19 #endif 20 21 #include "mbedtls/asn1.h" 22 #include "mbedtls/md.h" 23 24 #include <stddef.h> 25 #include <stdint.h> 26 27 /** Bad input parameters to function. */ 28 #define MBEDTLS_ERR_PKCS5_BAD_INPUT_DATA -0x2f80 29 /** Unexpected ASN.1 data. */ 30 #define MBEDTLS_ERR_PKCS5_INVALID_FORMAT -0x2f00 31 /** Requested encryption or digest alg not available. */ 32 #define MBEDTLS_ERR_PKCS5_FEATURE_UNAVAILABLE -0x2e80 33 /** Given private key password does not allow for correct decryption. */ 34 #define MBEDTLS_ERR_PKCS5_PASSWORD_MISMATCH -0x2e00 35 36 #define MBEDTLS_PKCS5_DECRYPT 0 37 #define MBEDTLS_PKCS5_ENCRYPT 1 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 #if defined(MBEDTLS_ASN1_PARSE_C) 44 45 /** 46 * \brief PKCS#5 PBES2 function 47 * 48 * \note When encrypting, #MBEDTLS_CIPHER_PADDING_PKCS7 must 49 * be enabled at compile time. 50 * 51 * \warning When decrypting: 52 * - if #MBEDTLS_CIPHER_PADDING_PKCS7 is enabled at compile 53 * time, this function validates the CBC padding and returns 54 * #MBEDTLS_ERR_PKCS5_PASSWORD_MISMATCH if the padding is 55 * invalid. Note that this can help active adversaries 56 * attempting to brute-forcing the password. Note also that 57 * there is no guarantee that an invalid password will be 58 * detected (the chances of a valid padding with a random 59 * password are about 1/255). 60 * - if #MBEDTLS_CIPHER_PADDING_PKCS7 is disabled at compile 61 * time, this function does not validate the CBC padding. 62 * 63 * \param pbe_params the ASN.1 algorithm parameters 64 * \param mode either #MBEDTLS_PKCS5_DECRYPT or #MBEDTLS_PKCS5_ENCRYPT 65 * \param pwd password to use when generating key 66 * \param pwdlen length of password 67 * \param data data to process 68 * \param datalen length of data 69 * \param output Output buffer. 70 * On success, it contains the encrypted or decrypted data, 71 * possibly followed by the CBC padding. 72 * On failure, the content is indeterminate. 73 * For decryption, there must be enough room for \p datalen 74 * bytes. 75 * For encryption, there must be enough room for 76 * \p datalen + 1 bytes, rounded up to the block size of 77 * the block cipher identified by \p pbe_params. 78 * 79 * \returns 0 on success, or a MBEDTLS_ERR_XXX code if verification fails. 80 */ 81 int mbedtls_pkcs5_pbes2(const mbedtls_asn1_buf *pbe_params, int mode, 82 const unsigned char *pwd, size_t pwdlen, 83 const unsigned char *data, size_t datalen, 84 unsigned char *output); 85 86 #if defined(MBEDTLS_CIPHER_PADDING_PKCS7) 87 88 /** 89 * \brief PKCS#5 PBES2 function 90 * 91 * \warning When decrypting: 92 * - This function validates the CBC padding and returns 93 * #MBEDTLS_ERR_PKCS5_PASSWORD_MISMATCH if the padding is 94 * invalid. Note that this can help active adversaries 95 * attempting to brute-forcing the password. Note also that 96 * there is no guarantee that an invalid password will be 97 * detected (the chances of a valid padding with a random 98 * password are about 1/255). 99 * 100 * \param pbe_params the ASN.1 algorithm parameters 101 * \param mode either #MBEDTLS_PKCS5_DECRYPT or #MBEDTLS_PKCS5_ENCRYPT 102 * \param pwd password to use when generating key 103 * \param pwdlen length of password 104 * \param data data to process 105 * \param datalen length of data 106 * \param output Output buffer. 107 * On success, it contains the decrypted data. 108 * On failure, the content is indetermidate. 109 * For decryption, there must be enough room for \p datalen 110 * bytes. 111 * For encryption, there must be enough room for 112 * \p datalen + 1 bytes, rounded up to the block size of 113 * the block cipher identified by \p pbe_params. 114 * \param output_size size of output buffer. 115 * This must be big enough to accommodate for output plus 116 * padding data. 117 * \param output_len On success, length of actual data written to the output buffer. 118 * 119 * \returns 0 on success, or a MBEDTLS_ERR_XXX code if parsing or decryption fails. 120 */ 121 int mbedtls_pkcs5_pbes2_ext(const mbedtls_asn1_buf *pbe_params, int mode, 122 const unsigned char *pwd, size_t pwdlen, 123 const unsigned char *data, size_t datalen, 124 unsigned char *output, size_t output_size, 125 size_t *output_len); 126 127 #endif /* MBEDTLS_CIPHER_PADDING_PKCS7 */ 128 129 #endif /* MBEDTLS_ASN1_PARSE_C */ 130 131 /** 132 * \brief PKCS#5 PBKDF2 using HMAC 133 * 134 * \param ctx Generic HMAC context 135 * \param password Password to use when generating key 136 * \param plen Length of password 137 * \param salt Salt to use when generating key 138 * \param slen Length of salt 139 * \param iteration_count Iteration count 140 * \param key_length Length of generated key in bytes 141 * \param output Generated key. Must be at least as big as key_length 142 * 143 * \returns 0 on success, or a MBEDTLS_ERR_XXX code if verification fails. 144 */ 145 int mbedtls_pkcs5_pbkdf2_hmac(mbedtls_md_context_t *ctx, const unsigned char *password, 146 size_t plen, const unsigned char *salt, size_t slen, 147 unsigned int iteration_count, 148 uint32_t key_length, unsigned char *output); 149 150 #if defined(MBEDTLS_SELF_TEST) 151 152 /** 153 * \brief Checkup routine 154 * 155 * \return 0 if successful, or 1 if the test failed 156 */ 157 int mbedtls_pkcs5_self_test(int verbose); 158 159 #endif /* MBEDTLS_SELF_TEST */ 160 161 #ifdef __cplusplus 162 } 163 #endif 164 165 #endif /* pkcs5.h */ 166