rsa.h 27 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793
  1. /*!
  2. \ingroup RSA
  3. \brief This function initializes a provided RsaKey struct. It also takes
  4. in a heap identifier, for use with user defined memory overrides
  5. (see XMALLOC, XFREE, XREALLOC).
  6. \return 0 Returned upon successfully initializing the RSA structure for
  7. use with encryption and decryption
  8. \return BAD_FUNC_ARGS Returned if the RSA key pointer evaluates to NULL
  9. \param key pointer to the RsaKey structure to initialize
  10. \param heap pointer to a heap identifier, for use with memory overrides,
  11. allowing custom handling of memory allocation. This heap will be the
  12. default used when allocating memory for use with this RSA object
  13. _Example_
  14. \code
  15. RsaKey enc;
  16. int ret;
  17. ret = wc_InitRsaKey(&enc, NULL); // not using heap hint. No custom memory
  18. if ( ret != 0 ) {
  19. // error initializing RSA key
  20. }
  21. \endcode
  22. \sa wc_RsaInitCavium
  23. \sa wc_FreeRsaKey
  24. */
  25. WOLFSSL_API int wc_InitRsaKey(RsaKey* key, void* heap);
  26. /*!
  27. \ingroup RSA
  28. \brief This function frees a provided RsaKey struct using mp_clear.
  29. \return 0 Returned upon successfully freeing the key
  30. \param key pointer to the RsaKey structure to free
  31. _Example_
  32. \code
  33. RsaKey enc;
  34. wc_RsaInitKey(&enc, NULL); // not using heap hint. No custom memory
  35. ... set key, do encryption
  36. wc_FreeRsaKey(&enc);
  37. \endcode
  38. \sa wc_InitRsaKey
  39. */
  40. WOLFSSL_API int wc_FreeRsaKey(RsaKey* key);
  41. /*!
  42. \ingroup RSA
  43. \brief This function encrypts a message from in and stores the result
  44. in out. It requires an initialized public key and a random number
  45. generator. As a side effect, this function will return the bytes written
  46. to out in outLen.
  47. \return Success Upon successfully encrypting the input message, returns
  48. the number bytes written to out
  49. \return -1 Returned if there is an error during RSA encryption and
  50. hardware acceleration via Cavium is enabled
  51. \return BAD_FUNC_ARG Returned if any of the input parameters are invalid
  52. \return RSA_BUFFER_E Returned if the output buffer is too small to store
  53. the ciphertext
  54. \return RNG_FAILURE_E Returned if there is an error generating a random
  55. block using the provided RNG structure
  56. \return MP_INIT_E May be returned if there is an error in the math
  57. library used while encrypting the message
  58. \return MP_READ_E May be returned if there is an error in the math
  59. library used while encrypting the message
  60. \return MP_CMP_E May be returned if there is an error in the math
  61. library used while encrypting the message
  62. \return MP_INVMOD_E May be returned if there is an error in the math
  63. library used while encrypting the message
  64. \return MP_EXPTMOD_E May be returned if there is an error in the math
  65. library used while encrypting the message
  66. \return MP_MOD_E May be returned if there is an error in the math
  67. library used while encrypting the message
  68. \return MP_MUL_E May be returned if there is an error in the math
  69. library used while encrypting the message
  70. \return MP_ADD_E May be returned if there is an error in the math
  71. library used while encrypting the message
  72. \return MP_MULMOD_E May be returned if there is an error in the math
  73. library used while encrypting the message
  74. \return MP_TO_E May be returned if there is an error in the math
  75. library used while encrypting the message
  76. \return MP_MEM May be returned if there is an error in the math
  77. library used while encrypting the message
  78. \return MP_ZERO_E May be returned if there is an error in the math
  79. library used while encrypting the message
  80. \param in pointer to a buffer containing the input message to encrypt
  81. \param inLen the length of the message to encrypt
  82. \param out pointer to the buffer in which to store the output ciphertext
  83. \param outLen the length of the output buffer
  84. \param key pointer to the RsaKey structure containing the public
  85. key to use for encryption
  86. \param rng The RNG structure with which to generate random block padding
  87. _Example_
  88. \code
  89. RsaKey pub;
  90. int ret = 0;
  91. byte n[] = { // initialize with received n component of public key };
  92. byte e[] = { // initialize with received e component of public key };
  93. byte msg[] = { // initialize with plaintext of message to encrypt };
  94. byte cipher[256]; // 256 bytes is large enough to store 2048 bit RSA
  95. ciphertext
  96. wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory
  97. wc_RsaPublicKeyDecodeRaw(n, sizeof(n), e, sizeof(e), &pub);
  98. // initialize with received public key parameters
  99. ret = wc_RsaPublicEncrypt(msg, sizeof(msg), out, sizeof(out), &pub, &rng);
  100. if ( ret != 0 ) {
  101. // error encrypting message
  102. }
  103. \endcode
  104. \sa wc_RsaPrivateDecrypt
  105. */
  106. WOLFSSL_API int wc_RsaPublicEncrypt(const byte* in, word32 inLen, byte* out,
  107. word32 outLen, RsaKey* key, WC_RNG* rng);
  108. /*!
  109. \ingroup RSA
  110. \brief This functions is utilized by the wc_RsaPrivateDecrypt function
  111. for decrypting.
  112. \return Success Length of decrypted data.
  113. \return RSA_PAD_E RsaUnPad error, bad formatting
  114. \param in The byte array to be decrypted.
  115. \param inLen The length of in.
  116. \param out The byte array for the decrypted data to be stored.
  117. \param key The key to use for decryption.
  118. _Example_
  119. \code
  120. none
  121. \endcode
  122. \sa wc_RsaPrivateDecrypt
  123. */
  124. WOLFSSL_API int wc_RsaPrivateDecryptInline(byte* in, word32 inLen, byte** out,
  125. RsaKey* key);
  126. /*!
  127. \ingroup RSA
  128. \brief This functions provides private RSA decryption.
  129. \return Success length of decrypted data.
  130. \return MEMORY_E -125, out of memory error
  131. \return BAD_FUNC_ARG -173, Bad function argument provided
  132. \param in The byte array to be decrypted.
  133. \param inLen The length of in.
  134. \param out The byte array for the decrypted data to be stored.
  135. \param outLen The length of out.
  136. \param key The key to use for decryption.
  137. _Example_
  138. \code
  139. ret = wc_RsaPublicEncrypt(in, inLen, out, sizeof(out), &key, &rng);
  140. if (ret < 0) {
  141. return -1;
  142. }
  143. ret = wc_RsaPrivateDecrypt(out, ret, plain, sizeof(plain), &key);
  144. if (ret < 0) {
  145. return -1;
  146. }
  147. \endcode
  148. \sa RsaUnPad
  149. \sa wc_RsaFunction
  150. \sa wc_RsaPrivateDecryptInline
  151. */
  152. WOLFSSL_API int wc_RsaPrivateDecrypt(const byte* in, word32 inLen, byte* out,
  153. word32 outLen, RsaKey* key);
  154. /*!
  155. \ingroup RSA
  156. \brief Signs the provided array with the private key.
  157. \return RSA_BUFFER_E: -131, RSA buffer error, output too small or
  158. input too large
  159. \param in The byte array to be encrypted.
  160. \param inLen The length of in.
  161. \param out The byte array for the encrypted data to be stored.
  162. \param outLen The length of out.
  163. \param key The key to use for encryption.
  164. \param RNG The RNG struct to use for random number purposes.
  165. _Example_
  166. \code
  167. ret = wc_RsaSSL_Sign(in, inLen, out, sizeof(out), &key, &rng);
  168. if (ret < 0) {
  169. return -1;
  170. }
  171. memset(plain, 0, sizeof(plain));
  172. ret = wc_RsaSSL_Verify(out, ret, plain, sizeof(plain), &key);
  173. if (ret < 0) {
  174. return -1;
  175. }
  176. \endcode
  177. \sa wc_RsaPad
  178. */
  179. WOLFSSL_API int wc_RsaSSL_Sign(const byte* in, word32 inLen, byte* out,
  180. word32 outLen, RsaKey* key, WC_RNG* rng);
  181. /*!
  182. \ingroup RSA
  183. \brief Used to verify that the message was signed by RSA key. The output
  184. uses the same byte array as the input.
  185. \return >0 Length of text.
  186. \return <0 An error occurred.
  187. \param in Byte array to be decrypted.
  188. \param inLen Length of the buffer input.
  189. \param out Pointer to a pointer for decrypted information.
  190. \param key RsaKey to use.
  191. _Example_
  192. \code
  193. RsaKey key;
  194. WC_WC_RNG rng;
  195. int ret = 0;
  196. long e = 65537; // standard value to use for exponent
  197. wc_InitRsaKey(&key, NULL); // not using heap hint. No custom memory
  198. wc_InitRng(&rng);
  199. wc_MakeRsaKey(&key, 2048, e, &rng);
  200. byte in[] = { // Initialize with some RSA encrypted information }
  201. byte* out;
  202. if(wc_RsaSSL_VerifyInline(in, sizeof(in), &out, &key) < 0)
  203. {
  204. // handle error
  205. }
  206. \endcode
  207. \sa wc_RsaSSL_Verify
  208. \sa wc_RsaSSL_Sign
  209. */
  210. WOLFSSL_API int wc_RsaSSL_VerifyInline(byte* in, word32 inLen, byte** out,
  211. RsaKey* key);
  212. /*!
  213. \ingroup RSA
  214. \brief Used to verify that the message was signed by key.
  215. \return Success Length of text on no error.
  216. \return MEMORY_E memory exception.
  217. \param in The byte array to be decrypted.
  218. \param inLen The length of in.
  219. \param out The byte array for the decrypted data to be stored.
  220. \param outLen The length of out.
  221. \param key The key to use for verification.
  222. _Example_
  223. \code
  224. ret = wc_RsaSSL_Sign(in, inLen, out, sizeof(out), &key, &rng);
  225. if (ret < 0) {
  226. return -1;
  227. }
  228. memset(plain, 0, sizeof(plain));
  229. ret = wc_RsaSSL_Verify(out, ret, plain, sizeof(plain), &key);
  230. if (ret < 0) {
  231. return -1;
  232. }
  233. \endcode
  234. \sa wc_RsaSSL_Sign
  235. */
  236. WOLFSSL_API int wc_RsaSSL_Verify(const byte* in, word32 inLen, byte* out,
  237. word32 outLen, RsaKey* key);
  238. /*!
  239. \ingroup RSA
  240. \brief Returns the encryption size for the provided key structure.
  241. \return Success Encryption size for the provided key structure.
  242. \param key The key to use for verification.
  243. _Example_
  244. \code
  245. int sz = wc_RsaEncryptSize(&key);
  246. \endcode
  247. \sa wc_InitRsaKey
  248. \sa wc_InitRsaKey_ex
  249. \sa wc_MakeRsaKey
  250. \sa XMEMSET
  251. */
  252. WOLFSSL_API int wc_RsaEncryptSize(RsaKey* key);
  253. /*!
  254. \ingroup RSA
  255. \brief This function parses a DER-formatted RSA private key, extracts the
  256. private key and stores it in the given RsaKey structure. It also sets the
  257. distance parsed in idx.
  258. \return 0 Returned upon successfully parsing the private key from the DER
  259. encoded input
  260. \return ASN_PARSE_E Returned if there is an error parsing the private key
  261. from the input buffer. This may happen if the input private key is not
  262. properly formatted according to ASN.1 standards
  263. \return ASN_RSA_KEY_E Returned if there is an error reading the private
  264. key elements of the RSA key input
  265. \param input pointer to the buffer containing the DER formatted private
  266. key to decode
  267. \param inOutIdx pointer to the index in the buffer at which the key begins
  268. (usually 0). As a side effect of this function, inOutIdx will store the
  269. distance parsed through the input buffer
  270. \param key pointer to the RsaKey structure in which to store the decoded
  271. private key
  272. \param inSz size of the input buffer
  273. _Example_
  274. \code
  275. RsaKey enc;
  276. word32 idx = 0;
  277. int ret = 0;
  278. byte der[] = { // initialize with DER-encoded RSA private key };
  279. wc_InitRsaKey(&enc, NULL); // not using heap hint. No custom memory
  280. ret = wc_RsaPrivateKeyDecode(der, &idx, &enc, sizeof(der));
  281. if( ret != 0 ) {
  282. // error parsing private key
  283. }
  284. \endcode
  285. \sa wc_RsaPublicKeyDecode
  286. \sa wc_MakeRsaKey
  287. */
  288. WOLFSSL_API int wc_RsaPrivateKeyDecode(const byte* input, word32* inOutIdx,
  289. RsaKey*, word32);
  290. /*!
  291. \ingroup RSA
  292. \brief This function parses a DER-formatted RSA public key, extracts the
  293. public key and stores it in the given RsaKey structure. It also sets the
  294. distance parsed in idx.
  295. \return 0 Returned upon successfully parsing the public key from the DER
  296. encoded input
  297. \return ASN_PARSE_E Returned if there is an error parsing the public key
  298. from the input buffer. This may happen if the input public key is not
  299. properly formatted according to ASN.1 standards
  300. \return ASN_OBJECT_ID_E Returned if the ASN.1 Object ID does not match
  301. that of a RSA public key
  302. \return ASN_EXPECT_0_E Returned if the input key is not correctly
  303. formatted according to ASN.1 standards
  304. \return ASN_BITSTR_E Returned if the input key is not correctly formatted
  305. according to ASN.1 standards
  306. \return ASN_RSA_KEY_E Returned if there is an error reading the public key
  307. elements of the RSA key input
  308. \param input pointer to the buffer containing the input DER-encoded RSA
  309. public key to decode
  310. \param inOutIdx pointer to the index in the buffer at which the key
  311. begins (usually 0). As a side effect of this function, inOutIdx will
  312. store the distance parsed through the input buffer
  313. \param key pointer to the RsaKey structure in which to store the decoded
  314. public key
  315. \param inSz size of the input buffer
  316. _Example_
  317. \code
  318. RsaKey pub;
  319. word32 idx = 0;
  320. int ret = 0;
  321. byte der[] = { // initialize with DER-encoded RSA public key };
  322. wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory
  323. ret = wc_RsaPublicKeyDecode(der, &idx, &pub, sizeof(der));
  324. if( ret != 0 ) {
  325. // error parsing public key
  326. }
  327. \endcode
  328. \sa wc_RsaPublicKeyDecodeRaw
  329. */
  330. WOLFSSL_API int wc_RsaPublicKeyDecode(const byte* input, word32* inOutIdx,
  331. RsaKey*, word32);
  332. /*!
  333. \ingroup RSA
  334. \brief This function decodes the raw elements of an RSA public key, taking
  335. in the public modulus (n) and exponent (e). It stores these raw elements
  336. in the provided RsaKey structure, allowing one to use them in the
  337. encryption/decryption process.
  338. \return 0 Returned upon successfully decoding the raw elements of the
  339. public key into the RsaKey structure
  340. \return BAD_FUNC_ARG Returned if any of the input arguments evaluates to
  341. NULL
  342. \return MP_INIT_E Returned if there is an error initializing an integer
  343. for use with the multiple precision integer (mp_int) library
  344. \return ASN_GETINT_E Returned if there is an error reading one of the
  345. provided RSA key elements, n or e
  346. \param n pointer to a buffer containing the raw modulus parameter of the
  347. public RSA key
  348. \param nSz size of the buffer containing n
  349. \param e pointer to a buffer containing the raw exponent parameter of
  350. the public RSA key
  351. \param eSz size of the buffer containing e
  352. \param key pointer to the RsaKey struct to initialize with the provided
  353. public key elements
  354. _Example_
  355. \code
  356. RsaKey pub;
  357. int ret = 0;
  358. byte n[] = { // initialize with received n component of public key };
  359. byte e[] = { // initialize with received e component of public key };
  360. wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory
  361. ret = wc_RsaPublicKeyDecodeRaw(n, sizeof(n), e, sizeof(e), &pub);
  362. if( ret != 0 ) {
  363. // error parsing public key elements
  364. }
  365. \endcode
  366. \sa wc_RsaPublicKeyDecode
  367. */
  368. WOLFSSL_API int wc_RsaPublicKeyDecodeRaw(const byte* n, word32 nSz,
  369. const byte* e, word32 eSz, RsaKey* key);
  370. /*!
  371. \ingroup RSA
  372. \brief This function converts an RsaKey key to DER format. The result is
  373. written to output and it returns the number of bytes written.
  374. \return 0 Success
  375. \return BAD_FUNC_ARG Returned if key or output is null, or if key->type
  376. is not RSA_PRIVATE, or if inLen isn't large enough for output buffer.
  377. \return MEMORY_E Returned if there is an error allocating memory.
  378. \param key Initialized RsaKey structure.
  379. \param output Pointer to output buffer.
  380. \param inLen Size of output buffer.
  381. _Example_
  382. \code
  383. byte* der;
  384. // Allocate memory for der
  385. int derSz = // Amount of memory allocated for der;
  386. RsaKey key;
  387. WC_WC_RNG rng;
  388. long e = 65537; // standard value to use for exponent
  389. ret = wc_MakeRsaKey(&key, 2048, e, &rng); // generate 2048 bit long
  390. private key
  391. wc_InitRsaKey(&key, NULL);
  392. wc_InitRng(&rng);
  393. if(wc_RsaKeyToDer(&key, der, derSz) != 0)
  394. {
  395. // Handle the error thrown
  396. }
  397. \endcode
  398. \sa wc_RsaKeyToPublicDer
  399. \sa wc_InitRsaKey
  400. \sa wc_MakeRsaKey
  401. \sa wc_InitRng
  402. */
  403. WOLFSSL_API int wc_RsaKeyToDer(RsaKey*, byte* output, word32 inLen);
  404. /*!
  405. \ingroup RSA
  406. \brief This function performs RSA encrypt while allowing the choice of
  407. which padding to use.
  408. \return size On successfully encryption the size of the encrypted buffer
  409. is returned
  410. \return RSA_BUFFER_E RSA buffer error, output too small or input too large
  411. \param in pointer to the buffer for encryption
  412. \param inLen length of the buffer to encrypt
  413. \param out encrypted msg created
  414. \param outLen length of buffer available to hold encrypted msg
  415. \param key initialized RSA key struct
  416. \param rng initialized WC_RNG struct
  417. \param type type of padding to use (WC_RSA_OAEP_PAD or WC_RSA_PKCSV15_PAD)
  418. \param hash type of hash to use (choices can be found in hash.h)
  419. \param mgf type of mask generation function to use
  420. \param label an optional label to associate with encrypted message
  421. \param labelSz size of the optional label used
  422. _Example_
  423. \code
  424. WC_WC_WC_RNG rng;
  425. RsaKey key;
  426. byte in[] = “I use Turing Machines to ask questions”
  427. byte out[256];
  428. int ret;
  429. ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key, &rng,
  430. WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
  431. if (ret < 0) {
  432. //handle error
  433. }
  434. \endcode
  435. \sa wc_RsaPublicEncrypt
  436. \sa wc_RsaPrivateDecrypt_ex
  437. */
  438. WOLFSSL_API int wc_RsaPublicEncrypt_ex(const byte* in, word32 inLen, byte* out,
  439. word32 outLen, RsaKey* key, WC_RNG* rng, int type,
  440. enum wc_HashType hash, int mgf, byte* label, word32 lableSz);
  441. /*!
  442. \ingroup RSA
  443. \brief This function uses RSA to decrypt a message and gives the
  444. option of what padding type.
  445. \return size On successful decryption, the size of the decrypted message
  446. is returned.
  447. \return MEMORY_E Returned if not enough memory on system to malloc a
  448. needed array.
  449. \return BAD_FUNC_ARG Returned if a bad argument was passed into the
  450. function.
  451. \param in pointer to the buffer for decryption
  452. \param inLen length of the buffer to decrypt
  453. \param out decrypted msg created
  454. \param outLen length of buffer available to hold decrypted msg
  455. \param key initialized RSA key struct
  456. \param type type of padding to use (WC_RSA_OAEP_PAD or WC_RSA_PKCSV15_PAD)
  457. \param hash type of hash to use (choices can be found in hash.h)
  458. \param mgf type of mask generation function to use
  459. \param label an optional label to associate with encrypted message
  460. \param labelSz size of the optional label used
  461. _Example_
  462. \code
  463. WC_WC_WC_RNG rng;
  464. RsaKey key;
  465. byte in[] = “I use Turing Machines to ask questions”
  466. byte out[256];
  467. byte plain[256];
  468. int ret;
  469. ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key,
  470. &rng, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
  471. if (ret < 0) {
  472. //handle error
  473. }
  474. ret = wc_RsaPrivateDecrypt_ex(out, ret, plain, sizeof(plain), &key,
  475. WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
  476. if (ret < 0) {
  477. //handle error
  478. }
  479. \endcode
  480. \sa none
  481. */
  482. WOLFSSL_API int wc_RsaPrivateDecrypt_ex(const byte* in, word32 inLen,
  483. byte* out, word32 outLen, RsaKey* key, int type,
  484. enum wc_HashType hash, int mgf, byte* label, word32 lableSz);
  485. /*!
  486. \ingroup RSA
  487. \brief This function uses RSA to decrypt a message inline and gives the
  488. option of what padding type. The in buffer will contain the decrypted
  489. message after being called and the out byte pointer will point to the
  490. location in the “in” buffer where the plain text is.
  491. \return size On successful decryption, the size of the decrypted message
  492. is returned.
  493. \return MEMORY_E: Returned if not enough memory on system to malloc a
  494. needed array.
  495. \return RSA_PAD_E: Returned if an error in the padding was encountered.
  496. \return BAD_PADDING_E: Returned if an error happened during parsing past
  497. padding.
  498. \return BAD_FUNC_ARG: Returned if a bad argument was passed into the
  499. function.
  500. \param in pointer to the buffer for decryption
  501. \param inLen length of the buffer to decrypt
  502. \param out pointer to location of decrypted message in “in” buffer
  503. \param key initialized RSA key struct
  504. \param type type of padding to use (WC_RSA_OAEP_PAD or WC_RSA_PKCSV15_PAD)
  505. \param hash type of hash to use (choices can be found in hash.h)
  506. \param mgf type of mask generation function to use
  507. \param label an optional label to associate with encrypted message
  508. \param labelSz size of the optional label used
  509. _Example_
  510. \code
  511. WC_WC_WC_RNG rng;
  512. RsaKey key;
  513. byte in[] = “I use Turing Machines to ask questions”
  514. byte out[256];
  515. byte* plain;
  516. int ret;
  517. ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key,
  518. &rng, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
  519. if (ret < 0) {
  520. //handle error
  521. }
  522. ret = wc_RsaPrivateDecryptInline_ex(out, ret, &plain, &key,
  523. WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
  524. if (ret < 0) {
  525. //handle error
  526. }
  527. \endcode
  528. \sa none
  529. */
  530. WOLFSSL_API int wc_RsaPrivateDecryptInline_ex(byte* in, word32 inLen,
  531. byte** out, RsaKey* key, int type, enum wc_HashType hash,
  532. int mgf, byte* label, word32 lableSz);
  533. /*!
  534. \ingroup RSA
  535. \brief Flattens the RsaKey structure into individual elements (e, n)
  536. used for the RSA algorithm.
  537. \return 0 Returned if the function executed normally, without error.
  538. \return BAD_FUNC_ARG: Returned if any of the parameters are passed in
  539. with a null value.
  540. \return RSA_BUFFER_E: Returned if the e or n buffers passed in are not
  541. the correct size.
  542. \return MP_MEM: Returned if an internal function has memory errors.
  543. \return MP_VAL: Returned if an internal function argument is not valid.
  544. \param key The key to use for verification.
  545. \param e a buffer for the value of e. e is a large positive integer in
  546. the RSA modular arithmetic operation.
  547. \param eSz the size of the e buffer.
  548. \param n a buffer for the value of n. n is a large positive integer in
  549. the RSA modular arithmetic operation.
  550. \param nSz the size of the n buffer.
  551. _Example_
  552. \code
  553. Rsa key; // A valid RSA key.
  554. byte e[ buffer sz E.g. 256 ];
  555. byte n[256];
  556. int ret;
  557. word32 eSz = sizeof(e);
  558. word32 nSz = sizeof(n);
  559. ...
  560. ret = wc_RsaFlattenPublicKey(&key, e, &eSz, n, &nSz);
  561. if (ret != 0) {
  562. // Failure case.
  563. }
  564. \endcode
  565. \sa wc_InitRsaKey
  566. \sa wc_InitRsaKey_ex
  567. \sa wc_MakeRsaKey
  568. \sa XMEMSET
  569. */
  570. WOLFSSL_API int wc_RsaFlattenPublicKey(RsaKey*, byte*, word32*, byte*,
  571. word32*);
  572. /*!
  573. \ingroup RSA
  574. \brief Convert Rsa Public key to DER format. Writes to output, and
  575. returns count of bytes written.
  576. \return >0 Success, number of bytes written.
  577. \return BAD_FUNC_ARG Returned if key or output is null.
  578. \return MEMORY_E Returned when an error allocating memory occurs.
  579. \return <0 Error
  580. \param key The RSA key structure to convert.
  581. \param output Output buffer to hold DER.
  582. \param inLen Length of buffer.
  583. _Example_
  584. \code
  585. RsaKey key;
  586. wc_RsaInitKey(&key, NULL);
  587. // Use key
  588. int BUFFER_SIZE = // Some adequate size for the buffer
  589. byte output[BUFFER_SIZE];
  590. if(wc_RsaKeyToPublicDer(&key, output, sizeof(output)) != 0)
  591. {
  592. // Handle Error
  593. }
  594. \endcode
  595. \sa wc_RsaKeyToPublicDer
  596. \sa wc_RsaInitKey
  597. */
  598. WOLFSSL_API int wc_RsaKeyToPublicDer(RsaKey*, byte* output, word32 inLen);
  599. /*!
  600. \ingroup RSA
  601. \brief This function generates a RSA private key of length size (in bits)
  602. and given exponent (e). It then stores this key in the provided RsaKey
  603. structure, so that it may be used for encryption/decryption. A secure
  604. number to use for e is 65537. size is required to be greater than
  605. RSA_MIN_SIZE and less than RSA_MAX_SIZE. For this function to be
  606. available, the option WOLFSSL_KEY_GEN must be enabled at compile time.
  607. This can be accomplished with --enable-keygen if using ./configure.
  608. \return 0 Returned upon successfully generating a RSA private key
  609. \return BAD_FUNC_ARG Returned if any of the input arguments are NULL,
  610. the size parameter falls outside of the necessary bounds, or e is
  611. incorrectly chosen
  612. \return RNG_FAILURE_E Returned if there is an error generating a random
  613. block using the provided RNG structure
  614. \return MP_INIT_E
  615. \return MP_READ_E May be May be returned if there is an error in the math
  616. library used while generating the RSA key returned if there is an error
  617. in the math library used while generating the RSA key
  618. \return MP_CMP_E May be returned if there is an error in the math library
  619. used while generating the RSA key
  620. \return MP_INVMOD_E May be returned if there is an error in the math
  621. library used while generating the RSA key
  622. \return MP_EXPTMOD_E May be returned if there is an error in the math
  623. library used while generating the RSA key
  624. \return MP_MOD_E May be returned if there is an error in the math
  625. library used while generating the RSA key
  626. \return MP_MUL_E May be returned if there is an error in the math
  627. library used while generating the RSA key
  628. \return MP_ADD_E May be returned if there is an error in the math
  629. library used while generating the RSA key
  630. \return MP_MULMOD_E May be returned if there is an error in the math
  631. library used while generating the RSA key
  632. \return MP_TO_E May be returned if there is an error in the math
  633. library used while generating the RSA key
  634. \return MP_MEM May be returned if there is an error in the math
  635. library used while generating the RSA key
  636. \return MP_ZERO_E May be returned if there is an error in the math
  637. library used while generating the RSA key
  638. \param key pointer to the RsaKey structure in which to store the
  639. generated private key
  640. \param size desired keylenth, in bits. Required to be greater than
  641. RSA_MIN_SIZE and less than RSA_MAX_SIZE
  642. \param e exponent parameter to use for generating the key. A secure
  643. choice is 65537
  644. \param rng pointer to an RNG structure to use for random number generation
  645. while making the ke
  646. _Example_
  647. \code
  648. RsaKey priv;
  649. WC_WC_RNG rng;
  650. int ret = 0;
  651. long e = 65537; // standard value to use for exponent
  652. wc_InitRsaKey(&priv, NULL); // not using heap hint. No custom memory
  653. wc_InitRng(&rng);
  654. // generate 2048 bit long private key
  655. ret = wc_MakeRsaKey(&priv, 2048, e, &rng);
  656. if( ret != 0 ) {
  657. // error generating private key
  658. }
  659. \endcode
  660. \sa none
  661. */
  662. WOLFSSL_API int wc_MakeRsaKey(RsaKey* key, int size, long e, WC_RNG* rng);