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