rsa.h 51 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138
  1. /**
  2. * \file rsa.h
  3. *
  4. * \brief The RSA public-key cryptosystem.
  5. *
  6. * For more information, see <em>Public-Key Cryptography Standards (PKCS)
  7. * #1 v1.5: RSA Encryption</em> and <em>Public-Key Cryptography Standards
  8. * (PKCS) #1 v2.1: RSA Cryptography Specifications</em>.
  9. *
  10. */
  11. /*
  12. * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  13. * SPDX-License-Identifier: Apache-2.0
  14. *
  15. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  16. * not use this file except in compliance with the License.
  17. * You may obtain a copy of the License at
  18. *
  19. * http://www.apache.org/licenses/LICENSE-2.0
  20. *
  21. * Unless required by applicable law or agreed to in writing, software
  22. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  23. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  24. * See the License for the specific language governing permissions and
  25. * limitations under the License.
  26. *
  27. * This file is part of Mbed TLS (https://tls.mbed.org)
  28. */
  29. #ifndef MBEDTLS_RSA_H
  30. #define MBEDTLS_RSA_H
  31. #if !defined(MBEDTLS_CONFIG_FILE)
  32. #include "config.h"
  33. #else
  34. #include MBEDTLS_CONFIG_FILE
  35. #endif
  36. #include "bignum.h"
  37. #include "md.h"
  38. #if defined(MBEDTLS_THREADING_C)
  39. #include "threading.h"
  40. #endif
  41. /*
  42. * RSA Error codes
  43. */
  44. #define MBEDTLS_ERR_RSA_BAD_INPUT_DATA -0x4080 /**< Bad input parameters to function. */
  45. #define MBEDTLS_ERR_RSA_INVALID_PADDING -0x4100 /**< Input data contains invalid padding and is rejected. */
  46. #define MBEDTLS_ERR_RSA_KEY_GEN_FAILED -0x4180 /**< Something failed during generation of a key. */
  47. #define MBEDTLS_ERR_RSA_KEY_CHECK_FAILED -0x4200 /**< Key failed to pass the validity check of the library. */
  48. #define MBEDTLS_ERR_RSA_PUBLIC_FAILED -0x4280 /**< The public key operation failed. */
  49. #define MBEDTLS_ERR_RSA_PRIVATE_FAILED -0x4300 /**< The private key operation failed. */
  50. #define MBEDTLS_ERR_RSA_VERIFY_FAILED -0x4380 /**< The PKCS#1 verification failed. */
  51. #define MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE -0x4400 /**< The output buffer for decryption is not large enough. */
  52. #define MBEDTLS_ERR_RSA_RNG_FAILED -0x4480 /**< The random generator failed to generate non-zeros. */
  53. #define MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION -0x4500 /**< The implementation does not offer the requested operation, for example, because of security violations or lack of functionality. */
  54. #define MBEDTLS_ERR_RSA_HW_ACCEL_FAILED -0x4580 /**< RSA hardware accelerator failed. */
  55. /*
  56. * RSA constants
  57. */
  58. #define MBEDTLS_RSA_PUBLIC 0 /**< Request private key operation. */
  59. #define MBEDTLS_RSA_PRIVATE 1 /**< Request public key operation. */
  60. #define MBEDTLS_RSA_PKCS_V15 0 /**< Use PKCS-1 v1.5 encoding. */
  61. #define MBEDTLS_RSA_PKCS_V21 1 /**< Use PKCS-1 v2.1 encoding. */
  62. #define MBEDTLS_RSA_SIGN 1 /**< Identifier for RSA signature operations. */
  63. #define MBEDTLS_RSA_CRYPT 2 /**< Identifier for RSA encryption and decryption operations. */
  64. #define MBEDTLS_RSA_SALT_LEN_ANY -1
  65. /*
  66. * The above constants may be used even if the RSA module is compile out,
  67. * eg for alternative (PKCS#11) RSA implemenations in the PK layers.
  68. */
  69. #if !defined(MBEDTLS_RSA_ALT)
  70. // Regular implementation
  71. //
  72. #ifdef __cplusplus
  73. extern "C" {
  74. #endif
  75. /**
  76. * \brief The RSA context structure.
  77. *
  78. * \note Direct manipulation of the members of this structure
  79. * is deprecated. All manipulation should instead be done through
  80. * the public interface functions.
  81. */
  82. typedef struct
  83. {
  84. int ver; /*!< Always 0.*/
  85. size_t len; /*!< The size of \p N in Bytes. */
  86. mbedtls_mpi N; /*!< The public modulus. */
  87. mbedtls_mpi E; /*!< The public exponent. */
  88. mbedtls_mpi D; /*!< The private exponent. */
  89. mbedtls_mpi P; /*!< The first prime factor. */
  90. mbedtls_mpi Q; /*!< The second prime factor. */
  91. mbedtls_mpi DP; /*!< \p D % (P - 1) */
  92. mbedtls_mpi DQ; /*!< \p D % (Q - 1) */
  93. mbedtls_mpi QP; /*!< 1 / (Q % P) */
  94. mbedtls_mpi RN; /*!< cached R^2 mod \p N */
  95. mbedtls_mpi RP; /*!< cached R^2 mod \p P */
  96. mbedtls_mpi RQ; /*!< cached R^2 mod \p Q */
  97. mbedtls_mpi Vi; /*!< The cached blinding value. */
  98. mbedtls_mpi Vf; /*!< The cached un-blinding value. */
  99. int padding; /*!< Selects padding mode:
  100. #MBEDTLS_RSA_PKCS_V15 for 1.5 padding and
  101. #MBEDTLS_RSA_PKCS_V21 for OAEP or PSS. */
  102. int hash_id; /*!< Hash identifier of mbedtls_md_type_t type,
  103. as specified in md.h for use in the MGF
  104. mask generating function used in the
  105. EME-OAEP and EMSA-PSS encodings. */
  106. #if defined(MBEDTLS_THREADING_C)
  107. mbedtls_threading_mutex_t mutex; /*!< Thread-safety mutex. */
  108. #endif
  109. }
  110. mbedtls_rsa_context;
  111. /**
  112. * \brief This function initializes an RSA context.
  113. *
  114. * \note Set padding to #MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP
  115. * encryption scheme and the RSASSA-PSS signature scheme.
  116. *
  117. * \param ctx The RSA context to initialize.
  118. * \param padding Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or
  119. * #MBEDTLS_RSA_PKCS_V21.
  120. * \param hash_id The hash identifier of #mbedtls_md_type_t type, if
  121. * \p padding is #MBEDTLS_RSA_PKCS_V21.
  122. *
  123. * \note The \p hash_id parameter is ignored when using
  124. * #MBEDTLS_RSA_PKCS_V15 padding.
  125. *
  126. * \note The choice of padding mode is strictly enforced for private key
  127. * operations, since there might be security concerns in
  128. * mixing padding modes. For public key operations it is
  129. * a default value, which can be overriden by calling specific
  130. * \c rsa_rsaes_xxx or \c rsa_rsassa_xxx functions.
  131. *
  132. * \note The hash selected in \p hash_id is always used for OEAP
  133. * encryption. For PSS signatures, it is always used for
  134. * making signatures, but can be overriden for verifying them.
  135. * If set to #MBEDTLS_MD_NONE, it is always overriden.
  136. */
  137. void mbedtls_rsa_init( mbedtls_rsa_context *ctx,
  138. int padding,
  139. int hash_id);
  140. /**
  141. * \brief This function imports a set of core parameters into an
  142. * RSA context.
  143. *
  144. * \param ctx The initialized RSA context to store the parameters in.
  145. * \param N The RSA modulus, or NULL.
  146. * \param P The first prime factor of \p N, or NULL.
  147. * \param Q The second prime factor of \p N, or NULL.
  148. * \param D The private exponent, or NULL.
  149. * \param E The public exponent, or NULL.
  150. *
  151. * \note This function can be called multiple times for successive
  152. * imports, if the parameters are not simultaneously present.
  153. *
  154. * Any sequence of calls to this function should be followed
  155. * by a call to mbedtls_rsa_complete(), which checks and
  156. * completes the provided information to a ready-for-use
  157. * public or private RSA key.
  158. *
  159. * \note See mbedtls_rsa_complete() for more information on which
  160. * parameters are necessary to set up a private or public
  161. * RSA key.
  162. *
  163. * \note The imported parameters are copied and need not be preserved
  164. * for the lifetime of the RSA context being set up.
  165. *
  166. * \return \c 0 on success, or a non-zero error code on failure.
  167. */
  168. int mbedtls_rsa_import( mbedtls_rsa_context *ctx,
  169. const mbedtls_mpi *N,
  170. const mbedtls_mpi *P, const mbedtls_mpi *Q,
  171. const mbedtls_mpi *D, const mbedtls_mpi *E );
  172. /**
  173. * \brief This function imports core RSA parameters, in raw big-endian
  174. * binary format, into an RSA context.
  175. *
  176. * \param ctx The initialized RSA context to store the parameters in.
  177. * \param N The RSA modulus, or NULL.
  178. * \param N_len The Byte length of \p N, ignored if \p N == NULL.
  179. * \param P The first prime factor of \p N, or NULL.
  180. * \param P_len The Byte length of \p P, ignored if \p P == NULL.
  181. * \param Q The second prime factor of \p N, or NULL.
  182. * \param Q_len The Byte length of \p Q, ignored if \p Q == NULL.
  183. * \param D The private exponent, or NULL.
  184. * \param D_len The Byte length of \p D, ignored if \p D == NULL.
  185. * \param E The public exponent, or NULL.
  186. * \param E_len The Byte length of \p E, ignored if \p E == NULL.
  187. *
  188. * \note This function can be called multiple times for successive
  189. * imports, if the parameters are not simultaneously present.
  190. *
  191. * Any sequence of calls to this function should be followed
  192. * by a call to mbedtls_rsa_complete(), which checks and
  193. * completes the provided information to a ready-for-use
  194. * public or private RSA key.
  195. *
  196. * \note See mbedtls_rsa_complete() for more information on which
  197. * parameters are necessary to set up a private or public
  198. * RSA key.
  199. *
  200. * \note The imported parameters are copied and need not be preserved
  201. * for the lifetime of the RSA context being set up.
  202. *
  203. * \return \c 0 on success, or a non-zero error code on failure.
  204. */
  205. int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx,
  206. unsigned char const *N, size_t N_len,
  207. unsigned char const *P, size_t P_len,
  208. unsigned char const *Q, size_t Q_len,
  209. unsigned char const *D, size_t D_len,
  210. unsigned char const *E, size_t E_len );
  211. /**
  212. * \brief This function completes an RSA context from
  213. * a set of imported core parameters.
  214. *
  215. * To setup an RSA public key, precisely \p N and \p E
  216. * must have been imported.
  217. *
  218. * To setup an RSA private key, sufficient information must
  219. * be present for the other parameters to be derivable.
  220. *
  221. * The default implementation supports the following:
  222. * <ul><li>Derive \p P, \p Q from \p N, \p D, \p E.</li>
  223. * <li>Derive \p N, \p D from \p P, \p Q, \p E.</li></ul>
  224. * Alternative implementations need not support these.
  225. *
  226. * If this function runs successfully, it guarantees that
  227. * the RSA context can be used for RSA operations without
  228. * the risk of failure or crash.
  229. *
  230. * \param ctx The initialized RSA context holding imported parameters.
  231. *
  232. * \return \c 0 on success, or #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the
  233. * attempted derivations failed.
  234. *
  235. * \warning This function need not perform consistency checks
  236. * for the imported parameters. In particular, parameters that
  237. * are not needed by the implementation might be silently
  238. * discarded and left unchecked. To check the consistency
  239. * of the key material, see mbedtls_rsa_check_privkey().
  240. *
  241. */
  242. int mbedtls_rsa_complete( mbedtls_rsa_context *ctx );
  243. /**
  244. * \brief This function exports the core parameters of an RSA key.
  245. *
  246. * If this function runs successfully, the non-NULL buffers
  247. * pointed to by \p N, \p P, \p Q, \p D, and \p E are fully
  248. * written, with additional unused space filled leading by
  249. * zero Bytes.
  250. *
  251. * Possible reasons for returning
  252. * #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION:<ul>
  253. * <li>An alternative RSA implementation is in use, which
  254. * stores the key externally, and either cannot or should
  255. * not export it into RAM.</li>
  256. * <li>A SW or HW implementation might not support a certain
  257. * deduction. For example, \p P, \p Q from \p N, \p D,
  258. * and \p E if the former are not part of the
  259. * implementation.</li></ul>
  260. *
  261. * If the function fails due to an unsupported operation,
  262. * the RSA context stays intact and remains usable.
  263. *
  264. * \param ctx The initialized RSA context.
  265. * \param N The MPI to hold the RSA modulus, or NULL.
  266. * \param P The MPI to hold the first prime factor of \p N, or NULL.
  267. * \param Q The MPI to hold the second prime factor of \p N, or NULL.
  268. * \param D The MPI to hold the private exponent, or NULL.
  269. * \param E The MPI to hold the public exponent, or NULL.
  270. *
  271. * \return \c 0 on success,
  272. * #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
  273. * requested parameters cannot be done due to missing
  274. * functionality or because of security policies,
  275. * or a non-zero return code on any other failure.
  276. *
  277. */
  278. int mbedtls_rsa_export( const mbedtls_rsa_context *ctx,
  279. mbedtls_mpi *N, mbedtls_mpi *P, mbedtls_mpi *Q,
  280. mbedtls_mpi *D, mbedtls_mpi *E );
  281. /**
  282. * \brief This function exports core parameters of an RSA key
  283. * in raw big-endian binary format.
  284. *
  285. * If this function runs successfully, the non-NULL buffers
  286. * pointed to by \p N, \p P, \p Q, \p D, and \p E are fully
  287. * written, with additional unused space filled leading by
  288. * zero Bytes.
  289. *
  290. * Possible reasons for returning
  291. * #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION:<ul>
  292. * <li>An alternative RSA implementation is in use, which
  293. * stores the key externally, and either cannot or should
  294. * not export it into RAM.</li>
  295. * <li>A SW or HW implementation might not support a certain
  296. * deduction. For example, \p P, \p Q from \p N, \p D,
  297. * and \p E if the former are not part of the
  298. * implementation.</li></ul>
  299. * If the function fails due to an unsupported operation,
  300. * the RSA context stays intact and remains usable.
  301. *
  302. * \param ctx The initialized RSA context.
  303. * \param N The Byte array to store the RSA modulus, or NULL.
  304. * \param N_len The size of the buffer for the modulus.
  305. * \param P The Byte array to hold the first prime factor of \p N, or
  306. * NULL.
  307. * \param P_len The size of the buffer for the first prime factor.
  308. * \param Q The Byte array to hold the second prime factor of \p N, or
  309. NULL.
  310. * \param Q_len The size of the buffer for the second prime factor.
  311. * \param D The Byte array to hold the private exponent, or NULL.
  312. * \param D_len The size of the buffer for the private exponent.
  313. * \param E The Byte array to hold the public exponent, or NULL.
  314. * \param E_len The size of the buffer for the public exponent.
  315. *
  316. * \note The length fields are ignored if the corresponding
  317. * buffer pointers are NULL.
  318. *
  319. * \return \c 0 on success,
  320. * #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
  321. * requested parameters cannot be done due to missing
  322. * functionality or because of security policies,
  323. * or a non-zero return code on any other failure.
  324. */
  325. int mbedtls_rsa_export_raw( const mbedtls_rsa_context *ctx,
  326. unsigned char *N, size_t N_len,
  327. unsigned char *P, size_t P_len,
  328. unsigned char *Q, size_t Q_len,
  329. unsigned char *D, size_t D_len,
  330. unsigned char *E, size_t E_len );
  331. /**
  332. * \brief This function exports CRT parameters of a private RSA key.
  333. *
  334. * \param ctx The initialized RSA context.
  335. * \param DP The MPI to hold D modulo P-1, or NULL.
  336. * \param DQ The MPI to hold D modulo Q-1, or NULL.
  337. * \param QP The MPI to hold modular inverse of Q modulo P, or NULL.
  338. *
  339. * \return \c 0 on success, non-zero error code otherwise.
  340. *
  341. * \note Alternative RSA implementations not using CRT-parameters
  342. * internally can implement this function based on
  343. * mbedtls_rsa_deduce_opt().
  344. *
  345. */
  346. int mbedtls_rsa_export_crt( const mbedtls_rsa_context *ctx,
  347. mbedtls_mpi *DP, mbedtls_mpi *DQ, mbedtls_mpi *QP );
  348. /**
  349. * \brief This function sets padding for an already initialized RSA
  350. * context. See mbedtls_rsa_init() for details.
  351. *
  352. * \param ctx The RSA context to be set.
  353. * \param padding Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or
  354. * #MBEDTLS_RSA_PKCS_V21.
  355. * \param hash_id The #MBEDTLS_RSA_PKCS_V21 hash identifier.
  356. */
  357. void mbedtls_rsa_set_padding( mbedtls_rsa_context *ctx, int padding,
  358. int hash_id);
  359. /**
  360. * \brief This function retrieves the length of RSA modulus in Bytes.
  361. *
  362. * \param ctx The initialized RSA context.
  363. *
  364. * \return The length of the RSA modulus in Bytes.
  365. *
  366. */
  367. size_t mbedtls_rsa_get_len( const mbedtls_rsa_context *ctx );
  368. /**
  369. * \brief This function generates an RSA keypair.
  370. *
  371. * \param ctx The RSA context used to hold the key.
  372. * \param f_rng The RNG function.
  373. * \param p_rng The RNG parameter.
  374. * \param nbits The size of the public key in bits.
  375. * \param exponent The public exponent. For example, 65537.
  376. *
  377. * \note mbedtls_rsa_init() must be called before this function,
  378. * to set up the RSA context.
  379. *
  380. * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
  381. on failure.
  382. */
  383. int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx,
  384. int (*f_rng)(void *, unsigned char *, size_t),
  385. void *p_rng,
  386. unsigned int nbits, int exponent );
  387. /**
  388. * \brief This function checks if a context contains at least an RSA
  389. * public key.
  390. *
  391. * If the function runs successfully, it is guaranteed that
  392. * enough information is present to perform an RSA public key
  393. * operation using mbedtls_rsa_public().
  394. *
  395. * \param ctx The RSA context to check.
  396. *
  397. * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
  398. * on failure.
  399. *
  400. */
  401. int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx );
  402. /**
  403. * \brief This function checks if a context contains an RSA private key
  404. * and perform basic consistency checks.
  405. *
  406. * \param ctx The RSA context to check.
  407. *
  408. * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code on
  409. * failure.
  410. *
  411. * \note The consistency checks performed by this function not only
  412. * ensure that mbedtls_rsa_private() can be called successfully
  413. * on the given context, but that the various parameters are
  414. * mutually consistent with high probability, in the sense that
  415. * mbedtls_rsa_public() and mbedtls_rsa_private() are inverses.
  416. *
  417. * \warning This function should catch accidental misconfigurations
  418. * like swapping of parameters, but it cannot establish full
  419. * trust in neither the quality nor the consistency of the key
  420. * material that was used to setup the given RSA context:
  421. * <ul><li>Consistency: Imported parameters that are irrelevant
  422. * for the implementation might be silently dropped. If dropped,
  423. * the current function does not have access to them,
  424. * and therefore cannot check them. See mbedtls_rsa_complete().
  425. * If you want to check the consistency of the entire
  426. * content of an PKCS1-encoded RSA private key, for example, you
  427. * should use mbedtls_rsa_validate_params() before setting
  428. * up the RSA context.
  429. * Additionally, if the implementation performs empirical checks,
  430. * these checks substantiate but do not guarantee consistency.</li>
  431. * <li>Quality: This function is not expected to perform
  432. * extended quality assessments like checking that the prime
  433. * factors are safe. Additionally, it is the responsibility of the
  434. * user to ensure the trustworthiness of the source of his RSA
  435. * parameters, which goes beyond what is effectively checkable
  436. * by the library.</li></ul>
  437. */
  438. int mbedtls_rsa_check_privkey( const mbedtls_rsa_context *ctx );
  439. /**
  440. * \brief This function checks a public-private RSA key pair.
  441. *
  442. * It checks each of the contexts, and makes sure they match.
  443. *
  444. * \param pub The RSA context holding the public key.
  445. * \param prv The RSA context holding the private key.
  446. *
  447. * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
  448. * on failure.
  449. */
  450. int mbedtls_rsa_check_pub_priv( const mbedtls_rsa_context *pub,
  451. const mbedtls_rsa_context *prv );
  452. /**
  453. * \brief This function performs an RSA public key operation.
  454. *
  455. * \param ctx The RSA context.
  456. * \param input The input buffer.
  457. * \param output The output buffer.
  458. *
  459. * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
  460. * on failure.
  461. *
  462. * \note This function does not handle message padding.
  463. *
  464. * \note Make sure to set \p input[0] = 0 or ensure that
  465. * input is smaller than \p N.
  466. *
  467. * \note The input and output buffers must be large
  468. * enough. For example, 128 Bytes if RSA-1024 is used.
  469. */
  470. int mbedtls_rsa_public( mbedtls_rsa_context *ctx,
  471. const unsigned char *input,
  472. unsigned char *output );
  473. /**
  474. * \brief This function performs an RSA private key operation.
  475. *
  476. * \param ctx The RSA context.
  477. * \param f_rng The RNG function. Needed for blinding.
  478. * \param p_rng The RNG parameter.
  479. * \param input The input buffer.
  480. * \param output The output buffer.
  481. *
  482. * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
  483. * on failure.
  484. *
  485. * \note The input and output buffers must be large
  486. * enough. For example, 128 Bytes if RSA-1024 is used.
  487. *
  488. * \note Blinding is used if and only if a PRNG is provided.
  489. *
  490. * \note If blinding is used, both the base of exponentation
  491. * and the exponent are blinded, providing protection
  492. * against some side-channel attacks.
  493. *
  494. * \warning It is deprecated and a security risk to not provide
  495. * a PRNG here and thereby prevent the use of blinding.
  496. * Future versions of the library may enforce the presence
  497. * of a PRNG.
  498. *
  499. */
  500. int mbedtls_rsa_private( mbedtls_rsa_context *ctx,
  501. int (*f_rng)(void *, unsigned char *, size_t),
  502. void *p_rng,
  503. const unsigned char *input,
  504. unsigned char *output );
  505. /**
  506. * \brief This function adds the message padding, then performs an RSA
  507. * operation.
  508. *
  509. * It is the generic wrapper for performing a PKCS#1 encryption
  510. * operation using the \p mode from the context.
  511. *
  512. *
  513. * \param ctx The RSA context.
  514. * \param f_rng The RNG function. Needed for padding, PKCS#1 v2.1
  515. * encoding, and #MBEDTLS_RSA_PRIVATE.
  516. * \param p_rng The RNG parameter.
  517. * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
  518. * \param ilen The length of the plaintext.
  519. * \param input The buffer holding the data to encrypt.
  520. * \param output The buffer used to hold the ciphertext.
  521. *
  522. * \deprecated It is deprecated and discouraged to call this function
  523. * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
  524. * are likely to remove the \p mode argument and have it
  525. * implicitly set to #MBEDTLS_RSA_PUBLIC.
  526. *
  527. * \note Alternative implementations of RSA need not support
  528. * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
  529. * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  530. *
  531. * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
  532. * on failure.
  533. *
  534. * \note The input and output buffers must be as large as the size
  535. * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  536. */
  537. int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx,
  538. int (*f_rng)(void *, unsigned char *, size_t),
  539. void *p_rng,
  540. int mode, size_t ilen,
  541. const unsigned char *input,
  542. unsigned char *output );
  543. /**
  544. * \brief This function performs a PKCS#1 v1.5 encryption operation
  545. * (RSAES-PKCS1-v1_5-ENCRYPT).
  546. *
  547. * \param ctx The RSA context.
  548. * \param f_rng The RNG function. Needed for padding and
  549. * #MBEDTLS_RSA_PRIVATE.
  550. * \param p_rng The RNG parameter.
  551. * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
  552. * \param ilen The length of the plaintext.
  553. * \param input The buffer holding the data to encrypt.
  554. * \param output The buffer used to hold the ciphertext.
  555. *
  556. * \deprecated It is deprecated and discouraged to call this function
  557. * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
  558. * are likely to remove the \p mode argument and have it
  559. * implicitly set to #MBEDTLS_RSA_PUBLIC.
  560. *
  561. * \note Alternative implementations of RSA need not support
  562. * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
  563. * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  564. *
  565. * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
  566. * on failure.
  567. *
  568. * \note The output buffer must be as large as the size
  569. * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  570. */
  571. int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx,
  572. int (*f_rng)(void *, unsigned char *, size_t),
  573. void *p_rng,
  574. int mode, size_t ilen,
  575. const unsigned char *input,
  576. unsigned char *output );
  577. /**
  578. * \brief This function performs a PKCS#1 v2.1 OAEP encryption
  579. * operation (RSAES-OAEP-ENCRYPT).
  580. *
  581. * \param ctx The RSA context.
  582. * \param f_rng The RNG function. Needed for padding and PKCS#1 v2.1
  583. * encoding and #MBEDTLS_RSA_PRIVATE.
  584. * \param p_rng The RNG parameter.
  585. * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
  586. * \param label The buffer holding the custom label to use.
  587. * \param label_len The length of the label.
  588. * \param ilen The length of the plaintext.
  589. * \param input The buffer holding the data to encrypt.
  590. * \param output The buffer used to hold the ciphertext.
  591. *
  592. * \deprecated It is deprecated and discouraged to call this function
  593. * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
  594. * are likely to remove the \p mode argument and have it
  595. * implicitly set to #MBEDTLS_RSA_PUBLIC.
  596. *
  597. * \note Alternative implementations of RSA need not support
  598. * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
  599. * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  600. *
  601. * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
  602. * on failure.
  603. *
  604. * \note The output buffer must be as large as the size
  605. * of ctx->N. For example, 128 Bytes if RSA-1024 is used.
  606. */
  607. int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx,
  608. int (*f_rng)(void *, unsigned char *, size_t),
  609. void *p_rng,
  610. int mode,
  611. const unsigned char *label, size_t label_len,
  612. size_t ilen,
  613. const unsigned char *input,
  614. unsigned char *output );
  615. /**
  616. * \brief This function performs an RSA operation, then removes the
  617. * message padding.
  618. *
  619. * It is the generic wrapper for performing a PKCS#1 decryption
  620. * operation using the \p mode from the context.
  621. *
  622. * \param ctx The RSA context.
  623. * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
  624. * \param p_rng The RNG parameter.
  625. * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
  626. * \param olen The length of the plaintext.
  627. * \param input The buffer holding the encrypted data.
  628. * \param output The buffer used to hold the plaintext.
  629. * \param output_max_len The maximum length of the output buffer.
  630. *
  631. * \deprecated It is deprecated and discouraged to call this function
  632. * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
  633. * are likely to remove the \p mode argument and have it
  634. * implicitly set to #MBEDTLS_RSA_PRIVATE.
  635. *
  636. * \note Alternative implementations of RSA need not support
  637. * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
  638. * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  639. *
  640. * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
  641. * on failure.
  642. *
  643. * \note The output buffer length \c output_max_len should be
  644. * as large as the size \p ctx->len of \p ctx->N (for example,
  645. * 128 Bytes if RSA-1024 is used) to be able to hold an
  646. * arbitrary decrypted message. If it is not large enough to
  647. * hold the decryption of the particular ciphertext provided,
  648. * the function returns \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
  649. *
  650. * \note The input buffer must be as large as the size
  651. * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  652. */
  653. int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx,
  654. int (*f_rng)(void *, unsigned char *, size_t),
  655. void *p_rng,
  656. int mode, size_t *olen,
  657. const unsigned char *input,
  658. unsigned char *output,
  659. size_t output_max_len );
  660. /**
  661. * \brief This function performs a PKCS#1 v1.5 decryption
  662. * operation (RSAES-PKCS1-v1_5-DECRYPT).
  663. *
  664. * \param ctx The RSA context.
  665. * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
  666. * \param p_rng The RNG parameter.
  667. * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
  668. * \param olen The length of the plaintext.
  669. * \param input The buffer holding the encrypted data.
  670. * \param output The buffer to hold the plaintext.
  671. * \param output_max_len The maximum length of the output buffer.
  672. *
  673. * \deprecated It is deprecated and discouraged to call this function
  674. * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
  675. * are likely to remove the \p mode argument and have it
  676. * implicitly set to #MBEDTLS_RSA_PRIVATE.
  677. *
  678. * \note Alternative implementations of RSA need not support
  679. * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
  680. * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  681. *
  682. * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
  683. * on failure.
  684. *
  685. * \note The output buffer length \c output_max_len should be
  686. * as large as the size \p ctx->len of \p ctx->N, for example,
  687. * 128 Bytes if RSA-1024 is used, to be able to hold an
  688. * arbitrary decrypted message. If it is not large enough to
  689. * hold the decryption of the particular ciphertext provided,
  690. * the function returns #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
  691. *
  692. * \note The input buffer must be as large as the size
  693. * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  694. */
  695. int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx,
  696. int (*f_rng)(void *, unsigned char *, size_t),
  697. void *p_rng,
  698. int mode, size_t *olen,
  699. const unsigned char *input,
  700. unsigned char *output,
  701. size_t output_max_len );
  702. /**
  703. * \brief This function performs a PKCS#1 v2.1 OAEP decryption
  704. * operation (RSAES-OAEP-DECRYPT).
  705. *
  706. * \param ctx The RSA context.
  707. * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
  708. * \param p_rng The RNG parameter.
  709. * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
  710. * \param label The buffer holding the custom label to use.
  711. * \param label_len The length of the label.
  712. * \param olen The length of the plaintext.
  713. * \param input The buffer holding the encrypted data.
  714. * \param output The buffer to hold the plaintext.
  715. * \param output_max_len The maximum length of the output buffer.
  716. *
  717. * \deprecated It is deprecated and discouraged to call this function
  718. * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
  719. * are likely to remove the \p mode argument and have it
  720. * implicitly set to #MBEDTLS_RSA_PRIVATE.
  721. *
  722. * \note Alternative implementations of RSA need not support
  723. * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
  724. * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  725. *
  726. * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
  727. * on failure.
  728. *
  729. * \note The output buffer length \c output_max_len should be
  730. * as large as the size \p ctx->len of \p ctx->N, for
  731. * example, 128 Bytes if RSA-1024 is used, to be able to
  732. * hold an arbitrary decrypted message. If it is not
  733. * large enough to hold the decryption of the particular
  734. * ciphertext provided, the function returns
  735. * #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
  736. *
  737. * \note The input buffer must be as large as the size
  738. * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  739. */
  740. int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx,
  741. int (*f_rng)(void *, unsigned char *, size_t),
  742. void *p_rng,
  743. int mode,
  744. const unsigned char *label, size_t label_len,
  745. size_t *olen,
  746. const unsigned char *input,
  747. unsigned char *output,
  748. size_t output_max_len );
  749. /**
  750. * \brief This function performs a private RSA operation to sign
  751. * a message digest using PKCS#1.
  752. *
  753. * It is the generic wrapper for performing a PKCS#1
  754. * signature using the \p mode from the context.
  755. *
  756. * \param ctx The RSA context.
  757. * \param f_rng The RNG function. Needed for PKCS#1 v2.1 encoding and for
  758. * #MBEDTLS_RSA_PRIVATE.
  759. * \param p_rng The RNG parameter.
  760. * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
  761. * \param md_alg The message-digest algorithm used to hash the original data.
  762. * Use #MBEDTLS_MD_NONE for signing raw data.
  763. * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
  764. * \param hash The buffer holding the message digest.
  765. * \param sig The buffer to hold the ciphertext.
  766. *
  767. * \deprecated It is deprecated and discouraged to call this function
  768. * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
  769. * are likely to remove the \p mode argument and have it
  770. * implicitly set to #MBEDTLS_RSA_PRIVATE.
  771. *
  772. * \note Alternative implementations of RSA need not support
  773. * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
  774. * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  775. *
  776. * \return \c 0 if the signing operation was successful,
  777. * or an \c MBEDTLS_ERR_RSA_XXX error code on failure.
  778. *
  779. * \note The \p sig buffer must be as large as the size
  780. * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  781. *
  782. * \note For PKCS#1 v2.1 encoding, see comments on
  783. * mbedtls_rsa_rsassa_pss_sign() for details on
  784. * \p md_alg and \p hash_id.
  785. */
  786. int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx,
  787. int (*f_rng)(void *, unsigned char *, size_t),
  788. void *p_rng,
  789. int mode,
  790. mbedtls_md_type_t md_alg,
  791. unsigned int hashlen,
  792. const unsigned char *hash,
  793. unsigned char *sig );
  794. /**
  795. * \brief This function performs a PKCS#1 v1.5 signature
  796. * operation (RSASSA-PKCS1-v1_5-SIGN).
  797. *
  798. * \param ctx The RSA context.
  799. * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
  800. * \param p_rng The RNG parameter.
  801. * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
  802. * \param md_alg The message-digest algorithm used to hash the original data.
  803. * Use #MBEDTLS_MD_NONE for signing raw data.
  804. * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
  805. * \param hash The buffer holding the message digest.
  806. * \param sig The buffer to hold the ciphertext.
  807. *
  808. * \deprecated It is deprecated and discouraged to call this function
  809. * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
  810. * are likely to remove the \p mode argument and have it
  811. * implicitly set to #MBEDTLS_RSA_PRIVATE.
  812. *
  813. * \note Alternative implementations of RSA need not support
  814. * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
  815. * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  816. *
  817. * \return \c 0 if the signing operation was successful,
  818. * or an \c MBEDTLS_ERR_RSA_XXX error code
  819. * on failure.
  820. *
  821. * \note The \p sig buffer must be as large as the size
  822. * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  823. */
  824. int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx,
  825. int (*f_rng)(void *, unsigned char *, size_t),
  826. void *p_rng,
  827. int mode,
  828. mbedtls_md_type_t md_alg,
  829. unsigned int hashlen,
  830. const unsigned char *hash,
  831. unsigned char *sig );
  832. /**
  833. * \brief This function performs a PKCS#1 v2.1 PSS signature
  834. * operation (RSASSA-PSS-SIGN).
  835. *
  836. * \param ctx The RSA context.
  837. * \param f_rng The RNG function. Needed for PKCS#1 v2.1 encoding and for
  838. * #MBEDTLS_RSA_PRIVATE.
  839. * \param p_rng The RNG parameter.
  840. * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
  841. * \param md_alg The message-digest algorithm used to hash the original data.
  842. * Use #MBEDTLS_MD_NONE for signing raw data.
  843. * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
  844. * \param hash The buffer holding the message digest.
  845. * \param sig The buffer to hold the ciphertext.
  846. *
  847. * \deprecated It is deprecated and discouraged to call this function
  848. * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
  849. * are likely to remove the \p mode argument and have it
  850. * implicitly set to #MBEDTLS_RSA_PRIVATE.
  851. *
  852. * \note Alternative implementations of RSA need not support
  853. * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
  854. * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  855. *
  856. * \return \c 0 if the signing operation was successful,
  857. * or an \c MBEDTLS_ERR_RSA_XXX error code
  858. * on failure.
  859. *
  860. * \note The \p sig buffer must be as large as the size
  861. * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  862. *
  863. * \note The \p hash_id in the RSA context is the one used for the
  864. * encoding. \p md_alg in the function call is the type of hash
  865. * that is encoded. According to <em>RFC-3447: Public-Key
  866. * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
  867. * Specifications</em> it is advised to keep both hashes the
  868. * same.
  869. */
  870. int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx,
  871. int (*f_rng)(void *, unsigned char *, size_t),
  872. void *p_rng,
  873. int mode,
  874. mbedtls_md_type_t md_alg,
  875. unsigned int hashlen,
  876. const unsigned char *hash,
  877. unsigned char *sig );
  878. /**
  879. * \brief This function performs a public RSA operation and checks
  880. * the message digest.
  881. *
  882. * This is the generic wrapper for performing a PKCS#1
  883. * verification using the mode from the context.
  884. *
  885. * \param ctx The RSA public key context.
  886. * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
  887. * \param p_rng The RNG parameter.
  888. * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
  889. * \param md_alg The message-digest algorithm used to hash the original data.
  890. * Use #MBEDTLS_MD_NONE for signing raw data.
  891. * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
  892. * \param hash The buffer holding the message digest.
  893. * \param sig The buffer holding the ciphertext.
  894. *
  895. * \deprecated It is deprecated and discouraged to call this function
  896. * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
  897. * are likely to remove the \p mode argument and have it
  898. * set to #MBEDTLS_RSA_PUBLIC.
  899. *
  900. * \note Alternative implementations of RSA need not support
  901. * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
  902. * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  903. *
  904. * \return \c 0 if the verify operation was successful,
  905. * or an \c MBEDTLS_ERR_RSA_XXX error code
  906. * on failure.
  907. *
  908. * \note The \p sig buffer must be as large as the size
  909. * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  910. *
  911. * \note For PKCS#1 v2.1 encoding, see comments on
  912. * mbedtls_rsa_rsassa_pss_verify() about \p md_alg and
  913. * \p hash_id.
  914. */
  915. int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx,
  916. int (*f_rng)(void *, unsigned char *, size_t),
  917. void *p_rng,
  918. int mode,
  919. mbedtls_md_type_t md_alg,
  920. unsigned int hashlen,
  921. const unsigned char *hash,
  922. const unsigned char *sig );
  923. /**
  924. * \brief This function performs a PKCS#1 v1.5 verification
  925. * operation (RSASSA-PKCS1-v1_5-VERIFY).
  926. *
  927. * \param ctx The RSA public key context.
  928. * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
  929. * \param p_rng The RNG parameter.
  930. * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
  931. * \param md_alg The message-digest algorithm used to hash the original data.
  932. * Use #MBEDTLS_MD_NONE for signing raw data.
  933. * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
  934. * \param hash The buffer holding the message digest.
  935. * \param sig The buffer holding the ciphertext.
  936. *
  937. * \deprecated It is deprecated and discouraged to call this function
  938. * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
  939. * are likely to remove the \p mode argument and have it
  940. * set to #MBEDTLS_RSA_PUBLIC.
  941. *
  942. * \note Alternative implementations of RSA need not support
  943. * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
  944. * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  945. *
  946. * \return \c 0 if the verify operation was successful,
  947. * or an \c MBEDTLS_ERR_RSA_XXX error code
  948. * on failure.
  949. *
  950. * \note The \p sig buffer must be as large as the size
  951. * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  952. */
  953. int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx,
  954. int (*f_rng)(void *, unsigned char *, size_t),
  955. void *p_rng,
  956. int mode,
  957. mbedtls_md_type_t md_alg,
  958. unsigned int hashlen,
  959. const unsigned char *hash,
  960. const unsigned char *sig );
  961. /**
  962. * \brief This function performs a PKCS#1 v2.1 PSS verification
  963. * operation (RSASSA-PSS-VERIFY).
  964. *
  965. * The hash function for the MGF mask generating function
  966. * is that specified in the RSA context.
  967. *
  968. * \param ctx The RSA public key context.
  969. * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
  970. * \param p_rng The RNG parameter.
  971. * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
  972. * \param md_alg The message-digest algorithm used to hash the original data.
  973. * Use #MBEDTLS_MD_NONE for signing raw data.
  974. * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
  975. * \param hash The buffer holding the message digest.
  976. * \param sig The buffer holding the ciphertext.
  977. *
  978. * \deprecated It is deprecated and discouraged to call this function
  979. * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
  980. * are likely to remove the \p mode argument and have it
  981. * implicitly set to #MBEDTLS_RSA_PUBLIC.
  982. *
  983. * \note Alternative implementations of RSA need not support
  984. * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
  985. * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  986. *
  987. * \return \c 0 if the verify operation was successful,
  988. * or an \c MBEDTLS_ERR_RSA_XXX error code
  989. * on failure.
  990. *
  991. * \note The \p sig buffer must be as large as the size
  992. * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  993. *
  994. * \note The \p hash_id in the RSA context is the one used for the
  995. * verification. \p md_alg in the function call is the type of
  996. * hash that is verified. According to <em>RFC-3447: Public-Key
  997. * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
  998. * Specifications</em> it is advised to keep both hashes the
  999. * same. If \p hash_id in the RSA context is unset,
  1000. * the \p md_alg from the function call is used.
  1001. */
  1002. int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx,
  1003. int (*f_rng)(void *, unsigned char *, size_t),
  1004. void *p_rng,
  1005. int mode,
  1006. mbedtls_md_type_t md_alg,
  1007. unsigned int hashlen,
  1008. const unsigned char *hash,
  1009. const unsigned char *sig );
  1010. /**
  1011. * \brief This function performs a PKCS#1 v2.1 PSS verification
  1012. * operation (RSASSA-PSS-VERIFY).
  1013. *
  1014. * The hash function for the MGF mask generating function
  1015. * is that specified in \p mgf1_hash_id.
  1016. *
  1017. * \param ctx The RSA public key context.
  1018. * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
  1019. * \param p_rng The RNG parameter.
  1020. * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
  1021. * \param md_alg The message-digest algorithm used to hash the original data.
  1022. * Use #MBEDTLS_MD_NONE for signing raw data.
  1023. * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
  1024. * \param hash The buffer holding the message digest.
  1025. * \param mgf1_hash_id The message digest used for mask generation.
  1026. * \param expected_salt_len The length of the salt used in padding. Use
  1027. * #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length.
  1028. * \param sig The buffer holding the ciphertext.
  1029. *
  1030. * \return \c 0 if the verify operation was successful,
  1031. * or an \c MBEDTLS_ERR_RSA_XXX error code
  1032. * on failure.
  1033. *
  1034. * \note The \p sig buffer must be as large as the size
  1035. * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  1036. *
  1037. * \note The \p hash_id in the RSA context is ignored.
  1038. */
  1039. int mbedtls_rsa_rsassa_pss_verify_ext( mbedtls_rsa_context *ctx,
  1040. int (*f_rng)(void *, unsigned char *, size_t),
  1041. void *p_rng,
  1042. int mode,
  1043. mbedtls_md_type_t md_alg,
  1044. unsigned int hashlen,
  1045. const unsigned char *hash,
  1046. mbedtls_md_type_t mgf1_hash_id,
  1047. int expected_salt_len,
  1048. const unsigned char *sig );
  1049. /**
  1050. * \brief This function copies the components of an RSA context.
  1051. *
  1052. * \param dst The destination context.
  1053. * \param src The source context.
  1054. *
  1055. * \return \c 0 on success,
  1056. * #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure.
  1057. */
  1058. int mbedtls_rsa_copy( mbedtls_rsa_context *dst, const mbedtls_rsa_context *src );
  1059. /**
  1060. * \brief This function frees the components of an RSA key.
  1061. *
  1062. * \param ctx The RSA Context to free.
  1063. */
  1064. void mbedtls_rsa_free( mbedtls_rsa_context *ctx );
  1065. #ifdef __cplusplus
  1066. }
  1067. #endif
  1068. #else /* MBEDTLS_RSA_ALT */
  1069. #include "rsa_alt.h"
  1070. #endif /* MBEDTLS_RSA_ALT */
  1071. #ifdef __cplusplus
  1072. extern "C" {
  1073. #endif
  1074. /**
  1075. * \brief The RSA checkup routine.
  1076. *
  1077. * \return \c 0 on success, or \c 1 on failure.
  1078. */
  1079. int mbedtls_rsa_self_test( int verbose );
  1080. #ifdef __cplusplus
  1081. }
  1082. #endif
  1083. #endif /* rsa.h */