Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1 | /** |
| 2 | * \file rsa.h |
Paul Bakker | e0ccd0a | 2009-01-04 16:27:10 +0000 | [diff] [blame] | 3 | * |
Rose Zadik | 21e2926 | 2018-04-17 14:08:56 +0100 | [diff] [blame] | 4 | * \brief This file provides an API for the RSA public-key cryptosystem. |
Paul Bakker | 37ca75d | 2011-01-06 12:28:03 +0000 | [diff] [blame] | 5 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 6 | * The RSA public-key cryptosystem is defined in <em>Public-Key |
| 7 | * Cryptography Standards (PKCS) #1 v1.5: RSA Encryption</em> |
Darryl Green | 11999bb | 2018-03-13 15:22:58 +0000 | [diff] [blame] | 8 | * and <em>Public-Key Cryptography Standards (PKCS) #1 v2.1: |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 9 | * RSA Cryptography Specifications</em>. |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 10 | * |
Darryl Green | a40a101 | 2018-01-05 15:33:17 +0000 | [diff] [blame] | 11 | */ |
| 12 | /* |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 13 | * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved |
Manuel Pégourié-Gonnard | 37ff140 | 2015-09-04 14:21:07 +0200 | [diff] [blame] | 14 | * 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 Bakker | b96f154 | 2010-07-18 20:36:00 +0000 | [diff] [blame] | 27 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 28 | * This file is part of Mbed TLS (https://tls.mbed.org) |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 29 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 30 | #ifndef MBEDTLS_RSA_H |
| 31 | #define MBEDTLS_RSA_H |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 32 | |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 33 | #if !defined(MBEDTLS_CONFIG_FILE) |
Jaeden Amero | c49fbbf | 2019-07-04 20:01:14 +0100 | [diff] [blame^] | 34 | #include "mbedtls/config.h" |
Manuel Pégourié-Gonnard | cef4ad2 | 2014-04-29 12:39:06 +0200 | [diff] [blame] | 35 | #else |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 36 | #include MBEDTLS_CONFIG_FILE |
Manuel Pégourié-Gonnard | cef4ad2 | 2014-04-29 12:39:06 +0200 | [diff] [blame] | 37 | #endif |
Paul Bakker | ed27a04 | 2013-04-18 22:46:23 +0200 | [diff] [blame] | 38 | |
Jaeden Amero | c49fbbf | 2019-07-04 20:01:14 +0100 | [diff] [blame^] | 39 | #include "mbedtls/bignum.h" |
| 40 | #include "mbedtls/md.h" |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 41 | |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 42 | #if defined(MBEDTLS_THREADING_C) |
Jaeden Amero | c49fbbf | 2019-07-04 20:01:14 +0100 | [diff] [blame^] | 43 | #include "mbedtls/threading.h" |
Paul Bakker | c9965dc | 2013-09-29 14:58:17 +0200 | [diff] [blame] | 44 | #endif |
| 45 | |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 46 | /* |
| 47 | * RSA Error codes |
| 48 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 49 | #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 Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 52 | #define MBEDTLS_ERR_RSA_KEY_CHECK_FAILED -0x4200 /**< Key failed to pass the validity check of the library. */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 53 | #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. */ |
Ron Eldor | 9924bdc | 2018-10-04 10:59:13 +0300 | [diff] [blame] | 58 | |
| 59 | /* MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION is deprecated and should not be used. |
| 60 | */ |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 61 | #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. */ |
Ron Eldor | 9924bdc | 2018-10-04 10:59:13 +0300 | [diff] [blame] | 62 | |
| 63 | /* MBEDTLS_ERR_RSA_HW_ACCEL_FAILED is deprecated and should not be used. */ |
Gilles Peskine | 7ecab3d | 2018-01-26 17:56:38 +0100 | [diff] [blame] | 64 | #define MBEDTLS_ERR_RSA_HW_ACCEL_FAILED -0x4580 /**< RSA hardware accelerator failed. */ |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 65 | |
| 66 | /* |
Paul Bakker | c70b982 | 2013-04-07 22:00:46 +0200 | [diff] [blame] | 67 | * RSA constants |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 68 | */ |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 69 | #define MBEDTLS_RSA_PUBLIC 0 /**< Request private key operation. */ |
| 70 | #define MBEDTLS_RSA_PRIVATE 1 /**< Request public key operation. */ |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 71 | |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 72 | #define MBEDTLS_RSA_PKCS_V15 0 /**< Use PKCS#1 v1.5 encoding. */ |
| 73 | #define MBEDTLS_RSA_PKCS_V21 1 /**< Use PKCS#1 v2.1 encoding. */ |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 74 | |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 75 | #define MBEDTLS_RSA_SIGN 1 /**< Identifier for RSA signature operations. */ |
| 76 | #define MBEDTLS_RSA_CRYPT 2 /**< Identifier for RSA encryption and decryption operations. */ |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 77 | |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 78 | #define MBEDTLS_RSA_SALT_LEN_ANY -1 |
Manuel Pégourié-Gonnard | 5ec628a | 2014-06-03 11:44:06 +0200 | [diff] [blame] | 79 | |
Manuel Pégourié-Gonnard | e511ffc | 2013-08-22 17:33:21 +0200 | [diff] [blame] | 80 | /* |
| 81 | * The above constants may be used even if the RSA module is compile out, |
| 82 | * eg for alternative (PKCS#11) RSA implemenations in the PK layers. |
| 83 | */ |
Hanno Becker | d22b78b | 2017-10-12 11:42:17 +0100 | [diff] [blame] | 84 | |
Paul Bakker | 407a0da | 2013-06-27 14:29:21 +0200 | [diff] [blame] | 85 | #ifdef __cplusplus |
| 86 | extern "C" { |
| 87 | #endif |
| 88 | |
Ron Eldor | 4e6d55d | 2018-02-07 16:36:15 +0200 | [diff] [blame] | 89 | #if !defined(MBEDTLS_RSA_ALT) |
| 90 | // Regular implementation |
| 91 | // |
| 92 | |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 93 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 94 | * \brief The RSA context structure. |
Hanno Becker | 5063cd2 | 2017-09-29 11:49:12 +0100 | [diff] [blame] | 95 | * |
| 96 | * \note Direct manipulation of the members of this structure |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 97 | * is deprecated. All manipulation should instead be done through |
| 98 | * the public interface functions. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 99 | */ |
Dawid Drozd | 428cc52 | 2018-07-24 10:02:47 +0200 | [diff] [blame] | 100 | typedef struct mbedtls_rsa_context |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 101 | { |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 102 | int ver; /*!< Always 0.*/ |
| 103 | size_t len; /*!< The size of \p N in Bytes. */ |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 104 | |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 105 | mbedtls_mpi N; /*!< The public modulus. */ |
| 106 | mbedtls_mpi E; /*!< The public exponent. */ |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 107 | |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 108 | mbedtls_mpi D; /*!< The private exponent. */ |
| 109 | mbedtls_mpi P; /*!< The first prime factor. */ |
| 110 | mbedtls_mpi Q; /*!< The second prime factor. */ |
Hanno Becker | 1a59e79 | 2017-08-23 07:41:10 +0100 | [diff] [blame] | 111 | |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 112 | mbedtls_mpi DP; /*!< <code>D % (P - 1)</code>. */ |
| 113 | mbedtls_mpi DQ; /*!< <code>D % (Q - 1)</code>. */ |
| 114 | mbedtls_mpi QP; /*!< <code>1 / (Q % P)</code>. */ |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 115 | |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 116 | mbedtls_mpi RN; /*!< cached <code>R^2 mod N</code>. */ |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 117 | |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 118 | mbedtls_mpi RP; /*!< cached <code>R^2 mod P</code>. */ |
| 119 | mbedtls_mpi RQ; /*!< cached <code>R^2 mod Q</code>. */ |
Manuel Pégourié-Gonnard | ea53a55 | 2013-09-10 13:29:30 +0200 | [diff] [blame] | 120 | |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 121 | mbedtls_mpi Vi; /*!< The cached blinding value. */ |
| 122 | mbedtls_mpi Vf; /*!< The cached un-blinding value. */ |
Paul Bakker | 9dcc322 | 2011-03-08 14:16:06 +0000 | [diff] [blame] | 123 | |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 124 | int padding; /*!< Selects padding mode: |
| 125 | #MBEDTLS_RSA_PKCS_V15 for 1.5 padding and |
| 126 | #MBEDTLS_RSA_PKCS_V21 for OAEP or PSS. */ |
| 127 | int hash_id; /*!< Hash identifier of mbedtls_md_type_t type, |
| 128 | as specified in md.h for use in the MGF |
| 129 | mask generating function used in the |
| 130 | EME-OAEP and EMSA-PSS encodings. */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 131 | #if defined(MBEDTLS_THREADING_C) |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 132 | mbedtls_threading_mutex_t mutex; /*!< Thread-safety mutex. */ |
Paul Bakker | c9965dc | 2013-09-29 14:58:17 +0200 | [diff] [blame] | 133 | #endif |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 134 | } |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 135 | mbedtls_rsa_context; |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 136 | |
Ron Eldor | 4e6d55d | 2018-02-07 16:36:15 +0200 | [diff] [blame] | 137 | #else /* MBEDTLS_RSA_ALT */ |
| 138 | #include "rsa_alt.h" |
| 139 | #endif /* MBEDTLS_RSA_ALT */ |
| 140 | |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 141 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 142 | * \brief This function initializes an RSA context. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 143 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 144 | * \note Set padding to #MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP |
Paul Bakker | 9a73632 | 2012-11-14 12:39:52 +0000 | [diff] [blame] | 145 | * encryption scheme and the RSASSA-PSS signature scheme. |
| 146 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 147 | * \note The \p hash_id parameter is ignored when using |
| 148 | * #MBEDTLS_RSA_PKCS_V15 padding. |
Manuel Pégourié-Gonnard | e6d1d82 | 2014-06-02 16:47:02 +0200 | [diff] [blame] | 149 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 150 | * \note The choice of padding mode is strictly enforced for private key |
Manuel Pégourié-Gonnard | e6d1d82 | 2014-06-02 16:47:02 +0200 | [diff] [blame] | 151 | * operations, since there might be security concerns in |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 152 | * mixing padding modes. For public key operations it is |
Antonin Décimo | 36e89b5 | 2019-01-23 15:24:37 +0100 | [diff] [blame] | 153 | * a default value, which can be overridden by calling specific |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 154 | * \c rsa_rsaes_xxx or \c rsa_rsassa_xxx functions. |
Manuel Pégourié-Gonnard | e6d1d82 | 2014-06-02 16:47:02 +0200 | [diff] [blame] | 155 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 156 | * \note The hash selected in \p hash_id is always used for OEAP |
| 157 | * encryption. For PSS signatures, it is always used for |
Antonin Décimo | 36e89b5 | 2019-01-23 15:24:37 +0100 | [diff] [blame] | 158 | * making signatures, but can be overridden for verifying them. |
| 159 | * If set to #MBEDTLS_MD_NONE, it is always overridden. |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 160 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 161 | * \param ctx The RSA context to initialize. This must not be \c NULL. |
| 162 | * \param padding The padding mode to use. This must be either |
| 163 | * #MBEDTLS_RSA_PKCS_V15 or #MBEDTLS_RSA_PKCS_V21. |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 164 | * \param hash_id The hash identifier of ::mbedtls_md_type_t type, if |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 165 | * \p padding is #MBEDTLS_RSA_PKCS_V21. It is unused |
| 166 | * otherwise. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 167 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 168 | void mbedtls_rsa_init( mbedtls_rsa_context *ctx, |
Hanno Becker | 8fd5548 | 2017-08-23 14:07:48 +0100 | [diff] [blame] | 169 | int padding, |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 170 | int hash_id ); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 171 | |
| 172 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 173 | * \brief This function imports a set of core parameters into an |
| 174 | * RSA context. |
Manuel Pégourié-Gonnard | 844a4c0 | 2014-03-10 21:55:35 +0100 | [diff] [blame] | 175 | * |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 176 | * \note This function can be called multiple times for successive |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 177 | * imports, if the parameters are not simultaneously present. |
| 178 | * |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 179 | * Any sequence of calls to this function should be followed |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 180 | * by a call to mbedtls_rsa_complete(), which checks and |
| 181 | * completes the provided information to a ready-for-use |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 182 | * public or private RSA key. |
| 183 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 184 | * \note See mbedtls_rsa_complete() for more information on which |
| 185 | * parameters are necessary to set up a private or public |
| 186 | * RSA key. |
Hanno Becker | 3319555 | 2017-10-25 17:04:10 +0100 | [diff] [blame] | 187 | * |
Hanno Becker | 5178dca | 2017-10-03 14:29:37 +0100 | [diff] [blame] | 188 | * \note The imported parameters are copied and need not be preserved |
| 189 | * for the lifetime of the RSA context being set up. |
| 190 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 191 | * \param ctx The initialized RSA context to store the parameters in. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 192 | * \param N The RSA modulus. This may be \c NULL. |
| 193 | * \param P The first prime factor of \p N. This may be \c NULL. |
| 194 | * \param Q The second prime factor of \p N. This may be \c NULL. |
| 195 | * \param D The private exponent. This may be \c NULL. |
| 196 | * \param E The public exponent. This may be \c NULL. |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 197 | * |
| 198 | * \return \c 0 on success. |
| 199 | * \return A non-zero error code on failure. |
Manuel Pégourié-Gonnard | 844a4c0 | 2014-03-10 21:55:35 +0100 | [diff] [blame] | 200 | */ |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 201 | int mbedtls_rsa_import( mbedtls_rsa_context *ctx, |
| 202 | const mbedtls_mpi *N, |
| 203 | const mbedtls_mpi *P, const mbedtls_mpi *Q, |
| 204 | const mbedtls_mpi *D, const mbedtls_mpi *E ); |
Manuel Pégourié-Gonnard | 844a4c0 | 2014-03-10 21:55:35 +0100 | [diff] [blame] | 205 | |
| 206 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 207 | * \brief This function imports core RSA parameters, in raw big-endian |
| 208 | * binary format, into an RSA context. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 209 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 210 | * \note This function can be called multiple times for successive |
| 211 | * imports, if the parameters are not simultaneously present. |
| 212 | * |
| 213 | * Any sequence of calls to this function should be followed |
| 214 | * by a call to mbedtls_rsa_complete(), which checks and |
| 215 | * completes the provided information to a ready-for-use |
| 216 | * public or private RSA key. |
| 217 | * |
| 218 | * \note See mbedtls_rsa_complete() for more information on which |
| 219 | * parameters are necessary to set up a private or public |
| 220 | * RSA key. |
| 221 | * |
| 222 | * \note The imported parameters are copied and need not be preserved |
| 223 | * for the lifetime of the RSA context being set up. |
| 224 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 225 | * \param ctx The initialized RSA context to store the parameters in. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 226 | * \param N The RSA modulus. This may be \c NULL. |
| 227 | * \param N_len The Byte length of \p N; it is ignored if \p N == NULL. |
| 228 | * \param P The first prime factor of \p N. This may be \c NULL. |
| 229 | * \param P_len The Byte length of \p P; it ns ignored if \p P == NULL. |
| 230 | * \param Q The second prime factor of \p N. This may be \c NULL. |
| 231 | * \param Q_len The Byte length of \p Q; it is ignored if \p Q == NULL. |
| 232 | * \param D The private exponent. This may be \c NULL. |
| 233 | * \param D_len The Byte length of \p D; it is ignored if \p D == NULL. |
| 234 | * \param E The public exponent. This may be \c NULL. |
| 235 | * \param E_len The Byte length of \p E; it is ignored if \p E == NULL. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 236 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 237 | * \return \c 0 on success. |
| 238 | * \return A non-zero error code on failure. |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 239 | */ |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 240 | int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx, |
Hanno Becker | 7471631 | 2017-10-02 10:00:37 +0100 | [diff] [blame] | 241 | unsigned char const *N, size_t N_len, |
| 242 | unsigned char const *P, size_t P_len, |
| 243 | unsigned char const *Q, size_t Q_len, |
| 244 | unsigned char const *D, size_t D_len, |
| 245 | unsigned char const *E, size_t E_len ); |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 246 | |
| 247 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 248 | * \brief This function completes an RSA context from |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 249 | * a set of imported core parameters. |
| 250 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 251 | * To setup an RSA public key, precisely \p N and \p E |
| 252 | * must have been imported. |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 253 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 254 | * To setup an RSA private key, sufficient information must |
| 255 | * be present for the other parameters to be derivable. |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 256 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 257 | * The default implementation supports the following: |
| 258 | * <ul><li>Derive \p P, \p Q from \p N, \p D, \p E.</li> |
| 259 | * <li>Derive \p N, \p D from \p P, \p Q, \p E.</li></ul> |
| 260 | * Alternative implementations need not support these. |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 261 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 262 | * If this function runs successfully, it guarantees that |
| 263 | * the RSA context can be used for RSA operations without |
| 264 | * the risk of failure or crash. |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 265 | * |
Hanno Becker | 1e801f5 | 2017-10-10 16:44:47 +0100 | [diff] [blame] | 266 | * \warning This function need not perform consistency checks |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 267 | * for the imported parameters. In particular, parameters that |
| 268 | * are not needed by the implementation might be silently |
| 269 | * discarded and left unchecked. To check the consistency |
| 270 | * of the key material, see mbedtls_rsa_check_privkey(). |
Hanno Becker | 43a08d0 | 2017-10-02 13:16:35 +0100 | [diff] [blame] | 271 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 272 | * \param ctx The initialized RSA context holding imported parameters. |
| 273 | * |
| 274 | * \return \c 0 on success. |
| 275 | * \return #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted derivations |
| 276 | * failed. |
| 277 | * |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 278 | */ |
Hanno Becker | f9e184b | 2017-10-10 16:49:26 +0100 | [diff] [blame] | 279 | int mbedtls_rsa_complete( mbedtls_rsa_context *ctx ); |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 280 | |
| 281 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 282 | * \brief This function exports the core parameters of an RSA key. |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 283 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 284 | * If this function runs successfully, the non-NULL buffers |
| 285 | * pointed to by \p N, \p P, \p Q, \p D, and \p E are fully |
| 286 | * written, with additional unused space filled leading by |
| 287 | * zero Bytes. |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 288 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 289 | * Possible reasons for returning |
Ron Eldor | 9924bdc | 2018-10-04 10:59:13 +0300 | [diff] [blame] | 290 | * #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED:<ul> |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 291 | * <li>An alternative RSA implementation is in use, which |
| 292 | * stores the key externally, and either cannot or should |
| 293 | * not export it into RAM.</li> |
| 294 | * <li>A SW or HW implementation might not support a certain |
| 295 | * deduction. For example, \p P, \p Q from \p N, \p D, |
| 296 | * and \p E if the former are not part of the |
| 297 | * implementation.</li></ul> |
Hanno Becker | 91c194d | 2017-09-29 12:50:12 +0100 | [diff] [blame] | 298 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 299 | * If the function fails due to an unsupported operation, |
| 300 | * the RSA context stays intact and remains usable. |
| 301 | * |
| 302 | * \param ctx The initialized RSA context. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 303 | * \param N The MPI to hold the RSA modulus. |
| 304 | * This may be \c NULL if this field need not be exported. |
| 305 | * \param P The MPI to hold the first prime factor of \p N. |
| 306 | * This may be \c NULL if this field need not be exported. |
| 307 | * \param Q The MPI to hold the second prime factor of \p N. |
| 308 | * This may be \c NULL if this field need not be exported. |
| 309 | * \param D The MPI to hold the private exponent. |
| 310 | * This may be \c NULL if this field need not be exported. |
| 311 | * \param E The MPI to hold the public exponent. |
| 312 | * This may be \c NULL if this field need not be exported. |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 313 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 314 | * \return \c 0 on success. |
Ron Eldor | 9924bdc | 2018-10-04 10:59:13 +0300 | [diff] [blame] | 315 | * \return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED if exporting the |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 316 | * requested parameters cannot be done due to missing |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 317 | * functionality or because of security policies. |
| 318 | * \return A non-zero return code on any other failure. |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 319 | * |
| 320 | */ |
| 321 | int mbedtls_rsa_export( const mbedtls_rsa_context *ctx, |
| 322 | mbedtls_mpi *N, mbedtls_mpi *P, mbedtls_mpi *Q, |
| 323 | mbedtls_mpi *D, mbedtls_mpi *E ); |
| 324 | |
| 325 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 326 | * \brief This function exports core parameters of an RSA key |
| 327 | * in raw big-endian binary format. |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 328 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 329 | * If this function runs successfully, the non-NULL buffers |
| 330 | * pointed to by \p N, \p P, \p Q, \p D, and \p E are fully |
| 331 | * written, with additional unused space filled leading by |
| 332 | * zero Bytes. |
| 333 | * |
| 334 | * Possible reasons for returning |
Ron Eldor | 9924bdc | 2018-10-04 10:59:13 +0300 | [diff] [blame] | 335 | * #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED:<ul> |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 336 | * <li>An alternative RSA implementation is in use, which |
| 337 | * stores the key externally, and either cannot or should |
| 338 | * not export it into RAM.</li> |
| 339 | * <li>A SW or HW implementation might not support a certain |
| 340 | * deduction. For example, \p P, \p Q from \p N, \p D, |
| 341 | * and \p E if the former are not part of the |
| 342 | * implementation.</li></ul> |
| 343 | * If the function fails due to an unsupported operation, |
| 344 | * the RSA context stays intact and remains usable. |
| 345 | * |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 346 | * \note The length parameters are ignored if the corresponding |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 347 | * buffer pointers are NULL. |
| 348 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 349 | * \param ctx The initialized RSA context. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 350 | * \param N The Byte array to store the RSA modulus, |
| 351 | * or \c NULL if this field need not be exported. |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 352 | * \param N_len The size of the buffer for the modulus. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 353 | * \param P The Byte array to hold the first prime factor of \p N, |
| 354 | * or \c NULL if this field need not be exported. |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 355 | * \param P_len The size of the buffer for the first prime factor. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 356 | * \param Q The Byte array to hold the second prime factor of \p N, |
| 357 | * or \c NULL if this field need not be exported. |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 358 | * \param Q_len The size of the buffer for the second prime factor. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 359 | * \param D The Byte array to hold the private exponent, |
| 360 | * or \c NULL if this field need not be exported. |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 361 | * \param D_len The size of the buffer for the private exponent. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 362 | * \param E The Byte array to hold the public exponent, |
| 363 | * or \c NULL if this field need not be exported. |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 364 | * \param E_len The size of the buffer for the public exponent. |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 365 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 366 | * \return \c 0 on success. |
Ron Eldor | 9924bdc | 2018-10-04 10:59:13 +0300 | [diff] [blame] | 367 | * \return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED if exporting the |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 368 | * requested parameters cannot be done due to missing |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 369 | * functionality or because of security policies. |
| 370 | * \return A non-zero return code on any other failure. |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 371 | */ |
| 372 | int mbedtls_rsa_export_raw( const mbedtls_rsa_context *ctx, |
| 373 | unsigned char *N, size_t N_len, |
| 374 | unsigned char *P, size_t P_len, |
| 375 | unsigned char *Q, size_t Q_len, |
| 376 | unsigned char *D, size_t D_len, |
| 377 | unsigned char *E, size_t E_len ); |
| 378 | |
| 379 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 380 | * \brief This function exports CRT parameters of a private RSA key. |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 381 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 382 | * \note Alternative RSA implementations not using CRT-parameters |
| 383 | * internally can implement this function based on |
| 384 | * mbedtls_rsa_deduce_opt(). |
| 385 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 386 | * \param ctx The initialized RSA context. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 387 | * \param DP The MPI to hold \c D modulo `P-1`, |
| 388 | * or \c NULL if it need not be exported. |
| 389 | * \param DQ The MPI to hold \c D modulo `Q-1`, |
| 390 | * or \c NULL if it need not be exported. |
| 391 | * \param QP The MPI to hold modular inverse of \c Q modulo \c P, |
| 392 | * or \c NULL if it need not be exported. |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 393 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 394 | * \return \c 0 on success. |
| 395 | * \return A non-zero error code on failure. |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 396 | * |
| 397 | */ |
| 398 | int mbedtls_rsa_export_crt( const mbedtls_rsa_context *ctx, |
| 399 | mbedtls_mpi *DP, mbedtls_mpi *DQ, mbedtls_mpi *QP ); |
| 400 | |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 401 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 402 | * \brief This function sets padding for an already initialized RSA |
| 403 | * context. See mbedtls_rsa_init() for details. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 404 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 405 | * \param ctx The initialized RSA context to be configured. |
| 406 | * \param padding The padding mode to use. This must be either |
| 407 | * #MBEDTLS_RSA_PKCS_V15 or #MBEDTLS_RSA_PKCS_V21. |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 408 | * \param hash_id The #MBEDTLS_RSA_PKCS_V21 hash identifier. |
Paul Bakker | 40e4694 | 2009-01-03 21:51:57 +0000 | [diff] [blame] | 409 | */ |
Hanno Becker | 8fd5548 | 2017-08-23 14:07:48 +0100 | [diff] [blame] | 410 | void mbedtls_rsa_set_padding( mbedtls_rsa_context *ctx, int padding, |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 411 | int hash_id ); |
Paul Bakker | 21eb280 | 2010-08-16 11:10:02 +0000 | [diff] [blame] | 412 | |
Paul Bakker | a3d195c | 2011-11-27 21:07:34 +0000 | [diff] [blame] | 413 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 414 | * \brief This function retrieves the length of RSA modulus in Bytes. |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 415 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 416 | * \param ctx The initialized RSA context. |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 417 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 418 | * \return The length of the RSA modulus in Bytes. |
Hanno Becker | cbb59bc | 2017-08-23 14:11:08 +0100 | [diff] [blame] | 419 | * |
| 420 | */ |
| 421 | size_t mbedtls_rsa_get_len( const mbedtls_rsa_context *ctx ); |
| 422 | |
| 423 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 424 | * \brief This function generates an RSA keypair. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 425 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 426 | * \note mbedtls_rsa_init() must be called before this function, |
| 427 | * to set up the RSA context. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 428 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 429 | * \param ctx The initialized RSA context used to hold the key. |
| 430 | * \param f_rng The RNG function to be used for key generation. |
| 431 | * This must not be \c NULL. |
| 432 | * \param p_rng The RNG context to be passed to \p f_rng. |
| 433 | * This may be \c NULL if \p f_rng doesn't need a context. |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 434 | * \param nbits The size of the public key in bits. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 435 | * \param exponent The public exponent to use. For example, \c 65537. |
Hanno Becker | f66f294 | 2018-12-18 13:30:08 +0000 | [diff] [blame] | 436 | * This must be odd and greater than \c 1. |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 437 | * |
| 438 | * \return \c 0 on success. |
| 439 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 440 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 441 | int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx, |
Hanno Becker | 8fd5548 | 2017-08-23 14:07:48 +0100 | [diff] [blame] | 442 | int (*f_rng)(void *, unsigned char *, size_t), |
| 443 | void *p_rng, |
| 444 | unsigned int nbits, int exponent ); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 445 | |
| 446 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 447 | * \brief This function checks if a context contains at least an RSA |
| 448 | * public key. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 449 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 450 | * If the function runs successfully, it is guaranteed that |
| 451 | * enough information is present to perform an RSA public key |
| 452 | * operation using mbedtls_rsa_public(). |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 453 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 454 | * \param ctx The initialized RSA context to check. |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 455 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 456 | * \return \c 0 on success. |
| 457 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. |
Hanno Becker | 43a08d0 | 2017-10-02 13:16:35 +0100 | [diff] [blame] | 458 | * |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 459 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 460 | int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx ); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 461 | |
| 462 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 463 | * \brief This function checks if a context contains an RSA private key |
Hanno Becker | 1e801f5 | 2017-10-10 16:44:47 +0100 | [diff] [blame] | 464 | * and perform basic consistency checks. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 465 | * |
Hanno Becker | 68767a6 | 2017-10-17 10:13:31 +0100 | [diff] [blame] | 466 | * \note The consistency checks performed by this function not only |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 467 | * ensure that mbedtls_rsa_private() can be called successfully |
Hanno Becker | 68767a6 | 2017-10-17 10:13:31 +0100 | [diff] [blame] | 468 | * on the given context, but that the various parameters are |
| 469 | * mutually consistent with high probability, in the sense that |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 470 | * mbedtls_rsa_public() and mbedtls_rsa_private() are inverses. |
Hanno Becker | 1e801f5 | 2017-10-10 16:44:47 +0100 | [diff] [blame] | 471 | * |
| 472 | * \warning This function should catch accidental misconfigurations |
| 473 | * like swapping of parameters, but it cannot establish full |
| 474 | * trust in neither the quality nor the consistency of the key |
| 475 | * material that was used to setup the given RSA context: |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 476 | * <ul><li>Consistency: Imported parameters that are irrelevant |
| 477 | * for the implementation might be silently dropped. If dropped, |
| 478 | * the current function does not have access to them, |
| 479 | * and therefore cannot check them. See mbedtls_rsa_complete(). |
| 480 | * If you want to check the consistency of the entire |
| 481 | * content of an PKCS1-encoded RSA private key, for example, you |
| 482 | * should use mbedtls_rsa_validate_params() before setting |
| 483 | * up the RSA context. |
| 484 | * Additionally, if the implementation performs empirical checks, |
| 485 | * these checks substantiate but do not guarantee consistency.</li> |
| 486 | * <li>Quality: This function is not expected to perform |
| 487 | * extended quality assessments like checking that the prime |
| 488 | * factors are safe. Additionally, it is the responsibility of the |
| 489 | * user to ensure the trustworthiness of the source of his RSA |
| 490 | * parameters, which goes beyond what is effectively checkable |
| 491 | * by the library.</li></ul> |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 492 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 493 | * \param ctx The initialized RSA context to check. |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 494 | * |
| 495 | * \return \c 0 on success. |
| 496 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 497 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 498 | int mbedtls_rsa_check_privkey( const mbedtls_rsa_context *ctx ); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 499 | |
| 500 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 501 | * \brief This function checks a public-private RSA key pair. |
Manuel Pégourié-Gonnard | 2f8d1f9 | 2014-11-06 14:02:51 +0100 | [diff] [blame] | 502 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 503 | * It checks each of the contexts, and makes sure they match. |
Manuel Pégourié-Gonnard | 2f8d1f9 | 2014-11-06 14:02:51 +0100 | [diff] [blame] | 504 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 505 | * \param pub The initialized RSA context holding the public key. |
| 506 | * \param prv The initialized RSA context holding the private key. |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 507 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 508 | * \return \c 0 on success. |
| 509 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. |
Manuel Pégourié-Gonnard | 2f8d1f9 | 2014-11-06 14:02:51 +0100 | [diff] [blame] | 510 | */ |
Hanno Becker | 98838b0 | 2017-10-02 13:16:10 +0100 | [diff] [blame] | 511 | int mbedtls_rsa_check_pub_priv( const mbedtls_rsa_context *pub, |
| 512 | const mbedtls_rsa_context *prv ); |
Manuel Pégourié-Gonnard | 2f8d1f9 | 2014-11-06 14:02:51 +0100 | [diff] [blame] | 513 | |
| 514 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 515 | * \brief This function performs an RSA public key operation. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 516 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 517 | * \param ctx The initialized RSA context to use. |
| 518 | * \param input The input buffer. This must be a readable buffer |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 519 | * of length \c ctx->len Bytes. For example, \c 256 Bytes |
| 520 | * for an 2048-bit RSA modulus. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 521 | * \param output The output buffer. This must be a writable buffer |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 522 | * of length \c ctx->len Bytes. For example, \c 256 Bytes |
| 523 | * for an 2048-bit RSA modulus. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 524 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 525 | * \note This function does not handle message padding. |
| 526 | * |
| 527 | * \note Make sure to set \p input[0] = 0 or ensure that |
| 528 | * input is smaller than \p N. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 529 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 530 | * \return \c 0 on success. |
| 531 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 532 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 533 | int mbedtls_rsa_public( mbedtls_rsa_context *ctx, |
Paul Bakker | ff60ee6 | 2010-03-16 21:09:09 +0000 | [diff] [blame] | 534 | const unsigned char *input, |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 535 | unsigned char *output ); |
| 536 | |
| 537 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 538 | * \brief This function performs an RSA private key operation. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 539 | * |
Hanno Becker | 2412061 | 2017-10-26 11:53:35 +0100 | [diff] [blame] | 540 | * \note Blinding is used if and only if a PRNG is provided. |
Hanno Becker | 88ec238 | 2017-05-03 13:51:16 +0100 | [diff] [blame] | 541 | * |
| 542 | * \note If blinding is used, both the base of exponentation |
Hanno Becker | 2412061 | 2017-10-26 11:53:35 +0100 | [diff] [blame] | 543 | * and the exponent are blinded, providing protection |
| 544 | * against some side-channel attacks. |
Hanno Becker | 88ec238 | 2017-05-03 13:51:16 +0100 | [diff] [blame] | 545 | * |
Hanno Becker | 4e1be39 | 2017-10-02 15:56:48 +0100 | [diff] [blame] | 546 | * \warning It is deprecated and a security risk to not provide |
| 547 | * a PRNG here and thereby prevent the use of blinding. |
| 548 | * Future versions of the library may enforce the presence |
| 549 | * of a PRNG. |
Hanno Becker | 88ec238 | 2017-05-03 13:51:16 +0100 | [diff] [blame] | 550 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 551 | * \param ctx The initialized RSA context to use. |
| 552 | * \param f_rng The RNG function, used for blinding. It is discouraged |
| 553 | * and deprecated to pass \c NULL here, in which case |
| 554 | * blinding will be omitted. |
| 555 | * \param p_rng The RNG context to pass to \p f_rng. This may be \c NULL |
| 556 | * if \p f_rng is \c NULL or if \p f_rng doesn't need a context. |
| 557 | * \param input The input buffer. This must be a readable buffer |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 558 | * of length \c ctx->len Bytes. For example, \c 256 Bytes |
| 559 | * for an 2048-bit RSA modulus. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 560 | * \param output The output buffer. This must be a writable buffer |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 561 | * of length \c ctx->len Bytes. For example, \c 256 Bytes |
| 562 | * for an 2048-bit RSA modulus. |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 563 | * |
| 564 | * \return \c 0 on success. |
| 565 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. |
| 566 | * |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 567 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 568 | int mbedtls_rsa_private( mbedtls_rsa_context *ctx, |
Paul Bakker | 548957d | 2013-08-30 10:30:02 +0200 | [diff] [blame] | 569 | int (*f_rng)(void *, unsigned char *, size_t), |
| 570 | void *p_rng, |
Paul Bakker | ff60ee6 | 2010-03-16 21:09:09 +0000 | [diff] [blame] | 571 | const unsigned char *input, |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 572 | unsigned char *output ); |
| 573 | |
| 574 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 575 | * \brief This function adds the message padding, then performs an RSA |
| 576 | * operation. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 577 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 578 | * It is the generic wrapper for performing a PKCS#1 encryption |
| 579 | * operation using the \p mode from the context. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 580 | * |
Hanno Becker | 3cdc711 | 2017-10-05 10:09:31 +0100 | [diff] [blame] | 581 | * \deprecated It is deprecated and discouraged to call this function |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 582 | * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library |
| 583 | * are likely to remove the \p mode argument and have it |
| 584 | * implicitly set to #MBEDTLS_RSA_PUBLIC. |
Hanno Becker | 3cdc711 | 2017-10-05 10:09:31 +0100 | [diff] [blame] | 585 | * |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 586 | * \note Alternative implementations of RSA need not support |
| 587 | * mode being set to #MBEDTLS_RSA_PRIVATE and might instead |
Ron Eldor | 9924bdc | 2018-10-04 10:59:13 +0300 | [diff] [blame] | 588 | * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 589 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 590 | * \param ctx The initialized RSA context to use. |
Hanno Becker | 974ca0d | 2018-12-18 18:03:24 +0000 | [diff] [blame] | 591 | * \param f_rng The RNG to use. It is mandatory for PKCS#1 v2.1 padding |
| 592 | * encoding, and for PKCS#1 v1.5 padding encoding when used |
| 593 | * with \p mode set to #MBEDTLS_RSA_PUBLIC. For PKCS#1 v1.5 |
| 594 | * padding encoding and \p mode set to #MBEDTLS_RSA_PRIVATE, |
| 595 | * it is used for blinding and should be provided in this |
| 596 | * case; see mbedtls_rsa_private() for more. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 597 | * \param p_rng The RNG context to be passed to \p f_rng. May be |
| 598 | * \c NULL if \p f_rng is \c NULL or if \p f_rng doesn't |
| 599 | * need a context argument. |
| 600 | * \param mode The mode of operation. This must be either |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 601 | * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated). |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 602 | * \param ilen The length of the plaintext in Bytes. |
| 603 | * \param input The input data to encrypt. This must be a readable |
Jaeden Amero | fb23673 | 2019-02-08 13:11:59 +0000 | [diff] [blame] | 604 | * buffer of size \p ilen Bytes. It may be \c NULL if |
| 605 | * `ilen == 0`. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 606 | * \param output The output buffer. This must be a writable buffer |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 607 | * of length \c ctx->len Bytes. For example, \c 256 Bytes |
| 608 | * for an 2048-bit RSA modulus. |
Hanno Becker | 3cdc711 | 2017-10-05 10:09:31 +0100 | [diff] [blame] | 609 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 610 | * \return \c 0 on success. |
| 611 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 612 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 613 | int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx, |
Paul Bakker | a3d195c | 2011-11-27 21:07:34 +0000 | [diff] [blame] | 614 | int (*f_rng)(void *, unsigned char *, size_t), |
Paul Bakker | 21eb280 | 2010-08-16 11:10:02 +0000 | [diff] [blame] | 615 | void *p_rng, |
Paul Bakker | 23986e5 | 2011-04-24 08:57:21 +0000 | [diff] [blame] | 616 | int mode, size_t ilen, |
Paul Bakker | ff60ee6 | 2010-03-16 21:09:09 +0000 | [diff] [blame] | 617 | const unsigned char *input, |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 618 | unsigned char *output ); |
| 619 | |
| 620 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 621 | * \brief This function performs a PKCS#1 v1.5 encryption operation |
| 622 | * (RSAES-PKCS1-v1_5-ENCRYPT). |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 623 | * |
Hanno Becker | 3cdc711 | 2017-10-05 10:09:31 +0100 | [diff] [blame] | 624 | * \deprecated It is deprecated and discouraged to call this function |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 625 | * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library |
| 626 | * are likely to remove the \p mode argument and have it |
| 627 | * implicitly set to #MBEDTLS_RSA_PUBLIC. |
Hanno Becker | 3cdc711 | 2017-10-05 10:09:31 +0100 | [diff] [blame] | 628 | * |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 629 | * \note Alternative implementations of RSA need not support |
| 630 | * mode being set to #MBEDTLS_RSA_PRIVATE and might instead |
Ron Eldor | 9924bdc | 2018-10-04 10:59:13 +0300 | [diff] [blame] | 631 | * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 632 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 633 | * \param ctx The initialized RSA context to use. |
Hanno Becker | a9020f2 | 2018-12-18 14:45:45 +0000 | [diff] [blame] | 634 | * \param f_rng The RNG function to use. It is needed for padding generation |
| 635 | * if \p mode is #MBEDTLS_RSA_PUBLIC. If \p mode is |
| 636 | * #MBEDTLS_RSA_PRIVATE (discouraged), it is used for |
| 637 | * blinding and should be provided; see mbedtls_rsa_private(). |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 638 | * \param p_rng The RNG context to be passed to \p f_rng. This may |
| 639 | * be \c NULL if \p f_rng is \c NULL or if \p f_rng |
| 640 | * doesn't need a context argument. |
| 641 | * \param mode The mode of operation. This must be either |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 642 | * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated). |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 643 | * \param ilen The length of the plaintext in Bytes. |
| 644 | * \param input The input data to encrypt. This must be a readable |
Jaeden Amero | fb23673 | 2019-02-08 13:11:59 +0000 | [diff] [blame] | 645 | * buffer of size \p ilen Bytes. It may be \c NULL if |
| 646 | * `ilen == 0`. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 647 | * \param output The output buffer. This must be a writable buffer |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 648 | * of length \c ctx->len Bytes. For example, \c 256 Bytes |
| 649 | * for an 2048-bit RSA modulus. |
Hanno Becker | 3cdc711 | 2017-10-05 10:09:31 +0100 | [diff] [blame] | 650 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 651 | * \return \c 0 on success. |
| 652 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 653 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 654 | int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx, |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 655 | int (*f_rng)(void *, unsigned char *, size_t), |
| 656 | void *p_rng, |
| 657 | int mode, size_t ilen, |
| 658 | const unsigned char *input, |
| 659 | unsigned char *output ); |
| 660 | |
| 661 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 662 | * \brief This function performs a PKCS#1 v2.1 OAEP encryption |
| 663 | * operation (RSAES-OAEP-ENCRYPT). |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 664 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 665 | * \note The output buffer must be as large as the size |
| 666 | * of ctx->N. For example, 128 Bytes if RSA-1024 is used. |
| 667 | * |
| 668 | * \deprecated It is deprecated and discouraged to call this function |
| 669 | * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library |
| 670 | * are likely to remove the \p mode argument and have it |
| 671 | * implicitly set to #MBEDTLS_RSA_PUBLIC. |
| 672 | * |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 673 | * \note Alternative implementations of RSA need not support |
| 674 | * mode being set to #MBEDTLS_RSA_PRIVATE and might instead |
Ron Eldor | 9924bdc | 2018-10-04 10:59:13 +0300 | [diff] [blame] | 675 | * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 676 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 677 | * \param ctx The initnialized RSA context to use. |
Hanno Becker | a9020f2 | 2018-12-18 14:45:45 +0000 | [diff] [blame] | 678 | * \param f_rng The RNG function to use. This is needed for padding |
| 679 | * generation and must be provided. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 680 | * \param p_rng The RNG context to be passed to \p f_rng. This may |
Hanno Becker | a9020f2 | 2018-12-18 14:45:45 +0000 | [diff] [blame] | 681 | * be \c NULL if \p f_rng doesn't need a context argument. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 682 | * \param mode The mode of operation. This must be either |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 683 | * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated). |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 684 | * \param label The buffer holding the custom label to use. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 685 | * This must be a readable buffer of length \p label_len |
| 686 | * Bytes. It may be \c NULL if \p label_len is \c 0. |
| 687 | * \param label_len The length of the label in Bytes. |
| 688 | * \param ilen The length of the plaintext buffer \p input in Bytes. |
| 689 | * \param input The input data to encrypt. This must be a readable |
Jaeden Amero | fb23673 | 2019-02-08 13:11:59 +0000 | [diff] [blame] | 690 | * buffer of size \p ilen Bytes. It may be \c NULL if |
| 691 | * `ilen == 0`. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 692 | * \param output The output buffer. This must be a writable buffer |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 693 | * of length \c ctx->len Bytes. For example, \c 256 Bytes |
| 694 | * for an 2048-bit RSA modulus. |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 695 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 696 | * \return \c 0 on success. |
| 697 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 698 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 699 | int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx, |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 700 | int (*f_rng)(void *, unsigned char *, size_t), |
| 701 | void *p_rng, |
Paul Bakker | a43231c | 2013-02-28 17:33:49 +0100 | [diff] [blame] | 702 | int mode, |
| 703 | const unsigned char *label, size_t label_len, |
| 704 | size_t ilen, |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 705 | const unsigned char *input, |
| 706 | unsigned char *output ); |
| 707 | |
| 708 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 709 | * \brief This function performs an RSA operation, then removes the |
| 710 | * message padding. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 711 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 712 | * It is the generic wrapper for performing a PKCS#1 decryption |
| 713 | * operation using the \p mode from the context. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 714 | * |
Hanno Becker | 248ae6d | 2017-05-04 11:27:39 +0100 | [diff] [blame] | 715 | * \note The output buffer length \c output_max_len should be |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 716 | * as large as the size \p ctx->len of \p ctx->N (for example, |
| 717 | * 128 Bytes if RSA-1024 is used) to be able to hold an |
| 718 | * arbitrary decrypted message. If it is not large enough to |
| 719 | * hold the decryption of the particular ciphertext provided, |
| 720 | * the function returns \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. |
Hanno Becker | 248ae6d | 2017-05-04 11:27:39 +0100 | [diff] [blame] | 721 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 722 | * \deprecated It is deprecated and discouraged to call this function |
| 723 | * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library |
| 724 | * are likely to remove the \p mode argument and have it |
| 725 | * implicitly set to #MBEDTLS_RSA_PRIVATE. |
| 726 | * |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 727 | * \note Alternative implementations of RSA need not support |
| 728 | * mode being set to #MBEDTLS_RSA_PUBLIC and might instead |
Ron Eldor | 9924bdc | 2018-10-04 10:59:13 +0300 | [diff] [blame] | 729 | * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 730 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 731 | * \param ctx The initialized RSA context to use. |
Hanno Becker | 5bdfca9 | 2018-12-18 13:59:28 +0000 | [diff] [blame] | 732 | * \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE, |
| 733 | * this is used for blinding and should be provided; see |
| 734 | * mbedtls_rsa_private() for more. If \p mode is |
| 735 | * #MBEDTLS_RSA_PUBLIC, it is ignored. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 736 | * \param p_rng The RNG context to be passed to \p f_rng. This may be |
| 737 | * \c NULL if \p f_rng is \c NULL or doesn't need a context. |
| 738 | * \param mode The mode of operation. This must be either |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 739 | * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated). |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 740 | * \param olen The address at which to store the length of |
| 741 | * the plaintext. This must not be \c NULL. |
| 742 | * \param input The ciphertext buffer. This must be a readable buffer |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 743 | * of length \c ctx->len Bytes. For example, \c 256 Bytes |
| 744 | * for an 2048-bit RSA modulus. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 745 | * \param output The buffer used to hold the plaintext. This must |
| 746 | * be a writable buffer of length \p output_max_len Bytes. |
Hanno Becker | f66f294 | 2018-12-18 13:30:08 +0000 | [diff] [blame] | 747 | * \param output_max_len The length in Bytes of the output buffer \p output. |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 748 | * |
| 749 | * \return \c 0 on success. |
| 750 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 751 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 752 | int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx, |
Paul Bakker | 548957d | 2013-08-30 10:30:02 +0200 | [diff] [blame] | 753 | int (*f_rng)(void *, unsigned char *, size_t), |
| 754 | void *p_rng, |
Paul Bakker | 23986e5 | 2011-04-24 08:57:21 +0000 | [diff] [blame] | 755 | int mode, size_t *olen, |
Paul Bakker | ff60ee6 | 2010-03-16 21:09:09 +0000 | [diff] [blame] | 756 | const unsigned char *input, |
Paul Bakker | 060c568 | 2009-01-12 21:48:39 +0000 | [diff] [blame] | 757 | unsigned char *output, |
Paul Bakker | 23986e5 | 2011-04-24 08:57:21 +0000 | [diff] [blame] | 758 | size_t output_max_len ); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 759 | |
| 760 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 761 | * \brief This function performs a PKCS#1 v1.5 decryption |
| 762 | * operation (RSAES-PKCS1-v1_5-DECRYPT). |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 763 | * |
Hanno Becker | 248ae6d | 2017-05-04 11:27:39 +0100 | [diff] [blame] | 764 | * \note The output buffer length \c output_max_len should be |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 765 | * as large as the size \p ctx->len of \p ctx->N, for example, |
| 766 | * 128 Bytes if RSA-1024 is used, to be able to hold an |
| 767 | * arbitrary decrypted message. If it is not large enough to |
| 768 | * hold the decryption of the particular ciphertext provided, |
| 769 | * the function returns #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. |
Hanno Becker | 248ae6d | 2017-05-04 11:27:39 +0100 | [diff] [blame] | 770 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 771 | * \deprecated It is deprecated and discouraged to call this function |
| 772 | * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library |
| 773 | * are likely to remove the \p mode argument and have it |
| 774 | * implicitly set to #MBEDTLS_RSA_PRIVATE. |
| 775 | * |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 776 | * \note Alternative implementations of RSA need not support |
| 777 | * mode being set to #MBEDTLS_RSA_PUBLIC and might instead |
Ron Eldor | 9924bdc | 2018-10-04 10:59:13 +0300 | [diff] [blame] | 778 | * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 779 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 780 | * \param ctx The initialized RSA context to use. |
Hanno Becker | 5bdfca9 | 2018-12-18 13:59:28 +0000 | [diff] [blame] | 781 | * \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE, |
| 782 | * this is used for blinding and should be provided; see |
| 783 | * mbedtls_rsa_private() for more. If \p mode is |
| 784 | * #MBEDTLS_RSA_PUBLIC, it is ignored. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 785 | * \param p_rng The RNG context to be passed to \p f_rng. This may be |
| 786 | * \c NULL if \p f_rng is \c NULL or doesn't need a context. |
| 787 | * \param mode The mode of operation. This must be either |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 788 | * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated). |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 789 | * \param olen The address at which to store the length of |
| 790 | * the plaintext. This must not be \c NULL. |
| 791 | * \param input The ciphertext buffer. This must be a readable buffer |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 792 | * of length \c ctx->len Bytes. For example, \c 256 Bytes |
| 793 | * for an 2048-bit RSA modulus. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 794 | * \param output The buffer used to hold the plaintext. This must |
| 795 | * be a writable buffer of length \p output_max_len Bytes. |
Hanno Becker | f66f294 | 2018-12-18 13:30:08 +0000 | [diff] [blame] | 796 | * \param output_max_len The length in Bytes of the output buffer \p output. |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 797 | * |
| 798 | * \return \c 0 on success. |
| 799 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. |
| 800 | * |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 801 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 802 | int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx, |
Paul Bakker | 548957d | 2013-08-30 10:30:02 +0200 | [diff] [blame] | 803 | int (*f_rng)(void *, unsigned char *, size_t), |
| 804 | void *p_rng, |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 805 | int mode, size_t *olen, |
| 806 | const unsigned char *input, |
| 807 | unsigned char *output, |
| 808 | size_t output_max_len ); |
| 809 | |
| 810 | /** |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 811 | * \brief This function performs a PKCS#1 v2.1 OAEP decryption |
| 812 | * operation (RSAES-OAEP-DECRYPT). |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 813 | * |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 814 | * \note The output buffer length \c output_max_len should be |
| 815 | * as large as the size \p ctx->len of \p ctx->N, for |
| 816 | * example, 128 Bytes if RSA-1024 is used, to be able to |
| 817 | * hold an arbitrary decrypted message. If it is not |
| 818 | * large enough to hold the decryption of the particular |
| 819 | * ciphertext provided, the function returns |
| 820 | * #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 821 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 822 | * \deprecated It is deprecated and discouraged to call this function |
| 823 | * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library |
| 824 | * are likely to remove the \p mode argument and have it |
| 825 | * implicitly set to #MBEDTLS_RSA_PRIVATE. |
| 826 | * |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 827 | * \note Alternative implementations of RSA need not support |
| 828 | * mode being set to #MBEDTLS_RSA_PUBLIC and might instead |
Ron Eldor | 9924bdc | 2018-10-04 10:59:13 +0300 | [diff] [blame] | 829 | * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 830 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 831 | * \param ctx The initialized RSA context to use. |
Hanno Becker | f66f294 | 2018-12-18 13:30:08 +0000 | [diff] [blame] | 832 | * \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE, |
| 833 | * this is used for blinding and should be provided; see |
| 834 | * mbedtls_rsa_private() for more. If \p mode is |
| 835 | * #MBEDTLS_RSA_PUBLIC, it is ignored. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 836 | * \param p_rng The RNG context to be passed to \p f_rng. This may be |
| 837 | * \c NULL if \p f_rng is \c NULL or doesn't need a context. |
| 838 | * \param mode The mode of operation. This must be either |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 839 | * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated). |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 840 | * \param label The buffer holding the custom label to use. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 841 | * This must be a readable buffer of length \p label_len |
| 842 | * Bytes. It may be \c NULL if \p label_len is \c 0. |
| 843 | * \param label_len The length of the label in Bytes. |
| 844 | * \param olen The address at which to store the length of |
| 845 | * the plaintext. This must not be \c NULL. |
| 846 | * \param input The ciphertext buffer. This must be a readable buffer |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 847 | * of length \c ctx->len Bytes. For example, \c 256 Bytes |
| 848 | * for an 2048-bit RSA modulus. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 849 | * \param output The buffer used to hold the plaintext. This must |
| 850 | * be a writable buffer of length \p output_max_len Bytes. |
Hanno Becker | f66f294 | 2018-12-18 13:30:08 +0000 | [diff] [blame] | 851 | * \param output_max_len The length in Bytes of the output buffer \p output. |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 852 | * |
| 853 | * \return \c 0 on success. |
| 854 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 855 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 856 | int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx, |
Paul Bakker | 548957d | 2013-08-30 10:30:02 +0200 | [diff] [blame] | 857 | int (*f_rng)(void *, unsigned char *, size_t), |
| 858 | void *p_rng, |
Paul Bakker | a43231c | 2013-02-28 17:33:49 +0100 | [diff] [blame] | 859 | int mode, |
| 860 | const unsigned char *label, size_t label_len, |
| 861 | size_t *olen, |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 862 | const unsigned char *input, |
| 863 | unsigned char *output, |
| 864 | size_t output_max_len ); |
| 865 | |
| 866 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 867 | * \brief This function performs a private RSA operation to sign |
| 868 | * a message digest using PKCS#1. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 869 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 870 | * It is the generic wrapper for performing a PKCS#1 |
| 871 | * signature using the \p mode from the context. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 872 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 873 | * \note The \p sig buffer must be as large as the size |
| 874 | * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. |
Paul Bakker | 9dcc322 | 2011-03-08 14:16:06 +0000 | [diff] [blame] | 875 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 876 | * \note For PKCS#1 v2.1 encoding, see comments on |
| 877 | * mbedtls_rsa_rsassa_pss_sign() for details on |
| 878 | * \p md_alg and \p hash_id. |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 879 | * |
| 880 | * \deprecated It is deprecated and discouraged to call this function |
| 881 | * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library |
| 882 | * are likely to remove the \p mode argument and have it |
| 883 | * implicitly set to #MBEDTLS_RSA_PRIVATE. |
| 884 | * |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 885 | * \note Alternative implementations of RSA need not support |
| 886 | * mode being set to #MBEDTLS_RSA_PUBLIC and might instead |
Ron Eldor | 9924bdc | 2018-10-04 10:59:13 +0300 | [diff] [blame] | 887 | * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 888 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 889 | * \param ctx The initialized RSA context to use. |
Hanno Becker | a9020f2 | 2018-12-18 14:45:45 +0000 | [diff] [blame] | 890 | * \param f_rng The RNG function to use. If the padding mode is PKCS#1 v2.1, |
| 891 | * this must be provided. If the padding mode is PKCS#1 v1.5 and |
| 892 | * \p mode is #MBEDTLS_RSA_PRIVATE, it is used for blinding |
| 893 | * and should be provided; see mbedtls_rsa_private() for more |
| 894 | * more. It is ignored otherwise. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 895 | * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL |
| 896 | * if \p f_rng is \c NULL or doesn't need a context argument. |
| 897 | * \param mode The mode of operation. This must be either |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 898 | * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated). |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 899 | * \param md_alg The message-digest algorithm used to hash the original data. |
| 900 | * Use #MBEDTLS_MD_NONE for signing raw data. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 901 | * \param hashlen The length of the message digest. |
| 902 | * Ths is only used if \p md_alg is #MBEDTLS_MD_NONE. |
| 903 | * \param hash The buffer holding the message digest or raw data. |
| 904 | * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable |
| 905 | * buffer of length \p hashlen Bytes. If \p md_alg is not |
| 906 | * #MBEDTLS_MD_NONE, it must be a readable buffer of length |
| 907 | * the size of the hash corresponding to \p md_alg. |
| 908 | * \param sig The buffer to hold the signature. This must be a writable |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 909 | * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes |
| 910 | * for an 2048-bit RSA modulus. |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 911 | * |
| 912 | * \return \c 0 if the signing operation was successful. |
| 913 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 914 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 915 | int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx, |
Paul Bakker | a3d195c | 2011-11-27 21:07:34 +0000 | [diff] [blame] | 916 | int (*f_rng)(void *, unsigned char *, size_t), |
Paul Bakker | 9dcc322 | 2011-03-08 14:16:06 +0000 | [diff] [blame] | 917 | void *p_rng, |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 918 | int mode, |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 919 | mbedtls_md_type_t md_alg, |
Paul Bakker | 23986e5 | 2011-04-24 08:57:21 +0000 | [diff] [blame] | 920 | unsigned int hashlen, |
Paul Bakker | ff60ee6 | 2010-03-16 21:09:09 +0000 | [diff] [blame] | 921 | const unsigned char *hash, |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 922 | unsigned char *sig ); |
| 923 | |
| 924 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 925 | * \brief This function performs a PKCS#1 v1.5 signature |
| 926 | * operation (RSASSA-PKCS1-v1_5-SIGN). |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 927 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 928 | * \deprecated It is deprecated and discouraged to call this function |
| 929 | * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library |
| 930 | * are likely to remove the \p mode argument and have it |
| 931 | * implicitly set to #MBEDTLS_RSA_PRIVATE. |
| 932 | * |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 933 | * \note Alternative implementations of RSA need not support |
| 934 | * mode being set to #MBEDTLS_RSA_PUBLIC and might instead |
Ron Eldor | 9924bdc | 2018-10-04 10:59:13 +0300 | [diff] [blame] | 935 | * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 936 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 937 | * \param ctx The initialized RSA context to use. |
Hanno Becker | f66f294 | 2018-12-18 13:30:08 +0000 | [diff] [blame] | 938 | * \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE, |
| 939 | * this is used for blinding and should be provided; see |
| 940 | * mbedtls_rsa_private() for more. If \p mode is |
| 941 | * #MBEDTLS_RSA_PUBLIC, it is ignored. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 942 | * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL |
| 943 | * if \p f_rng is \c NULL or doesn't need a context argument. |
| 944 | * \param mode The mode of operation. This must be either |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 945 | * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated). |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 946 | * \param md_alg The message-digest algorithm used to hash the original data. |
| 947 | * Use #MBEDTLS_MD_NONE for signing raw data. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 948 | * \param hashlen The length of the message digest. |
| 949 | * Ths is only used if \p md_alg is #MBEDTLS_MD_NONE. |
| 950 | * \param hash The buffer holding the message digest or raw data. |
| 951 | * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable |
| 952 | * buffer of length \p hashlen Bytes. If \p md_alg is not |
| 953 | * #MBEDTLS_MD_NONE, it must be a readable buffer of length |
| 954 | * the size of the hash corresponding to \p md_alg. |
| 955 | * \param sig The buffer to hold the signature. This must be a writable |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 956 | * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes |
| 957 | * for an 2048-bit RSA modulus. |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 958 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 959 | * \return \c 0 if the signing operation was successful. |
| 960 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 961 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 962 | int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx, |
Paul Bakker | 548957d | 2013-08-30 10:30:02 +0200 | [diff] [blame] | 963 | int (*f_rng)(void *, unsigned char *, size_t), |
| 964 | void *p_rng, |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 965 | int mode, |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 966 | mbedtls_md_type_t md_alg, |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 967 | unsigned int hashlen, |
| 968 | const unsigned char *hash, |
| 969 | unsigned char *sig ); |
| 970 | |
| 971 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 972 | * \brief This function performs a PKCS#1 v2.1 PSS signature |
| 973 | * operation (RSASSA-PSS-SIGN). |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 974 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 975 | * \note The \p hash_id in the RSA context is the one used for the |
| 976 | * encoding. \p md_alg in the function call is the type of hash |
| 977 | * that is encoded. According to <em>RFC-3447: Public-Key |
| 978 | * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography |
| 979 | * Specifications</em> it is advised to keep both hashes the |
| 980 | * same. |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 981 | * |
Jaeden Amero | 3725bb2 | 2018-09-07 19:12:36 +0100 | [diff] [blame] | 982 | * \note This function always uses the maximum possible salt size, |
| 983 | * up to the length of the payload hash. This choice of salt |
| 984 | * size complies with FIPS 186-4 §5.5 (e) and RFC 8017 (PKCS#1 |
| 985 | * v2.2) §9.1.1 step 3. Furthermore this function enforces a |
| 986 | * minimum salt size which is the hash size minus 2 bytes. If |
| 987 | * this minimum size is too large given the key size (the salt |
| 988 | * size, plus the hash size, plus 2 bytes must be no more than |
| 989 | * the key size in bytes), this function returns |
| 990 | * #MBEDTLS_ERR_RSA_BAD_INPUT_DATA. |
| 991 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 992 | * \deprecated It is deprecated and discouraged to call this function |
| 993 | * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library |
| 994 | * are likely to remove the \p mode argument and have it |
| 995 | * implicitly set to #MBEDTLS_RSA_PRIVATE. |
| 996 | * |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 997 | * \note Alternative implementations of RSA need not support |
| 998 | * mode being set to #MBEDTLS_RSA_PUBLIC and might instead |
Ron Eldor | 9924bdc | 2018-10-04 10:59:13 +0300 | [diff] [blame] | 999 | * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 1000 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 1001 | * \param ctx The initialized RSA context to use. |
| 1002 | * \param f_rng The RNG function. It must not be \c NULL. |
| 1003 | * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL |
| 1004 | * if \p f_rng doesn't need a context argument. |
| 1005 | * \param mode The mode of operation. This must be either |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 1006 | * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated). |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 1007 | * \param md_alg The message-digest algorithm used to hash the original data. |
| 1008 | * Use #MBEDTLS_MD_NONE for signing raw data. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 1009 | * \param hashlen The length of the message digest. |
| 1010 | * Ths is only used if \p md_alg is #MBEDTLS_MD_NONE. |
| 1011 | * \param hash The buffer holding the message digest or raw data. |
| 1012 | * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable |
| 1013 | * buffer of length \p hashlen Bytes. If \p md_alg is not |
| 1014 | * #MBEDTLS_MD_NONE, it must be a readable buffer of length |
| 1015 | * the size of the hash corresponding to \p md_alg. |
| 1016 | * \param sig The buffer to hold the signature. This must be a writable |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 1017 | * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes |
| 1018 | * for an 2048-bit RSA modulus. |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 1019 | * |
| 1020 | * \return \c 0 if the signing operation was successful. |
| 1021 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 1022 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 1023 | int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx, |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 1024 | int (*f_rng)(void *, unsigned char *, size_t), |
| 1025 | void *p_rng, |
| 1026 | int mode, |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 1027 | mbedtls_md_type_t md_alg, |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 1028 | unsigned int hashlen, |
| 1029 | const unsigned char *hash, |
| 1030 | unsigned char *sig ); |
| 1031 | |
| 1032 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 1033 | * \brief This function performs a public RSA operation and checks |
| 1034 | * the message digest. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1035 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 1036 | * This is the generic wrapper for performing a PKCS#1 |
| 1037 | * verification using the mode from the context. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1038 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 1039 | * \note For PKCS#1 v2.1 encoding, see comments on |
| 1040 | * mbedtls_rsa_rsassa_pss_verify() about \p md_alg and |
| 1041 | * \p hash_id. |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 1042 | * |
| 1043 | * \deprecated It is deprecated and discouraged to call this function |
| 1044 | * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library |
| 1045 | * are likely to remove the \p mode argument and have it |
| 1046 | * set to #MBEDTLS_RSA_PUBLIC. |
| 1047 | * |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 1048 | * \note Alternative implementations of RSA need not support |
| 1049 | * mode being set to #MBEDTLS_RSA_PRIVATE and might instead |
Ron Eldor | 9924bdc | 2018-10-04 10:59:13 +0300 | [diff] [blame] | 1050 | * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 1051 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 1052 | * \param ctx The initialized RSA public key context to use. |
Hanno Becker | a9020f2 | 2018-12-18 14:45:45 +0000 | [diff] [blame] | 1053 | * \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE, |
| 1054 | * this is used for blinding and should be provided; see |
| 1055 | * mbedtls_rsa_private() for more. Otherwise, it is ignored. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 1056 | * \param p_rng The RNG context to be passed to \p f_rng. This may be |
| 1057 | * \c NULL if \p f_rng is \c NULL or doesn't need a context. |
| 1058 | * \param mode The mode of operation. This must be either |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 1059 | * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated). |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 1060 | * \param md_alg The message-digest algorithm used to hash the original data. |
| 1061 | * Use #MBEDTLS_MD_NONE for signing raw data. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 1062 | * \param hashlen The length of the message digest. |
| 1063 | * This is only used if \p md_alg is #MBEDTLS_MD_NONE. |
| 1064 | * \param hash The buffer holding the message digest or raw data. |
| 1065 | * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable |
| 1066 | * buffer of length \p hashlen Bytes. If \p md_alg is not |
| 1067 | * #MBEDTLS_MD_NONE, it must be a readable buffer of length |
| 1068 | * the size of the hash corresponding to \p md_alg. |
| 1069 | * \param sig The buffer holding the signature. This must be a readable |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 1070 | * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes |
| 1071 | * for an 2048-bit RSA modulus. |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 1072 | * |
| 1073 | * \return \c 0 if the verify operation was successful. |
| 1074 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1075 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 1076 | int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx, |
Paul Bakker | 548957d | 2013-08-30 10:30:02 +0200 | [diff] [blame] | 1077 | int (*f_rng)(void *, unsigned char *, size_t), |
| 1078 | void *p_rng, |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1079 | int mode, |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 1080 | mbedtls_md_type_t md_alg, |
Paul Bakker | 23986e5 | 2011-04-24 08:57:21 +0000 | [diff] [blame] | 1081 | unsigned int hashlen, |
Paul Bakker | ff60ee6 | 2010-03-16 21:09:09 +0000 | [diff] [blame] | 1082 | const unsigned char *hash, |
Manuel Pégourié-Gonnard | cc0a9d0 | 2013-08-12 11:34:35 +0200 | [diff] [blame] | 1083 | const unsigned char *sig ); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1084 | |
| 1085 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 1086 | * \brief This function performs a PKCS#1 v1.5 verification |
| 1087 | * operation (RSASSA-PKCS1-v1_5-VERIFY). |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 1088 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 1089 | * \deprecated It is deprecated and discouraged to call this function |
| 1090 | * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library |
| 1091 | * are likely to remove the \p mode argument and have it |
| 1092 | * set to #MBEDTLS_RSA_PUBLIC. |
| 1093 | * |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 1094 | * \note Alternative implementations of RSA need not support |
| 1095 | * mode being set to #MBEDTLS_RSA_PRIVATE and might instead |
Ron Eldor | 9924bdc | 2018-10-04 10:59:13 +0300 | [diff] [blame] | 1096 | * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 1097 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 1098 | * \param ctx The initialized RSA public key context to use. |
Hanno Becker | a9020f2 | 2018-12-18 14:45:45 +0000 | [diff] [blame] | 1099 | * \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE, |
| 1100 | * this is used for blinding and should be provided; see |
| 1101 | * mbedtls_rsa_private() for more. Otherwise, it is ignored. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 1102 | * \param p_rng The RNG context to be passed to \p f_rng. This may be |
| 1103 | * \c NULL if \p f_rng is \c NULL or doesn't need a context. |
| 1104 | * \param mode The mode of operation. This must be either |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 1105 | * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated). |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 1106 | * \param md_alg The message-digest algorithm used to hash the original data. |
| 1107 | * Use #MBEDTLS_MD_NONE for signing raw data. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 1108 | * \param hashlen The length of the message digest. |
| 1109 | * This is only used if \p md_alg is #MBEDTLS_MD_NONE. |
| 1110 | * \param hash The buffer holding the message digest or raw data. |
| 1111 | * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable |
| 1112 | * buffer of length \p hashlen Bytes. If \p md_alg is not |
| 1113 | * #MBEDTLS_MD_NONE, it must be a readable buffer of length |
| 1114 | * the size of the hash corresponding to \p md_alg. |
| 1115 | * \param sig The buffer holding the signature. This must be a readable |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 1116 | * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes |
| 1117 | * for an 2048-bit RSA modulus. |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 1118 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 1119 | * \return \c 0 if the verify operation was successful. |
| 1120 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 1121 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 1122 | int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx, |
Paul Bakker | 548957d | 2013-08-30 10:30:02 +0200 | [diff] [blame] | 1123 | int (*f_rng)(void *, unsigned char *, size_t), |
| 1124 | void *p_rng, |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 1125 | int mode, |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 1126 | mbedtls_md_type_t md_alg, |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 1127 | unsigned int hashlen, |
| 1128 | const unsigned char *hash, |
Manuel Pégourié-Gonnard | cc0a9d0 | 2013-08-12 11:34:35 +0200 | [diff] [blame] | 1129 | const unsigned char *sig ); |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 1130 | |
| 1131 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 1132 | * \brief This function performs a PKCS#1 v2.1 PSS verification |
| 1133 | * operation (RSASSA-PSS-VERIFY). |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 1134 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 1135 | * The hash function for the MGF mask generating function |
| 1136 | * is that specified in the RSA context. |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 1137 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 1138 | * \note The \p hash_id in the RSA context is the one used for the |
| 1139 | * verification. \p md_alg in the function call is the type of |
| 1140 | * hash that is verified. According to <em>RFC-3447: Public-Key |
| 1141 | * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography |
| 1142 | * Specifications</em> it is advised to keep both hashes the |
| 1143 | * same. If \p hash_id in the RSA context is unset, |
| 1144 | * the \p md_alg from the function call is used. |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 1145 | * |
| 1146 | * \deprecated It is deprecated and discouraged to call this function |
| 1147 | * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library |
| 1148 | * are likely to remove the \p mode argument and have it |
| 1149 | * implicitly set to #MBEDTLS_RSA_PUBLIC. |
| 1150 | * |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 1151 | * \note Alternative implementations of RSA need not support |
| 1152 | * mode being set to #MBEDTLS_RSA_PRIVATE and might instead |
Ron Eldor | 9924bdc | 2018-10-04 10:59:13 +0300 | [diff] [blame] | 1153 | * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. |
Rose Zadik | f2ec288 | 2018-04-17 10:27:25 +0100 | [diff] [blame] | 1154 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 1155 | * \param ctx The initialized RSA public key context to use. |
Hanno Becker | a9020f2 | 2018-12-18 14:45:45 +0000 | [diff] [blame] | 1156 | * \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE, |
| 1157 | * this is used for blinding and should be provided; see |
| 1158 | * mbedtls_rsa_private() for more. Otherwise, it is ignored. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 1159 | * \param p_rng The RNG context to be passed to \p f_rng. This may be |
| 1160 | * \c NULL if \p f_rng is \c NULL or doesn't need a context. |
| 1161 | * \param mode The mode of operation. This must be either |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 1162 | * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated). |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 1163 | * \param md_alg The message-digest algorithm used to hash the original data. |
| 1164 | * Use #MBEDTLS_MD_NONE for signing raw data. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 1165 | * \param hashlen The length of the message digest. |
| 1166 | * This is only used if \p md_alg is #MBEDTLS_MD_NONE. |
| 1167 | * \param hash The buffer holding the message digest or raw data. |
| 1168 | * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable |
| 1169 | * buffer of length \p hashlen Bytes. If \p md_alg is not |
| 1170 | * #MBEDTLS_MD_NONE, it must be a readable buffer of length |
| 1171 | * the size of the hash corresponding to \p md_alg. |
| 1172 | * \param sig The buffer holding the signature. This must be a readable |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 1173 | * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes |
| 1174 | * for an 2048-bit RSA modulus. |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 1175 | * |
| 1176 | * \return \c 0 if the verify operation was successful. |
| 1177 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 1178 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 1179 | int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx, |
Paul Bakker | 548957d | 2013-08-30 10:30:02 +0200 | [diff] [blame] | 1180 | int (*f_rng)(void *, unsigned char *, size_t), |
| 1181 | void *p_rng, |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 1182 | int mode, |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 1183 | mbedtls_md_type_t md_alg, |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 1184 | unsigned int hashlen, |
| 1185 | const unsigned char *hash, |
Manuel Pégourié-Gonnard | cc0a9d0 | 2013-08-12 11:34:35 +0200 | [diff] [blame] | 1186 | const unsigned char *sig ); |
Paul Bakker | b386913 | 2013-02-28 17:21:01 +0100 | [diff] [blame] | 1187 | |
| 1188 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 1189 | * \brief This function performs a PKCS#1 v2.1 PSS verification |
| 1190 | * operation (RSASSA-PSS-VERIFY). |
Manuel Pégourié-Gonnard | 5ec628a | 2014-06-03 11:44:06 +0200 | [diff] [blame] | 1191 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 1192 | * The hash function for the MGF mask generating function |
| 1193 | * is that specified in \p mgf1_hash_id. |
Manuel Pégourié-Gonnard | 5ec628a | 2014-06-03 11:44:06 +0200 | [diff] [blame] | 1194 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 1195 | * \note The \p sig buffer must be as large as the size |
| 1196 | * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. |
Manuel Pégourié-Gonnard | 5ec628a | 2014-06-03 11:44:06 +0200 | [diff] [blame] | 1197 | * |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 1198 | * \note The \p hash_id in the RSA context is ignored. |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 1199 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 1200 | * \param ctx The initialized RSA public key context to use. |
Hanno Becker | a9020f2 | 2018-12-18 14:45:45 +0000 | [diff] [blame] | 1201 | * \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE, |
| 1202 | * this is used for blinding and should be provided; see |
| 1203 | * mbedtls_rsa_private() for more. Otherwise, it is ignored. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 1204 | * \param p_rng The RNG context to be passed to \p f_rng. This may be |
| 1205 | * \c NULL if \p f_rng is \c NULL or doesn't need a context. |
| 1206 | * \param mode The mode of operation. This must be either |
| 1207 | * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 1208 | * \param md_alg The message-digest algorithm used to hash the original data. |
| 1209 | * Use #MBEDTLS_MD_NONE for signing raw data. |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 1210 | * \param hashlen The length of the message digest. |
| 1211 | * This is only used if \p md_alg is #MBEDTLS_MD_NONE. |
| 1212 | * \param hash The buffer holding the message digest or raw data. |
| 1213 | * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable |
| 1214 | * buffer of length \p hashlen Bytes. If \p md_alg is not |
| 1215 | * #MBEDTLS_MD_NONE, it must be a readable buffer of length |
| 1216 | * the size of the hash corresponding to \p md_alg. |
| 1217 | * \param mgf1_hash_id The message digest used for mask generation. |
| 1218 | * \param expected_salt_len The length of the salt used in padding. Use |
| 1219 | * #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length. |
| 1220 | * \param sig The buffer holding the signature. This must be a readable |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 1221 | * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes |
| 1222 | * for an 2048-bit RSA modulus. |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 1223 | * |
| 1224 | * \return \c 0 if the verify operation was successful. |
| 1225 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. |
Manuel Pégourié-Gonnard | 5ec628a | 2014-06-03 11:44:06 +0200 | [diff] [blame] | 1226 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 1227 | int mbedtls_rsa_rsassa_pss_verify_ext( mbedtls_rsa_context *ctx, |
Manuel Pégourié-Gonnard | 5ec628a | 2014-06-03 11:44:06 +0200 | [diff] [blame] | 1228 | int (*f_rng)(void *, unsigned char *, size_t), |
| 1229 | void *p_rng, |
| 1230 | int mode, |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 1231 | mbedtls_md_type_t md_alg, |
Manuel Pégourié-Gonnard | 5ec628a | 2014-06-03 11:44:06 +0200 | [diff] [blame] | 1232 | unsigned int hashlen, |
| 1233 | const unsigned char *hash, |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 1234 | mbedtls_md_type_t mgf1_hash_id, |
Manuel Pégourié-Gonnard | 5ec628a | 2014-06-03 11:44:06 +0200 | [diff] [blame] | 1235 | int expected_salt_len, |
| 1236 | const unsigned char *sig ); |
| 1237 | |
| 1238 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 1239 | * \brief This function copies the components of an RSA context. |
Manuel Pégourié-Gonnard | 3053f5b | 2013-08-14 13:39:57 +0200 | [diff] [blame] | 1240 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 1241 | * \param dst The destination context. This must be initialized. |
| 1242 | * \param src The source context. This must be initialized. |
Manuel Pégourié-Gonnard | 3053f5b | 2013-08-14 13:39:57 +0200 | [diff] [blame] | 1243 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 1244 | * \return \c 0 on success. |
| 1245 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure. |
Manuel Pégourié-Gonnard | 3053f5b | 2013-08-14 13:39:57 +0200 | [diff] [blame] | 1246 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 1247 | int mbedtls_rsa_copy( mbedtls_rsa_context *dst, const mbedtls_rsa_context *src ); |
Manuel Pégourié-Gonnard | 3053f5b | 2013-08-14 13:39:57 +0200 | [diff] [blame] | 1248 | |
| 1249 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 1250 | * \brief This function frees the components of an RSA key. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 1251 | * |
Hanno Becker | 9a46777 | 2018-12-13 09:54:59 +0000 | [diff] [blame] | 1252 | * \param ctx The RSA context to free. May be \c NULL, in which case |
| 1253 | * this function is a no-op. If it is not \c NULL, it must |
Hanno Becker | 385ce91 | 2018-12-13 18:33:12 +0000 | [diff] [blame] | 1254 | * point to an initialized RSA context. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1255 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 1256 | void mbedtls_rsa_free( mbedtls_rsa_context *ctx ); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1257 | |
Ron Eldor | fa8f635 | 2017-06-20 15:48:46 +0300 | [diff] [blame] | 1258 | #if defined(MBEDTLS_SELF_TEST) |
| 1259 | |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1260 | /** |
Rose Zadik | 042e97f | 2018-01-26 16:35:10 +0000 | [diff] [blame] | 1261 | * \brief The RSA checkup routine. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1262 | * |
Rose Zadik | e8b5b99 | 2018-03-27 12:19:47 +0100 | [diff] [blame] | 1263 | * \return \c 0 on success. |
| 1264 | * \return \c 1 on failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1265 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 1266 | int mbedtls_rsa_self_test( int verbose ); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1267 | |
Ron Eldor | fa8f635 | 2017-06-20 15:48:46 +0300 | [diff] [blame] | 1268 | #endif /* MBEDTLS_SELF_TEST */ |
| 1269 | |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1270 | #ifdef __cplusplus |
| 1271 | } |
| 1272 | #endif |
| 1273 | |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1274 | #endif /* rsa.h */ |