rsa.h 63 KB

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