blob: 63e2e63b58945def82a6d5628e653f9bec5bb180 [file] [log] [blame]
Paul Bakkerf1f21fe2013-06-24 19:17:19 +02001/**
2 * \file pkcs12.h
3 *
4 * \brief PKCS#12 Personal Information Exchange Syntax
Darryl Greena40a1012018-01-05 15:33:17 +00005 */
6/*
Bence Szépkúti1e148272020-08-07 13:07:28 +02007 * Copyright The Mbed TLS Contributors
Manuel Pégourié-Gonnard37ff1402015-09-04 14:21:07 +02008 * SPDX-License-Identifier: Apache-2.0
9 *
10 * Licensed under the Apache License, Version 2.0 (the "License"); you may
11 * not use this file except in compliance with the License.
12 * You may obtain a copy of the License at
13 *
14 * http://www.apache.org/licenses/LICENSE-2.0
15 *
16 * Unless required by applicable law or agreed to in writing, software
17 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
18 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 * See the License for the specific language governing permissions and
20 * limitations under the License.
Paul Bakkerf1f21fe2013-06-24 19:17:19 +020021 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020022#ifndef MBEDTLS_PKCS12_H
23#define MBEDTLS_PKCS12_H
Paul Bakkerf1f21fe2013-06-24 19:17:19 +020024
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050025#if !defined(MBEDTLS_CONFIG_FILE)
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010026#include "mbedtls/config.h"
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050027#else
28#include MBEDTLS_CONFIG_FILE
29#endif
30
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010031#include "mbedtls/md.h"
32#include "mbedtls/cipher.h"
33#include "mbedtls/asn1.h"
Paul Bakkerf1f21fe2013-06-24 19:17:19 +020034
Rich Evans00ab4702015-02-06 13:43:58 +000035#include <stddef.h>
36
Gilles Peskinea3974432021-07-26 18:48:10 +020037/** Bad input parameters to function. */
38#define MBEDTLS_ERR_PKCS12_BAD_INPUT_DATA -0x1F80
39/** Feature not available, e.g. unsupported encryption scheme. */
40#define MBEDTLS_ERR_PKCS12_FEATURE_UNAVAILABLE -0x1F00
41/** PBE ASN.1 data not as expected. */
42#define MBEDTLS_ERR_PKCS12_PBE_INVALID_FORMAT -0x1E80
43/** Given private key password does not allow for correct decryption. */
44#define MBEDTLS_ERR_PKCS12_PASSWORD_MISMATCH -0x1E00
Paul Bakkerf1f21fe2013-06-24 19:17:19 +020045
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020046#define MBEDTLS_PKCS12_DERIVE_KEY 1 /**< encryption/decryption key */
47#define MBEDTLS_PKCS12_DERIVE_IV 2 /**< initialization vector */
48#define MBEDTLS_PKCS12_DERIVE_MAC_KEY 3 /**< integrity / MAC key */
Paul Bakkerf1f21fe2013-06-24 19:17:19 +020049
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020050#define MBEDTLS_PKCS12_PBE_DECRYPT 0
51#define MBEDTLS_PKCS12_PBE_ENCRYPT 1
Paul Bakkerf1f21fe2013-06-24 19:17:19 +020052
Paul Bakkerf1f21fe2013-06-24 19:17:19 +020053#ifdef __cplusplus
54extern "C" {
55#endif
56
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050057#if defined(MBEDTLS_ASN1_PARSE_C)
58
Paul Bakkerf1f21fe2013-06-24 19:17:19 +020059/**
60 * \brief PKCS12 Password Based function (encryption / decryption)
61 * for pbeWithSHAAnd128BitRC4
62 *
63 * \param pbe_params an ASN1 buffer containing the pkcs-12PbeParams structure
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020064 * \param mode either MBEDTLS_PKCS12_PBE_ENCRYPT or MBEDTLS_PKCS12_PBE_DECRYPT
Paul Bakkerf1f21fe2013-06-24 19:17:19 +020065 * \param pwd the password used (may be NULL if no password is used)
66 * \param pwdlen length of the password (may be 0)
67 * \param input the input data
68 * \param len data length
69 * \param output the output buffer
Paul Bakker38b50d72013-06-24 19:33:27 +020070 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020071 * \return 0 if successful, or a MBEDTLS_ERR_XXX code
Paul Bakkerf1f21fe2013-06-24 19:17:19 +020072 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010073int mbedtls_pkcs12_pbe_sha1_rc4_128(mbedtls_asn1_buf *pbe_params, int mode,
74 const unsigned char *pwd, size_t pwdlen,
75 const unsigned char *input, size_t len,
76 unsigned char *output);
Paul Bakkerf1f21fe2013-06-24 19:17:19 +020077
78/**
79 * \brief PKCS12 Password Based function (encryption / decryption)
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020080 * for cipher-based and mbedtls_md-based PBE's
Paul Bakkerf1f21fe2013-06-24 19:17:19 +020081 *
Waleed Elmelegy38a89ad2023-09-04 15:11:22 +010082 * \note When encrypting, #MBEDTLS_CIPHER_PADDING_PKCS7 must
83 * be enabled at compile time.
84 *
85 * \warning When decrypting:
86 * - if #MBEDTLS_CIPHER_PADDING_PKCS7 is enabled at compile
87 * time, this function validates the CBC padding and returns
88 * #MBEDTLS_ERR_PKCS12_PASSWORD_MISMATCH if the padding is
89 * invalid. Note that this can help active adversaries
90 * attempting to brute-forcing the password. Note also that
91 * there is no guarantee that an invalid password will be
92 * detected (the chances of a valid padding with a random
93 * password are about 1/255).
94 * - if #MBEDTLS_CIPHER_PADDING_PKCS7 is disabled at compile
95 * time, this function does not validate the CBC padding.
96 *
Paul Elliottfe724fe2021-11-11 19:00:38 +000097 * \param pbe_params an ASN1 buffer containing the pkcs-12 PbeParams structure
Paul Elliotta59cc3d2021-11-18 12:39:10 +000098 * \param mode either #MBEDTLS_PKCS12_PBE_ENCRYPT or
99 * #MBEDTLS_PKCS12_PBE_DECRYPT
Paul Bakker38b50d72013-06-24 19:33:27 +0200100 * \param cipher_type the cipher used
Paul Elliottfe724fe2021-11-11 19:00:38 +0000101 * \param md_type the mbedtls_md used
Paul Elliotta59cc3d2021-11-18 12:39:10 +0000102 * \param pwd Latin1-encoded password used. This may only be \c NULL when
Paul Elliottce220082021-11-30 15:37:49 +0000103 * \p pwdlen is 0. No null terminator should be used.
Paul Bakkerf1f21fe2013-06-24 19:17:19 +0200104 * \param pwdlen length of the password (may be 0)
Waleed Elmelegy6060cf12023-09-06 15:48:08 +0100105 * \param data the input data
Paul Bakkerf1f21fe2013-06-24 19:17:19 +0200106 * \param len data length
Waleed Elmelegy38a89ad2023-09-04 15:11:22 +0100107 * \param output Output buffer.
108 * On success, it contains the encrypted or decrypted data,
109 * possibly followed by the CBC padding.
110 * On failure, the content is indeterminate.
111 * For decryption, there must be enough room for \p len
112 * bytes.
113 * For encryption, there must be enough room for
114 * \p len + 1 bytes, rounded up to the block size of
115 * the block cipher identified by \p pbe_params.
Paul Bakkerf1f21fe2013-06-24 19:17:19 +0200116 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200117 * \return 0 if successful, or a MBEDTLS_ERR_XXX code
Paul Bakkerf1f21fe2013-06-24 19:17:19 +0200118 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100119int mbedtls_pkcs12_pbe(mbedtls_asn1_buf *pbe_params, int mode,
120 mbedtls_cipher_type_t cipher_type, mbedtls_md_type_t md_type,
121 const unsigned char *pwd, size_t pwdlen,
Waleed Elmelegy6060cf12023-09-06 15:48:08 +0100122 const unsigned char *data, size_t len,
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100123 unsigned char *output);
Paul Bakkerf1f21fe2013-06-24 19:17:19 +0200124
Waleed Elmelegy6060cf12023-09-06 15:48:08 +0100125#if defined(MBEDTLS_CIPHER_PADDING_PKCS7)
126
127/**
128 * \brief PKCS12 Password Based function (encryption / decryption)
129 * for cipher-based and mbedtls_md-based PBE's
130 *
131 *
132 * \warning When decrypting:
133 * - This function validates the CBC padding and returns
134 * #MBEDTLS_ERR_PKCS12_PASSWORD_MISMATCH if the padding is
135 * invalid. Note that this can help active adversaries
136 * attempting to brute-forcing the password. Note also that
137 * there is no guarantee that an invalid password will be
138 * detected (the chances of a valid padding with a random
139 * password are about 1/255).
140 *
141 * \param pbe_params an ASN1 buffer containing the pkcs-12 PbeParams structure
142 * \param mode either #MBEDTLS_PKCS12_PBE_ENCRYPT or
143 * #MBEDTLS_PKCS12_PBE_DECRYPT
144 * \param cipher_type the cipher used
145 * \param md_type the mbedtls_md used
146 * \param pwd Latin1-encoded password used. This may only be \c NULL when
147 * \p pwdlen is 0. No null terminator should be used.
148 * \param pwdlen length of the password (may be 0)
149 * \param data the input data
150 * \param len data length
151 * \param output Output buffer.
152 * On success, it contains the encrypted or decrypted data,
153 * possibly followed by the CBC padding.
154 * On failure, the content is indeterminate.
155 * For decryption, there must be enough room for \p len
156 * bytes.
157 * For encryption, there must be enough room for
158 * \p len + 1 bytes, rounded up to the block size of
159 * the block cipher identified by \p pbe_params.
160 * \param output_size size of output buffer.
161 * This must be big enough to accommodate for output plus
162 * padding data.
163 * \param output_len On success, length of actual data written to the output buffer.
164 *
165 * \return 0 if successful, or a MBEDTLS_ERR_XXX code
166 */
167int mbedtls_pkcs12_pbe_ext(mbedtls_asn1_buf *pbe_params, int mode,
168 mbedtls_cipher_type_t cipher_type, mbedtls_md_type_t md_type,
169 const unsigned char *pwd, size_t pwdlen,
170 const unsigned char *data, size_t len,
171 unsigned char *output, size_t output_size,
172 size_t *output_len);
173
174#endif /* MBEDTLS_CIPHER_PADDING_PKCS7 */
175
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500176#endif /* MBEDTLS_ASN1_PARSE_C */
177
Paul Bakkerf1f21fe2013-06-24 19:17:19 +0200178/**
179 * \brief The PKCS#12 derivation function uses a password and a salt
180 * to produce pseudo-random bits for a particular "purpose".
181 *
182 * Depending on the given id, this function can produce an
Paul Elliotta59cc3d2021-11-18 12:39:10 +0000183 * encryption/decryption key, an initialization vector or an
Paul Bakkerf1f21fe2013-06-24 19:17:19 +0200184 * integrity key.
185 *
186 * \param data buffer to store the derived data in
Paul Elliottfe724fe2021-11-11 19:00:38 +0000187 * \param datalen length of buffer to fill
Paul Elliotta59cc3d2021-11-18 12:39:10 +0000188 * \param pwd The password to use. For compliance with PKCS#12 §B.1, this
189 * should be a BMPString, i.e. a Unicode string where each
190 * character is encoded as 2 bytes in big-endian order, with
191 * no byte order mark and with a null terminator (i.e. the
192 * last two bytes should be 0x00 0x00).
193 * \param pwdlen length of the password (may be 0).
194 * \param salt Salt buffer to use This may only be \c NULL when
Paul Elliottce220082021-11-30 15:37:49 +0000195 * \p saltlen is 0.
Paul Elliotta59cc3d2021-11-18 12:39:10 +0000196 * \param saltlen length of the salt (may be zero)
Paul Elliottfe724fe2021-11-11 19:00:38 +0000197 * \param mbedtls_md mbedtls_md type to use during the derivation
198 * \param id id that describes the purpose (can be
Paul Elliotta59cc3d2021-11-18 12:39:10 +0000199 * #MBEDTLS_PKCS12_DERIVE_KEY, #MBEDTLS_PKCS12_DERIVE_IV or
200 * #MBEDTLS_PKCS12_DERIVE_MAC_KEY)
Paul Bakkerf1f21fe2013-06-24 19:17:19 +0200201 * \param iterations number of iterations
202 *
203 * \return 0 if successful, or a MD, BIGNUM type error.
204 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100205int mbedtls_pkcs12_derivation(unsigned char *data, size_t datalen,
206 const unsigned char *pwd, size_t pwdlen,
207 const unsigned char *salt, size_t saltlen,
208 mbedtls_md_type_t mbedtls_md, int id, int iterations);
Paul Bakkerf1f21fe2013-06-24 19:17:19 +0200209
210#ifdef __cplusplus
211}
212#endif
213
214#endif /* pkcs12.h */