blob: f8b8965925ad0456bc3a7304daf74df7d06b7cce [file] [log] [blame]
Paul Bakker5121ce52009-01-03 21:22:43 +00001/**
2 * \file rsa.h
Paul Bakkere0ccd0a2009-01-04 16:27:10 +00003 *
Rose Zadik21e29262018-04-17 14:08:56 +01004 * \brief This file provides an API for the RSA public-key cryptosystem.
Paul Bakker37ca75d2011-01-06 12:28:03 +00005 *
Rose Zadike8b5b992018-03-27 12:19:47 +01006 * The RSA public-key cryptosystem is defined in <em>Public-Key
7 * Cryptography Standards (PKCS) #1 v1.5: RSA Encryption</em>
8 * and <em>Public-Key Cryptography Standards (PKCS) #1 v2.1:
9 * RSA Cryptography Specifications</em>.
Rose Zadik042e97f2018-01-26 16:35:10 +000010 *
Darryl Greena40a1012018-01-05 15:33:17 +000011 */
12/*
Rose Zadik042e97f2018-01-26 16:35:10 +000013 * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
Manuel Pégourié-Gonnard37ff1402015-09-04 14:21:07 +020014 * SPDX-License-Identifier: Apache-2.0
15 *
16 * Licensed under the Apache License, Version 2.0 (the "License"); you may
17 * not use this file except in compliance with the License.
18 * You may obtain a copy of the License at
19 *
20 * http://www.apache.org/licenses/LICENSE-2.0
21 *
22 * Unless required by applicable law or agreed to in writing, software
23 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
24 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
25 * See the License for the specific language governing permissions and
26 * limitations under the License.
Paul Bakkerb96f1542010-07-18 20:36:00 +000027 *
Rose Zadik042e97f2018-01-26 16:35:10 +000028 * This file is part of Mbed TLS (https://tls.mbed.org)
Paul Bakker5121ce52009-01-03 21:22:43 +000029 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020030#ifndef MBEDTLS_RSA_H
31#define MBEDTLS_RSA_H
Paul Bakker5121ce52009-01-03 21:22:43 +000032
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020033#if !defined(MBEDTLS_CONFIG_FILE)
Paul Bakkered27a042013-04-18 22:46:23 +020034#include "config.h"
Manuel Pégourié-Gonnardcef4ad22014-04-29 12:39:06 +020035#else
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020036#include MBEDTLS_CONFIG_FILE
Manuel Pégourié-Gonnardcef4ad22014-04-29 12:39:06 +020037#endif
Paul Bakkered27a042013-04-18 22:46:23 +020038
Paul Bakker314052f2011-08-15 09:07:52 +000039#include "bignum.h"
Paul Bakkerc70b9822013-04-07 22:00:46 +020040#include "md.h"
Paul Bakker5121ce52009-01-03 21:22:43 +000041
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020042#if defined(MBEDTLS_THREADING_C)
Paul Bakkerc9965dc2013-09-29 14:58:17 +020043#include "threading.h"
44#endif
45
Paul Bakker13e2dfe2009-07-28 07:18:38 +000046/*
47 * RSA Error codes
48 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020049#define MBEDTLS_ERR_RSA_BAD_INPUT_DATA -0x4080 /**< Bad input parameters to function. */
50#define MBEDTLS_ERR_RSA_INVALID_PADDING -0x4100 /**< Input data contains invalid padding and is rejected. */
51#define MBEDTLS_ERR_RSA_KEY_GEN_FAILED -0x4180 /**< Something failed during generation of a key. */
Rose Zadik042e97f2018-01-26 16:35:10 +000052#define MBEDTLS_ERR_RSA_KEY_CHECK_FAILED -0x4200 /**< Key failed to pass the validity check of the library. */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020053#define MBEDTLS_ERR_RSA_PUBLIC_FAILED -0x4280 /**< The public key operation failed. */
54#define MBEDTLS_ERR_RSA_PRIVATE_FAILED -0x4300 /**< The private key operation failed. */
55#define MBEDTLS_ERR_RSA_VERIFY_FAILED -0x4380 /**< The PKCS#1 verification failed. */
56#define MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE -0x4400 /**< The output buffer for decryption is not large enough. */
57#define MBEDTLS_ERR_RSA_RNG_FAILED -0x4480 /**< The random generator failed to generate non-zeros. */
Rose Zadik042e97f2018-01-26 16:35:10 +000058#define MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION -0x4500 /**< The implementation does not offer the requested operation, for example, because of security violations or lack of functionality. */
Gilles Peskine7ecab3d2018-01-26 17:56:38 +010059#define MBEDTLS_ERR_RSA_HW_ACCEL_FAILED -0x4580 /**< RSA hardware accelerator failed. */
Paul Bakker5121ce52009-01-03 21:22:43 +000060
61/*
Paul Bakkerc70b9822013-04-07 22:00:46 +020062 * RSA constants
Paul Bakker5121ce52009-01-03 21:22:43 +000063 */
Rose Zadik042e97f2018-01-26 16:35:10 +000064#define MBEDTLS_RSA_PUBLIC 0 /**< Request private key operation. */
65#define MBEDTLS_RSA_PRIVATE 1 /**< Request public key operation. */
Paul Bakker5121ce52009-01-03 21:22:43 +000066
Rose Zadike8b5b992018-03-27 12:19:47 +010067#define MBEDTLS_RSA_PKCS_V15 0 /**< Use PKCS#1 v1.5 encoding. */
68#define MBEDTLS_RSA_PKCS_V21 1 /**< Use PKCS#1 v2.1 encoding. */
Paul Bakker5121ce52009-01-03 21:22:43 +000069
Rose Zadik042e97f2018-01-26 16:35:10 +000070#define MBEDTLS_RSA_SIGN 1 /**< Identifier for RSA signature operations. */
71#define MBEDTLS_RSA_CRYPT 2 /**< Identifier for RSA encryption and decryption operations. */
Paul Bakker5121ce52009-01-03 21:22:43 +000072
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020073#define MBEDTLS_RSA_SALT_LEN_ANY -1
Manuel Pégourié-Gonnard5ec628a2014-06-03 11:44:06 +020074
Manuel Pégourié-Gonnarde511ffc2013-08-22 17:33:21 +020075/*
76 * The above constants may be used even if the RSA module is compile out,
77 * eg for alternative (PKCS#11) RSA implemenations in the PK layers.
78 */
Hanno Beckerd22b78b2017-10-12 11:42:17 +010079
80#if !defined(MBEDTLS_RSA_ALT)
81// Regular implementation
82//
Manuel Pégourié-Gonnarde511ffc2013-08-22 17:33:21 +020083
Paul Bakker407a0da2013-06-27 14:29:21 +020084#ifdef __cplusplus
85extern "C" {
86#endif
87
Paul Bakker5121ce52009-01-03 21:22:43 +000088/**
Rose Zadik042e97f2018-01-26 16:35:10 +000089 * \brief The RSA context structure.
Hanno Becker5063cd22017-09-29 11:49:12 +010090 *
91 * \note Direct manipulation of the members of this structure
Rose Zadik042e97f2018-01-26 16:35:10 +000092 * is deprecated. All manipulation should instead be done through
93 * the public interface functions.
Paul Bakker5121ce52009-01-03 21:22:43 +000094 */
95typedef struct
96{
Rose Zadik042e97f2018-01-26 16:35:10 +000097 int ver; /*!< Always 0.*/
98 size_t len; /*!< The size of \p N in Bytes. */
Paul Bakker5121ce52009-01-03 21:22:43 +000099
Rose Zadike8b5b992018-03-27 12:19:47 +0100100 mbedtls_mpi N; /*!< The public modulus. */
101 mbedtls_mpi E; /*!< The public exponent. */
Paul Bakker5121ce52009-01-03 21:22:43 +0000102
Rose Zadike8b5b992018-03-27 12:19:47 +0100103 mbedtls_mpi D; /*!< The private exponent. */
104 mbedtls_mpi P; /*!< The first prime factor. */
105 mbedtls_mpi Q; /*!< The second prime factor. */
Hanno Becker1a59e792017-08-23 07:41:10 +0100106
Rose Zadikf2ec2882018-04-17 10:27:25 +0100107 mbedtls_mpi DP; /*!< <code>D % (P - 1)</code>. */
108 mbedtls_mpi DQ; /*!< <code>D % (Q - 1)</code>. */
109 mbedtls_mpi QP; /*!< <code>1 / (Q % P)</code>. */
Paul Bakker5121ce52009-01-03 21:22:43 +0000110
Rose Zadikf2ec2882018-04-17 10:27:25 +0100111 mbedtls_mpi RN; /*!< cached <code>R^2 mod N</code>. */
Paul Bakker5121ce52009-01-03 21:22:43 +0000112
Rose Zadikf2ec2882018-04-17 10:27:25 +0100113 mbedtls_mpi RP; /*!< cached <code>R^2 mod P</code>. */
114 mbedtls_mpi RQ; /*!< cached <code>R^2 mod Q</code>. */
Manuel Pégourié-Gonnardea53a552013-09-10 13:29:30 +0200115
Rose Zadike8b5b992018-03-27 12:19:47 +0100116 mbedtls_mpi Vi; /*!< The cached blinding value. */
117 mbedtls_mpi Vf; /*!< The cached un-blinding value. */
Paul Bakker9dcc3222011-03-08 14:16:06 +0000118
Rose Zadik042e97f2018-01-26 16:35:10 +0000119 int padding; /*!< Selects padding mode:
120 #MBEDTLS_RSA_PKCS_V15 for 1.5 padding and
121 #MBEDTLS_RSA_PKCS_V21 for OAEP or PSS. */
122 int hash_id; /*!< Hash identifier of mbedtls_md_type_t type,
123 as specified in md.h for use in the MGF
124 mask generating function used in the
125 EME-OAEP and EMSA-PSS encodings. */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200126#if defined(MBEDTLS_THREADING_C)
Rose Zadik042e97f2018-01-26 16:35:10 +0000127 mbedtls_threading_mutex_t mutex; /*!< Thread-safety mutex. */
Paul Bakkerc9965dc2013-09-29 14:58:17 +0200128#endif
Paul Bakker5121ce52009-01-03 21:22:43 +0000129}
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200130mbedtls_rsa_context;
Paul Bakker5121ce52009-01-03 21:22:43 +0000131
Paul Bakker5121ce52009-01-03 21:22:43 +0000132/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000133 * \brief This function initializes an RSA context.
Paul Bakker5121ce52009-01-03 21:22:43 +0000134 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000135 * \note Set padding to #MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP
Paul Bakker9a736322012-11-14 12:39:52 +0000136 * encryption scheme and the RSASSA-PSS signature scheme.
137 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000138 * \note The \p hash_id parameter is ignored when using
139 * #MBEDTLS_RSA_PKCS_V15 padding.
Manuel Pégourié-Gonnarde6d1d822014-06-02 16:47:02 +0200140 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000141 * \note The choice of padding mode is strictly enforced for private key
Manuel Pégourié-Gonnarde6d1d822014-06-02 16:47:02 +0200142 * operations, since there might be security concerns in
Rose Zadik042e97f2018-01-26 16:35:10 +0000143 * mixing padding modes. For public key operations it is
Manuel Pégourié-Gonnarde6d1d822014-06-02 16:47:02 +0200144 * a default value, which can be overriden by calling specific
Rose Zadik042e97f2018-01-26 16:35:10 +0000145 * \c rsa_rsaes_xxx or \c rsa_rsassa_xxx functions.
Manuel Pégourié-Gonnarde6d1d822014-06-02 16:47:02 +0200146 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000147 * \note The hash selected in \p hash_id is always used for OEAP
148 * encryption. For PSS signatures, it is always used for
149 * making signatures, but can be overriden for verifying them.
150 * If set to #MBEDTLS_MD_NONE, it is always overriden.
Rose Zadike8b5b992018-03-27 12:19:47 +0100151 *
152 * \param ctx The RSA context to initialize.
153 * \param padding Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or
154 * #MBEDTLS_RSA_PKCS_V21.
155 * \param hash_id The hash identifier of #mbedtls_md_type_t type, if
156 * \p padding is #MBEDTLS_RSA_PKCS_V21.
Paul Bakker5121ce52009-01-03 21:22:43 +0000157 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200158void mbedtls_rsa_init( mbedtls_rsa_context *ctx,
Hanno Becker8fd55482017-08-23 14:07:48 +0100159 int padding,
160 int hash_id);
Paul Bakker5121ce52009-01-03 21:22:43 +0000161
162/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000163 * \brief This function imports a set of core parameters into an
164 * RSA context.
Manuel Pégourié-Gonnard844a4c02014-03-10 21:55:35 +0100165 *
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100166 * \note This function can be called multiple times for successive
Rose Zadik042e97f2018-01-26 16:35:10 +0000167 * imports, if the parameters are not simultaneously present.
168 *
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100169 * Any sequence of calls to this function should be followed
Rose Zadik042e97f2018-01-26 16:35:10 +0000170 * by a call to mbedtls_rsa_complete(), which checks and
171 * completes the provided information to a ready-for-use
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100172 * public or private RSA key.
173 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000174 * \note See mbedtls_rsa_complete() for more information on which
175 * parameters are necessary to set up a private or public
176 * RSA key.
Hanno Becker33195552017-10-25 17:04:10 +0100177 *
Hanno Becker5178dca2017-10-03 14:29:37 +0100178 * \note The imported parameters are copied and need not be preserved
179 * for the lifetime of the RSA context being set up.
180 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100181 * \param ctx The initialized RSA context to store the parameters in.
182 * \param N The RSA modulus, or NULL.
183 * \param P The first prime factor of \p N, or NULL.
184 * \param Q The second prime factor of \p N, or NULL.
185 * \param D The private exponent, or NULL.
186 * \param E The public exponent, or NULL.
187 *
188 * \return \c 0 on success.
189 * \return A non-zero error code on failure.
Manuel Pégourié-Gonnard844a4c02014-03-10 21:55:35 +0100190 */
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100191int mbedtls_rsa_import( mbedtls_rsa_context *ctx,
192 const mbedtls_mpi *N,
193 const mbedtls_mpi *P, const mbedtls_mpi *Q,
194 const mbedtls_mpi *D, const mbedtls_mpi *E );
Manuel Pégourié-Gonnard844a4c02014-03-10 21:55:35 +0100195
196/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000197 * \brief This function imports core RSA parameters, in raw big-endian
198 * binary format, into an RSA context.
Paul Bakker5121ce52009-01-03 21:22:43 +0000199 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100200 * \note This function can be called multiple times for successive
201 * imports, if the parameters are not simultaneously present.
202 *
203 * Any sequence of calls to this function should be followed
204 * by a call to mbedtls_rsa_complete(), which checks and
205 * completes the provided information to a ready-for-use
206 * public or private RSA key.
207 *
208 * \note See mbedtls_rsa_complete() for more information on which
209 * parameters are necessary to set up a private or public
210 * RSA key.
211 *
212 * \note The imported parameters are copied and need not be preserved
213 * for the lifetime of the RSA context being set up.
214 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000215 * \param ctx The initialized RSA context to store the parameters in.
216 * \param N The RSA modulus, or NULL.
217 * \param N_len The Byte length of \p N, ignored if \p N == NULL.
218 * \param P The first prime factor of \p N, or NULL.
219 * \param P_len The Byte length of \p P, ignored if \p P == NULL.
220 * \param Q The second prime factor of \p N, or NULL.
221 * \param Q_len The Byte length of \p Q, ignored if \p Q == NULL.
222 * \param D The private exponent, or NULL.
223 * \param D_len The Byte length of \p D, ignored if \p D == NULL.
224 * \param E The public exponent, or NULL.
225 * \param E_len The Byte length of \p E, ignored if \p E == NULL.
Paul Bakker5121ce52009-01-03 21:22:43 +0000226 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100227 * \return \c 0 on success.
228 * \return A non-zero error code on failure.
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100229 */
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100230int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx,
Hanno Becker74716312017-10-02 10:00:37 +0100231 unsigned char const *N, size_t N_len,
232 unsigned char const *P, size_t P_len,
233 unsigned char const *Q, size_t Q_len,
234 unsigned char const *D, size_t D_len,
235 unsigned char const *E, size_t E_len );
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100236
237/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000238 * \brief This function completes an RSA context from
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100239 * a set of imported core parameters.
240 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000241 * To setup an RSA public key, precisely \p N and \p E
242 * must have been imported.
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100243 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000244 * To setup an RSA private key, sufficient information must
245 * be present for the other parameters to be derivable.
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100246 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000247 * The default implementation supports the following:
248 * <ul><li>Derive \p P, \p Q from \p N, \p D, \p E.</li>
249 * <li>Derive \p N, \p D from \p P, \p Q, \p E.</li></ul>
250 * Alternative implementations need not support these.
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100251 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000252 * If this function runs successfully, it guarantees that
253 * the RSA context can be used for RSA operations without
254 * the risk of failure or crash.
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100255 *
Hanno Becker1e801f52017-10-10 16:44:47 +0100256 * \warning This function need not perform consistency checks
Rose Zadik042e97f2018-01-26 16:35:10 +0000257 * for the imported parameters. In particular, parameters that
258 * are not needed by the implementation might be silently
259 * discarded and left unchecked. To check the consistency
260 * of the key material, see mbedtls_rsa_check_privkey().
Hanno Becker43a08d02017-10-02 13:16:35 +0100261 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100262 * \param ctx The initialized RSA context holding imported parameters.
263 *
264 * \return \c 0 on success.
265 * \return #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted derivations
266 * failed.
267 *
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100268 */
Hanno Beckerf9e184b2017-10-10 16:49:26 +0100269int mbedtls_rsa_complete( mbedtls_rsa_context *ctx );
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100270
271/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000272 * \brief This function exports the core parameters of an RSA key.
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100273 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000274 * If this function runs successfully, the non-NULL buffers
275 * pointed to by \p N, \p P, \p Q, \p D, and \p E are fully
276 * written, with additional unused space filled leading by
277 * zero Bytes.
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100278 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000279 * Possible reasons for returning
280 * #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION:<ul>
281 * <li>An alternative RSA implementation is in use, which
282 * stores the key externally, and either cannot or should
283 * not export it into RAM.</li>
284 * <li>A SW or HW implementation might not support a certain
285 * deduction. For example, \p P, \p Q from \p N, \p D,
286 * and \p E if the former are not part of the
287 * implementation.</li></ul>
Hanno Becker91c194d2017-09-29 12:50:12 +0100288 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000289 * If the function fails due to an unsupported operation,
290 * the RSA context stays intact and remains usable.
291 *
292 * \param ctx The initialized RSA context.
293 * \param N The MPI to hold the RSA modulus, or NULL.
294 * \param P The MPI to hold the first prime factor of \p N, or NULL.
295 * \param Q The MPI to hold the second prime factor of \p N, or NULL.
296 * \param D The MPI to hold the private exponent, or NULL.
297 * \param E The MPI to hold the public exponent, or NULL.
298 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100299 * \return \c 0 on success.
300 * \return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
Rose Zadik042e97f2018-01-26 16:35:10 +0000301 * requested parameters cannot be done due to missing
Rose Zadike8b5b992018-03-27 12:19:47 +0100302 * functionality or because of security policies.
303 * \return A non-zero return code on any other failure.
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100304 *
305 */
306int mbedtls_rsa_export( const mbedtls_rsa_context *ctx,
307 mbedtls_mpi *N, mbedtls_mpi *P, mbedtls_mpi *Q,
308 mbedtls_mpi *D, mbedtls_mpi *E );
309
310/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000311 * \brief This function exports core parameters of an RSA key
312 * in raw big-endian binary format.
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100313 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000314 * If this function runs successfully, the non-NULL buffers
315 * pointed to by \p N, \p P, \p Q, \p D, and \p E are fully
316 * written, with additional unused space filled leading by
317 * zero Bytes.
318 *
319 * Possible reasons for returning
320 * #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION:<ul>
321 * <li>An alternative RSA implementation is in use, which
322 * stores the key externally, and either cannot or should
323 * not export it into RAM.</li>
324 * <li>A SW or HW implementation might not support a certain
325 * deduction. For example, \p P, \p Q from \p N, \p D,
326 * and \p E if the former are not part of the
327 * implementation.</li></ul>
328 * If the function fails due to an unsupported operation,
329 * the RSA context stays intact and remains usable.
330 *
Rose Zadikf2ec2882018-04-17 10:27:25 +0100331 * \note The length parameters are ignored if the corresponding
Rose Zadike8b5b992018-03-27 12:19:47 +0100332 * buffer pointers are NULL.
333 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000334 * \param ctx The initialized RSA context.
335 * \param N The Byte array to store the RSA modulus, or NULL.
336 * \param N_len The size of the buffer for the modulus.
337 * \param P The Byte array to hold the first prime factor of \p N, or
338 * NULL.
339 * \param P_len The size of the buffer for the first prime factor.
340 * \param Q The Byte array to hold the second prime factor of \p N, or
Rose Zadikf2ec2882018-04-17 10:27:25 +0100341 * NULL.
Rose Zadik042e97f2018-01-26 16:35:10 +0000342 * \param Q_len The size of the buffer for the second prime factor.
343 * \param D The Byte array to hold the private exponent, or NULL.
344 * \param D_len The size of the buffer for the private exponent.
345 * \param E The Byte array to hold the public exponent, or NULL.
346 * \param E_len The size of the buffer for the public exponent.
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100347 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100348 * \return \c 0 on success.
349 * \return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
Rose Zadik042e97f2018-01-26 16:35:10 +0000350 * requested parameters cannot be done due to missing
Rose Zadike8b5b992018-03-27 12:19:47 +0100351 * functionality or because of security policies.
352 * \return A non-zero return code on any other failure.
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100353 */
354int mbedtls_rsa_export_raw( const mbedtls_rsa_context *ctx,
355 unsigned char *N, size_t N_len,
356 unsigned char *P, size_t P_len,
357 unsigned char *Q, size_t Q_len,
358 unsigned char *D, size_t D_len,
359 unsigned char *E, size_t E_len );
360
361/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000362 * \brief This function exports CRT parameters of a private RSA key.
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100363 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100364 * \note Alternative RSA implementations not using CRT-parameters
365 * internally can implement this function based on
366 * mbedtls_rsa_deduce_opt().
367 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000368 * \param ctx The initialized RSA context.
369 * \param DP The MPI to hold D modulo P-1, or NULL.
370 * \param DQ The MPI to hold D modulo Q-1, or NULL.
371 * \param QP The MPI to hold modular inverse of Q modulo P, or NULL.
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100372 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100373 * \return \c 0 on success.
374 * \return A non-zero error code on failure.
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100375 *
376 */
377int mbedtls_rsa_export_crt( const mbedtls_rsa_context *ctx,
378 mbedtls_mpi *DP, mbedtls_mpi *DQ, mbedtls_mpi *QP );
379
Paul Bakker5121ce52009-01-03 21:22:43 +0000380/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000381 * \brief This function sets padding for an already initialized RSA
382 * context. See mbedtls_rsa_init() for details.
Paul Bakker5121ce52009-01-03 21:22:43 +0000383 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000384 * \param ctx The RSA context to be set.
385 * \param padding Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or
386 * #MBEDTLS_RSA_PKCS_V21.
387 * \param hash_id The #MBEDTLS_RSA_PKCS_V21 hash identifier.
Paul Bakker40e46942009-01-03 21:51:57 +0000388 */
Hanno Becker8fd55482017-08-23 14:07:48 +0100389void mbedtls_rsa_set_padding( mbedtls_rsa_context *ctx, int padding,
390 int hash_id);
Paul Bakker21eb2802010-08-16 11:10:02 +0000391
Paul Bakkera3d195c2011-11-27 21:07:34 +0000392/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000393 * \brief This function retrieves the length of RSA modulus in Bytes.
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100394 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000395 * \param ctx The initialized RSA context.
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100396 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000397 * \return The length of the RSA modulus in Bytes.
Hanno Beckercbb59bc2017-08-23 14:11:08 +0100398 *
399 */
400size_t mbedtls_rsa_get_len( const mbedtls_rsa_context *ctx );
401
402/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000403 * \brief This function generates an RSA keypair.
Paul Bakker5121ce52009-01-03 21:22:43 +0000404 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000405 * \note mbedtls_rsa_init() must be called before this function,
406 * to set up the RSA context.
Paul Bakker5121ce52009-01-03 21:22:43 +0000407 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100408 * \param ctx The RSA context used to hold the key.
409 * \param f_rng The RNG function.
410 * \param p_rng The RNG context.
411 * \param nbits The size of the public key in bits.
412 * \param exponent The public exponent. For example, 65537.
413 *
414 * \return \c 0 on success.
415 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +0000416 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200417int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx,
Hanno Becker8fd55482017-08-23 14:07:48 +0100418 int (*f_rng)(void *, unsigned char *, size_t),
419 void *p_rng,
420 unsigned int nbits, int exponent );
Paul Bakker5121ce52009-01-03 21:22:43 +0000421
422/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000423 * \brief This function checks if a context contains at least an RSA
424 * public key.
Paul Bakker5121ce52009-01-03 21:22:43 +0000425 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000426 * If the function runs successfully, it is guaranteed that
427 * enough information is present to perform an RSA public key
428 * operation using mbedtls_rsa_public().
Paul Bakker5121ce52009-01-03 21:22:43 +0000429 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000430 * \param ctx The RSA context to check.
431 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100432 * \return \c 0 on success.
433 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
Hanno Becker43a08d02017-10-02 13:16:35 +0100434 *
Paul Bakker5121ce52009-01-03 21:22:43 +0000435 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200436int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx );
Paul Bakker5121ce52009-01-03 21:22:43 +0000437
438/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000439 * \brief This function checks if a context contains an RSA private key
Hanno Becker1e801f52017-10-10 16:44:47 +0100440 * and perform basic consistency checks.
Paul Bakker5121ce52009-01-03 21:22:43 +0000441 *
Hanno Becker68767a62017-10-17 10:13:31 +0100442 * \note The consistency checks performed by this function not only
Rose Zadik042e97f2018-01-26 16:35:10 +0000443 * ensure that mbedtls_rsa_private() can be called successfully
Hanno Becker68767a62017-10-17 10:13:31 +0100444 * on the given context, but that the various parameters are
445 * mutually consistent with high probability, in the sense that
Rose Zadik042e97f2018-01-26 16:35:10 +0000446 * mbedtls_rsa_public() and mbedtls_rsa_private() are inverses.
Hanno Becker1e801f52017-10-10 16:44:47 +0100447 *
448 * \warning This function should catch accidental misconfigurations
449 * like swapping of parameters, but it cannot establish full
450 * trust in neither the quality nor the consistency of the key
451 * material that was used to setup the given RSA context:
Rose Zadik042e97f2018-01-26 16:35:10 +0000452 * <ul><li>Consistency: Imported parameters that are irrelevant
453 * for the implementation might be silently dropped. If dropped,
454 * the current function does not have access to them,
455 * and therefore cannot check them. See mbedtls_rsa_complete().
456 * If you want to check the consistency of the entire
457 * content of an PKCS1-encoded RSA private key, for example, you
458 * should use mbedtls_rsa_validate_params() before setting
459 * up the RSA context.
460 * Additionally, if the implementation performs empirical checks,
461 * these checks substantiate but do not guarantee consistency.</li>
462 * <li>Quality: This function is not expected to perform
463 * extended quality assessments like checking that the prime
464 * factors are safe. Additionally, it is the responsibility of the
465 * user to ensure the trustworthiness of the source of his RSA
466 * parameters, which goes beyond what is effectively checkable
467 * by the library.</li></ul>
Rose Zadike8b5b992018-03-27 12:19:47 +0100468 *
469 * \param ctx The RSA context to check.
470 *
471 * \return \c 0 on success.
472 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +0000473 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200474int mbedtls_rsa_check_privkey( const mbedtls_rsa_context *ctx );
Paul Bakker5121ce52009-01-03 21:22:43 +0000475
476/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000477 * \brief This function checks a public-private RSA key pair.
Manuel Pégourié-Gonnard2f8d1f92014-11-06 14:02:51 +0100478 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000479 * It checks each of the contexts, and makes sure they match.
Manuel Pégourié-Gonnard2f8d1f92014-11-06 14:02:51 +0100480 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000481 * \param pub The RSA context holding the public key.
482 * \param prv The RSA context holding the private key.
483 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100484 * \return \c 0 on success.
485 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
Manuel Pégourié-Gonnard2f8d1f92014-11-06 14:02:51 +0100486 */
Hanno Becker98838b02017-10-02 13:16:10 +0100487int mbedtls_rsa_check_pub_priv( const mbedtls_rsa_context *pub,
488 const mbedtls_rsa_context *prv );
Manuel Pégourié-Gonnard2f8d1f92014-11-06 14:02:51 +0100489
490/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000491 * \brief This function performs an RSA public key operation.
Paul Bakker5121ce52009-01-03 21:22:43 +0000492 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000493 * \note This function does not handle message padding.
494 *
495 * \note Make sure to set \p input[0] = 0 or ensure that
496 * input is smaller than \p N.
Paul Bakker5121ce52009-01-03 21:22:43 +0000497 *
498 * \note The input and output buffers must be large
Rose Zadik042e97f2018-01-26 16:35:10 +0000499 * enough. For example, 128 Bytes if RSA-1024 is used.
Rose Zadike8b5b992018-03-27 12:19:47 +0100500 *
501 * \param ctx The RSA context.
502 * \param input The input buffer.
503 * \param output The output buffer.
504 *
505 * \return \c 0 on success.
506 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +0000507 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200508int mbedtls_rsa_public( mbedtls_rsa_context *ctx,
Paul Bakkerff60ee62010-03-16 21:09:09 +0000509 const unsigned char *input,
Paul Bakker5121ce52009-01-03 21:22:43 +0000510 unsigned char *output );
511
512/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000513 * \brief This function performs an RSA private key operation.
Paul Bakker5121ce52009-01-03 21:22:43 +0000514 *
Paul Bakker5121ce52009-01-03 21:22:43 +0000515 * \note The input and output buffers must be large
Rose Zadik042e97f2018-01-26 16:35:10 +0000516 * enough. For example, 128 Bytes if RSA-1024 is used.
Hanno Becker88ec2382017-05-03 13:51:16 +0100517 *
Hanno Becker24120612017-10-26 11:53:35 +0100518 * \note Blinding is used if and only if a PRNG is provided.
Hanno Becker88ec2382017-05-03 13:51:16 +0100519 *
520 * \note If blinding is used, both the base of exponentation
Hanno Becker24120612017-10-26 11:53:35 +0100521 * and the exponent are blinded, providing protection
522 * against some side-channel attacks.
Hanno Becker88ec2382017-05-03 13:51:16 +0100523 *
Hanno Becker4e1be392017-10-02 15:56:48 +0100524 * \warning It is deprecated and a security risk to not provide
525 * a PRNG here and thereby prevent the use of blinding.
526 * Future versions of the library may enforce the presence
527 * of a PRNG.
Hanno Becker88ec2382017-05-03 13:51:16 +0100528 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100529 * \param ctx The RSA context.
530 * \param f_rng The RNG function. Needed for blinding.
531 * \param p_rng The RNG context.
532 * \param input The input buffer.
533 * \param output The output buffer.
534 *
535 * \return \c 0 on success.
536 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
537 *
Paul Bakker5121ce52009-01-03 21:22:43 +0000538 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200539int mbedtls_rsa_private( mbedtls_rsa_context *ctx,
Paul Bakker548957d2013-08-30 10:30:02 +0200540 int (*f_rng)(void *, unsigned char *, size_t),
541 void *p_rng,
Paul Bakkerff60ee62010-03-16 21:09:09 +0000542 const unsigned char *input,
Paul Bakker5121ce52009-01-03 21:22:43 +0000543 unsigned char *output );
544
545/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000546 * \brief This function adds the message padding, then performs an RSA
547 * operation.
Paul Bakker5121ce52009-01-03 21:22:43 +0000548 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000549 * It is the generic wrapper for performing a PKCS#1 encryption
550 * operation using the \p mode from the context.
Paul Bakker5121ce52009-01-03 21:22:43 +0000551 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100552 * \note The input and output buffers must be as large as the size
553 * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
Paul Bakker5121ce52009-01-03 21:22:43 +0000554 *
Hanno Becker3cdc7112017-10-05 10:09:31 +0100555 * \deprecated It is deprecated and discouraged to call this function
Rose Zadik042e97f2018-01-26 16:35:10 +0000556 * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
557 * are likely to remove the \p mode argument and have it
558 * implicitly set to #MBEDTLS_RSA_PUBLIC.
Hanno Becker3cdc7112017-10-05 10:09:31 +0100559 *
Rose Zadikf2ec2882018-04-17 10:27:25 +0100560 * \note Alternative implementations of RSA need not support
561 * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
562 * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
563 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100564 * \param ctx The RSA context.
565 * \param f_rng The RNG function. Needed for padding, PKCS#1 v2.1
566 * encoding, and #MBEDTLS_RSA_PRIVATE.
567 * \param p_rng The RNG context.
568 * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
569 * \param ilen The length of the plaintext.
570 * \param input The buffer holding the data to encrypt.
571 * \param output The buffer used to hold the ciphertext.
Hanno Becker3cdc7112017-10-05 10:09:31 +0100572 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100573 * \return \c 0 on success.
574 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +0000575 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200576int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx,
Paul Bakkera3d195c2011-11-27 21:07:34 +0000577 int (*f_rng)(void *, unsigned char *, size_t),
Paul Bakker21eb2802010-08-16 11:10:02 +0000578 void *p_rng,
Paul Bakker23986e52011-04-24 08:57:21 +0000579 int mode, size_t ilen,
Paul Bakkerff60ee62010-03-16 21:09:09 +0000580 const unsigned char *input,
Paul Bakker5121ce52009-01-03 21:22:43 +0000581 unsigned char *output );
582
583/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000584 * \brief This function performs a PKCS#1 v1.5 encryption operation
585 * (RSAES-PKCS1-v1_5-ENCRYPT).
Paul Bakkerb3869132013-02-28 17:21:01 +0100586 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100587 * \note The output buffer must be as large as the size
588 * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
Paul Bakkerb3869132013-02-28 17:21:01 +0100589 *
Hanno Becker3cdc7112017-10-05 10:09:31 +0100590 * \deprecated It is deprecated and discouraged to call this function
Rose Zadik042e97f2018-01-26 16:35:10 +0000591 * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
592 * are likely to remove the \p mode argument and have it
593 * implicitly set to #MBEDTLS_RSA_PUBLIC.
Hanno Becker3cdc7112017-10-05 10:09:31 +0100594 *
Rose Zadikf2ec2882018-04-17 10:27:25 +0100595 * \note Alternative implementations of RSA need not support
596 * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
597 * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
598 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100599 * \param ctx The RSA context.
600 * \param f_rng The RNG function. Needed for padding and
601 * #MBEDTLS_RSA_PRIVATE.
602 * \param p_rng The RNG context.
603 * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
604 * \param ilen The length of the plaintext.
605 * \param input The buffer holding the data to encrypt.
606 * \param output The buffer used to hold the ciphertext.
Hanno Becker3cdc7112017-10-05 10:09:31 +0100607 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100608 * \return \c 0 on success.
609 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
Paul Bakkerb3869132013-02-28 17:21:01 +0100610 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200611int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx,
Paul Bakkerb3869132013-02-28 17:21:01 +0100612 int (*f_rng)(void *, unsigned char *, size_t),
613 void *p_rng,
614 int mode, size_t ilen,
615 const unsigned char *input,
616 unsigned char *output );
617
618/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000619 * \brief This function performs a PKCS#1 v2.1 OAEP encryption
620 * operation (RSAES-OAEP-ENCRYPT).
Paul Bakkerb3869132013-02-28 17:21:01 +0100621 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100622 * \note The output buffer must be as large as the size
623 * of ctx->N. For example, 128 Bytes if RSA-1024 is used.
624 *
625 * \deprecated It is deprecated and discouraged to call this function
626 * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
627 * are likely to remove the \p mode argument and have it
628 * implicitly set to #MBEDTLS_RSA_PUBLIC.
629 *
Rose Zadikf2ec2882018-04-17 10:27:25 +0100630 * \note Alternative implementations of RSA need not support
631 * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
632 * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
633 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000634 * \param ctx The RSA context.
635 * \param f_rng The RNG function. Needed for padding and PKCS#1 v2.1
636 * encoding and #MBEDTLS_RSA_PRIVATE.
Rose Zadike8b5b992018-03-27 12:19:47 +0100637 * \param p_rng The RNG context.
Rose Zadik042e97f2018-01-26 16:35:10 +0000638 * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
639 * \param label The buffer holding the custom label to use.
640 * \param label_len The length of the label.
641 * \param ilen The length of the plaintext.
642 * \param input The buffer holding the data to encrypt.
643 * \param output The buffer used to hold the ciphertext.
Paul Bakkerb3869132013-02-28 17:21:01 +0100644 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100645 * \return \c 0 on success.
646 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
Paul Bakkerb3869132013-02-28 17:21:01 +0100647 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200648int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx,
Paul Bakkerb3869132013-02-28 17:21:01 +0100649 int (*f_rng)(void *, unsigned char *, size_t),
650 void *p_rng,
Paul Bakkera43231c2013-02-28 17:33:49 +0100651 int mode,
652 const unsigned char *label, size_t label_len,
653 size_t ilen,
Paul Bakkerb3869132013-02-28 17:21:01 +0100654 const unsigned char *input,
655 unsigned char *output );
656
657/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000658 * \brief This function performs an RSA operation, then removes the
659 * message padding.
Paul Bakker5121ce52009-01-03 21:22:43 +0000660 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000661 * It is the generic wrapper for performing a PKCS#1 decryption
662 * operation using the \p mode from the context.
Paul Bakker5121ce52009-01-03 21:22:43 +0000663 *
Hanno Becker248ae6d2017-05-04 11:27:39 +0100664 * \note The output buffer length \c output_max_len should be
Rose Zadik042e97f2018-01-26 16:35:10 +0000665 * as large as the size \p ctx->len of \p ctx->N (for example,
666 * 128 Bytes if RSA-1024 is used) to be able to hold an
667 * arbitrary decrypted message. If it is not large enough to
668 * hold the decryption of the particular ciphertext provided,
669 * the function returns \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
Hanno Becker248ae6d2017-05-04 11:27:39 +0100670 *
671 * \note The input buffer must be as large as the size
Rose Zadik042e97f2018-01-26 16:35:10 +0000672 * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
Rose Zadike8b5b992018-03-27 12:19:47 +0100673 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100674 * \deprecated It is deprecated and discouraged to call this function
675 * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
676 * are likely to remove the \p mode argument and have it
677 * implicitly set to #MBEDTLS_RSA_PRIVATE.
678 *
Rose Zadikf2ec2882018-04-17 10:27:25 +0100679 * \note Alternative implementations of RSA need not support
680 * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
681 * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
682 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100683 * \param ctx The RSA context.
684 * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
685 * \param p_rng The RNG context.
686 * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
687 * \param olen The length of the plaintext.
688 * \param input The buffer holding the encrypted data.
689 * \param output The buffer used to hold the plaintext.
690 * \param output_max_len The maximum length of the output buffer.
691 *
692 * \return \c 0 on success.
693 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +0000694 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200695int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx,
Paul Bakker548957d2013-08-30 10:30:02 +0200696 int (*f_rng)(void *, unsigned char *, size_t),
697 void *p_rng,
Paul Bakker23986e52011-04-24 08:57:21 +0000698 int mode, size_t *olen,
Paul Bakkerff60ee62010-03-16 21:09:09 +0000699 const unsigned char *input,
Paul Bakker060c5682009-01-12 21:48:39 +0000700 unsigned char *output,
Paul Bakker23986e52011-04-24 08:57:21 +0000701 size_t output_max_len );
Paul Bakker5121ce52009-01-03 21:22:43 +0000702
703/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000704 * \brief This function performs a PKCS#1 v1.5 decryption
705 * operation (RSAES-PKCS1-v1_5-DECRYPT).
Paul Bakkerb3869132013-02-28 17:21:01 +0100706 *
Hanno Becker248ae6d2017-05-04 11:27:39 +0100707 * \note The output buffer length \c output_max_len should be
Rose Zadik042e97f2018-01-26 16:35:10 +0000708 * as large as the size \p ctx->len of \p ctx->N, for example,
709 * 128 Bytes if RSA-1024 is used, to be able to hold an
710 * arbitrary decrypted message. If it is not large enough to
711 * hold the decryption of the particular ciphertext provided,
712 * the function returns #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
Hanno Becker248ae6d2017-05-04 11:27:39 +0100713 *
714 * \note The input buffer must be as large as the size
Rose Zadik042e97f2018-01-26 16:35:10 +0000715 * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
Rose Zadike8b5b992018-03-27 12:19:47 +0100716 *
717 * \deprecated It is deprecated and discouraged to call this function
718 * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
719 * are likely to remove the \p mode argument and have it
720 * implicitly set to #MBEDTLS_RSA_PRIVATE.
721 *
Rose Zadikf2ec2882018-04-17 10:27:25 +0100722 * \note Alternative implementations of RSA need not support
723 * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
724 * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
725 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100726 * \param ctx The RSA context.
727 * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
728 * \param p_rng The RNG context.
729 * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
730 * \param olen The length of the plaintext.
731 * \param input The buffer holding the encrypted data.
732 * \param output The buffer to hold the plaintext.
733 * \param output_max_len The maximum length of the output buffer.
734 *
735 * \return \c 0 on success.
736 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
737 *
Paul Bakkerb3869132013-02-28 17:21:01 +0100738 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200739int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx,
Paul Bakker548957d2013-08-30 10:30:02 +0200740 int (*f_rng)(void *, unsigned char *, size_t),
741 void *p_rng,
Paul Bakkerb3869132013-02-28 17:21:01 +0100742 int mode, size_t *olen,
743 const unsigned char *input,
744 unsigned char *output,
745 size_t output_max_len );
746
747/**
Rose Zadike8b5b992018-03-27 12:19:47 +0100748 * \brief This function performs a PKCS#1 v2.1 OAEP decryption
749 * operation (RSAES-OAEP-DECRYPT).
Paul Bakkerb3869132013-02-28 17:21:01 +0100750 *
Rose Zadikf2ec2882018-04-17 10:27:25 +0100751 * \note The output buffer length \c output_max_len should be
752 * as large as the size \p ctx->len of \p ctx->N, for
753 * example, 128 Bytes if RSA-1024 is used, to be able to
754 * hold an arbitrary decrypted message. If it is not
755 * large enough to hold the decryption of the particular
756 * ciphertext provided, the function returns
757 * #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
Paul Bakkerb3869132013-02-28 17:21:01 +0100758 *
Rose Zadikf2ec2882018-04-17 10:27:25 +0100759 * \note The input buffer must be as large as the size
760 * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
Rose Zadike8b5b992018-03-27 12:19:47 +0100761 *
762 * \deprecated It is deprecated and discouraged to call this function
763 * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
764 * are likely to remove the \p mode argument and have it
765 * implicitly set to #MBEDTLS_RSA_PRIVATE.
766 *
Rose Zadikf2ec2882018-04-17 10:27:25 +0100767 * \note Alternative implementations of RSA need not support
768 * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
769 * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
770 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100771 * \param ctx The RSA context.
772 * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
773 * \param p_rng The RNG context.
774 * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
775 * \param label The buffer holding the custom label to use.
776 * \param label_len The length of the label.
777 * \param olen The length of the plaintext.
778 * \param input The buffer holding the encrypted data.
779 * \param output The buffer to hold the plaintext.
780 * \param output_max_len The maximum length of the output buffer.
781 *
782 * \return \c 0 on success.
783 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
Paul Bakkerb3869132013-02-28 17:21:01 +0100784 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200785int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx,
Paul Bakker548957d2013-08-30 10:30:02 +0200786 int (*f_rng)(void *, unsigned char *, size_t),
787 void *p_rng,
Paul Bakkera43231c2013-02-28 17:33:49 +0100788 int mode,
789 const unsigned char *label, size_t label_len,
790 size_t *olen,
Paul Bakkerb3869132013-02-28 17:21:01 +0100791 const unsigned char *input,
792 unsigned char *output,
793 size_t output_max_len );
794
795/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000796 * \brief This function performs a private RSA operation to sign
797 * a message digest using PKCS#1.
Paul Bakker5121ce52009-01-03 21:22:43 +0000798 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000799 * It is the generic wrapper for performing a PKCS#1
800 * signature using the \p mode from the context.
Paul Bakker5121ce52009-01-03 21:22:43 +0000801 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000802 * \note The \p sig buffer must be as large as the size
803 * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
Paul Bakker9dcc3222011-03-08 14:16:06 +0000804 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000805 * \note For PKCS#1 v2.1 encoding, see comments on
806 * mbedtls_rsa_rsassa_pss_sign() for details on
807 * \p md_alg and \p hash_id.
Rose Zadike8b5b992018-03-27 12:19:47 +0100808 *
809 * \deprecated It is deprecated and discouraged to call this function
810 * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
811 * are likely to remove the \p mode argument and have it
812 * implicitly set to #MBEDTLS_RSA_PRIVATE.
813 *
Rose Zadikf2ec2882018-04-17 10:27:25 +0100814 * \note Alternative implementations of RSA need not support
815 * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
816 * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
817 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100818 * \param ctx The RSA context.
819 * \param f_rng The RNG function. Needed for PKCS#1 v2.1 encoding and for
820 * #MBEDTLS_RSA_PRIVATE.
821 * \param p_rng The RNG context.
822 * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
823 * \param md_alg The message-digest algorithm used to hash the original data.
824 * Use #MBEDTLS_MD_NONE for signing raw data.
825 * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
826 * \param hash The buffer holding the message digest.
827 * \param sig The buffer to hold the ciphertext.
828 *
829 * \return \c 0 if the signing operation was successful.
830 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +0000831 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200832int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx,
Paul Bakkera3d195c2011-11-27 21:07:34 +0000833 int (*f_rng)(void *, unsigned char *, size_t),
Paul Bakker9dcc3222011-03-08 14:16:06 +0000834 void *p_rng,
Paul Bakker5121ce52009-01-03 21:22:43 +0000835 int mode,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200836 mbedtls_md_type_t md_alg,
Paul Bakker23986e52011-04-24 08:57:21 +0000837 unsigned int hashlen,
Paul Bakkerff60ee62010-03-16 21:09:09 +0000838 const unsigned char *hash,
Paul Bakker5121ce52009-01-03 21:22:43 +0000839 unsigned char *sig );
840
841/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000842 * \brief This function performs a PKCS#1 v1.5 signature
843 * operation (RSASSA-PKCS1-v1_5-SIGN).
Paul Bakkerb3869132013-02-28 17:21:01 +0100844 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100845 * \note The \p sig buffer must be as large as the size
846 * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
847 *
848 * \deprecated It is deprecated and discouraged to call this function
849 * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
850 * are likely to remove the \p mode argument and have it
851 * implicitly set to #MBEDTLS_RSA_PRIVATE.
852 *
Rose Zadikf2ec2882018-04-17 10:27:25 +0100853 * \note Alternative implementations of RSA need not support
854 * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
855 * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
856 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000857 * \param ctx The RSA context.
858 * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
Rose Zadike8b5b992018-03-27 12:19:47 +0100859 * \param p_rng The RNG context.
Rose Zadik042e97f2018-01-26 16:35:10 +0000860 * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
861 * \param md_alg The message-digest algorithm used to hash the original data.
862 * Use #MBEDTLS_MD_NONE for signing raw data.
863 * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
864 * \param hash The buffer holding the message digest.
865 * \param sig The buffer to hold the ciphertext.
Paul Bakkerb3869132013-02-28 17:21:01 +0100866 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100867 * \return \c 0 if the signing operation was successful.
868 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
Paul Bakkerb3869132013-02-28 17:21:01 +0100869 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200870int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx,
Paul Bakker548957d2013-08-30 10:30:02 +0200871 int (*f_rng)(void *, unsigned char *, size_t),
872 void *p_rng,
Paul Bakkerb3869132013-02-28 17:21:01 +0100873 int mode,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200874 mbedtls_md_type_t md_alg,
Paul Bakkerb3869132013-02-28 17:21:01 +0100875 unsigned int hashlen,
876 const unsigned char *hash,
877 unsigned char *sig );
878
879/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000880 * \brief This function performs a PKCS#1 v2.1 PSS signature
881 * operation (RSASSA-PSS-SIGN).
Paul Bakkerb3869132013-02-28 17:21:01 +0100882 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000883 * \note The \p sig buffer must be as large as the size
884 * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
Paul Bakkerb3869132013-02-28 17:21:01 +0100885 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000886 * \note The \p hash_id in the RSA context is the one used for the
887 * encoding. \p md_alg in the function call is the type of hash
888 * that is encoded. According to <em>RFC-3447: Public-Key
889 * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
890 * Specifications</em> it is advised to keep both hashes the
891 * same.
Rose Zadike8b5b992018-03-27 12:19:47 +0100892 *
893 * \deprecated It is deprecated and discouraged to call this function
894 * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
895 * are likely to remove the \p mode argument and have it
896 * implicitly set to #MBEDTLS_RSA_PRIVATE.
897 *
Rose Zadikf2ec2882018-04-17 10:27:25 +0100898 * \note Alternative implementations of RSA need not support
899 * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
900 * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
901 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100902 * \param ctx The RSA context.
903 * \param f_rng The RNG function. Needed for PKCS#1 v2.1 encoding and for
904 * #MBEDTLS_RSA_PRIVATE.
905 * \param p_rng The RNG context.
906 * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
907 * \param md_alg The message-digest algorithm used to hash the original data.
908 * Use #MBEDTLS_MD_NONE for signing raw data.
909 * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
910 * \param hash The buffer holding the message digest.
911 * \param sig The buffer to hold the ciphertext.
912 *
913 * \return \c 0 if the signing operation was successful.
914 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
Paul Bakkerb3869132013-02-28 17:21:01 +0100915 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200916int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx,
Paul Bakkerb3869132013-02-28 17:21:01 +0100917 int (*f_rng)(void *, unsigned char *, size_t),
918 void *p_rng,
919 int mode,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200920 mbedtls_md_type_t md_alg,
Paul Bakkerb3869132013-02-28 17:21:01 +0100921 unsigned int hashlen,
922 const unsigned char *hash,
923 unsigned char *sig );
924
925/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000926 * \brief This function performs a public RSA operation and checks
927 * the message digest.
Paul Bakker5121ce52009-01-03 21:22:43 +0000928 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000929 * This is the generic wrapper for performing a PKCS#1
930 * verification using the mode from the context.
Paul Bakker5121ce52009-01-03 21:22:43 +0000931 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000932 * \note The \p sig buffer must be as large as the size
933 * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
Paul Bakker9dcc3222011-03-08 14:16:06 +0000934 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000935 * \note For PKCS#1 v2.1 encoding, see comments on
936 * mbedtls_rsa_rsassa_pss_verify() about \p md_alg and
937 * \p hash_id.
Rose Zadike8b5b992018-03-27 12:19:47 +0100938 *
939 * \deprecated It is deprecated and discouraged to call this function
940 * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
941 * are likely to remove the \p mode argument and have it
942 * set to #MBEDTLS_RSA_PUBLIC.
943 *
Rose Zadikf2ec2882018-04-17 10:27:25 +0100944 * \note Alternative implementations of RSA need not support
945 * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
946 * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
947 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100948 * \param ctx The RSA public key context.
949 * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
950 * \param p_rng The RNG context.
951 * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
952 * \param md_alg The message-digest algorithm used to hash the original data.
953 * Use #MBEDTLS_MD_NONE for signing raw data.
954 * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
955 * \param hash The buffer holding the message digest.
956 * \param sig The buffer holding the ciphertext.
957 *
958 * \return \c 0 if the verify operation was successful.
959 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +0000960 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200961int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx,
Paul Bakker548957d2013-08-30 10:30:02 +0200962 int (*f_rng)(void *, unsigned char *, size_t),
963 void *p_rng,
Paul Bakker5121ce52009-01-03 21:22:43 +0000964 int mode,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200965 mbedtls_md_type_t md_alg,
Paul Bakker23986e52011-04-24 08:57:21 +0000966 unsigned int hashlen,
Paul Bakkerff60ee62010-03-16 21:09:09 +0000967 const unsigned char *hash,
Manuel Pégourié-Gonnardcc0a9d02013-08-12 11:34:35 +0200968 const unsigned char *sig );
Paul Bakker5121ce52009-01-03 21:22:43 +0000969
970/**
Rose Zadik042e97f2018-01-26 16:35:10 +0000971 * \brief This function performs a PKCS#1 v1.5 verification
972 * operation (RSASSA-PKCS1-v1_5-VERIFY).
Paul Bakkerb3869132013-02-28 17:21:01 +0100973 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100974 * \note The \p sig buffer must be as large as the size
975 * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
976 *
977 * \deprecated It is deprecated and discouraged to call this function
978 * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
979 * are likely to remove the \p mode argument and have it
980 * set to #MBEDTLS_RSA_PUBLIC.
981 *
Rose Zadikf2ec2882018-04-17 10:27:25 +0100982 * \note Alternative implementations of RSA need not support
983 * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
984 * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
985 *
Rose Zadik042e97f2018-01-26 16:35:10 +0000986 * \param ctx The RSA public key context.
987 * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
Rose Zadike8b5b992018-03-27 12:19:47 +0100988 * \param p_rng The RNG context.
Rose Zadik042e97f2018-01-26 16:35:10 +0000989 * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
990 * \param md_alg The message-digest algorithm used to hash the original data.
991 * Use #MBEDTLS_MD_NONE for signing raw data.
992 * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
993 * \param hash The buffer holding the message digest.
994 * \param sig The buffer holding the ciphertext.
Paul Bakkerb3869132013-02-28 17:21:01 +0100995 *
Rose Zadike8b5b992018-03-27 12:19:47 +0100996 * \return \c 0 if the verify operation was successful.
997 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
Paul Bakkerb3869132013-02-28 17:21:01 +0100998 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200999int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx,
Paul Bakker548957d2013-08-30 10:30:02 +02001000 int (*f_rng)(void *, unsigned char *, size_t),
1001 void *p_rng,
Paul Bakkerb3869132013-02-28 17:21:01 +01001002 int mode,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001003 mbedtls_md_type_t md_alg,
Paul Bakkerb3869132013-02-28 17:21:01 +01001004 unsigned int hashlen,
1005 const unsigned char *hash,
Manuel Pégourié-Gonnardcc0a9d02013-08-12 11:34:35 +02001006 const unsigned char *sig );
Paul Bakkerb3869132013-02-28 17:21:01 +01001007
1008/**
Rose Zadik042e97f2018-01-26 16:35:10 +00001009 * \brief This function performs a PKCS#1 v2.1 PSS verification
1010 * operation (RSASSA-PSS-VERIFY).
Paul Bakkerb3869132013-02-28 17:21:01 +01001011 *
Rose Zadik042e97f2018-01-26 16:35:10 +00001012 * The hash function for the MGF mask generating function
1013 * is that specified in the RSA context.
Paul Bakkerb3869132013-02-28 17:21:01 +01001014 *
Rose Zadik042e97f2018-01-26 16:35:10 +00001015 * \note The \p sig buffer must be as large as the size
1016 * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
Paul Bakkerb3869132013-02-28 17:21:01 +01001017 *
Rose Zadik042e97f2018-01-26 16:35:10 +00001018 * \note The \p hash_id in the RSA context is the one used for the
1019 * verification. \p md_alg in the function call is the type of
1020 * hash that is verified. According to <em>RFC-3447: Public-Key
1021 * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
1022 * Specifications</em> it is advised to keep both hashes the
1023 * same. If \p hash_id in the RSA context is unset,
1024 * the \p md_alg from the function call is used.
Rose Zadike8b5b992018-03-27 12:19:47 +01001025 *
1026 * \deprecated It is deprecated and discouraged to call this function
1027 * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
1028 * are likely to remove the \p mode argument and have it
1029 * implicitly set to #MBEDTLS_RSA_PUBLIC.
1030 *
Rose Zadikf2ec2882018-04-17 10:27:25 +01001031 * \note Alternative implementations of RSA need not support
1032 * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
1033 * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
1034 *
Rose Zadike8b5b992018-03-27 12:19:47 +01001035 * \param ctx The RSA public key context.
1036 * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
1037 * \param p_rng The RNG context.
1038 * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
1039 * \param md_alg The message-digest algorithm used to hash the original data.
1040 * Use #MBEDTLS_MD_NONE for signing raw data.
1041 * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
1042 * \param hash The buffer holding the message digest.
1043 * \param sig The buffer holding the ciphertext.
1044 *
1045 * \return \c 0 if the verify operation was successful.
1046 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
Paul Bakkerb3869132013-02-28 17:21:01 +01001047 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001048int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx,
Paul Bakker548957d2013-08-30 10:30:02 +02001049 int (*f_rng)(void *, unsigned char *, size_t),
1050 void *p_rng,
Paul Bakkerb3869132013-02-28 17:21:01 +01001051 int mode,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001052 mbedtls_md_type_t md_alg,
Paul Bakkerb3869132013-02-28 17:21:01 +01001053 unsigned int hashlen,
1054 const unsigned char *hash,
Manuel Pégourié-Gonnardcc0a9d02013-08-12 11:34:35 +02001055 const unsigned char *sig );
Paul Bakkerb3869132013-02-28 17:21:01 +01001056
1057/**
Rose Zadik042e97f2018-01-26 16:35:10 +00001058 * \brief This function performs a PKCS#1 v2.1 PSS verification
1059 * operation (RSASSA-PSS-VERIFY).
Manuel Pégourié-Gonnard5ec628a2014-06-03 11:44:06 +02001060 *
Rose Zadik042e97f2018-01-26 16:35:10 +00001061 * The hash function for the MGF mask generating function
1062 * is that specified in \p mgf1_hash_id.
Manuel Pégourié-Gonnard5ec628a2014-06-03 11:44:06 +02001063 *
Rose Zadik042e97f2018-01-26 16:35:10 +00001064 * \note The \p sig buffer must be as large as the size
1065 * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
Manuel Pégourié-Gonnard5ec628a2014-06-03 11:44:06 +02001066 *
Rose Zadik042e97f2018-01-26 16:35:10 +00001067 * \note The \p hash_id in the RSA context is ignored.
Rose Zadike8b5b992018-03-27 12:19:47 +01001068 *
1069 * \param ctx The RSA public key context.
1070 * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
1071 * \param p_rng The RNG context.
1072 * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
1073 * \param md_alg The message-digest algorithm used to hash the original data.
1074 * Use #MBEDTLS_MD_NONE for signing raw data.
1075 * \param hashlen The length of the message digest. Only used if \p md_alg is
1076 * #MBEDTLS_MD_NONE.
1077 * \param hash The buffer holding the message digest.
1078 * \param mgf1_hash_id The message digest used for mask generation.
1079 * \param expected_salt_len The length of the salt used in padding. Use
1080 * #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length.
1081 * \param sig The buffer holding the ciphertext.
1082 *
1083 * \return \c 0 if the verify operation was successful.
1084 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
Manuel Pégourié-Gonnard5ec628a2014-06-03 11:44:06 +02001085 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001086int mbedtls_rsa_rsassa_pss_verify_ext( mbedtls_rsa_context *ctx,
Manuel Pégourié-Gonnard5ec628a2014-06-03 11:44:06 +02001087 int (*f_rng)(void *, unsigned char *, size_t),
1088 void *p_rng,
1089 int mode,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001090 mbedtls_md_type_t md_alg,
Manuel Pégourié-Gonnard5ec628a2014-06-03 11:44:06 +02001091 unsigned int hashlen,
1092 const unsigned char *hash,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001093 mbedtls_md_type_t mgf1_hash_id,
Manuel Pégourié-Gonnard5ec628a2014-06-03 11:44:06 +02001094 int expected_salt_len,
1095 const unsigned char *sig );
1096
1097/**
Rose Zadik042e97f2018-01-26 16:35:10 +00001098 * \brief This function copies the components of an RSA context.
Manuel Pégourié-Gonnard3053f5b2013-08-14 13:39:57 +02001099 *
Rose Zadik042e97f2018-01-26 16:35:10 +00001100 * \param dst The destination context.
1101 * \param src The source context.
Manuel Pégourié-Gonnard3053f5b2013-08-14 13:39:57 +02001102 *
Rose Zadike8b5b992018-03-27 12:19:47 +01001103 * \return \c 0 on success.
1104 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure.
Manuel Pégourié-Gonnard3053f5b2013-08-14 13:39:57 +02001105 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001106int mbedtls_rsa_copy( mbedtls_rsa_context *dst, const mbedtls_rsa_context *src );
Manuel Pégourié-Gonnard3053f5b2013-08-14 13:39:57 +02001107
1108/**
Rose Zadik042e97f2018-01-26 16:35:10 +00001109 * \brief This function frees the components of an RSA key.
Paul Bakker13e2dfe2009-07-28 07:18:38 +00001110 *
Rose Zadik042e97f2018-01-26 16:35:10 +00001111 * \param ctx The RSA Context to free.
Paul Bakker5121ce52009-01-03 21:22:43 +00001112 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001113void mbedtls_rsa_free( mbedtls_rsa_context *ctx );
Paul Bakker5121ce52009-01-03 21:22:43 +00001114
Hanno Beckerd22b78b2017-10-12 11:42:17 +01001115#ifdef __cplusplus
1116}
1117#endif
1118
1119#else /* MBEDTLS_RSA_ALT */
1120#include "rsa_alt.h"
1121#endif /* MBEDTLS_RSA_ALT */
1122
1123#ifdef __cplusplus
1124extern "C" {
1125#endif
1126
Paul Bakker5121ce52009-01-03 21:22:43 +00001127/**
Rose Zadik042e97f2018-01-26 16:35:10 +00001128 * \brief The RSA checkup routine.
Paul Bakker5121ce52009-01-03 21:22:43 +00001129 *
Rose Zadike8b5b992018-03-27 12:19:47 +01001130 * \return \c 0 on success.
1131 * \return \c 1 on failure.
Paul Bakker5121ce52009-01-03 21:22:43 +00001132 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001133int mbedtls_rsa_self_test( int verbose );
Paul Bakker5121ce52009-01-03 21:22:43 +00001134
1135#ifdef __cplusplus
1136}
1137#endif
1138
Paul Bakker5121ce52009-01-03 21:22:43 +00001139#endif /* rsa.h */