EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2026-05-10 08:44:50
0001 /** 0002 * \file rsa.h 0003 * 0004 * \brief This file provides an API for the RSA public-key cryptosystem. 0005 * 0006 * The RSA public-key cryptosystem is defined in <em>Public-Key 0007 * Cryptography Standards (PKCS) #1 v1.5: RSA Encryption</em> 0008 * and <em>Public-Key Cryptography Standards (PKCS) #1 v2.1: 0009 * RSA Cryptography Specifications</em>. 0010 * 0011 */ 0012 /* 0013 * Copyright The Mbed TLS Contributors 0014 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 0015 */ 0016 #ifndef MBEDTLS_RSA_H 0017 #define MBEDTLS_RSA_H 0018 #include "mbedtls/private_access.h" 0019 0020 #include "tf-psa-crypto/build_info.h" 0021 0022 #include "mbedtls/private/bignum.h" 0023 #include "mbedtls/md.h" 0024 0025 #if defined(MBEDTLS_THREADING_C) 0026 #include "mbedtls/threading.h" 0027 #endif 0028 0029 /* 0030 * RSA Error codes 0031 */ 0032 /** Bad input parameters to function. */ 0033 #define MBEDTLS_ERR_RSA_BAD_INPUT_DATA PSA_ERROR_INVALID_ARGUMENT 0034 /** Input data contains invalid padding and is rejected. */ 0035 #define MBEDTLS_ERR_RSA_INVALID_PADDING PSA_ERROR_INVALID_PADDING 0036 /** Something failed during generation of a key. */ 0037 #define MBEDTLS_ERR_RSA_KEY_GEN_FAILED -0x4180 0038 /** Key failed to pass the validity check of the library. */ 0039 #define MBEDTLS_ERR_RSA_KEY_CHECK_FAILED -0x4200 0040 /** The public key operation failed. */ 0041 #define MBEDTLS_ERR_RSA_PUBLIC_FAILED -0x4280 0042 /** The private key operation failed. */ 0043 #define MBEDTLS_ERR_RSA_PRIVATE_FAILED -0x4300 0044 /** The PKCS#1 verification failed. */ 0045 #define MBEDTLS_ERR_RSA_VERIFY_FAILED PSA_ERROR_INVALID_SIGNATURE 0046 /** The output buffer for decryption is not large enough. */ 0047 #define MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE PSA_ERROR_BUFFER_TOO_SMALL 0048 /** The random generator failed to generate non-zeros. */ 0049 #define MBEDTLS_ERR_RSA_RNG_FAILED -0x4480 0050 0051 /* 0052 * RSA constants 0053 */ 0054 0055 #define MBEDTLS_RSA_PKCS_V15 0 /**< Use PKCS#1 v1.5 encoding. */ 0056 #define MBEDTLS_RSA_PKCS_V21 1 /**< Use PKCS#1 v2.1 encoding. */ 0057 0058 #define MBEDTLS_RSA_SIGN 1 /**< Identifier for RSA signature operations. */ 0059 #define MBEDTLS_RSA_CRYPT 2 /**< Identifier for RSA encryption and decryption operations. */ 0060 0061 #define MBEDTLS_RSA_SALT_LEN_ANY -1 0062 0063 /* 0064 * The above constants may be used even if the RSA module is compile out, 0065 * eg for alternative (PKCS#11) RSA implementations in the PK layers. 0066 */ 0067 0068 #ifdef __cplusplus 0069 extern "C" { 0070 #endif 0071 0072 #if !defined(MBEDTLS_RSA_GEN_KEY_MIN_BITS) 0073 #define MBEDTLS_RSA_GEN_KEY_MIN_BITS 1024 0074 #elif MBEDTLS_RSA_GEN_KEY_MIN_BITS < 128 0075 #error "MBEDTLS_RSA_GEN_KEY_MIN_BITS must be at least 128 bits" 0076 #endif 0077 0078 /** 0079 * \brief The RSA context structure. 0080 */ 0081 typedef struct mbedtls_rsa_context { 0082 int MBEDTLS_PRIVATE(ver); /*!< Reserved for internal purposes. 0083 * Do not set this field in application 0084 * code. Its meaning might change without 0085 * notice. */ 0086 size_t MBEDTLS_PRIVATE(len); /*!< The size of \p N in Bytes. */ 0087 0088 mbedtls_mpi MBEDTLS_PRIVATE(N); /*!< The public modulus. */ 0089 mbedtls_mpi MBEDTLS_PRIVATE(E); /*!< The public exponent. */ 0090 0091 mbedtls_mpi MBEDTLS_PRIVATE(D); /*!< The private exponent. */ 0092 mbedtls_mpi MBEDTLS_PRIVATE(P); /*!< The first prime factor. */ 0093 mbedtls_mpi MBEDTLS_PRIVATE(Q); /*!< The second prime factor. */ 0094 0095 mbedtls_mpi MBEDTLS_PRIVATE(DP); /*!< <code>D % (P - 1)</code>. */ 0096 mbedtls_mpi MBEDTLS_PRIVATE(DQ); /*!< <code>D % (Q - 1)</code>. */ 0097 mbedtls_mpi MBEDTLS_PRIVATE(QP); /*!< <code>1 / (Q % P)</code>. */ 0098 0099 mbedtls_mpi MBEDTLS_PRIVATE(RN); /*!< cached <code>R^2 mod N</code>. */ 0100 0101 mbedtls_mpi MBEDTLS_PRIVATE(RP); /*!< cached <code>R^2 mod P</code>. */ 0102 mbedtls_mpi MBEDTLS_PRIVATE(RQ); /*!< cached <code>R^2 mod Q</code>. */ 0103 0104 mbedtls_mpi MBEDTLS_PRIVATE(Vi); /*!< The cached blinding value. */ 0105 mbedtls_mpi MBEDTLS_PRIVATE(Vf); /*!< The cached un-blinding value. */ 0106 0107 int MBEDTLS_PRIVATE(padding); /*!< Selects padding mode: 0108 #MBEDTLS_RSA_PKCS_V15 for 1.5 padding and 0109 #MBEDTLS_RSA_PKCS_V21 for OAEP or PSS. */ 0110 int MBEDTLS_PRIVATE(hash_id); /*!< Hash identifier of mbedtls_md_type_t type, 0111 as specified in md.h for use in the MGF 0112 mask generating function used in the 0113 EME-OAEP and EMSA-PSS encodings. */ 0114 #if defined(MBEDTLS_THREADING_C) 0115 /* Invariant: the mutex is initialized iff ver != 0. */ 0116 mbedtls_threading_mutex_t MBEDTLS_PRIVATE(mutex); /*!< Thread-safety mutex. */ 0117 #endif 0118 } 0119 mbedtls_rsa_context; 0120 0121 /** 0122 * \brief This function initializes an RSA context. 0123 * 0124 * \note This function initializes the padding and the hash 0125 * identifier to respectively #MBEDTLS_RSA_PKCS_V15 and 0126 * #MBEDTLS_MD_NONE. See mbedtls_rsa_set_padding() for more 0127 * information about those parameters. 0128 * 0129 * \param ctx The RSA context to initialize. This must not be \c NULL. 0130 */ 0131 void mbedtls_rsa_init(mbedtls_rsa_context *ctx); 0132 0133 /** 0134 * \brief This function sets padding for an already initialized RSA 0135 * context. 0136 * 0137 * \note Set padding to #MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP 0138 * encryption scheme and the RSASSA-PSS signature scheme. 0139 * 0140 * \note The \p hash_id parameter is ignored when using 0141 * #MBEDTLS_RSA_PKCS_V15 padding. 0142 * 0143 * \note The choice of padding mode is strictly enforced for private 0144 * key operations, since there might be security concerns in 0145 * mixing padding modes. For public key operations it is 0146 * a default value, which can be overridden by calling specific 0147 * \c mbedtls_rsa_rsaes_xxx or \c mbedtls_rsa_rsassa_xxx 0148 * functions. 0149 * 0150 * \note The hash selected in \p hash_id is always used for OEAP 0151 * encryption. For PSS signatures, it is always used for 0152 * making signatures, but can be overridden for verifying them. 0153 * If set to #MBEDTLS_MD_NONE, it is always overridden. 0154 * 0155 * \param ctx The initialized RSA context to be configured. 0156 * \param padding The padding mode to use. This must be either 0157 * #MBEDTLS_RSA_PKCS_V15 or #MBEDTLS_RSA_PKCS_V21. 0158 * \param hash_id The hash identifier for PSS or OAEP, if \p padding is 0159 * #MBEDTLS_RSA_PKCS_V21. #MBEDTLS_MD_NONE is accepted by this 0160 * function but may be not suitable for some operations. 0161 * Ignored if \p padding is #MBEDTLS_RSA_PKCS_V15. 0162 * 0163 * \return \c 0 on success. 0164 * \return #MBEDTLS_ERR_RSA_INVALID_PADDING failure: 0165 * \p padding or \p hash_id is invalid. 0166 */ 0167 int mbedtls_rsa_set_padding(mbedtls_rsa_context *ctx, int padding, 0168 mbedtls_md_type_t hash_id); 0169 0170 /** 0171 * \brief This function retrieves padding mode of initialized 0172 * RSA context. 0173 * 0174 * \param ctx The initialized RSA context. 0175 * 0176 * \return RSA padding mode. 0177 * 0178 */ 0179 int mbedtls_rsa_get_padding_mode(const mbedtls_rsa_context *ctx); 0180 0181 /** 0182 * \brief This function retrieves hash identifier of mbedtls_md_type_t 0183 * type. 0184 * 0185 * \param ctx The initialized RSA context. 0186 * 0187 * \return Hash identifier of mbedtls_md_type_t type. 0188 * 0189 */ 0190 int mbedtls_rsa_get_md_alg(const mbedtls_rsa_context *ctx); 0191 0192 /** 0193 * \brief This function imports a set of core parameters into an 0194 * RSA context. 0195 * 0196 * \note This function can be called multiple times for successive 0197 * imports, if the parameters are not simultaneously present. 0198 * 0199 * Any sequence of calls to this function should be followed 0200 * by a call to mbedtls_rsa_complete(), which checks and 0201 * completes the provided information to a ready-for-use 0202 * public or private RSA key. 0203 * 0204 * \note See mbedtls_rsa_complete() for more information on which 0205 * parameters are necessary to set up a private or public 0206 * RSA key. 0207 * 0208 * \note The imported parameters are copied and need not be preserved 0209 * for the lifetime of the RSA context being set up. 0210 * 0211 * \param ctx The initialized RSA context to store the parameters in. 0212 * \param N The RSA modulus. This may be \c NULL. 0213 * \param P The first prime factor of \p N. This may be \c NULL. 0214 * \param Q The second prime factor of \p N. This may be \c NULL. 0215 * \param D The private exponent. This may be \c NULL. 0216 * \param E The public exponent. This may be \c NULL. 0217 * 0218 * \return \c 0 on success. 0219 * \return A non-zero error code on failure. 0220 */ 0221 int mbedtls_rsa_import(mbedtls_rsa_context *ctx, 0222 const mbedtls_mpi *N, 0223 const mbedtls_mpi *P, const mbedtls_mpi *Q, 0224 const mbedtls_mpi *D, const mbedtls_mpi *E); 0225 0226 /** 0227 * \brief This function imports core RSA parameters, in raw big-endian 0228 * binary format, into an RSA context. 0229 * 0230 * \note This function can be called multiple times for successive 0231 * imports, if the parameters are not simultaneously present. 0232 * 0233 * Any sequence of calls to this function should be followed 0234 * by a call to mbedtls_rsa_complete(), which checks and 0235 * completes the provided information to a ready-for-use 0236 * public or private RSA key. 0237 * 0238 * \note See mbedtls_rsa_complete() for more information on which 0239 * parameters are necessary to set up a private or public 0240 * RSA key. 0241 * 0242 * \note The imported parameters are copied and need not be preserved 0243 * for the lifetime of the RSA context being set up. 0244 * 0245 * \param ctx The initialized RSA context to store the parameters in. 0246 * \param N The RSA modulus. This may be \c NULL. 0247 * \param N_len The Byte length of \p N; it is ignored if \p N == NULL. 0248 * \param P The first prime factor of \p N. This may be \c NULL. 0249 * \param P_len The Byte length of \p P; it is ignored if \p P == NULL. 0250 * \param Q The second prime factor of \p N. This may be \c NULL. 0251 * \param Q_len The Byte length of \p Q; it is ignored if \p Q == NULL. 0252 * \param D The private exponent. This may be \c NULL. 0253 * \param D_len The Byte length of \p D; it is ignored if \p D == NULL. 0254 * \param E The public exponent. This may be \c NULL. 0255 * \param E_len The Byte length of \p E; it is ignored if \p E == NULL. 0256 * 0257 * \return \c 0 on success. 0258 * \return A non-zero error code on failure. 0259 */ 0260 int mbedtls_rsa_import_raw(mbedtls_rsa_context *ctx, 0261 unsigned char const *N, size_t N_len, 0262 unsigned char const *P, size_t P_len, 0263 unsigned char const *Q, size_t Q_len, 0264 unsigned char const *D, size_t D_len, 0265 unsigned char const *E, size_t E_len); 0266 0267 /** 0268 * \brief This function completes an RSA context from 0269 * a set of imported core parameters. 0270 * 0271 * To setup an RSA public key, precisely \c N and \c E 0272 * must have been imported. 0273 * 0274 * To setup an RSA private key, sufficient information must 0275 * be present for the other parameters to be derivable. 0276 * 0277 * The default implementation supports the following: 0278 * <ul><li>Derive \c P, \c Q from \c N, \c D, \c E.</li> 0279 * <li>Derive \c N, \c D from \c P, \c Q, \c E.</li></ul> 0280 * Alternative implementations need not support these. 0281 * 0282 * If this function runs successfully, it guarantees that 0283 * the RSA context can be used for RSA operations without 0284 * the risk of failure or crash. 0285 * 0286 * \warning This function need not perform consistency checks 0287 * for the imported parameters. In particular, parameters that 0288 * are not needed by the implementation might be silently 0289 * discarded and left unchecked. To check the consistency 0290 * of the key material, see mbedtls_rsa_check_privkey(). 0291 * 0292 * \param ctx The initialized RSA context holding imported parameters. 0293 * 0294 * \return \c 0 on success. 0295 * \return #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted derivations 0296 * failed. 0297 * 0298 */ 0299 int mbedtls_rsa_complete(mbedtls_rsa_context *ctx); 0300 0301 /** 0302 * \brief This function exports the core parameters of an RSA key. 0303 * 0304 * If this function runs successfully, the non-NULL buffers 0305 * pointed to by \p N, \p P, \p Q, \p D, and \p E are fully 0306 * written, with additional unused space filled leading by 0307 * zero Bytes. 0308 * 0309 * Possible reasons for returning 0310 * #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED:<ul> 0311 * <li>An alternative RSA implementation is in use, which 0312 * stores the key externally, and either cannot or should 0313 * not export it into RAM.</li> 0314 * <li>A SW or HW implementation might not support a certain 0315 * deduction. For example, \p P, \p Q from \p N, \p D, 0316 * and \p E if the former are not part of the 0317 * implementation.</li></ul> 0318 * 0319 * If the function fails due to an unsupported operation, 0320 * the RSA context stays intact and remains usable. 0321 * 0322 * \param ctx The initialized RSA context. 0323 * \param N The MPI to hold the RSA modulus. 0324 * This may be \c NULL if this field need not be exported. 0325 * \param P The MPI to hold the first prime factor of \p N. 0326 * This may be \c NULL if this field need not be exported. 0327 * \param Q The MPI to hold the second prime factor of \p N. 0328 * This may be \c NULL if this field need not be exported. 0329 * \param D The MPI to hold the private exponent. 0330 * This may be \c NULL if this field need not be exported. 0331 * \param E The MPI to hold the public exponent. 0332 * This may be \c NULL if this field need not be exported. 0333 * 0334 * \return \c 0 on success. 0335 * \return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED if exporting the 0336 * requested parameters cannot be done due to missing 0337 * functionality or because of security policies. 0338 * \return A non-zero return code on any other failure. 0339 * 0340 */ 0341 int mbedtls_rsa_export(const mbedtls_rsa_context *ctx, 0342 mbedtls_mpi *N, mbedtls_mpi *P, mbedtls_mpi *Q, 0343 mbedtls_mpi *D, mbedtls_mpi *E); 0344 0345 /** 0346 * \brief This function exports core parameters of an RSA key 0347 * in raw big-endian binary format. 0348 * 0349 * If this function runs successfully, the non-NULL buffers 0350 * pointed to by \p N, \p P, \p Q, \p D, and \p E are fully 0351 * written, with additional unused space filled leading by 0352 * zero Bytes. 0353 * 0354 * Possible reasons for returning 0355 * #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED:<ul> 0356 * <li>An alternative RSA implementation is in use, which 0357 * stores the key externally, and either cannot or should 0358 * not export it into RAM.</li> 0359 * <li>A SW or HW implementation might not support a certain 0360 * deduction. For example, \p P, \p Q from \p N, \p D, 0361 * and \p E if the former are not part of the 0362 * implementation.</li></ul> 0363 * If the function fails due to an unsupported operation, 0364 * the RSA context stays intact and remains usable. 0365 * 0366 * \note The length parameters are ignored if the corresponding 0367 * buffer pointers are NULL. 0368 * 0369 * \param ctx The initialized RSA context. 0370 * \param N The Byte array to store the RSA modulus, 0371 * or \c NULL if this field need not be exported. 0372 * \param N_len The size of the buffer for the modulus. 0373 * \param P The Byte array to hold the first prime factor of \p N, 0374 * or \c NULL if this field need not be exported. 0375 * \param P_len The size of the buffer for the first prime factor. 0376 * \param Q The Byte array to hold the second prime factor of \p N, 0377 * or \c NULL if this field need not be exported. 0378 * \param Q_len The size of the buffer for the second prime factor. 0379 * \param D The Byte array to hold the private exponent, 0380 * or \c NULL if this field need not be exported. 0381 * \param D_len The size of the buffer for the private exponent. 0382 * \param E The Byte array to hold the public exponent, 0383 * or \c NULL if this field need not be exported. 0384 * \param E_len The size of the buffer for the public exponent. 0385 * 0386 * \return \c 0 on success. 0387 * \return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED if exporting the 0388 * requested parameters cannot be done due to missing 0389 * functionality or because of security policies. 0390 * \return A non-zero return code on any other failure. 0391 */ 0392 int mbedtls_rsa_export_raw(const mbedtls_rsa_context *ctx, 0393 unsigned char *N, size_t N_len, 0394 unsigned char *P, size_t P_len, 0395 unsigned char *Q, size_t Q_len, 0396 unsigned char *D, size_t D_len, 0397 unsigned char *E, size_t E_len); 0398 0399 /** 0400 * \brief This function exports CRT parameters of a private RSA key. 0401 * 0402 * \note Alternative RSA implementations not using CRT-parameters 0403 * internally can implement this function based on 0404 * mbedtls_rsa_deduce_opt(). 0405 * 0406 * \param ctx The initialized RSA context. 0407 * \param DP The MPI to hold \c D modulo `P-1`, 0408 * or \c NULL if it need not be exported. 0409 * \param DQ The MPI to hold \c D modulo `Q-1`, 0410 * or \c NULL if it need not be exported. 0411 * \param QP The MPI to hold modular inverse of \c Q modulo \c P, 0412 * or \c NULL if it need not be exported. 0413 * 0414 * \return \c 0 on success. 0415 * \return A non-zero error code on failure. 0416 * 0417 */ 0418 int mbedtls_rsa_export_crt(const mbedtls_rsa_context *ctx, 0419 mbedtls_mpi *DP, mbedtls_mpi *DQ, mbedtls_mpi *QP); 0420 0421 /** 0422 * \brief This function retrieves the length of the RSA modulus in bits. 0423 * 0424 * \param ctx The initialized RSA context. 0425 * 0426 * \return The length of the RSA modulus in bits. 0427 * 0428 */ 0429 size_t mbedtls_rsa_get_bitlen(const mbedtls_rsa_context *ctx); 0430 0431 /** 0432 * \brief This function retrieves the length of RSA modulus in Bytes. 0433 * 0434 * \param ctx The initialized RSA context. 0435 * 0436 * \return The length of the RSA modulus in Bytes. 0437 * 0438 */ 0439 size_t mbedtls_rsa_get_len(const mbedtls_rsa_context *ctx); 0440 0441 /** 0442 * \brief This function generates an RSA keypair. 0443 * 0444 * \note mbedtls_rsa_init() must be called before this function, 0445 * to set up the RSA context. 0446 * 0447 * \param ctx The initialized RSA context used to hold the key. 0448 * \param f_rng The RNG function to be used for key generation. 0449 * This is mandatory and must not be \c NULL. 0450 * \param p_rng The RNG context to be passed to \p f_rng. 0451 * This may be \c NULL if \p f_rng doesn't need a context. 0452 * \param nbits The size of the public key in bits. 0453 * \param exponent The public exponent to use. For example, \c 65537. 0454 * This must be odd and greater than \c 1. 0455 * 0456 * \return \c 0 on success. 0457 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 0458 */ 0459 int mbedtls_rsa_gen_key(mbedtls_rsa_context *ctx, 0460 int (*f_rng)(void *, unsigned char *, size_t), 0461 void *p_rng, 0462 unsigned int nbits, int exponent); 0463 0464 /** 0465 * \brief This function checks if a context contains at least an RSA 0466 * public key. 0467 * 0468 * If the function runs successfully, it is guaranteed that 0469 * enough information is present to perform an RSA public key 0470 * operation using mbedtls_rsa_public(). 0471 * 0472 * \param ctx The initialized RSA context to check. 0473 * 0474 * \return \c 0 on success. 0475 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 0476 * 0477 */ 0478 int mbedtls_rsa_check_pubkey(const mbedtls_rsa_context *ctx); 0479 0480 /** 0481 * \brief This function checks if a context contains an RSA private key 0482 * and perform basic consistency checks. 0483 * 0484 * \note The consistency checks performed by this function not only 0485 * ensure that mbedtls_rsa_private() can be called successfully 0486 * on the given context, but that the various parameters are 0487 * mutually consistent with high probability, in the sense that 0488 * mbedtls_rsa_public() and mbedtls_rsa_private() are inverses. 0489 * 0490 * \warning This function should catch accidental misconfigurations 0491 * like swapping of parameters, but it cannot establish full 0492 * trust in neither the quality nor the consistency of the key 0493 * material that was used to setup the given RSA context: 0494 * <ul><li>Consistency: Imported parameters that are irrelevant 0495 * for the implementation might be silently dropped. If dropped, 0496 * the current function does not have access to them, 0497 * and therefore cannot check them. See mbedtls_rsa_complete(). 0498 * If you want to check the consistency of the entire 0499 * content of a PKCS1-encoded RSA private key, for example, you 0500 * should use mbedtls_rsa_validate_params() before setting 0501 * up the RSA context. 0502 * Additionally, if the implementation performs empirical checks, 0503 * these checks substantiate but do not guarantee consistency.</li> 0504 * <li>Quality: This function is not expected to perform 0505 * extended quality assessments like checking that the prime 0506 * factors are safe. Additionally, it is the responsibility of the 0507 * user to ensure the trustworthiness of the source of his RSA 0508 * parameters, which goes beyond what is effectively checkable 0509 * by the library.</li></ul> 0510 * 0511 * \param ctx The initialized RSA context to check. 0512 * 0513 * \return \c 0 on success. 0514 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 0515 */ 0516 int mbedtls_rsa_check_privkey(const mbedtls_rsa_context *ctx); 0517 0518 /** 0519 * \brief This function checks a public-private RSA key pair. 0520 * 0521 * It checks each of the contexts, and makes sure they match. 0522 * 0523 * \param pub The initialized RSA context holding the public key. 0524 * \param prv The initialized RSA context holding the private key. 0525 * 0526 * \return \c 0 on success. 0527 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 0528 */ 0529 int mbedtls_rsa_check_pub_priv(const mbedtls_rsa_context *pub, 0530 const mbedtls_rsa_context *prv); 0531 0532 /** 0533 * \brief This function performs an RSA public key operation. 0534 * 0535 * \param ctx The initialized RSA context to use. 0536 * \param input The input buffer. This must be a readable buffer 0537 * of length \c ctx->len Bytes. For example, \c 256 Bytes 0538 * for an 2048-bit RSA modulus. 0539 * \param output The output buffer. This must be a writable buffer 0540 * of length \c ctx->len Bytes. For example, \c 256 Bytes 0541 * for an 2048-bit RSA modulus. 0542 * 0543 * \note This function does not handle message padding. 0544 * 0545 * \note Make sure to set \p input[0] = 0 or ensure that 0546 * input is smaller than \c N. 0547 * 0548 * \return \c 0 on success. 0549 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 0550 */ 0551 int mbedtls_rsa_public(mbedtls_rsa_context *ctx, 0552 const unsigned char *input, 0553 unsigned char *output); 0554 0555 /** 0556 * \brief This function performs an RSA private key operation. 0557 * 0558 * \note Blinding is used if and only if a PRNG is provided. 0559 * 0560 * \note If blinding is used, both the base of exponentiation 0561 * and the exponent are blinded, providing protection 0562 * against some side-channel attacks. 0563 * 0564 * \warning It is deprecated and a security risk to not provide 0565 * a PRNG here and thereby prevent the use of blinding. 0566 * Future versions of the library may enforce the presence 0567 * of a PRNG. 0568 * 0569 * \param ctx The initialized RSA context to use. 0570 * \param f_rng The RNG function, used for blinding. It is mandatory. 0571 * \param p_rng The RNG context to pass to \p f_rng. This may be \c NULL 0572 * if \p f_rng doesn't need a context. 0573 * \param input The input buffer. This must be a readable buffer 0574 * of length \c ctx->len Bytes. For example, \c 256 Bytes 0575 * for an 2048-bit RSA modulus. 0576 * \param output The output buffer. This must be a writable buffer 0577 * of length \c ctx->len Bytes. For example, \c 256 Bytes 0578 * for an 2048-bit RSA modulus. 0579 * 0580 * \return \c 0 on success. 0581 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 0582 * 0583 */ 0584 int mbedtls_rsa_private(mbedtls_rsa_context *ctx, 0585 int (*f_rng)(void *, unsigned char *, size_t), 0586 void *p_rng, 0587 const unsigned char *input, 0588 unsigned char *output); 0589 0590 /** 0591 * \brief This function adds the message padding, then performs an RSA 0592 * operation. 0593 * 0594 * It is the generic wrapper for performing a PKCS#1 encryption 0595 * operation. 0596 * 0597 * \param ctx The initialized RSA context to use. 0598 * \param f_rng The RNG to use. It is used for padding generation 0599 * and it is mandatory. 0600 * \param p_rng The RNG context to be passed to \p f_rng. May be 0601 * \c NULL if \p f_rng doesn't need a context argument. 0602 * \param ilen The length of the plaintext in Bytes. 0603 * \param input The input data to encrypt. This must be a readable 0604 * buffer of size \p ilen Bytes. It may be \c NULL if 0605 * `ilen == 0`. 0606 * \param output The output buffer. This must be a writable buffer 0607 * of length \c ctx->len Bytes. For example, \c 256 Bytes 0608 * for an 2048-bit RSA modulus. 0609 * 0610 * \return \c 0 on success. 0611 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 0612 */ 0613 int mbedtls_rsa_pkcs1_encrypt(mbedtls_rsa_context *ctx, 0614 int (*f_rng)(void *, unsigned char *, size_t), 0615 void *p_rng, 0616 size_t ilen, 0617 const unsigned char *input, 0618 unsigned char *output); 0619 0620 /** 0621 * \brief This function performs a PKCS#1 v1.5 encryption operation 0622 * (RSAES-PKCS1-v1_5-ENCRYPT). 0623 * 0624 * \param ctx The initialized RSA context to use. 0625 * \param f_rng The RNG function to use. It is mandatory and used for 0626 * padding generation. 0627 * \param p_rng The RNG context to be passed to \p f_rng. This may 0628 * be \c NULL if \p f_rng doesn't need a context argument. 0629 * \param ilen The length of the plaintext in Bytes. 0630 * \param input The input data to encrypt. This must be a readable 0631 * buffer of size \p ilen Bytes. It may be \c NULL if 0632 * `ilen == 0`. 0633 * \param output The output buffer. This must be a writable buffer 0634 * of length \c ctx->len Bytes. For example, \c 256 Bytes 0635 * for an 2048-bit RSA modulus. 0636 * 0637 * \return \c 0 on success. 0638 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 0639 */ 0640 int mbedtls_rsa_rsaes_pkcs1_v15_encrypt(mbedtls_rsa_context *ctx, 0641 int (*f_rng)(void *, unsigned char *, size_t), 0642 void *p_rng, 0643 size_t ilen, 0644 const unsigned char *input, 0645 unsigned char *output); 0646 0647 /** 0648 * \brief This function performs a PKCS#1 v2.1 OAEP encryption 0649 * operation (RSAES-OAEP-ENCRYPT). 0650 * 0651 * \note The output buffer must be as large as the size 0652 * of ctx->N. For example, 128 Bytes if RSA-1024 is used. 0653 * 0654 * \param ctx The initialized RSA context to use. 0655 * \param f_rng The RNG function to use. This is needed for padding 0656 * generation and is mandatory. 0657 * \param p_rng The RNG context to be passed to \p f_rng. This may 0658 * be \c NULL if \p f_rng doesn't need a context argument. 0659 * \param label The buffer holding the custom label to use. 0660 * This must be a readable buffer of length \p label_len 0661 * Bytes. It may be \c NULL if \p label_len is \c 0. 0662 * \param label_len The length of the label in Bytes. 0663 * \param ilen The length of the plaintext buffer \p input in Bytes. 0664 * \param input The input data to encrypt. This must be a readable 0665 * buffer of size \p ilen Bytes. It may be \c NULL if 0666 * `ilen == 0`. 0667 * \param output The output buffer. This must be a writable buffer 0668 * of length \c ctx->len Bytes. For example, \c 256 Bytes 0669 * for an 2048-bit RSA modulus. 0670 * 0671 * \return \c 0 on success. 0672 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 0673 */ 0674 int mbedtls_rsa_rsaes_oaep_encrypt(mbedtls_rsa_context *ctx, 0675 int (*f_rng)(void *, unsigned char *, size_t), 0676 void *p_rng, 0677 const unsigned char *label, size_t label_len, 0678 size_t ilen, 0679 const unsigned char *input, 0680 unsigned char *output); 0681 0682 /** 0683 * \brief This function performs an RSA operation, then removes the 0684 * message padding. 0685 * 0686 * It is the generic wrapper for performing a PKCS#1 decryption 0687 * operation. 0688 * 0689 * \warning When \p ctx->padding is set to #MBEDTLS_RSA_PKCS_V15, 0690 * mbedtls_rsa_rsaes_pkcs1_v15_decrypt() is called, which is an 0691 * inherently dangerous function (CWE-242). 0692 * 0693 * \note The output buffer length \c output_max_len should be 0694 * as large as the size \p ctx->len of \p ctx->N (for example, 0695 * 128 Bytes if RSA-1024 is used) to be able to hold an 0696 * arbitrary decrypted message. If it is not large enough to 0697 * hold the decryption of the particular ciphertext provided, 0698 * the function returns \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. 0699 * 0700 * \param ctx The initialized RSA context to use. 0701 * \param f_rng The RNG function. This is used for blinding and is 0702 * mandatory; see mbedtls_rsa_private() for more. 0703 * \param p_rng The RNG context to be passed to \p f_rng. This may be 0704 * \c NULL if \p f_rng doesn't need a context. 0705 * \param olen The address at which to store the length of 0706 * the plaintext. This must not be \c NULL. 0707 * \param input The ciphertext buffer. This must be a readable buffer 0708 * of length \c ctx->len Bytes. For example, \c 256 Bytes 0709 * for an 2048-bit RSA modulus. 0710 * \param output The buffer used to hold the plaintext. This must 0711 * be a writable buffer of length \p output_max_len Bytes. 0712 * \param output_max_len The length in Bytes of the output buffer \p output. 0713 * 0714 * \return \c 0 on success. 0715 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 0716 */ 0717 int mbedtls_rsa_pkcs1_decrypt(mbedtls_rsa_context *ctx, 0718 int (*f_rng)(void *, unsigned char *, size_t), 0719 void *p_rng, 0720 size_t *olen, 0721 const unsigned char *input, 0722 unsigned char *output, 0723 size_t output_max_len); 0724 0725 /** 0726 * \brief This function performs a PKCS#1 v1.5 decryption 0727 * operation (RSAES-PKCS1-v1_5-DECRYPT). 0728 * 0729 * \warning This is an inherently dangerous function (CWE-242). Unless 0730 * it is used in a side channel free and safe way (eg. 0731 * implementing the TLS protocol as per 7.4.7.1 of RFC 5246), 0732 * the calling code is vulnerable. 0733 * 0734 * \note The output buffer length \c output_max_len should be 0735 * as large as the size \p ctx->len of \p ctx->N, for example, 0736 * 128 Bytes if RSA-1024 is used, to be able to hold an 0737 * arbitrary decrypted message. If it is not large enough to 0738 * hold the decryption of the particular ciphertext provided, 0739 * the function returns #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. 0740 * 0741 * \param ctx The initialized RSA context to use. 0742 * \param f_rng The RNG function. This is used for blinding and is 0743 * mandatory; see mbedtls_rsa_private() for more. 0744 * \param p_rng The RNG context to be passed to \p f_rng. This may be 0745 * \c NULL if \p f_rng doesn't need a context. 0746 * \param olen The address at which to store the length of 0747 * the plaintext. This must not be \c NULL. 0748 * \param input The ciphertext buffer. This must be a readable buffer 0749 * of length \c ctx->len Bytes. For example, \c 256 Bytes 0750 * for an 2048-bit RSA modulus. 0751 * \param output The buffer used to hold the plaintext. This must 0752 * be a writable buffer of length \p output_max_len Bytes. 0753 * \param output_max_len The length in Bytes of the output buffer \p output. 0754 * 0755 * \return \c 0 on success. 0756 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 0757 * 0758 */ 0759 int mbedtls_rsa_rsaes_pkcs1_v15_decrypt(mbedtls_rsa_context *ctx, 0760 int (*f_rng)(void *, unsigned char *, size_t), 0761 void *p_rng, 0762 size_t *olen, 0763 const unsigned char *input, 0764 unsigned char *output, 0765 size_t output_max_len); 0766 0767 /** 0768 * \brief This function performs a PKCS#1 v2.1 OAEP decryption 0769 * operation (RSAES-OAEP-DECRYPT). 0770 * 0771 * \note The output buffer length \c output_max_len should be 0772 * as large as the size \p ctx->len of \p ctx->N, for 0773 * example, 128 Bytes if RSA-1024 is used, to be able to 0774 * hold an arbitrary decrypted message. If it is not 0775 * large enough to hold the decryption of the particular 0776 * ciphertext provided, the function returns 0777 * #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. 0778 * 0779 * \param ctx The initialized RSA context to use. 0780 * \param f_rng The RNG function. This is used for blinding and is 0781 * mandatory. 0782 * \param p_rng The RNG context to be passed to \p f_rng. This may be 0783 * \c NULL if \p f_rng doesn't need a context. 0784 * \param label The buffer holding the custom label to use. 0785 * This must be a readable buffer of length \p label_len 0786 * Bytes. It may be \c NULL if \p label_len is \c 0. 0787 * \param label_len The length of the label in Bytes. 0788 * \param olen The address at which to store the length of 0789 * the plaintext. This must not be \c NULL. 0790 * \param input The ciphertext buffer. This must be a readable buffer 0791 * of length \c ctx->len Bytes. For example, \c 256 Bytes 0792 * for an 2048-bit RSA modulus. 0793 * \param output The buffer used to hold the plaintext. This must 0794 * be a writable buffer of length \p output_max_len Bytes. 0795 * \param output_max_len The length in Bytes of the output buffer \p output. 0796 * 0797 * \return \c 0 on success. 0798 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 0799 */ 0800 int mbedtls_rsa_rsaes_oaep_decrypt(mbedtls_rsa_context *ctx, 0801 int (*f_rng)(void *, unsigned char *, size_t), 0802 void *p_rng, 0803 const unsigned char *label, size_t label_len, 0804 size_t *olen, 0805 const unsigned char *input, 0806 unsigned char *output, 0807 size_t output_max_len); 0808 0809 /** 0810 * \brief This function performs a private RSA operation to sign 0811 * a message digest using PKCS#1. 0812 * 0813 * It is the generic wrapper for performing a PKCS#1 0814 * signature. 0815 * 0816 * \note The \p sig buffer must be as large as the size 0817 * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. 0818 * 0819 * \note For PKCS#1 v2.1 encoding, see comments on 0820 * mbedtls_rsa_rsassa_pss_sign() for details on 0821 * \p md_alg and \p hash_id. 0822 * 0823 * \param ctx The initialized RSA context to use. 0824 * \param f_rng The RNG function to use. This is mandatory and 0825 * must not be \c NULL. 0826 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL 0827 * if \p f_rng doesn't need a context argument. 0828 * \param md_alg The message-digest algorithm used to hash the original data. 0829 * Use #MBEDTLS_MD_NONE for signing raw data. 0830 * \param hashlen The length of the message digest or raw data in Bytes. 0831 * If \p md_alg is not #MBEDTLS_MD_NONE, this must match the 0832 * output length of the corresponding hash algorithm. 0833 * \param hash The buffer holding the message digest or raw data. 0834 * This must be a readable buffer of at least \p hashlen Bytes. 0835 * \param sig The buffer to hold the signature. This must be a writable 0836 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 0837 * for an 2048-bit RSA modulus. A buffer length of 0838 * #MBEDTLS_MPI_MAX_SIZE is always safe. 0839 * 0840 * \return \c 0 if the signing operation was successful. 0841 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 0842 */ 0843 int mbedtls_rsa_pkcs1_sign(mbedtls_rsa_context *ctx, 0844 int (*f_rng)(void *, unsigned char *, size_t), 0845 void *p_rng, 0846 mbedtls_md_type_t md_alg, 0847 unsigned int hashlen, 0848 const unsigned char *hash, 0849 unsigned char *sig); 0850 0851 /** 0852 * \brief This function performs a PKCS#1 v1.5 signature 0853 * operation (RSASSA-PKCS1-v1_5-SIGN). 0854 * 0855 * \param ctx The initialized RSA context to use. 0856 * \param f_rng The RNG function. This is used for blinding and is 0857 * mandatory; see mbedtls_rsa_private() for more. 0858 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL 0859 * if \p f_rng doesn't need a context argument. 0860 * \param md_alg The message-digest algorithm used to hash the original data. 0861 * Use #MBEDTLS_MD_NONE for signing raw data. 0862 * \param hashlen The length of the message digest or raw data in Bytes. 0863 * If \p md_alg is not #MBEDTLS_MD_NONE, this must match the 0864 * output length of the corresponding hash algorithm. 0865 * \param hash The buffer holding the message digest or raw data. 0866 * This must be a readable buffer of at least \p hashlen Bytes. 0867 * \param sig The buffer to hold the signature. This must be a writable 0868 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 0869 * for an 2048-bit RSA modulus. A buffer length of 0870 * #MBEDTLS_MPI_MAX_SIZE is always safe. 0871 * 0872 * \return \c 0 if the signing operation was successful. 0873 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 0874 */ 0875 int mbedtls_rsa_rsassa_pkcs1_v15_sign(mbedtls_rsa_context *ctx, 0876 int (*f_rng)(void *, unsigned char *, size_t), 0877 void *p_rng, 0878 mbedtls_md_type_t md_alg, 0879 unsigned int hashlen, 0880 const unsigned char *hash, 0881 unsigned char *sig); 0882 0883 #if defined(MBEDTLS_PKCS1_V21) 0884 /** 0885 * \brief This function performs a PKCS#1 v2.1 PSS signature 0886 * operation (RSASSA-PSS-SIGN). 0887 * 0888 * \note The \c hash_id set in \p ctx by calling 0889 * mbedtls_rsa_set_padding() selects the hash used for the 0890 * encoding operation and for the mask generation function 0891 * (MGF1). For more details on the encoding operation and the 0892 * mask generation function, consult <em>RFC-3447: Public-Key 0893 * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography 0894 * Specifications</em>. 0895 * 0896 * \note This function enforces that the provided salt length complies 0897 * with FIPS 186-4 §5.5 (e) and RFC 8017 (PKCS#1 v2.2) §9.1.1 0898 * step 3. The constraint is that the hash length plus the salt 0899 * length plus 2 bytes must be at most the key length. If this 0900 * constraint is not met, this function returns 0901 * #MBEDTLS_ERR_RSA_BAD_INPUT_DATA. 0902 * 0903 * \param ctx The initialized RSA context to use. 0904 * \param f_rng The RNG function. It is mandatory and must not be \c NULL. 0905 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL 0906 * if \p f_rng doesn't need a context argument. 0907 * \param md_alg The message-digest algorithm used to hash the original data. 0908 * Use #MBEDTLS_MD_NONE for signing raw data. 0909 * \param hashlen The length of the message digest or raw data in Bytes. 0910 * If \p md_alg is not #MBEDTLS_MD_NONE, this must match the 0911 * output length of the corresponding hash algorithm. 0912 * \param hash The buffer holding the message digest or raw data. 0913 * This must be a readable buffer of at least \p hashlen Bytes. 0914 * \param saltlen The length of the salt that should be used. 0915 * If passed #MBEDTLS_RSA_SALT_LEN_ANY, the function will use 0916 * the largest possible salt length up to the hash length, 0917 * which is the largest permitted by some standards including 0918 * FIPS 186-4 §5.5. 0919 * \param sig The buffer to hold the signature. This must be a writable 0920 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 0921 * for an 2048-bit RSA modulus. A buffer length of 0922 * #MBEDTLS_MPI_MAX_SIZE is always safe. 0923 * 0924 * \return \c 0 if the signing operation was successful. 0925 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 0926 */ 0927 int mbedtls_rsa_rsassa_pss_sign_ext(mbedtls_rsa_context *ctx, 0928 int (*f_rng)(void *, unsigned char *, size_t), 0929 void *p_rng, 0930 mbedtls_md_type_t md_alg, 0931 unsigned int hashlen, 0932 const unsigned char *hash, 0933 int saltlen, 0934 unsigned char *sig); 0935 0936 /** 0937 * \brief This function performs a PKCS#1 v2.1 PSS signature 0938 * operation (RSASSA-PSS-SIGN). 0939 * 0940 * \note The \c hash_id set in \p ctx by calling 0941 * mbedtls_rsa_set_padding() selects the hash used for the 0942 * encoding operation and for the mask generation function 0943 * (MGF1). For more details on the encoding operation and the 0944 * mask generation function, consult <em>RFC-3447: Public-Key 0945 * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography 0946 * Specifications</em>. 0947 * 0948 * \note This function always uses the maximum possible salt size, 0949 * up to the length of the payload hash. This choice of salt 0950 * size complies with FIPS 186-4 §5.5 (e) and RFC 8017 (PKCS#1 0951 * v2.2) §9.1.1 step 3. Furthermore this function enforces a 0952 * minimum salt size which is the hash size minus 2 bytes. If 0953 * this minimum size is too large given the key size (the salt 0954 * size, plus the hash size, plus 2 bytes must be no more than 0955 * the key size in bytes), this function returns 0956 * #MBEDTLS_ERR_RSA_BAD_INPUT_DATA. 0957 * 0958 * \param ctx The initialized RSA context to use. 0959 * \param f_rng The RNG function. It is mandatory and must not be \c NULL. 0960 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL 0961 * if \p f_rng doesn't need a context argument. 0962 * \param md_alg The message-digest algorithm used to hash the original data. 0963 * Use #MBEDTLS_MD_NONE for signing raw data. 0964 * \param hashlen The length of the message digest or raw data in Bytes. 0965 * If \p md_alg is not #MBEDTLS_MD_NONE, this must match the 0966 * output length of the corresponding hash algorithm. 0967 * \param hash The buffer holding the message digest or raw data. 0968 * This must be a readable buffer of at least \p hashlen Bytes. 0969 * \param sig The buffer to hold the signature. This must be a writable 0970 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 0971 * for an 2048-bit RSA modulus. A buffer length of 0972 * #MBEDTLS_MPI_MAX_SIZE is always safe. 0973 * 0974 * \return \c 0 if the signing operation was successful. 0975 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 0976 */ 0977 int mbedtls_rsa_rsassa_pss_sign(mbedtls_rsa_context *ctx, 0978 int (*f_rng)(void *, unsigned char *, size_t), 0979 void *p_rng, 0980 mbedtls_md_type_t md_alg, 0981 unsigned int hashlen, 0982 const unsigned char *hash, 0983 unsigned char *sig); 0984 #endif /* MBEDTLS_PKCS1_V21 */ 0985 0986 /** 0987 * \brief This function performs a public RSA operation and checks 0988 * the message digest. 0989 * 0990 * This is the generic wrapper for performing a PKCS#1 0991 * verification. 0992 * 0993 * \note For PKCS#1 v2.1 encoding, see comments on 0994 * mbedtls_rsa_rsassa_pss_verify() about \c md_alg and 0995 * \c hash_id. 0996 * 0997 * \param ctx The initialized RSA public key context to use. 0998 * \param md_alg The message-digest algorithm used to hash the original data. 0999 * Use #MBEDTLS_MD_NONE for signing raw data. 1000 * \param hashlen The length of the message digest or raw data in Bytes. 1001 * If \p md_alg is not #MBEDTLS_MD_NONE, this must match the 1002 * output length of the corresponding hash algorithm. 1003 * \param hash The buffer holding the message digest or raw data. 1004 * This must be a readable buffer of at least \p hashlen Bytes. 1005 * \param sig The buffer holding the signature. This must be a readable 1006 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 1007 * for an 2048-bit RSA modulus. 1008 * 1009 * \return \c 0 if the verify operation was successful. 1010 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 1011 */ 1012 int mbedtls_rsa_pkcs1_verify(mbedtls_rsa_context *ctx, 1013 mbedtls_md_type_t md_alg, 1014 unsigned int hashlen, 1015 const unsigned char *hash, 1016 const unsigned char *sig); 1017 1018 /** 1019 * \brief This function performs a PKCS#1 v1.5 verification 1020 * operation (RSASSA-PKCS1-v1_5-VERIFY). 1021 * 1022 * \param ctx The initialized RSA public key context to use. 1023 * \param md_alg The message-digest algorithm used to hash the original data. 1024 * Use #MBEDTLS_MD_NONE for signing raw data. 1025 * \param hashlen The length of the message digest or raw data in Bytes. 1026 * If \p md_alg is not #MBEDTLS_MD_NONE, this must match the 1027 * output length of the corresponding hash algorithm. 1028 * \param hash The buffer holding the message digest or raw data. 1029 * This must be a readable buffer of at least \p hashlen Bytes. 1030 * \param sig The buffer holding the signature. This must be a readable 1031 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 1032 * for an 2048-bit RSA modulus. 1033 * 1034 * \return \c 0 if the verify operation was successful. 1035 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 1036 */ 1037 int mbedtls_rsa_rsassa_pkcs1_v15_verify(mbedtls_rsa_context *ctx, 1038 mbedtls_md_type_t md_alg, 1039 unsigned int hashlen, 1040 const unsigned char *hash, 1041 const unsigned char *sig); 1042 1043 /** 1044 * \brief This function performs a PKCS#1 v2.1 PSS verification 1045 * operation (RSASSA-PSS-VERIFY). 1046 * 1047 * \note The \c hash_id set in \p ctx by calling 1048 * mbedtls_rsa_set_padding() selects the hash used for the 1049 * encoding operation and for the mask generation function 1050 * (MGF1). For more details on the encoding operation and the 1051 * mask generation function, consult <em>RFC-3447: Public-Key 1052 * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography 1053 * Specifications</em>. If the \c hash_id set in \p ctx by 1054 * mbedtls_rsa_set_padding() is #MBEDTLS_MD_NONE, the \p md_alg 1055 * parameter is used. 1056 * 1057 * \param ctx The initialized RSA public key context to use. 1058 * \param md_alg The message-digest algorithm used to hash the original data. 1059 * Use #MBEDTLS_MD_NONE for signing raw data. 1060 * \param hashlen The length of the message digest or raw data in Bytes. 1061 * If \p md_alg is not #MBEDTLS_MD_NONE, this must match the 1062 * output length of the corresponding hash algorithm. 1063 * \param hash The buffer holding the message digest or raw data. 1064 * This must be a readable buffer of at least \p hashlen Bytes. 1065 * \param sig The buffer holding the signature. This must be a readable 1066 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 1067 * for an 2048-bit RSA modulus. 1068 * 1069 * \return \c 0 if the verify operation was successful. 1070 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 1071 */ 1072 int mbedtls_rsa_rsassa_pss_verify(mbedtls_rsa_context *ctx, 1073 mbedtls_md_type_t md_alg, 1074 unsigned int hashlen, 1075 const unsigned char *hash, 1076 const unsigned char *sig); 1077 1078 /** 1079 * \brief This function performs a PKCS#1 v2.1 PSS verification 1080 * operation (RSASSA-PSS-VERIFY). 1081 * 1082 * \note The \p sig buffer must be as large as the size 1083 * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. 1084 * 1085 * \note The \c hash_id set in \p ctx by mbedtls_rsa_set_padding() is 1086 * ignored. 1087 * 1088 * \param ctx The initialized RSA public key context to use. 1089 * \param md_alg The message-digest algorithm used to hash the original data. 1090 * Use #MBEDTLS_MD_NONE for signing raw data. 1091 * \param hashlen The length of the message digest or raw data in Bytes. 1092 * If \p md_alg is not #MBEDTLS_MD_NONE, this must match the 1093 * output length of the corresponding hash algorithm. 1094 * \param hash The buffer holding the message digest or raw data. 1095 * This must be a readable buffer of at least \p hashlen Bytes. 1096 * \param mgf1_hash_id The message digest algorithm used for the 1097 * verification operation and the mask generation 1098 * function (MGF1). For more details on the encoding 1099 * operation and the mask generation function, consult 1100 * <em>RFC-3447: Public-Key Cryptography Standards 1101 * (PKCS) #1 v2.1: RSA Cryptography 1102 * Specifications</em>. 1103 * \param expected_salt_len The length of the salt used in padding. Use 1104 * #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length. 1105 * \param sig The buffer holding the signature. This must be a readable 1106 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 1107 * for an 2048-bit RSA modulus. 1108 * 1109 * \return \c 0 if the verify operation was successful. 1110 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 1111 */ 1112 int mbedtls_rsa_rsassa_pss_verify_ext(mbedtls_rsa_context *ctx, 1113 mbedtls_md_type_t md_alg, 1114 unsigned int hashlen, 1115 const unsigned char *hash, 1116 mbedtls_md_type_t mgf1_hash_id, 1117 int expected_salt_len, 1118 const unsigned char *sig); 1119 1120 /** 1121 * \brief This function copies the components of an RSA context. 1122 * 1123 * \param dst The destination context. This must be initialized. 1124 * \param src The source context. This must be initialized. 1125 * 1126 * \return \c 0 on success. 1127 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure. 1128 */ 1129 int mbedtls_rsa_copy(mbedtls_rsa_context *dst, const mbedtls_rsa_context *src); 1130 1131 /** 1132 * \brief This function frees the components of an RSA key. 1133 * 1134 * \param ctx The RSA context to free. May be \c NULL, in which case 1135 * this function is a no-op. If it is not \c NULL, it must 1136 * point to an initialized RSA context. 1137 */ 1138 void mbedtls_rsa_free(mbedtls_rsa_context *ctx); 1139 1140 #if defined(MBEDTLS_SELF_TEST) 1141 1142 /** 1143 * \brief The RSA checkup routine. 1144 * 1145 * \return \c 0 on success. 1146 * \return \c 1 on failure. 1147 */ 1148 int mbedtls_rsa_self_test(int verbose); 1149 1150 #endif /* MBEDTLS_SELF_TEST */ 1151 1152 #ifdef __cplusplus 1153 } 1154 #endif 1155 1156 #endif /* rsa.h */
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|