Kenji Arai
/
mbed-os_TYBLE16
Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
Embed:
(wiki syntax)
Show/hide line numbers
rsa.h
Go to the documentation of this file.
00001 /** 00002 * \file rsa.h 00003 * 00004 * \brief This file provides an API for the RSA public-key cryptosystem. 00005 * 00006 * The RSA public-key cryptosystem is defined in <em>Public-Key 00007 * Cryptography Standards (PKCS) #1 v1.5: RSA Encryption</em> 00008 * and <em>Public-Key Cryptography Standards (PKCS) #1 v2.1: 00009 * RSA Cryptography Specifications</em>. 00010 * 00011 */ 00012 /* 00013 * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved 00014 * SPDX-License-Identifier: Apache-2.0 00015 * 00016 * Licensed under the Apache License, Version 2.0 (the "License"); you may 00017 * not use this file except in compliance with the License. 00018 * You may obtain a copy of the License at 00019 * 00020 * http://www.apache.org/licenses/LICENSE-2.0 00021 * 00022 * Unless required by applicable law or agreed to in writing, software 00023 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 00024 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00025 * See the License for the specific language governing permissions and 00026 * limitations under the License. 00027 * 00028 * This file is part of Mbed TLS (https://tls.mbed.org) 00029 */ 00030 #ifndef MBEDTLS_RSA_H 00031 #define MBEDTLS_RSA_H 00032 00033 #if !defined(MBEDTLS_CONFIG_FILE) 00034 #include "mbedtls/config.h" 00035 #else 00036 #include MBEDTLS_CONFIG_FILE 00037 #endif 00038 00039 #include "mbedtls/bignum.h" 00040 #include "mbedtls/md.h" 00041 00042 #if defined(MBEDTLS_THREADING_C) 00043 #include "mbedtls/threading.h" 00044 #endif 00045 00046 /* 00047 * RSA Error codes 00048 */ 00049 #define MBEDTLS_ERR_RSA_BAD_INPUT_DATA -0x4080 /**< Bad input parameters to function. */ 00050 #define MBEDTLS_ERR_RSA_INVALID_PADDING -0x4100 /**< Input data contains invalid padding and is rejected. */ 00051 #define MBEDTLS_ERR_RSA_KEY_GEN_FAILED -0x4180 /**< Something failed during generation of a key. */ 00052 #define MBEDTLS_ERR_RSA_KEY_CHECK_FAILED -0x4200 /**< Key failed to pass the validity check of the library. */ 00053 #define MBEDTLS_ERR_RSA_PUBLIC_FAILED -0x4280 /**< The public key operation failed. */ 00054 #define MBEDTLS_ERR_RSA_PRIVATE_FAILED -0x4300 /**< The private key operation failed. */ 00055 #define MBEDTLS_ERR_RSA_VERIFY_FAILED -0x4380 /**< The PKCS#1 verification failed. */ 00056 #define MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE -0x4400 /**< The output buffer for decryption is not large enough. */ 00057 #define MBEDTLS_ERR_RSA_RNG_FAILED -0x4480 /**< The random generator failed to generate non-zeros. */ 00058 00059 /* MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION is deprecated and should not be used. 00060 */ 00061 #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. */ 00062 00063 /* MBEDTLS_ERR_RSA_HW_ACCEL_FAILED is deprecated and should not be used. */ 00064 #define MBEDTLS_ERR_RSA_HW_ACCEL_FAILED -0x4580 /**< RSA hardware accelerator failed. */ 00065 00066 /* 00067 * RSA constants 00068 */ 00069 #define MBEDTLS_RSA_PUBLIC 0 /**< Request private key operation. */ 00070 #define MBEDTLS_RSA_PRIVATE 1 /**< Request public key operation. */ 00071 00072 #define MBEDTLS_RSA_PKCS_V15 0 /**< Use PKCS#1 v1.5 encoding. */ 00073 #define MBEDTLS_RSA_PKCS_V21 1 /**< Use PKCS#1 v2.1 encoding. */ 00074 00075 #define MBEDTLS_RSA_SIGN 1 /**< Identifier for RSA signature operations. */ 00076 #define MBEDTLS_RSA_CRYPT 2 /**< Identifier for RSA encryption and decryption operations. */ 00077 00078 #define MBEDTLS_RSA_SALT_LEN_ANY -1 00079 00080 /* 00081 * The above constants may be used even if the RSA module is compile out, 00082 * eg for alternative (PKCS#11) RSA implemenations in the PK layers. 00083 */ 00084 00085 #ifdef __cplusplus 00086 extern "C" { 00087 #endif 00088 00089 #if !defined(MBEDTLS_RSA_ALT) 00090 // Regular implementation 00091 // 00092 00093 /** 00094 * \brief The RSA context structure. 00095 * 00096 * \note Direct manipulation of the members of this structure 00097 * is deprecated. All manipulation should instead be done through 00098 * the public interface functions. 00099 */ 00100 typedef struct mbedtls_rsa_context 00101 { 00102 int ver ; /*!< Always 0.*/ 00103 size_t len ; /*!< The size of \p N in Bytes. */ 00104 00105 mbedtls_mpi N ; /*!< The public modulus. */ 00106 mbedtls_mpi E ; /*!< The public exponent. */ 00107 00108 mbedtls_mpi D ; /*!< The private exponent. */ 00109 mbedtls_mpi P ; /*!< The first prime factor. */ 00110 mbedtls_mpi Q ; /*!< The second prime factor. */ 00111 00112 mbedtls_mpi DP ; /*!< <code>D % (P - 1)</code>. */ 00113 mbedtls_mpi DQ ; /*!< <code>D % (Q - 1)</code>. */ 00114 mbedtls_mpi QP ; /*!< <code>1 / (Q % P)</code>. */ 00115 00116 mbedtls_mpi RN ; /*!< cached <code>R^2 mod N</code>. */ 00117 00118 mbedtls_mpi RP ; /*!< cached <code>R^2 mod P</code>. */ 00119 mbedtls_mpi RQ ; /*!< cached <code>R^2 mod Q</code>. */ 00120 00121 mbedtls_mpi Vi ; /*!< The cached blinding value. */ 00122 mbedtls_mpi Vf ; /*!< The cached un-blinding value. */ 00123 00124 int padding ; /*!< Selects padding mode: 00125 #MBEDTLS_RSA_PKCS_V15 for 1.5 padding and 00126 #MBEDTLS_RSA_PKCS_V21 for OAEP or PSS. */ 00127 int hash_id ; /*!< Hash identifier of mbedtls_md_type_t type, 00128 as specified in md.h for use in the MGF 00129 mask generating function used in the 00130 EME-OAEP and EMSA-PSS encodings. */ 00131 #if defined(MBEDTLS_THREADING_C) 00132 mbedtls_threading_mutex_t mutex ; /*!< Thread-safety mutex. */ 00133 #endif 00134 } 00135 mbedtls_rsa_context; 00136 00137 #else /* MBEDTLS_RSA_ALT */ 00138 #include "rsa_alt.h" 00139 #endif /* MBEDTLS_RSA_ALT */ 00140 00141 /** 00142 * \brief This function initializes an RSA context. 00143 * 00144 * \note Set padding to #MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP 00145 * encryption scheme and the RSASSA-PSS signature scheme. 00146 * 00147 * \note The \p hash_id parameter is ignored when using 00148 * #MBEDTLS_RSA_PKCS_V15 padding. 00149 * 00150 * \note The choice of padding mode is strictly enforced for private key 00151 * operations, since there might be security concerns in 00152 * mixing padding modes. For public key operations it is 00153 * a default value, which can be overridden by calling specific 00154 * \c rsa_rsaes_xxx or \c rsa_rsassa_xxx functions. 00155 * 00156 * \note The hash selected in \p hash_id is always used for OEAP 00157 * encryption. For PSS signatures, it is always used for 00158 * making signatures, but can be overridden for verifying them. 00159 * If set to #MBEDTLS_MD_NONE, it is always overridden. 00160 * 00161 * \param ctx The RSA context to initialize. This must not be \c NULL. 00162 * \param padding The padding mode to use. This must be either 00163 * #MBEDTLS_RSA_PKCS_V15 or #MBEDTLS_RSA_PKCS_V21. 00164 * \param hash_id The hash identifier of ::mbedtls_md_type_t type, if 00165 * \p padding is #MBEDTLS_RSA_PKCS_V21. It is unused 00166 * otherwise. 00167 */ 00168 void mbedtls_rsa_init( mbedtls_rsa_context *ctx, 00169 int padding, 00170 int hash_id ); 00171 00172 /** 00173 * \brief This function imports a set of core parameters into an 00174 * RSA context. 00175 * 00176 * \note This function can be called multiple times for successive 00177 * imports, if the parameters are not simultaneously present. 00178 * 00179 * Any sequence of calls to this function should be followed 00180 * by a call to mbedtls_rsa_complete(), which checks and 00181 * completes the provided information to a ready-for-use 00182 * public or private RSA key. 00183 * 00184 * \note See mbedtls_rsa_complete() for more information on which 00185 * parameters are necessary to set up a private or public 00186 * RSA key. 00187 * 00188 * \note The imported parameters are copied and need not be preserved 00189 * for the lifetime of the RSA context being set up. 00190 * 00191 * \param ctx The initialized RSA context to store the parameters in. 00192 * \param N The RSA modulus. This may be \c NULL. 00193 * \param P The first prime factor of \p N. This may be \c NULL. 00194 * \param Q The second prime factor of \p N. This may be \c NULL. 00195 * \param D The private exponent. This may be \c NULL. 00196 * \param E The public exponent. This may be \c NULL. 00197 * 00198 * \return \c 0 on success. 00199 * \return A non-zero error code on failure. 00200 */ 00201 int mbedtls_rsa_import( mbedtls_rsa_context *ctx, 00202 const mbedtls_mpi *N, 00203 const mbedtls_mpi *P, const mbedtls_mpi *Q, 00204 const mbedtls_mpi *D, const mbedtls_mpi *E ); 00205 00206 /** 00207 * \brief This function imports core RSA parameters, in raw big-endian 00208 * binary format, into an RSA context. 00209 * 00210 * \note This function can be called multiple times for successive 00211 * imports, if the parameters are not simultaneously present. 00212 * 00213 * Any sequence of calls to this function should be followed 00214 * by a call to mbedtls_rsa_complete(), which checks and 00215 * completes the provided information to a ready-for-use 00216 * public or private RSA key. 00217 * 00218 * \note See mbedtls_rsa_complete() for more information on which 00219 * parameters are necessary to set up a private or public 00220 * RSA key. 00221 * 00222 * \note The imported parameters are copied and need not be preserved 00223 * for the lifetime of the RSA context being set up. 00224 * 00225 * \param ctx The initialized RSA context to store the parameters in. 00226 * \param N The RSA modulus. This may be \c NULL. 00227 * \param N_len The Byte length of \p N; it is ignored if \p N == NULL. 00228 * \param P The first prime factor of \p N. This may be \c NULL. 00229 * \param P_len The Byte length of \p P; it ns ignored if \p P == NULL. 00230 * \param Q The second prime factor of \p N. This may be \c NULL. 00231 * \param Q_len The Byte length of \p Q; it is ignored if \p Q == NULL. 00232 * \param D The private exponent. This may be \c NULL. 00233 * \param D_len The Byte length of \p D; it is ignored if \p D == NULL. 00234 * \param E The public exponent. This may be \c NULL. 00235 * \param E_len The Byte length of \p E; it is ignored if \p E == NULL. 00236 * 00237 * \return \c 0 on success. 00238 * \return A non-zero error code on failure. 00239 */ 00240 int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx, 00241 unsigned char const *N, size_t N_len, 00242 unsigned char const *P, size_t P_len, 00243 unsigned char const *Q, size_t Q_len, 00244 unsigned char const *D, size_t D_len, 00245 unsigned char const *E, size_t E_len ); 00246 00247 /** 00248 * \brief This function completes an RSA context from 00249 * a set of imported core parameters. 00250 * 00251 * To setup an RSA public key, precisely \p N and \p E 00252 * must have been imported. 00253 * 00254 * To setup an RSA private key, sufficient information must 00255 * be present for the other parameters to be derivable. 00256 * 00257 * The default implementation supports the following: 00258 * <ul><li>Derive \p P, \p Q from \p N, \p D, \p E.</li> 00259 * <li>Derive \p N, \p D from \p P, \p Q, \p E.</li></ul> 00260 * Alternative implementations need not support these. 00261 * 00262 * If this function runs successfully, it guarantees that 00263 * the RSA context can be used for RSA operations without 00264 * the risk of failure or crash. 00265 * 00266 * \warning This function need not perform consistency checks 00267 * for the imported parameters. In particular, parameters that 00268 * are not needed by the implementation might be silently 00269 * discarded and left unchecked. To check the consistency 00270 * of the key material, see mbedtls_rsa_check_privkey(). 00271 * 00272 * \param ctx The initialized RSA context holding imported parameters. 00273 * 00274 * \return \c 0 on success. 00275 * \return #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted derivations 00276 * failed. 00277 * 00278 */ 00279 int mbedtls_rsa_complete( mbedtls_rsa_context *ctx ); 00280 00281 /** 00282 * \brief This function exports the core parameters of an RSA key. 00283 * 00284 * If this function runs successfully, the non-NULL buffers 00285 * pointed to by \p N, \p P, \p Q, \p D, and \p E are fully 00286 * written, with additional unused space filled leading by 00287 * zero Bytes. 00288 * 00289 * Possible reasons for returning 00290 * #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED:<ul> 00291 * <li>An alternative RSA implementation is in use, which 00292 * stores the key externally, and either cannot or should 00293 * not export it into RAM.</li> 00294 * <li>A SW or HW implementation might not support a certain 00295 * deduction. For example, \p P, \p Q from \p N, \p D, 00296 * and \p E if the former are not part of the 00297 * implementation.</li></ul> 00298 * 00299 * If the function fails due to an unsupported operation, 00300 * the RSA context stays intact and remains usable. 00301 * 00302 * \param ctx The initialized RSA context. 00303 * \param N The MPI to hold the RSA modulus. 00304 * This may be \c NULL if this field need not be exported. 00305 * \param P The MPI to hold the first prime factor of \p N. 00306 * This may be \c NULL if this field need not be exported. 00307 * \param Q The MPI to hold the second prime factor of \p N. 00308 * This may be \c NULL if this field need not be exported. 00309 * \param D The MPI to hold the private exponent. 00310 * This may be \c NULL if this field need not be exported. 00311 * \param E The MPI to hold the public exponent. 00312 * This may be \c NULL if this field need not be exported. 00313 * 00314 * \return \c 0 on success. 00315 * \return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED if exporting the 00316 * requested parameters cannot be done due to missing 00317 * functionality or because of security policies. 00318 * \return A non-zero return code on any other failure. 00319 * 00320 */ 00321 int mbedtls_rsa_export( const mbedtls_rsa_context *ctx, 00322 mbedtls_mpi *N, mbedtls_mpi *P, mbedtls_mpi *Q, 00323 mbedtls_mpi *D, mbedtls_mpi *E ); 00324 00325 /** 00326 * \brief This function exports core parameters of an RSA key 00327 * in raw big-endian binary format. 00328 * 00329 * If this function runs successfully, the non-NULL buffers 00330 * pointed to by \p N, \p P, \p Q, \p D, and \p E are fully 00331 * written, with additional unused space filled leading by 00332 * zero Bytes. 00333 * 00334 * Possible reasons for returning 00335 * #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED:<ul> 00336 * <li>An alternative RSA implementation is in use, which 00337 * stores the key externally, and either cannot or should 00338 * not export it into RAM.</li> 00339 * <li>A SW or HW implementation might not support a certain 00340 * deduction. For example, \p P, \p Q from \p N, \p D, 00341 * and \p E if the former are not part of the 00342 * implementation.</li></ul> 00343 * If the function fails due to an unsupported operation, 00344 * the RSA context stays intact and remains usable. 00345 * 00346 * \note The length parameters are ignored if the corresponding 00347 * buffer pointers are NULL. 00348 * 00349 * \param ctx The initialized RSA context. 00350 * \param N The Byte array to store the RSA modulus, 00351 * or \c NULL if this field need not be exported. 00352 * \param N_len The size of the buffer for the modulus. 00353 * \param P The Byte array to hold the first prime factor of \p N, 00354 * or \c NULL if this field need not be exported. 00355 * \param P_len The size of the buffer for the first prime factor. 00356 * \param Q The Byte array to hold the second prime factor of \p N, 00357 * or \c NULL if this field need not be exported. 00358 * \param Q_len The size of the buffer for the second prime factor. 00359 * \param D The Byte array to hold the private exponent, 00360 * or \c NULL if this field need not be exported. 00361 * \param D_len The size of the buffer for the private exponent. 00362 * \param E The Byte array to hold the public exponent, 00363 * or \c NULL if this field need not be exported. 00364 * \param E_len The size of the buffer for the public exponent. 00365 * 00366 * \return \c 0 on success. 00367 * \return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED if exporting the 00368 * requested parameters cannot be done due to missing 00369 * functionality or because of security policies. 00370 * \return A non-zero return code on any other failure. 00371 */ 00372 int mbedtls_rsa_export_raw( const mbedtls_rsa_context *ctx, 00373 unsigned char *N, size_t N_len, 00374 unsigned char *P, size_t P_len, 00375 unsigned char *Q, size_t Q_len, 00376 unsigned char *D, size_t D_len, 00377 unsigned char *E, size_t E_len ); 00378 00379 /** 00380 * \brief This function exports CRT parameters of a private RSA key. 00381 * 00382 * \note Alternative RSA implementations not using CRT-parameters 00383 * internally can implement this function based on 00384 * mbedtls_rsa_deduce_opt(). 00385 * 00386 * \param ctx The initialized RSA context. 00387 * \param DP The MPI to hold \c D modulo `P-1`, 00388 * or \c NULL if it need not be exported. 00389 * \param DQ The MPI to hold \c D modulo `Q-1`, 00390 * or \c NULL if it need not be exported. 00391 * \param QP The MPI to hold modular inverse of \c Q modulo \c P, 00392 * or \c NULL if it need not be exported. 00393 * 00394 * \return \c 0 on success. 00395 * \return A non-zero error code on failure. 00396 * 00397 */ 00398 int mbedtls_rsa_export_crt( const mbedtls_rsa_context *ctx, 00399 mbedtls_mpi *DP, mbedtls_mpi *DQ, mbedtls_mpi *QP ); 00400 00401 /** 00402 * \brief This function sets padding for an already initialized RSA 00403 * context. See mbedtls_rsa_init() for details. 00404 * 00405 * \param ctx The initialized RSA context to be configured. 00406 * \param padding The padding mode to use. This must be either 00407 * #MBEDTLS_RSA_PKCS_V15 or #MBEDTLS_RSA_PKCS_V21. 00408 * \param hash_id The #MBEDTLS_RSA_PKCS_V21 hash identifier. 00409 */ 00410 void mbedtls_rsa_set_padding( mbedtls_rsa_context *ctx, int padding, 00411 int hash_id ); 00412 00413 /** 00414 * \brief This function retrieves the length of RSA modulus in Bytes. 00415 * 00416 * \param ctx The initialized RSA context. 00417 * 00418 * \return The length of the RSA modulus in Bytes. 00419 * 00420 */ 00421 size_t mbedtls_rsa_get_len( const mbedtls_rsa_context *ctx ); 00422 00423 /** 00424 * \brief This function generates an RSA keypair. 00425 * 00426 * \note mbedtls_rsa_init() must be called before this function, 00427 * to set up the RSA context. 00428 * 00429 * \param ctx The initialized RSA context used to hold the key. 00430 * \param f_rng The RNG function to be used for key generation. 00431 * This must not be \c NULL. 00432 * \param p_rng The RNG context to be passed to \p f_rng. 00433 * This may be \c NULL if \p f_rng doesn't need a context. 00434 * \param nbits The size of the public key in bits. 00435 * \param exponent The public exponent to use. For example, \c 65537. 00436 * This must be odd and greater than \c 1. 00437 * 00438 * \return \c 0 on success. 00439 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 00440 */ 00441 int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx, 00442 int (*f_rng)(void *, unsigned char *, size_t), 00443 void *p_rng, 00444 unsigned int nbits, int exponent ); 00445 00446 /** 00447 * \brief This function checks if a context contains at least an RSA 00448 * public key. 00449 * 00450 * If the function runs successfully, it is guaranteed that 00451 * enough information is present to perform an RSA public key 00452 * operation using mbedtls_rsa_public(). 00453 * 00454 * \param ctx The initialized RSA context to check. 00455 * 00456 * \return \c 0 on success. 00457 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 00458 * 00459 */ 00460 int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx ); 00461 00462 /** 00463 * \brief This function checks if a context contains an RSA private key 00464 * and perform basic consistency checks. 00465 * 00466 * \note The consistency checks performed by this function not only 00467 * ensure that mbedtls_rsa_private() can be called successfully 00468 * on the given context, but that the various parameters are 00469 * mutually consistent with high probability, in the sense that 00470 * mbedtls_rsa_public() and mbedtls_rsa_private() are inverses. 00471 * 00472 * \warning This function should catch accidental misconfigurations 00473 * like swapping of parameters, but it cannot establish full 00474 * trust in neither the quality nor the consistency of the key 00475 * material that was used to setup the given RSA context: 00476 * <ul><li>Consistency: Imported parameters that are irrelevant 00477 * for the implementation might be silently dropped. If dropped, 00478 * the current function does not have access to them, 00479 * and therefore cannot check them. See mbedtls_rsa_complete(). 00480 * If you want to check the consistency of the entire 00481 * content of an PKCS1-encoded RSA private key, for example, you 00482 * should use mbedtls_rsa_validate_params() before setting 00483 * up the RSA context. 00484 * Additionally, if the implementation performs empirical checks, 00485 * these checks substantiate but do not guarantee consistency.</li> 00486 * <li>Quality: This function is not expected to perform 00487 * extended quality assessments like checking that the prime 00488 * factors are safe. Additionally, it is the responsibility of the 00489 * user to ensure the trustworthiness of the source of his RSA 00490 * parameters, which goes beyond what is effectively checkable 00491 * by the library.</li></ul> 00492 * 00493 * \param ctx The initialized RSA context to check. 00494 * 00495 * \return \c 0 on success. 00496 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 00497 */ 00498 int mbedtls_rsa_check_privkey( const mbedtls_rsa_context *ctx ); 00499 00500 /** 00501 * \brief This function checks a public-private RSA key pair. 00502 * 00503 * It checks each of the contexts, and makes sure they match. 00504 * 00505 * \param pub The initialized RSA context holding the public key. 00506 * \param prv The initialized RSA context holding the private key. 00507 * 00508 * \return \c 0 on success. 00509 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 00510 */ 00511 int mbedtls_rsa_check_pub_priv( const mbedtls_rsa_context *pub, 00512 const mbedtls_rsa_context *prv ); 00513 00514 /** 00515 * \brief This function performs an RSA public key operation. 00516 * 00517 * \param ctx The initialized RSA context to use. 00518 * \param input The input buffer. This must be a readable buffer 00519 * of length \c ctx->len Bytes. For example, \c 256 Bytes 00520 * for an 2048-bit RSA modulus. 00521 * \param output The output buffer. This must be a writable buffer 00522 * of length \c ctx->len Bytes. For example, \c 256 Bytes 00523 * for an 2048-bit RSA modulus. 00524 * 00525 * \note This function does not handle message padding. 00526 * 00527 * \note Make sure to set \p input[0] = 0 or ensure that 00528 * input is smaller than \p N. 00529 * 00530 * \return \c 0 on success. 00531 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 00532 */ 00533 int mbedtls_rsa_public( mbedtls_rsa_context *ctx, 00534 const unsigned char *input, 00535 unsigned char *output ); 00536 00537 /** 00538 * \brief This function performs an RSA private key operation. 00539 * 00540 * \note Blinding is used if and only if a PRNG is provided. 00541 * 00542 * \note If blinding is used, both the base of exponentation 00543 * and the exponent are blinded, providing protection 00544 * against some side-channel attacks. 00545 * 00546 * \warning It is deprecated and a security risk to not provide 00547 * a PRNG here and thereby prevent the use of blinding. 00548 * Future versions of the library may enforce the presence 00549 * of a PRNG. 00550 * 00551 * \param ctx The initialized RSA context to use. 00552 * \param f_rng The RNG function, used for blinding. It is discouraged 00553 * and deprecated to pass \c NULL here, in which case 00554 * blinding will be omitted. 00555 * \param p_rng The RNG context to pass to \p f_rng. This may be \c NULL 00556 * if \p f_rng is \c NULL or if \p f_rng doesn't need a context. 00557 * \param input The input buffer. This must be a readable buffer 00558 * of length \c ctx->len Bytes. For example, \c 256 Bytes 00559 * for an 2048-bit RSA modulus. 00560 * \param output The output buffer. This must be a writable buffer 00561 * of length \c ctx->len Bytes. For example, \c 256 Bytes 00562 * for an 2048-bit RSA modulus. 00563 * 00564 * \return \c 0 on success. 00565 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 00566 * 00567 */ 00568 int mbedtls_rsa_private( mbedtls_rsa_context *ctx, 00569 int (*f_rng)(void *, unsigned char *, size_t), 00570 void *p_rng, 00571 const unsigned char *input, 00572 unsigned char *output ); 00573 00574 /** 00575 * \brief This function adds the message padding, then performs an RSA 00576 * operation. 00577 * 00578 * It is the generic wrapper for performing a PKCS#1 encryption 00579 * operation using the \p mode from the context. 00580 * 00581 * \deprecated It is deprecated and discouraged to call this function 00582 * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library 00583 * are likely to remove the \p mode argument and have it 00584 * implicitly set to #MBEDTLS_RSA_PUBLIC. 00585 * 00586 * \note Alternative implementations of RSA need not support 00587 * mode being set to #MBEDTLS_RSA_PRIVATE and might instead 00588 * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. 00589 * 00590 * \param ctx The initialized RSA context to use. 00591 * \param f_rng The RNG to use. It is mandatory for PKCS#1 v2.1 padding 00592 * encoding, and for PKCS#1 v1.5 padding encoding when used 00593 * with \p mode set to #MBEDTLS_RSA_PUBLIC. For PKCS#1 v1.5 00594 * padding encoding and \p mode set to #MBEDTLS_RSA_PRIVATE, 00595 * it is used for blinding and should be provided in this 00596 * case; see mbedtls_rsa_private() for more. 00597 * \param p_rng The RNG context to be passed to \p f_rng. May be 00598 * \c NULL if \p f_rng is \c NULL or if \p f_rng doesn't 00599 * need a context argument. 00600 * \param mode The mode of operation. This must be either 00601 * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated). 00602 * \param ilen The length of the plaintext in Bytes. 00603 * \param input The input data to encrypt. This must be a readable 00604 * buffer of size \p ilen Bytes. It may be \c NULL if 00605 * `ilen == 0`. 00606 * \param output The output buffer. This must be a writable buffer 00607 * of length \c ctx->len Bytes. For example, \c 256 Bytes 00608 * for an 2048-bit RSA modulus. 00609 * 00610 * \return \c 0 on success. 00611 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 00612 */ 00613 int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx, 00614 int (*f_rng)(void *, unsigned char *, size_t), 00615 void *p_rng, 00616 int mode, size_t ilen, 00617 const unsigned char *input, 00618 unsigned char *output ); 00619 00620 /** 00621 * \brief This function performs a PKCS#1 v1.5 encryption operation 00622 * (RSAES-PKCS1-v1_5-ENCRYPT). 00623 * 00624 * \deprecated It is deprecated and discouraged to call this function 00625 * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library 00626 * are likely to remove the \p mode argument and have it 00627 * implicitly set to #MBEDTLS_RSA_PUBLIC. 00628 * 00629 * \note Alternative implementations of RSA need not support 00630 * mode being set to #MBEDTLS_RSA_PRIVATE and might instead 00631 * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. 00632 * 00633 * \param ctx The initialized RSA context to use. 00634 * \param f_rng The RNG function to use. It is needed for padding generation 00635 * if \p mode is #MBEDTLS_RSA_PUBLIC. If \p mode is 00636 * #MBEDTLS_RSA_PRIVATE (discouraged), it is used for 00637 * blinding and should be provided; see mbedtls_rsa_private(). 00638 * \param p_rng The RNG context to be passed to \p f_rng. This may 00639 * be \c NULL if \p f_rng is \c NULL or if \p f_rng 00640 * doesn't need a context argument. 00641 * \param mode The mode of operation. This must be either 00642 * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated). 00643 * \param ilen The length of the plaintext in Bytes. 00644 * \param input The input data to encrypt. This must be a readable 00645 * buffer of size \p ilen Bytes. It may be \c NULL if 00646 * `ilen == 0`. 00647 * \param output The output buffer. This must be a writable buffer 00648 * of length \c ctx->len Bytes. For example, \c 256 Bytes 00649 * for an 2048-bit RSA modulus. 00650 * 00651 * \return \c 0 on success. 00652 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 00653 */ 00654 int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx, 00655 int (*f_rng)(void *, unsigned char *, size_t), 00656 void *p_rng, 00657 int mode, size_t ilen, 00658 const unsigned char *input, 00659 unsigned char *output ); 00660 00661 /** 00662 * \brief This function performs a PKCS#1 v2.1 OAEP encryption 00663 * operation (RSAES-OAEP-ENCRYPT). 00664 * 00665 * \note The output buffer must be as large as the size 00666 * of ctx->N. For example, 128 Bytes if RSA-1024 is used. 00667 * 00668 * \deprecated It is deprecated and discouraged to call this function 00669 * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library 00670 * are likely to remove the \p mode argument and have it 00671 * implicitly set to #MBEDTLS_RSA_PUBLIC. 00672 * 00673 * \note Alternative implementations of RSA need not support 00674 * mode being set to #MBEDTLS_RSA_PRIVATE and might instead 00675 * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. 00676 * 00677 * \param ctx The initnialized RSA context to use. 00678 * \param f_rng The RNG function to use. This is needed for padding 00679 * generation and must be provided. 00680 * \param p_rng The RNG context to be passed to \p f_rng. This may 00681 * be \c NULL if \p f_rng doesn't need a context argument. 00682 * \param mode The mode of operation. This must be either 00683 * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated). 00684 * \param label The buffer holding the custom label to use. 00685 * This must be a readable buffer of length \p label_len 00686 * Bytes. It may be \c NULL if \p label_len is \c 0. 00687 * \param label_len The length of the label in Bytes. 00688 * \param ilen The length of the plaintext buffer \p input in Bytes. 00689 * \param input The input data to encrypt. This must be a readable 00690 * buffer of size \p ilen Bytes. It may be \c NULL if 00691 * `ilen == 0`. 00692 * \param output The output buffer. This must be a writable buffer 00693 * of length \c ctx->len Bytes. For example, \c 256 Bytes 00694 * for an 2048-bit RSA modulus. 00695 * 00696 * \return \c 0 on success. 00697 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 00698 */ 00699 int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx, 00700 int (*f_rng)(void *, unsigned char *, size_t), 00701 void *p_rng, 00702 int mode, 00703 const unsigned char *label, size_t label_len, 00704 size_t ilen, 00705 const unsigned char *input, 00706 unsigned char *output ); 00707 00708 /** 00709 * \brief This function performs an RSA operation, then removes the 00710 * message padding. 00711 * 00712 * It is the generic wrapper for performing a PKCS#1 decryption 00713 * operation using the \p mode from the context. 00714 * 00715 * \note The output buffer length \c output_max_len should be 00716 * as large as the size \p ctx->len of \p ctx->N (for example, 00717 * 128 Bytes if RSA-1024 is used) to be able to hold an 00718 * arbitrary decrypted message. If it is not large enough to 00719 * hold the decryption of the particular ciphertext provided, 00720 * the function returns \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. 00721 * 00722 * \deprecated It is deprecated and discouraged to call this function 00723 * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library 00724 * are likely to remove the \p mode argument and have it 00725 * implicitly set to #MBEDTLS_RSA_PRIVATE. 00726 * 00727 * \note Alternative implementations of RSA need not support 00728 * mode being set to #MBEDTLS_RSA_PUBLIC and might instead 00729 * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. 00730 * 00731 * \param ctx The initialized RSA context to use. 00732 * \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE, 00733 * this is used for blinding and should be provided; see 00734 * mbedtls_rsa_private() for more. If \p mode is 00735 * #MBEDTLS_RSA_PUBLIC, it is ignored. 00736 * \param p_rng The RNG context to be passed to \p f_rng. This may be 00737 * \c NULL if \p f_rng is \c NULL or doesn't need a context. 00738 * \param mode The mode of operation. This must be either 00739 * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated). 00740 * \param olen The address at which to store the length of 00741 * the plaintext. This must not be \c NULL. 00742 * \param input The ciphertext buffer. This must be a readable buffer 00743 * of length \c ctx->len Bytes. For example, \c 256 Bytes 00744 * for an 2048-bit RSA modulus. 00745 * \param output The buffer used to hold the plaintext. This must 00746 * be a writable buffer of length \p output_max_len Bytes. 00747 * \param output_max_len The length in Bytes of the output buffer \p output. 00748 * 00749 * \return \c 0 on success. 00750 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 00751 */ 00752 int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx, 00753 int (*f_rng)(void *, unsigned char *, size_t), 00754 void *p_rng, 00755 int mode, size_t *olen, 00756 const unsigned char *input, 00757 unsigned char *output, 00758 size_t output_max_len ); 00759 00760 /** 00761 * \brief This function performs a PKCS#1 v1.5 decryption 00762 * operation (RSAES-PKCS1-v1_5-DECRYPT). 00763 * 00764 * \note The output buffer length \c output_max_len should be 00765 * as large as the size \p ctx->len of \p ctx->N, for example, 00766 * 128 Bytes if RSA-1024 is used, to be able to hold an 00767 * arbitrary decrypted message. If it is not large enough to 00768 * hold the decryption of the particular ciphertext provided, 00769 * the function returns #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. 00770 * 00771 * \deprecated It is deprecated and discouraged to call this function 00772 * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library 00773 * are likely to remove the \p mode argument and have it 00774 * implicitly set to #MBEDTLS_RSA_PRIVATE. 00775 * 00776 * \note Alternative implementations of RSA need not support 00777 * mode being set to #MBEDTLS_RSA_PUBLIC and might instead 00778 * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. 00779 * 00780 * \param ctx The initialized RSA context to use. 00781 * \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE, 00782 * this is used for blinding and should be provided; see 00783 * mbedtls_rsa_private() for more. If \p mode is 00784 * #MBEDTLS_RSA_PUBLIC, it is ignored. 00785 * \param p_rng The RNG context to be passed to \p f_rng. This may be 00786 * \c NULL if \p f_rng is \c NULL or doesn't need a context. 00787 * \param mode The mode of operation. This must be either 00788 * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated). 00789 * \param olen The address at which to store the length of 00790 * the plaintext. This must not be \c NULL. 00791 * \param input The ciphertext buffer. This must be a readable buffer 00792 * of length \c ctx->len Bytes. For example, \c 256 Bytes 00793 * for an 2048-bit RSA modulus. 00794 * \param output The buffer used to hold the plaintext. This must 00795 * be a writable buffer of length \p output_max_len Bytes. 00796 * \param output_max_len The length in Bytes of the output buffer \p output. 00797 * 00798 * \return \c 0 on success. 00799 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 00800 * 00801 */ 00802 int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx, 00803 int (*f_rng)(void *, unsigned char *, size_t), 00804 void *p_rng, 00805 int mode, size_t *olen, 00806 const unsigned char *input, 00807 unsigned char *output, 00808 size_t output_max_len ); 00809 00810 /** 00811 * \brief This function performs a PKCS#1 v2.1 OAEP decryption 00812 * operation (RSAES-OAEP-DECRYPT). 00813 * 00814 * \note The output buffer length \c output_max_len should be 00815 * as large as the size \p ctx->len of \p ctx->N, for 00816 * example, 128 Bytes if RSA-1024 is used, to be able to 00817 * hold an arbitrary decrypted message. If it is not 00818 * large enough to hold the decryption of the particular 00819 * ciphertext provided, the function returns 00820 * #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. 00821 * 00822 * \deprecated It is deprecated and discouraged to call this function 00823 * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library 00824 * are likely to remove the \p mode argument and have it 00825 * implicitly set to #MBEDTLS_RSA_PRIVATE. 00826 * 00827 * \note Alternative implementations of RSA need not support 00828 * mode being set to #MBEDTLS_RSA_PUBLIC and might instead 00829 * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. 00830 * 00831 * \param ctx The initialized RSA context to use. 00832 * \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE, 00833 * this is used for blinding and should be provided; see 00834 * mbedtls_rsa_private() for more. If \p mode is 00835 * #MBEDTLS_RSA_PUBLIC, it is ignored. 00836 * \param p_rng The RNG context to be passed to \p f_rng. This may be 00837 * \c NULL if \p f_rng is \c NULL or doesn't need a context. 00838 * \param mode The mode of operation. This must be either 00839 * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated). 00840 * \param label The buffer holding the custom label to use. 00841 * This must be a readable buffer of length \p label_len 00842 * Bytes. It may be \c NULL if \p label_len is \c 0. 00843 * \param label_len The length of the label in Bytes. 00844 * \param olen The address at which to store the length of 00845 * the plaintext. This must not be \c NULL. 00846 * \param input The ciphertext buffer. This must be a readable buffer 00847 * of length \c ctx->len Bytes. For example, \c 256 Bytes 00848 * for an 2048-bit RSA modulus. 00849 * \param output The buffer used to hold the plaintext. This must 00850 * be a writable buffer of length \p output_max_len Bytes. 00851 * \param output_max_len The length in Bytes of the output buffer \p output. 00852 * 00853 * \return \c 0 on success. 00854 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 00855 */ 00856 int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx, 00857 int (*f_rng)(void *, unsigned char *, size_t), 00858 void *p_rng, 00859 int mode, 00860 const unsigned char *label, size_t label_len, 00861 size_t *olen, 00862 const unsigned char *input, 00863 unsigned char *output, 00864 size_t output_max_len ); 00865 00866 /** 00867 * \brief This function performs a private RSA operation to sign 00868 * a message digest using PKCS#1. 00869 * 00870 * It is the generic wrapper for performing a PKCS#1 00871 * signature using the \p mode from the context. 00872 * 00873 * \note The \p sig buffer must be as large as the size 00874 * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. 00875 * 00876 * \note For PKCS#1 v2.1 encoding, see comments on 00877 * mbedtls_rsa_rsassa_pss_sign() for details on 00878 * \p md_alg and \p hash_id. 00879 * 00880 * \deprecated It is deprecated and discouraged to call this function 00881 * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library 00882 * are likely to remove the \p mode argument and have it 00883 * implicitly set to #MBEDTLS_RSA_PRIVATE. 00884 * 00885 * \note Alternative implementations of RSA need not support 00886 * mode being set to #MBEDTLS_RSA_PUBLIC and might instead 00887 * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. 00888 * 00889 * \param ctx The initialized RSA context to use. 00890 * \param f_rng The RNG function to use. If the padding mode is PKCS#1 v2.1, 00891 * this must be provided. If the padding mode is PKCS#1 v1.5 and 00892 * \p mode is #MBEDTLS_RSA_PRIVATE, it is used for blinding 00893 * and should be provided; see mbedtls_rsa_private() for more 00894 * more. It is ignored otherwise. 00895 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL 00896 * if \p f_rng is \c NULL or doesn't need a context argument. 00897 * \param mode The mode of operation. This must be either 00898 * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated). 00899 * \param md_alg The message-digest algorithm used to hash the original data. 00900 * Use #MBEDTLS_MD_NONE for signing raw data. 00901 * \param hashlen The length of the message digest. 00902 * Ths is only used if \p md_alg is #MBEDTLS_MD_NONE. 00903 * \param hash The buffer holding the message digest or raw data. 00904 * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable 00905 * buffer of length \p hashlen Bytes. If \p md_alg is not 00906 * #MBEDTLS_MD_NONE, it must be a readable buffer of length 00907 * the size of the hash corresponding to \p md_alg. 00908 * \param sig The buffer to hold the signature. This must be a writable 00909 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 00910 * for an 2048-bit RSA modulus. 00911 * 00912 * \return \c 0 if the signing operation was successful. 00913 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 00914 */ 00915 int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx, 00916 int (*f_rng)(void *, unsigned char *, size_t), 00917 void *p_rng, 00918 int mode, 00919 mbedtls_md_type_t md_alg, 00920 unsigned int hashlen, 00921 const unsigned char *hash, 00922 unsigned char *sig ); 00923 00924 /** 00925 * \brief This function performs a PKCS#1 v1.5 signature 00926 * operation (RSASSA-PKCS1-v1_5-SIGN). 00927 * 00928 * \deprecated It is deprecated and discouraged to call this function 00929 * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library 00930 * are likely to remove the \p mode argument and have it 00931 * implicitly set to #MBEDTLS_RSA_PRIVATE. 00932 * 00933 * \note Alternative implementations of RSA need not support 00934 * mode being set to #MBEDTLS_RSA_PUBLIC and might instead 00935 * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. 00936 * 00937 * \param ctx The initialized RSA context to use. 00938 * \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE, 00939 * this is used for blinding and should be provided; see 00940 * mbedtls_rsa_private() for more. If \p mode is 00941 * #MBEDTLS_RSA_PUBLIC, it is ignored. 00942 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL 00943 * if \p f_rng is \c NULL or doesn't need a context argument. 00944 * \param mode The mode of operation. This must be either 00945 * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated). 00946 * \param md_alg The message-digest algorithm used to hash the original data. 00947 * Use #MBEDTLS_MD_NONE for signing raw data. 00948 * \param hashlen The length of the message digest. 00949 * Ths is only used if \p md_alg is #MBEDTLS_MD_NONE. 00950 * \param hash The buffer holding the message digest or raw data. 00951 * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable 00952 * buffer of length \p hashlen Bytes. If \p md_alg is not 00953 * #MBEDTLS_MD_NONE, it must be a readable buffer of length 00954 * the size of the hash corresponding to \p md_alg. 00955 * \param sig The buffer to hold the signature. This must be a writable 00956 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 00957 * for an 2048-bit RSA modulus. 00958 * 00959 * \return \c 0 if the signing operation was successful. 00960 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 00961 */ 00962 int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx, 00963 int (*f_rng)(void *, unsigned char *, size_t), 00964 void *p_rng, 00965 int mode, 00966 mbedtls_md_type_t md_alg, 00967 unsigned int hashlen, 00968 const unsigned char *hash, 00969 unsigned char *sig ); 00970 00971 /** 00972 * \brief This function performs a PKCS#1 v2.1 PSS signature 00973 * operation (RSASSA-PSS-SIGN). 00974 * 00975 * \note The \p hash_id in the RSA context is the one used for the 00976 * encoding. \p md_alg in the function call is the type of hash 00977 * that is encoded. According to <em>RFC-3447: Public-Key 00978 * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography 00979 * Specifications</em> it is advised to keep both hashes the 00980 * same. 00981 * 00982 * \note This function always uses the maximum possible salt size, 00983 * up to the length of the payload hash. This choice of salt 00984 * size complies with FIPS 186-4 §5.5 (e) and RFC 8017 (PKCS#1 00985 * v2.2) §9.1.1 step 3. Furthermore this function enforces a 00986 * minimum salt size which is the hash size minus 2 bytes. If 00987 * this minimum size is too large given the key size (the salt 00988 * size, plus the hash size, plus 2 bytes must be no more than 00989 * the key size in bytes), this function returns 00990 * #MBEDTLS_ERR_RSA_BAD_INPUT_DATA. 00991 * 00992 * \deprecated It is deprecated and discouraged to call this function 00993 * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library 00994 * are likely to remove the \p mode argument and have it 00995 * implicitly set to #MBEDTLS_RSA_PRIVATE. 00996 * 00997 * \note Alternative implementations of RSA need not support 00998 * mode being set to #MBEDTLS_RSA_PUBLIC and might instead 00999 * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. 01000 * 01001 * \param ctx The initialized RSA context to use. 01002 * \param f_rng The RNG function. It must not be \c NULL. 01003 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL 01004 * if \p f_rng doesn't need a context argument. 01005 * \param mode The mode of operation. This must be either 01006 * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated). 01007 * \param md_alg The message-digest algorithm used to hash the original data. 01008 * Use #MBEDTLS_MD_NONE for signing raw data. 01009 * \param hashlen The length of the message digest. 01010 * Ths is only used if \p md_alg is #MBEDTLS_MD_NONE. 01011 * \param hash The buffer holding the message digest or raw data. 01012 * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable 01013 * buffer of length \p hashlen Bytes. If \p md_alg is not 01014 * #MBEDTLS_MD_NONE, it must be a readable buffer of length 01015 * the size of the hash corresponding to \p md_alg. 01016 * \param sig The buffer to hold the signature. This must be a writable 01017 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 01018 * for an 2048-bit RSA modulus. 01019 * 01020 * \return \c 0 if the signing operation was successful. 01021 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 01022 */ 01023 int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx, 01024 int (*f_rng)(void *, unsigned char *, size_t), 01025 void *p_rng, 01026 int mode, 01027 mbedtls_md_type_t md_alg, 01028 unsigned int hashlen, 01029 const unsigned char *hash, 01030 unsigned char *sig ); 01031 01032 /** 01033 * \brief This function performs a public RSA operation and checks 01034 * the message digest. 01035 * 01036 * This is the generic wrapper for performing a PKCS#1 01037 * verification using the mode from the context. 01038 * 01039 * \note For PKCS#1 v2.1 encoding, see comments on 01040 * mbedtls_rsa_rsassa_pss_verify() about \p md_alg and 01041 * \p hash_id. 01042 * 01043 * \deprecated It is deprecated and discouraged to call this function 01044 * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library 01045 * are likely to remove the \p mode argument and have it 01046 * set to #MBEDTLS_RSA_PUBLIC. 01047 * 01048 * \note Alternative implementations of RSA need not support 01049 * mode being set to #MBEDTLS_RSA_PRIVATE and might instead 01050 * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. 01051 * 01052 * \param ctx The initialized RSA public key context to use. 01053 * \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE, 01054 * this is used for blinding and should be provided; see 01055 * mbedtls_rsa_private() for more. Otherwise, it is ignored. 01056 * \param p_rng The RNG context to be passed to \p f_rng. This may be 01057 * \c NULL if \p f_rng is \c NULL or doesn't need a context. 01058 * \param mode The mode of operation. This must be either 01059 * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated). 01060 * \param md_alg The message-digest algorithm used to hash the original data. 01061 * Use #MBEDTLS_MD_NONE for signing raw data. 01062 * \param hashlen The length of the message digest. 01063 * This is only used if \p md_alg is #MBEDTLS_MD_NONE. 01064 * \param hash The buffer holding the message digest or raw data. 01065 * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable 01066 * buffer of length \p hashlen Bytes. If \p md_alg is not 01067 * #MBEDTLS_MD_NONE, it must be a readable buffer of length 01068 * the size of the hash corresponding to \p md_alg. 01069 * \param sig The buffer holding the signature. This must be a readable 01070 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 01071 * for an 2048-bit RSA modulus. 01072 * 01073 * \return \c 0 if the verify operation was successful. 01074 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 01075 */ 01076 int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx, 01077 int (*f_rng)(void *, unsigned char *, size_t), 01078 void *p_rng, 01079 int mode, 01080 mbedtls_md_type_t md_alg, 01081 unsigned int hashlen, 01082 const unsigned char *hash, 01083 const unsigned char *sig ); 01084 01085 /** 01086 * \brief This function performs a PKCS#1 v1.5 verification 01087 * operation (RSASSA-PKCS1-v1_5-VERIFY). 01088 * 01089 * \deprecated It is deprecated and discouraged to call this function 01090 * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library 01091 * are likely to remove the \p mode argument and have it 01092 * set to #MBEDTLS_RSA_PUBLIC. 01093 * 01094 * \note Alternative implementations of RSA need not support 01095 * mode being set to #MBEDTLS_RSA_PRIVATE and might instead 01096 * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. 01097 * 01098 * \param ctx The initialized RSA public key context to use. 01099 * \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE, 01100 * this is used for blinding and should be provided; see 01101 * mbedtls_rsa_private() for more. Otherwise, it is ignored. 01102 * \param p_rng The RNG context to be passed to \p f_rng. This may be 01103 * \c NULL if \p f_rng is \c NULL or doesn't need a context. 01104 * \param mode The mode of operation. This must be either 01105 * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated). 01106 * \param md_alg The message-digest algorithm used to hash the original data. 01107 * Use #MBEDTLS_MD_NONE for signing raw data. 01108 * \param hashlen The length of the message digest. 01109 * This is only used if \p md_alg is #MBEDTLS_MD_NONE. 01110 * \param hash The buffer holding the message digest or raw data. 01111 * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable 01112 * buffer of length \p hashlen Bytes. If \p md_alg is not 01113 * #MBEDTLS_MD_NONE, it must be a readable buffer of length 01114 * the size of the hash corresponding to \p md_alg. 01115 * \param sig The buffer holding the signature. This must be a readable 01116 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 01117 * for an 2048-bit RSA modulus. 01118 * 01119 * \return \c 0 if the verify operation was successful. 01120 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 01121 */ 01122 int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx, 01123 int (*f_rng)(void *, unsigned char *, size_t), 01124 void *p_rng, 01125 int mode, 01126 mbedtls_md_type_t md_alg, 01127 unsigned int hashlen, 01128 const unsigned char *hash, 01129 const unsigned char *sig ); 01130 01131 /** 01132 * \brief This function performs a PKCS#1 v2.1 PSS verification 01133 * operation (RSASSA-PSS-VERIFY). 01134 * 01135 * The hash function for the MGF mask generating function 01136 * is that specified in the RSA context. 01137 * 01138 * \note The \p hash_id in the RSA context is the one used for the 01139 * verification. \p md_alg in the function call is the type of 01140 * hash that is verified. According to <em>RFC-3447: Public-Key 01141 * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography 01142 * Specifications</em> it is advised to keep both hashes the 01143 * same. If \p hash_id in the RSA context is unset, 01144 * the \p md_alg from the function call is used. 01145 * 01146 * \deprecated It is deprecated and discouraged to call this function 01147 * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library 01148 * are likely to remove the \p mode argument and have it 01149 * implicitly set to #MBEDTLS_RSA_PUBLIC. 01150 * 01151 * \note Alternative implementations of RSA need not support 01152 * mode being set to #MBEDTLS_RSA_PRIVATE and might instead 01153 * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED. 01154 * 01155 * \param ctx The initialized RSA public key context to use. 01156 * \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE, 01157 * this is used for blinding and should be provided; see 01158 * mbedtls_rsa_private() for more. Otherwise, it is ignored. 01159 * \param p_rng The RNG context to be passed to \p f_rng. This may be 01160 * \c NULL if \p f_rng is \c NULL or doesn't need a context. 01161 * \param mode The mode of operation. This must be either 01162 * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated). 01163 * \param md_alg The message-digest algorithm used to hash the original data. 01164 * Use #MBEDTLS_MD_NONE for signing raw data. 01165 * \param hashlen The length of the message digest. 01166 * This is only used if \p md_alg is #MBEDTLS_MD_NONE. 01167 * \param hash The buffer holding the message digest or raw data. 01168 * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable 01169 * buffer of length \p hashlen Bytes. If \p md_alg is not 01170 * #MBEDTLS_MD_NONE, it must be a readable buffer of length 01171 * the size of the hash corresponding to \p md_alg. 01172 * \param sig The buffer holding the signature. This must be a readable 01173 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 01174 * for an 2048-bit RSA modulus. 01175 * 01176 * \return \c 0 if the verify operation was successful. 01177 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 01178 */ 01179 int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx, 01180 int (*f_rng)(void *, unsigned char *, size_t), 01181 void *p_rng, 01182 int mode, 01183 mbedtls_md_type_t md_alg, 01184 unsigned int hashlen, 01185 const unsigned char *hash, 01186 const unsigned char *sig ); 01187 01188 /** 01189 * \brief This function performs a PKCS#1 v2.1 PSS verification 01190 * operation (RSASSA-PSS-VERIFY). 01191 * 01192 * The hash function for the MGF mask generating function 01193 * is that specified in \p mgf1_hash_id. 01194 * 01195 * \note The \p sig buffer must be as large as the size 01196 * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. 01197 * 01198 * \note The \p hash_id in the RSA context is ignored. 01199 * 01200 * \param ctx The initialized RSA public key context to use. 01201 * \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE, 01202 * this is used for blinding and should be provided; see 01203 * mbedtls_rsa_private() for more. Otherwise, it is ignored. 01204 * \param p_rng The RNG context to be passed to \p f_rng. This may be 01205 * \c NULL if \p f_rng is \c NULL or doesn't need a context. 01206 * \param mode The mode of operation. This must be either 01207 * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. 01208 * \param md_alg The message-digest algorithm used to hash the original data. 01209 * Use #MBEDTLS_MD_NONE for signing raw data. 01210 * \param hashlen The length of the message digest. 01211 * This is only used if \p md_alg is #MBEDTLS_MD_NONE. 01212 * \param hash The buffer holding the message digest or raw data. 01213 * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable 01214 * buffer of length \p hashlen Bytes. If \p md_alg is not 01215 * #MBEDTLS_MD_NONE, it must be a readable buffer of length 01216 * the size of the hash corresponding to \p md_alg. 01217 * \param mgf1_hash_id The message digest used for mask generation. 01218 * \param expected_salt_len The length of the salt used in padding. Use 01219 * #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length. 01220 * \param sig The buffer holding the signature. This must be a readable 01221 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 01222 * for an 2048-bit RSA modulus. 01223 * 01224 * \return \c 0 if the verify operation was successful. 01225 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 01226 */ 01227 int mbedtls_rsa_rsassa_pss_verify_ext( mbedtls_rsa_context *ctx, 01228 int (*f_rng)(void *, unsigned char *, size_t), 01229 void *p_rng, 01230 int mode, 01231 mbedtls_md_type_t md_alg, 01232 unsigned int hashlen, 01233 const unsigned char *hash, 01234 mbedtls_md_type_t mgf1_hash_id, 01235 int expected_salt_len, 01236 const unsigned char *sig ); 01237 01238 /** 01239 * \brief This function copies the components of an RSA context. 01240 * 01241 * \param dst The destination context. This must be initialized. 01242 * \param src The source context. This must be initialized. 01243 * 01244 * \return \c 0 on success. 01245 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure. 01246 */ 01247 int mbedtls_rsa_copy( mbedtls_rsa_context *dst, const mbedtls_rsa_context *src ); 01248 01249 /** 01250 * \brief This function frees the components of an RSA key. 01251 * 01252 * \param ctx The RSA context to free. May be \c NULL, in which case 01253 * this function is a no-op. If it is not \c NULL, it must 01254 * point to an initialized RSA context. 01255 */ 01256 void mbedtls_rsa_free( mbedtls_rsa_context *ctx ); 01257 01258 #if defined(MBEDTLS_SELF_TEST) 01259 01260 /** 01261 * \brief The RSA checkup routine. 01262 * 01263 * \return \c 0 on success. 01264 * \return \c 1 on failure. 01265 */ 01266 int mbedtls_rsa_self_test( int verbose ); 01267 01268 #endif /* MBEDTLS_SELF_TEST */ 01269 01270 #ifdef __cplusplus 01271 } 01272 #endif 01273 01274 #endif /* rsa.h */
Generated on Tue Jul 12 2022 13:54:48 by
1.7.2