luna - wolfssl/doc/dox_comments/header

   1/*!
   2    \ingroup RSA
   3
   4    \brief This function initializes a provided RsaKey struct. It also takes
   5    in a heap identifier, for use with user defined memory overrides
   6    (see XMALLOC, XFREE, XREALLOC).
   7
   8    The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING
   9    is enabled.
  10
  11    \return 0 Returned upon successfully initializing the RSA structure for
  12    use with encryption and decryption
  13    \return BAD_FUNC_ARGS Returned if the RSA key pointer evaluates to NULL
  14
  15    \param key pointer to the RsaKey structure to initialize
  16    \param heap pointer to a heap identifier, for use with memory overrides,
  17    allowing custom handling of memory allocation. This heap will be the
  18    default used when allocating memory for use with this RSA object
  19
  20    _Example_
  21    \code
  22    RsaKey enc;
  23    int ret;
  24    ret = wc_InitRsaKey(&enc, NULL); // not using heap hint. No custom memory
  25    if ( ret != 0 ) {
  26    	// error initializing RSA key
  27    }
  28    \endcode
  29
  30    \sa wc_FreeRsaKey
  31    \sa wc_RsaSetRNG
  32*/
  33int  wc_InitRsaKey(RsaKey* key, void* heap);
  34
  35/*!
  36    \ingroup RSA
  37
  38    \brief This function initializes a provided RsaKey struct. The id and
  39    len are used to identify the key on the device while the devId identifies
  40    the device.  It also takes in a heap identifier, for use with user defined
  41    memory overrides (see XMALLOC, XFREE, XREALLOC).
  42
  43    The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING
  44    is enabled.
  45
  46    \note This API is only available when WOLF_PRIVATE_KEY_ID is defined,
  47    which is set for PKCS11 support.
  48
  49    \return 0 Returned upon successfully initializing the RSA structure for
  50    use with encryption and decryption
  51    \return BAD_FUNC_ARGS Returned if the RSA key pointer evaluates to NULL
  52    \return BUFFER_E Returned if len is less than 0 or greater than
  53    RSA_MAX_ID_LEN.
  54
  55    \param key pointer to the RsaKey structure to initialize
  56    \param id identifier of key on device
  57    \param len length of identifier in bytes
  58    \param heap pointer to a heap identifier, for use with memory overrides,
  59    allowing custom handling of memory allocation. This heap will be the
  60    default used when allocating memory for use with this RSA object
  61    \param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
  62
  63    _Example_
  64    \code
  65    RsaKey enc;
  66    unsigned char* id = (unsigned char*)"RSA2048";
  67    int len = 7;
  68    int devId = 1;
  69    int ret;
  70    ret = wc_CryptoDev_RegisterDevice(devId, wc_Pkcs11_CryptoDevCb,
  71                                      &token);
  72    if ( ret != 0) {
  73        // error associating callback and token with device id
  74    }
  75    ret = wc_InitRsaKey_Id(&enc, id, len, NULL, devId); // not using heap hint
  76    if ( ret != 0 ) {
  77        // error initializing RSA key
  78    }
  79    \endcode
  80
  81    \sa wc_InitRsaKey
  82    \sa wc_FreeRsaKey
  83    \sa wc_RsaSetRNG
  84*/
  85int  wc_InitRsaKey_Id(RsaKey* key, unsigned char* id, int len,
  86        void* heap, int devId);
  87
  88/*!
  89    \ingroup RSA
  90
  91    \brief This function associates RNG with Key. It is needed when WC_RSA_BLINDING
  92    is enabled.
  93
  94    \return 0 Returned upon success
  95    \return BAD_FUNC_ARGS Returned if the RSA key, rng pointer evaluates to NULL
  96
  97    \param key pointer to the RsaKey structure to be associated
  98    \param rng pointer to the WC_RNG structure to associate with
  99
 100    _Example_
 101    \code
 102    ret = wc_InitRsaKey(&key, NULL);
 103    if (ret == 0) {
 104        ret = wc_InitRng(&rng);
 105    } else return -1;
 106    if (ret == 0) {
 107        ret = wc_RsaSetRNG(&key, &rng);
 108    \endcode
 109
 110    \sa wc_InitRsaKey
 111    \sa wc_RsaSetRNG
 112*/
 113int wc_RsaSetRNG(RsaKey* key, WC_RNG* rng);
 114
 115/*!
 116    \ingroup RSA
 117
 118    \brief This function frees a provided RsaKey struct using mp_clear.
 119
 120    \return 0 Returned upon successfully freeing the key
 121
 122    \param key pointer to the RsaKey structure to free
 123
 124    _Example_
 125    \code
 126    RsaKey enc;
 127    wc_InitRsaKey(&enc, NULL); // not using heap hint. No custom memory
 128    ... set key, do encryption
 129
 130    wc_FreeRsaKey(&enc);
 131    \endcode
 132
 133    \sa wc_InitRsaKey
 134*/
 135int  wc_FreeRsaKey(RsaKey* key);
 136
 137/*!
 138    \ingroup RSA
 139
 140    \brief Function that does the RSA operation directly with no padding. The input
 141        size must match key size. Typically this is
 142        used when padding is already done on the RSA input.
 143
 144    \return size On successfully encryption the size of the encrypted buffer
 145    is returned
 146    \return RSA_BUFFER_E RSA buffer error, output too small or input too large
 147
 148    \param in buffer to do operation on
 149    \param inLen length of input buffer
 150    \param out buffer to hold results
 151    \param outSz gets set to size of result buffer. Should be passed in as length
 152        of out buffer. If the pointer "out" is null then outSz gets set to the
 153        expected buffer size needed and LENGTH_ONLY_E gets returned.
 154    \param key initialized RSA key to use for encrypt/decrypt
 155    \param type if using private or public key (RSA_PUBLIC_ENCRYPT,
 156        RSA_PUBLIC_DECRYPT, RSA_PRIVATE_ENCRYPT, RSA_PRIVATE_DECRYPT)
 157    \param rng initialized WC_RNG struct
 158
 159    _Example_
 160    \code
 161    int ret;
 162    WC_RNG rng;
 163    RsaKey key;
 164    byte  in[256];
 165    byte out[256];
 166    word32 outSz = (word32)sizeof(out);
 167    …
 168
 169    ret = wc_RsaDirect(in, (word32)sizeof(in), out, &outSz, &key,
 170        RSA_PRIVATE_ENCRYPT, &rng);
 171    if (ret < 0) {
 172	    //handle error
 173    }
 174    \endcode
 175
 176    \sa wc_RsaPublicEncrypt
 177    \sa wc_RsaPrivateDecrypt
 178*/
 179int wc_RsaDirect(const byte* in, word32 inLen, byte* out, word32* outSz,
 180        RsaKey* key, int type, WC_RNG* rng);
 181
 182/*!
 183    \ingroup RSA
 184
 185    \brief This function encrypts a message from in and stores the result
 186    in out. It requires an initialized public key and a random number
 187    generator. As a side effect, this function will return the bytes written
 188    to out in outLen.
 189
 190    \return Success Upon successfully encrypting the input message, returns
 191    the number of bytes written on success and less than zero for failure.
 192    \return BAD_FUNC_ARG Returned if any of the input parameters are invalid
 193    \return RSA_BUFFER_E Returned if the output buffer is too small to store
 194    the ciphertext
 195    \return RNG_FAILURE_E Returned if there is an error generating a random
 196    block using the provided RNG structure
 197    \return MP_INIT_E May be returned if there is an error in the math
 198    library used while encrypting the message
 199    \return MP_READ_E May be returned if there is an error in the math
 200    library used while encrypting the message
 201    \return MP_CMP_E May be returned if there is an error in the math
 202    library used while encrypting the message
 203    \return MP_INVMOD_E May be returned if there is an error in the math
 204    library used while encrypting the message
 205    \return MP_EXPTMOD_E May be returned if there is an error in the math
 206    library used while encrypting the message
 207    \return MP_MOD_E May be returned if there is an error in the math
 208    library used while encrypting the message
 209    \return MP_MUL_E May be returned if there is an error in the math
 210    library used while encrypting the message
 211    \return MP_ADD_E May be returned if there is an error in the math
 212    library used while encrypting the message
 213    \return MP_MULMOD_E May be returned if there is an error in the math
 214    library used while encrypting the message
 215    \return MP_TO_E May be returned if there is an error in the math
 216    library used while encrypting the message
 217    \return MP_MEM May be returned if there is an error in the math
 218    library used while encrypting the message
 219    \return MP_ZERO_E May be returned if there is an error in the math
 220    library used while encrypting the message
 221
 222    \param in pointer to a buffer containing the input message to encrypt
 223    \param inLen the length of the message to encrypt
 224    \param out pointer to the buffer in which to store the output ciphertext
 225    \param outLen the length of the output buffer
 226    \param key pointer to the RsaKey structure containing the public
 227    key to use for encryption
 228    \param rng The RNG structure with which to generate random block padding
 229
 230    _Example_
 231    \code
 232    RsaKey pub;
 233    int ret = 0;
 234    byte n[] = { // initialize with received n component of public key };
 235    byte e[] = { // initialize with received e component of public key };
 236    byte msg[] = { // initialize with plaintext of message to encrypt };
 237    byte cipher[256]; // 256 bytes is large enough to store 2048 bit RSA
 238    ciphertext
 239
 240    wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory
 241    wc_RsaPublicKeyDecodeRaw(n, sizeof(n), e, sizeof(e), &pub);
 242    // initialize with received public key parameters
 243    ret = wc_RsaPublicEncrypt(msg, sizeof(msg), out, sizeof(out), &pub, &rng);
 244    if ( ret != 0 ) {
 245    	// error encrypting message
 246    }
 247    \endcode
 248
 249    \sa wc_RsaPrivateDecrypt
 250*/
 251int  wc_RsaPublicEncrypt(const byte* in, word32 inLen, byte* out,
 252                                 word32 outLen, RsaKey* key, WC_RNG* rng);
 253
 254/*!
 255    \ingroup RSA
 256
 257    \brief This functions is utilized by the wc_RsaPrivateDecrypt function
 258    for decrypting.
 259
 260    \return Success Length of decrypted data.
 261    \return RSA_PAD_E RsaUnPad error, bad formatting
 262
 263    \param in The byte array to be decrypted.
 264    \param inLen The length of in.
 265    \param out The byte array for the decrypted data to be stored.
 266    \param key The key to use for decryption.
 267
 268    _Example_
 269    \code
 270    none
 271    \endcode
 272
 273    \sa wc_RsaPrivateDecrypt
 274*/
 275int  wc_RsaPrivateDecryptInline(byte* in, word32 inLen, byte** out,
 276                                        RsaKey* key);
 277
 278/*!
 279    \ingroup RSA
 280
 281    \brief This functions provides private RSA decryption.
 282
 283    \return Success length of decrypted data.
 284    \return MEMORY_E -125, out of memory error
 285    \return BAD_FUNC_ARG -173, Bad function argument provided
 286
 287    \param in The byte array to be decrypted.
 288    \param inLen The length of in.
 289    \param out The byte array for the decrypted data to be stored.
 290    \param outLen The length of out.
 291    \param key The key to use for decryption.
 292
 293    _Example_
 294    \code
 295    ret = wc_RsaPublicEncrypt(in, inLen, out, sizeof(out), &key, &rng);
 296    if (ret < 0) {
 297        return -1;
 298    }
 299    ret = wc_RsaPrivateDecrypt(out, ret, plain, sizeof(plain), &key);
 300    if (ret < 0) {
 301        return -1;
 302    }
 303    \endcode
 304
 305    \sa RsaUnPad
 306    \sa wc_RsaFunction
 307    \sa wc_RsaPrivateDecryptInline
 308*/
 309int  wc_RsaPrivateDecrypt(const byte* in, word32 inLen, byte* out,
 310                                  word32 outLen, RsaKey* key);
 311
 312/*!
 313    \ingroup RSA
 314
 315    \brief Signs the provided array with the private key.
 316
 317    \return RSA_BUFFER_E: -131, RSA buffer error, output too small or
 318    input too large
 319
 320    \param in The byte array to be encrypted.
 321    \param inLen The length of in.
 322    \param out The byte array for the encrypted data to be stored.
 323    \param outLen The length of out.
 324    \param key The key to use for encryption.
 325    \param RNG The RNG struct to use for random number purposes.
 326
 327    _Example_
 328    \code
 329    ret = wc_RsaSSL_Sign(in, inLen, out, sizeof(out), &key, &rng);
 330    if (ret < 0) {
 331        return -1;
 332    }
 333    memset(plain, 0, sizeof(plain));
 334    ret = wc_RsaSSL_Verify(out, ret, plain, sizeof(plain), &key);
 335    if (ret < 0) {
 336        return -1;
 337    }
 338    if (ret != inLen) {
 339        return -1;
 340    }
 341    if (XMEMCMP(in, plain, ret) != 0) {
 342        return -1;
 343    }
 344    \endcode
 345
 346    \sa wc_RsaPad
 347*/
 348int  wc_RsaSSL_Sign(const byte* in, word32 inLen, byte* out,
 349                            word32 outLen, RsaKey* key, WC_RNG* rng);
 350
 351/*!
 352    \ingroup RSA
 353
 354    \brief Used to verify that the message was signed by RSA key.  The output
 355    uses the same byte array as the input.
 356
 357    \return >0 Length of the digest.
 358    \return <0 An error occurred.
 359
 360    \param in Byte array to be decrypted.
 361    \param inLen Length of the buffer input.
 362    \param out Pointer to a pointer for decrypted information.
 363    \param key RsaKey to use.
 364
 365    _Example_
 366    \code
 367    RsaKey key;
 368    WC_RNG rng;
 369    int ret = 0;
 370    long e = 65537; // standard value to use for exponent
 371    wc_InitRsaKey(&key, NULL); // not using heap hint. No custom memory
 372    wc_InitRng(&rng);
 373    wc_MakeRsaKey(&key, 2048, e, &rng);
 374
 375    byte in[] = { // Initialize with some RSA encrypted information }
 376    byte* out;
 377    if(wc_RsaSSL_VerifyInline(in, sizeof(in), &out, &key) < 0)
 378    {
 379        // handle error
 380    }
 381    \endcode
 382
 383    \sa wc_RsaSSL_Verify
 384    \sa wc_RsaSSL_Sign
 385*/
 386int  wc_RsaSSL_VerifyInline(byte* in, word32 inLen, byte** out,
 387                                    RsaKey* key);
 388
 389/*!
 390    \ingroup RSA
 391
 392    \brief Used to verify that the message was signed by key.
 393
 394    \return Success Length of digest on no error.
 395    \return MEMORY_E memory exception.
 396
 397    \param in The byte array to be decrypted.
 398    \param inLen The length of in.
 399    \param out The byte array for the decrypted data to be stored.
 400    \param outLen The length of out.
 401    \param key The key to use for verification.
 402
 403    _Example_
 404    \code
 405    ret = wc_RsaSSL_Sign(in, inLen, out, sizeof(out), &key, &rng);
 406    if (ret < 0) {
 407        return -1;
 408    }
 409    memset(plain, 0, sizeof(plain));
 410    ret = wc_RsaSSL_Verify(out, ret, plain, sizeof(plain), &key);
 411    if (ret < 0) {
 412        return -1;
 413    }
 414    if (ret != inLen) {
 415        return -1;
 416    }
 417    if (XMEMCMP(in, plain, ret) != 0) {
 418        return -1;
 419    }
 420    \endcode
 421
 422    \sa wc_RsaSSL_Sign
 423*/
 424int  wc_RsaSSL_Verify(const byte* in, word32 inLen, byte* out,
 425                              word32 outLen, RsaKey* key);
 426
 427/*!
 428    \ingroup RSA
 429
 430    \brief Signs the provided array with the private key.
 431
 432    \return RSA_BUFFER_E: -131, RSA buffer error, output too small or
 433    input too large
 434
 435    \param in The byte array to be encrypted.
 436    \param inLen The length of in.
 437    \param out The byte array for the encrypted data to be stored.
 438    \param outLen The length of out.
 439    \param hash The hash type to be in message
 440    \param mgf Mask Generation Function Identifiers
 441    \param key The key to use for verification.
 442
 443    _Example_
 444    \code
 445    ret = wc_InitRsaKey(&key, NULL);
 446    if (ret == 0) {
 447        ret = wc_InitRng(&rng);
 448    } else return -1;
 449    if (ret == 0) {
 450        ret = wc_RsaSetRNG(&key, &rng);
 451    } else return -1;
 452    if (ret == 0) {
 453            ret = wc_MakeRsaKey(&key, 2048, WC_RSA_EXPONENT, &rng);
 454    } else return -1;
 455
 456    ret = wc_RsaPSS_Sign((byte*)szMessage, (word32)XSTRLEN(szMessage)+1,
 457            pSignature, sizeof(pSignature),
 458            WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
 459    if (ret > 0 ){
 460        sz = ret;
 461    } else return -1;
 462
 463    ret = wc_RsaPSS_Verify(pSignature, sz, pt, outLen,
 464            WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key);
 465    if (ret <= 0)return -1;
 466
 467    wc_FreeRsaKey(&key);
 468    wc_FreeRng(&rng);
 469    \endcode
 470
 471    \sa wc_RsaPSS_Verify
 472    \sa wc_RsaSetRNG
 473*/
 474int  wc_RsaPSS_Sign(const byte* in, word32 inLen, byte* out,
 475                                word32 outLen, enum wc_HashType hash, int mgf,
 476                                RsaKey* key, WC_RNG* rng);
 477
 478/*!
 479    \ingroup RSA
 480
 481    \brief Decrypt input signature to verify that the message was signed by key.
 482    The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.
 483
 484    \return Success Length of text on no error.
 485    \return MEMORY_E memory exception.
 486    \return MP_EXPTMOD_E - When using fastmath and FP_MAX_BITS not set to at least 2 times the keySize (Example when using 4096-bit key set FP_MAX_BITS to 8192 or greater value)
 487
 488    \param in The byte array to be decrypted.
 489    \param inLen The length of in.
 490    \param out The byte array for the decrypted data to be stored.
 491    \param outLen The length of out.
 492    \param hash The hash type to be in message
 493    \param mgf Mask Generation Function Identifiers
 494    \param key The key to use for verification.
 495
 496    _Example_
 497    \code
 498    ret = wc_InitRsaKey(&key, NULL);
 499    if (ret == 0) {
 500        ret = wc_InitRng(&rng);
 501    } else return -1;
 502    if (ret == 0) {
 503        ret = wc_RsaSetRNG(&key, &rng);
 504    } else return -1;
 505    if (ret == 0) {
 506            ret = wc_MakeRsaKey(&key, 2048, WC_RSA_EXPONENT, &rng);
 507    } else return -1;
 508    ret = wc_RsaPSS_Sign((byte*)szMessage, (word32)XSTRLEN(szMessage)+1,
 509            pSignature, sizeof(pSignature),
 510            WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
 511    if (ret > 0 ){
 512        sz = ret;
 513    } else return -1;
 514
 515    ret = wc_RsaPSS_Verify(pSignature, sz, pt, outLen,
 516            WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key);
 517    if (ret <= 0)return -1;
 518
 519    wc_FreeRsaKey(&key);
 520    wc_FreeRng(&rng);
 521    \endcode
 522
 523    \sa wc_RsaPSS_Sign
 524    \sa wc_RsaPSS_VerifyInline
 525    \sa wc_RsaPSS_CheckPadding
 526    \sa wc_RsaSetRNG
 527*/
 528int  wc_RsaPSS_Verify(const byte* in, word32 inLen, byte* out,
 529                                  word32 outLen, enum wc_HashType hash, int mgf,
 530                                  RsaKey* key);
 531
 532/*!
 533    \ingroup RSA
 534
 535    \brief Decrypt input signature to verify that the message was signed by RSA
 536    key.
 537    The output uses the same byte array as the input.
 538    The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING
 539    is enabled.
 540
 541    \return >0 Length of text.
 542    \return <0 An error occurred.
 543
 544    \param in Byte array to be decrypted.
 545    \param inLen Length of the buffer input.
 546    \param out Pointer to address containing the PSS data.
 547    \param hash The hash type to be in message
 548    \param mgf Mask Generation Function Identifiers
 549    \param key RsaKey to use.
 550
 551    _Example_
 552    \code
 553    ret = wc_InitRsaKey(&key, NULL);
 554    if (ret == 0) {
 555        ret = wc_InitRng(&rng);
 556    } else return -1;
 557    if (ret == 0) {
 558        ret = wc_RsaSetRNG(&key, &rng);
 559    } else return -1;
 560    if (ret == 0) {
 561            ret = wc_MakeRsaKey(&key, 2048, WC_RSA_EXPONENT, &rng);
 562    } else return -1;
 563    ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, pSignatureSz,
 564            WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
 565    if (ret > 0 ){
 566        sz = ret;
 567    } else return -1;
 568
 569    ret = wc_RsaPSS_VerifyInline(pSignature, sz, pt,
 570            WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key);
 571    if (ret <= 0)return -1;
 572
 573    wc_FreeRsaKey(&key);
 574    wc_FreeRng(&rng);
 575    \endcode
 576
 577    \sa wc_RsaPSS_Verify
 578    \sa wc_RsaPSS_Sign
 579    \sa wc_RsaPSS_VerifyCheck
 580    \sa wc_RsaPSS_VerifyCheck_ex
 581    \sa wc_RsaPSS_VerifyCheckInline
 582    \sa wc_RsaPSS_VerifyCheckInline_ex
 583    \sa wc_RsaPSS_CheckPadding
 584    \sa wc_RsaPSS_CheckPadding_ex
 585    \sa wc_RsaSetRNG
 586*/
 587
 588
 589int  wc_RsaPSS_VerifyInline(byte* in, word32 inLen, byte** out,
 590                                        enum wc_HashType hash, int mgf,
 591                                        RsaKey* key);
 592/*!
 593    \ingroup RSA
 594
 595    \brief Verify the message signed with RSA-PSS.
 596    Salt length is equal to hash length.
 597    The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.
 598
 599    \return the length of the PSS data on success and negative indicates failure.
 600    \return MEMORY_E memory exception.
 601
 602    \param in The byte array to be decrypted.
 603    \param inLen The length of in.
 604    \param out Pointer to address containing the PSS data.
 605    \param outLen The length of out.
 606    \param digest Hash of the data that is being verified.
 607    \param digestLen Length of hash.
 608    \param hash Hash algorithm.
 609    \param mgf Mask generation function.
 610    \param key Public RSA key.
 611
 612    _Example_
 613    \code
 614    ret = wc_InitRsaKey(&key, NULL);
 615    if (ret == 0) {
 616        ret = wc_InitRng(&rng);
 617    } else return -1;
 618    if (ret == 0) {
 619        ret = wc_RsaSetRNG(&key, &rng);
 620    } else return -1;
 621    if (ret == 0) {
 622            ret = wc_MakeRsaKey(&key, 2048, WC_RSA_EXPONENT, &rng);
 623    } else return -1;
 624
 625    if (ret == 0) {
 626        digestSz = wc_HashGetDigestSize(WC_HASH_TYPE_SHA256);
 627        ret = wc_Hash(WC_HASH_TYPE_SHA256, message, sz, digest, digestSz);
 628    } else return -1;
 629
 630    if (ret == 0) {
 631        ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, pSignatureSz,
 632                WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
 633        if (ret > 0 ){
 634            sz = ret;
 635        } else return -1;
 636    } else return -1;
 637    if (ret == 0) {
 638        ret = wc_RsaPSS_VerifyCheck(pSignature, sz, pt, outLen,
 639                digest, digestSz, WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key);
 640            if (ret <= 0) return -1;
 641    } else return -1;
 642
 643    wc_FreeRsaKey(&key);
 644    wc_FreeRng(&rng);
 645    \endcode
 646
 647    \sa wc_RsaPSS_Sign
 648    \sa wc_RsaPSS_Verify
 649    \sa wc_RsaPSS_VerifyCheck_ex
 650    \sa wc_RsaPSS_VerifyCheckInline
 651    \sa wc_RsaPSS_VerifyCheckInline_ex
 652    \sa wc_RsaPSS_CheckPadding
 653    \sa wc_RsaPSS_CheckPadding_ex
 654    \sa wc_RsaSetRNG
 655*/
 656
 657int  wc_RsaPSS_VerifyCheck(const byte* in, word32 inLen,
 658                               byte* out, word32 outLen,
 659                               const byte* digest, word32 digestLen,
 660                               enum wc_HashType hash, int mgf,
 661                               RsaKey* key);
 662/*!
 663    \ingroup RSA
 664
 665    \brief Verify the message signed with RSA-PSS.
 666    The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.
 667
 668    \return the length of the PSS data on success and negative indicates failure.
 669    \return MEMORY_E memory exception.
 670
 671    \param in The byte array to be decrypted.
 672    \param inLen The length of in.
 673    \param out Pointer to address containing the PSS data.
 674    \param outLen The length of out.
 675    \param digest Hash of the data that is being verified.
 676    \param digestLen Length of hash.
 677    \param hash Hash algorithm.
 678    \param mgf Mask generation function.
 679    \param saltLen  Length of salt used. RSA_PSS_SALT_LEN_DEFAULT (-1) indicates salt
 680    length is the same as the hash length. RSA_PSS_SALT_LEN_DISCOVER
 681    indicates salt length is determined from the data.
 682
 683    \param key Public RSA key.
 684
 685    _Example_
 686    \code
 687    ret = wc_InitRsaKey(&key, NULL);
 688    if (ret == 0) {
 689        ret = wc_InitRng(&rng);
 690    } else return -1;
 691    if (ret == 0) {
 692        ret = wc_RsaSetRNG(&key, &rng);
 693    } else return -1;
 694    if (ret == 0) {
 695            ret = wc_MakeRsaKey(&key, 2048, WC_RSA_EXPONENT, &rng);
 696    } else return -1;
 697
 698    if (ret == 0) {
 699        digestSz = wc_HashGetDigestSize(WC_HASH_TYPE_SHA256);
 700        ret = wc_Hash(WC_HASH_TYPE_SHA256, message, sz, digest, digestSz);
 701    } else return -1;
 702
 703    if (ret == 0) {
 704        ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, pSignatureSz,
 705                WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
 706        if (ret > 0 ){
 707            sz = ret;
 708        } else return -1;
 709    } else return -1;
 710    if (ret == 0) {
 711        ret = wc_RsaPSS_VerifyCheck_ex(pSignature, sz, pt, outLen,
 712                digest, digestSz, WC_HASH_TYPE_SHA256, WC_MGF1SHA256, saltLen, &key);
 713            if (ret <= 0) return -1;
 714    } else return -1;
 715
 716    wc_FreeRsaKey(&key);
 717    wc_FreeRng(&rng);
 718    \endcode
 719
 720    \sa wc_RsaPSS_Sign
 721    \sa wc_RsaPSS_Verify
 722    \sa wc_RsaPSS_VerifyCheck
 723    \sa wc_RsaPSS_VerifyCheckInline
 724    \sa wc_RsaPSS_VerifyCheckInline_ex
 725    \sa wc_RsaPSS_CheckPadding
 726    \sa wc_RsaPSS_CheckPadding_ex
 727    \sa wc_RsaSetRNG
 728*/
 729int  wc_RsaPSS_VerifyCheck_ex(byte* in, word32 inLen,
 730                               byte* out, word32 outLen,
 731                               const byte* digest, word32 digestLen,
 732                               enum wc_HashType hash, int mgf, int saltLen,
 733                               RsaKey* key);
 734
 735/*!
 736    \ingroup RSA
 737
 738    \brief Verify the message signed with RSA-PSS.
 739    The input buffer is reused for the output buffer.
 740    Salt length is equal to hash length.
 741
 742    The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.
 743
 744    \return the length of the PSS data on success and negative indicates failure.
 745
 746    \param in The byte array to be decrypted.
 747    \param inLen The length of in.
 748    \param out The byte array for the decrypted data to be stored.
 749    \param digest Hash of the data that is being verified.
 750    \param digestLen Length of hash.
 751    \param hash The hash type to be in message
 752    \param mgf Mask Generation Function Identifiers
 753    \param key The key to use for verification.
 754
 755    _Example_
 756    \code
 757    ret = wc_InitRsaKey(&key, NULL);
 758    if (ret == 0) {
 759        ret = wc_InitRng(&rng);
 760    } else return -1;
 761    if (ret == 0) {
 762        ret = wc_RsaSetRNG(&key, &rng);
 763    } else return -1;
 764    if (ret == 0) {
 765            ret = wc_MakeRsaKey(&key, 2048, WC_RSA_EXPONENT, &rng);
 766    } else return -1;
 767
 768    if (ret == 0) {
 769        digestSz = wc_HashGetDigestSize(WC_HASH_TYPE_SHA256);
 770        ret = wc_Hash(WC_HASH_TYPE_SHA256, message, sz, digest, digestSz);
 771    } else return -1;
 772
 773    if (ret == 0) {
 774        ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, pSignatureSz,
 775                WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
 776        if (ret > 0 ){
 777            sz = ret;
 778        } else return -1;
 779    } else return -1;
 780    if (ret == 0) {
 781        ret = wc_RsaPSS_VerifyCheckInline(pSignature, sz, pt,
 782                digest, digestSz, WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key);
 783            if (ret <= 0) return -1;
 784    } else return -1;
 785
 786    wc_FreeRsaKey(&key);
 787    wc_FreeRng(&rng);
 788    \endcode
 789
 790    \sa wc_RsaPSS_Sign
 791    \sa wc_RsaPSS_Verify
 792    \sa wc_RsaPSS_VerifyCheck
 793    \sa wc_RsaPSS_VerifyCheck_ex
 794    \sa wc_RsaPSS_VerifyCheckInline_ex
 795    \sa wc_RsaPSS_CheckPadding
 796    \sa wc_RsaPSS_CheckPadding_ex
 797    \sa wc_RsaSetRNG
 798*/
 799int  wc_RsaPSS_VerifyCheckInline(byte* in, word32 inLen, byte** out,
 800                               const byte* digest, word32 digentLen,
 801                               enum wc_HashType hash, int mgf,
 802                               RsaKey* key);
 803/*!
 804    \ingroup RSA
 805
 806    \brief Verify the message signed with RSA-PSS.
 807    The input buffer is reused for the output buffer.
 808    The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.
 809
 810    \return the length of the PSS data on success and negative indicates failure.
 811
 812    \param in The byte array to be decrypted.
 813    \param inLen The length of in.
 814    \param out The byte array for the decrypted data to be stored.
 815    \param digest Hash of the data that is being verified.
 816    \param digestLen Length of hash.
 817    \param hash The hash type to be in message
 818    \param mgf Mask Generation Function Identifiers
 819    \param saltLen  Length of salt used. RSA_PSS_SALT_LEN_DEFAULT (-1) indicates salt
 820    length is the same as the hash length. RSA_PSS_SALT_LEN_DISCOVER
 821    indicates salt length is determined from the data.
 822    \param key The key to use for verification.
 823
 824    _Example_
 825    \code
 826    ret = wc_InitRsaKey(&key, NULL);
 827    if (ret == 0) {
 828        ret = wc_InitRng(&rng);
 829    } else return -1;
 830    if (ret == 0) {
 831        ret = wc_RsaSetRNG(&key, &rng);
 832    } else return -1;
 833    if (ret == 0) {
 834            ret = wc_MakeRsaKey(&key, 2048, WC_RSA_EXPONENT, &rng);
 835    } else return -1;
 836
 837    if (ret == 0) {
 838        digestSz = wc_HashGetDigestSize(WC_HASH_TYPE_SHA256);
 839        ret = wc_Hash(WC_HASH_TYPE_SHA256, message, sz, digest, digestSz);
 840    } else return -1;
 841
 842    if (ret == 0) {
 843        ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, pSignatureSz,
 844                WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
 845        if (ret > 0 ){
 846            sz = ret;
 847        } else return -1;
 848    } else return -1;
 849    if (ret == 0) {
 850        ret = wc_RsaPSS_VerifyCheckInline_ex(pSignature, sz, pt,
 851                digest, digestSz, WC_HASH_TYPE_SHA256, WC_MGF1SHA256, saltLen, &key);
 852            if (ret <= 0) return -1;
 853    } else return -1;
 854
 855    wc_FreeRsaKey(&key);
 856    wc_FreeRng(&rng);
 857    \endcode
 858
 859    \sa wc_RsaPSS_Sign
 860    \sa wc_RsaPSS_Verify
 861    \sa wc_RsaPSS_VerifyCheck
 862    \sa wc_RsaPSS_VerifyCheck_ex
 863    \sa wc_RsaPSS_VerifyCheckInline
 864    \sa wc_RsaPSS_CheckPadding
 865    \sa wc_RsaPSS_CheckPadding_ex
 866    \sa wc_RsaSetRNG
 867*/
 868int  wc_RsaPSS_VerifyCheckInline_ex(byte* in, word32 inLen, byte** out,
 869                               const byte* digest, word32 digentLen,
 870                               enum wc_HashType hash, int mgf, int saltLen,
 871                               RsaKey* key);
 872
 873/*!
 874    \ingroup RSA
 875
 876    \brief Checks the PSS data to ensure that the signature matches.
 877    Salt length is equal to hash length.
 878    The key has to be associated with RNG by wc_RsaSetRNG when WC_RSA_BLINDING is enabled.
 879
 880    \return BAD_PADDING_E when the PSS data is invalid, BAD_FUNC_ARG when
 881    NULL is passed in to in or sig or inSz is not the same as the hash
 882    algorithm length and 0 on success.
 883    \return MEMORY_E memory exception.
 884
 885    \param in Hash of the data that is being verified.
 886    \param inSz Length of hash.
 887    \param sig Buffer holding PSS data.
 888    \param sigSz Size of PSS data.
 889    \param hashType Hash algorithm.
 890
 891    _Example_
 892    \code
 893    ret = wc_InitRsaKey(&key, NULL);
 894    if (ret == 0) {
 895        ret = wc_InitRng(&rng);
 896    } else return -1;
 897    if (ret == 0) {
 898        ret = wc_RsaSetRNG(&key, &rng);
 899    } else return -1;
 900    if (ret == 0) {
 901            ret = wc_MakeRsaKey(&key, 2048, WC_RSA_EXPONENT, &rng);
 902    } else return -1;
 903    if (ret == 0) {
 904        digestSz = wc_HashGetDigestSize(WC_HASH_TYPE_SHA256);
 905        ret = wc_Hash(WC_HASH_TYPE_SHA256, message, sz, digest, digestSz);
 906    } else return -1;
 907    ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, sizeof(pSignature),
 908            WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
 909    if (ret > 0 ){
 910        sz = ret;
 911    } else return -1;
 912
 913    verify = wc_RsaPSS_Verify(pSignature, sz, out, outLen,
 914            WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key);
 915    if (verify <= 0)return -1;
 916
 917    ret = wc_RsaPSS_CheckPadding(digest, digestSz, out, verify, hash);
 918
 919    wc_FreeRsaKey(&key);
 920    wc_FreeRng(&rng);
 921    \endcode
 922
 923    \sa wc_RsaPSS_Sign
 924    \sa wc_RsaPSS_Verify
 925    \sa wc_RsaPSS_VerifyInline
 926    \sa wc_RsaPSS_VerifyCheck
 927    \sa wc_RsaPSS_VerifyCheck_ex
 928    \sa wc_RsaPSS_VerifyCheckInline
 929    \sa wc_RsaPSS_VerifyCheckInline_ex
 930    \sa wc_RsaPSS_CheckPadding_ex
 931    \sa wc_RsaSetRNG
 932*/
 933int  wc_RsaPSS_CheckPadding(const byte* in, word32 inLen, const byte* sig,
 934                                        word32 sigSz,
 935                                        enum wc_HashType hashType);
 936/*!
 937    \ingroup RSA
 938
 939    \brief Checks the PSS data to ensure that the signature matches.
 940    Salt length is equal to hash length.
 941
 942    \return BAD_PADDING_E when the PSS data is invalid, BAD_FUNC_ARG when
 943    NULL is passed in to in or sig or inSz is not the same as the hash
 944    algorithm length and 0 on success.
 945    \return MEMORY_E memory exception.
 946
 947    \param in        Hash of the data that is being verified.
 948    \param inSz      Length of hash.
 949    \param sig       Buffer holding PSS data.
 950    \param sigSz     Size of PSS data.
 951    \param hashType  Hash algorithm.
 952    \param saltLen   Length of salt used. RSA_PSS_SALT_LEN_DEFAULT (-1) indicates salt
 953        length is the same as the hash length. RSA_PSS_SALT_LEN_DISCOVER
 954        indicates salt length is determined from the data.
 955    \param bits      Can be used to calculate salt size in FIPS case
 956
 957    _Example_
 958    \code
 959    ret = wc_InitRsaKey(&key, NULL);
 960    if (ret == 0) {
 961        ret = wc_InitRng(&rng);
 962    } else return -1;
 963    if (ret == 0) {
 964        ret = wc_RsaSetRNG(&key, &rng);
 965    } else return -1;
 966    if (ret == 0) {
 967            ret = wc_MakeRsaKey(&key, 2048, WC_RSA_EXPONENT, &rng);
 968    } else return -1;
 969    if (ret == 0) {
 970        digestSz = wc_HashGetDigestSize(WC_HASH_TYPE_SHA256);
 971        ret = wc_Hash(WC_HASH_TYPE_SHA256, message, sz, digest, digestSz);
 972    } else return -1;
 973    ret = wc_RsaPSS_Sign(digest, digestSz, pSignature, sizeof(pSignature),
 974            WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key, &rng);
 975    if (ret > 0 ){
 976        sz = ret;
 977    } else return -1;
 978
 979    verify = wc_RsaPSS_Verify(pSignature, sz, out, outLen,
 980            WC_HASH_TYPE_SHA256, WC_MGF1SHA256, &key);
 981    if (verify <= 0)return -1;
 982
 983    ret = wc_RsaPSS_CheckPadding_ex(digest, digestSz, out, verify, hash, saltLen, 0);
 984
 985    wc_FreeRsaKey(&key);
 986    wc_FreeRng(&rng);
 987    \endcode
 988
 989    \sa wc_RsaPSS_Sign
 990    \sa wc_RsaPSS_Verify
 991    \sa wc_RsaPSS_VerifyInline
 992    \sa wc_RsaPSS_VerifyCheck
 993    \sa wc_RsaPSS_VerifyCheck_ex
 994    \sa wc_RsaPSS_VerifyCheckInline
 995    \sa wc_RsaPSS_VerifyCheckInline_ex
 996    \sa wc_RsaPSS_CheckPadding
 997*/
 998int  wc_RsaPSS_CheckPadding_ex(const byte* in, word32 inLen, const byte* sig,
 999                word32 sigSz, enum wc_HashType hashType, int saltLen, int bits);
1000/*!
1001    \ingroup RSA
1002
1003    \brief Returns the encryption size for the provided key structure.
1004
1005    \return Success Encryption size for the provided key structure.
1006
1007    \param key The key to use for verification.
1008
1009    _Example_
1010    \code
1011    int sz = wc_RsaEncryptSize(&key);
1012    \endcode
1013
1014    \sa wc_InitRsaKey
1015    \sa wc_InitRsaKey_ex
1016    \sa wc_MakeRsaKey
1017*/
1018int  wc_RsaEncryptSize(const RsaKey* key);
1019
1020/*!
1021    \ingroup RSA
1022
1023    \brief This function parses a DER-formatted RSA private key, extracts the
1024    private key and stores it in the given RsaKey structure. It also sets the
1025    distance parsed in idx.
1026
1027    \return 0 Returned upon successfully parsing the private key from the DER
1028    encoded input
1029    \return ASN_PARSE_E Returned if there is an error parsing the private key
1030    from the input buffer. This may happen if the input private key is not
1031    properly formatted according to ASN.1 standards
1032    \return ASN_RSA_KEY_E Returned if there is an error reading the private
1033    key elements of the RSA key input
1034
1035    \param input pointer to the buffer containing the DER formatted private
1036    key to decode
1037    \param inOutIdx pointer to the index in the buffer at which the key begins
1038    (usually 0). As a side effect of this function, inOutIdx will store the
1039    distance parsed through the input buffer
1040    \param key pointer to the RsaKey structure in which to store the decoded
1041    private key
1042    \param inSz size of the input buffer
1043
1044    _Example_
1045    \code
1046    RsaKey enc;
1047    word32 idx = 0;
1048    int ret = 0;
1049    byte der[] = { // initialize with DER-encoded RSA private key };
1050
1051    wc_InitRsaKey(&enc, NULL); // not using heap hint. No custom memory
1052    ret = wc_RsaPrivateKeyDecode(der, &idx, &enc, sizeof(der));
1053    if( ret != 0 ) {
1054    	// error parsing private key
1055    }
1056    \endcode
1057
1058    \sa wc_RsaPublicKeyDecode
1059    \sa wc_MakeRsaKey
1060*/
1061int  wc_RsaPrivateKeyDecode(const byte* input, word32* inOutIdx,
1062                            RsaKey* key, word32 inSz);
1063
1064/*!
1065    \ingroup RSA
1066
1067    \brief This function parses a DER-formatted RSA public key, extracts the
1068    public key and stores it in the given RsaKey structure. It also sets the
1069    distance parsed in idx.
1070
1071    \return 0 Returned upon successfully parsing the public key from the DER
1072    encoded input
1073    \return ASN_PARSE_E Returned if there is an error parsing the public key
1074    from the input buffer. This may happen if the input public key is not
1075    properly formatted according to ASN.1 standards
1076    \return ASN_OBJECT_ID_E Returned if the ASN.1 Object ID does not match
1077    that of a RSA public key
1078    \return ASN_EXPECT_0_E Returned if the input key is not correctly
1079    formatted according to ASN.1 standards
1080    \return ASN_BITSTR_E Returned if the input key is not correctly formatted
1081    according to ASN.1 standards
1082    \return ASN_RSA_KEY_E Returned if there is an error reading the public key
1083    elements of the RSA key input
1084
1085    \param input pointer to the buffer containing the input DER-encoded RSA
1086    public key to decode
1087    \param inOutIdx pointer to the index in the buffer at which the key
1088    begins (usually 0). As a side effect of this function, inOutIdx will
1089    store the distance parsed through the input buffer
1090    \param key pointer to the RsaKey structure in which to store the decoded
1091    public key
1092    \param inSz size of the input buffer
1093
1094    _Example_
1095    \code
1096    RsaKey pub;
1097    word32 idx = 0;
1098    int ret = 0;
1099    byte der[] = { // initialize with DER-encoded RSA public key };
1100
1101    wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory
1102    ret = wc_RsaPublicKeyDecode(der, &idx, &pub, sizeof(der));
1103    if( ret != 0 ) {
1104    	// error parsing public key
1105    }
1106    \endcode
1107
1108    \sa wc_RsaPublicKeyDecodeRaw
1109*/
1110int  wc_RsaPublicKeyDecode(const byte* input, word32* inOutIdx,
1111                           RsaKey* key, word32 inSz);
1112
1113/*!
1114    \ingroup RSA
1115
1116    \brief This function decodes the raw elements of an RSA public key, taking
1117    in the public modulus (n) and exponent (e). It stores these raw elements
1118    in the provided RsaKey structure, allowing one to use them in the
1119    encryption/decryption process.
1120
1121    \return 0 Returned upon successfully decoding the raw elements of the
1122    public key into the RsaKey structure
1123    \return BAD_FUNC_ARG Returned if any of the input arguments evaluates to
1124    NULL
1125    \return MP_INIT_E Returned if there is an error initializing an integer
1126    for use with the multiple precision integer (mp_int) library
1127    \return ASN_GETINT_E Returned if there is an error reading one of the
1128    provided RSA key elements, n or e
1129
1130    \param n pointer to a buffer containing the raw modulus parameter of the
1131    public RSA key
1132    \param nSz size of the buffer containing n
1133    \param e pointer to a buffer containing the raw exponent parameter of
1134    the public RSA key
1135    \param eSz size of the buffer containing e
1136    \param key pointer to the RsaKey struct to initialize with the provided
1137    public key elements
1138
1139    _Example_
1140    \code
1141    RsaKey pub;
1142    int ret = 0;
1143    byte n[] = { // initialize with received n component of public key };
1144    byte e[] = { // initialize with received e component of public key };
1145
1146    wc_InitRsaKey(&pub, NULL); // not using heap hint. No custom memory
1147    ret = wc_RsaPublicKeyDecodeRaw(n, sizeof(n), e, sizeof(e), &pub);
1148    if( ret != 0 ) {
1149    	// error parsing public key elements
1150    }
1151    \endcode
1152
1153    \sa wc_RsaPublicKeyDecode
1154*/
1155int  wc_RsaPublicKeyDecodeRaw(const byte* n, word32 nSz,
1156                                        const byte* e, word32 eSz, RsaKey* key);
1157
1158/*!
1159    \ingroup RSA
1160
1161    \brief This function converts an RsaKey key to DER format.  The result is
1162    written to output and it returns the number of bytes written.
1163
1164    \return >0 Success, number of bytes written.
1165    \return BAD_FUNC_ARG Returned if key or output is null, or if key->type
1166    is not RSA_PRIVATE, or if inLen isn't large enough for output buffer.
1167    \return MEMORY_E Returned if there is an error allocating memory.
1168
1169    \param key Initialized RsaKey structure.
1170    \param output Pointer to output buffer.
1171    \param inLen Size of output buffer.
1172
1173    _Example_
1174    \code
1175    byte* der;
1176    // Allocate memory for der
1177    int derSz = // Amount of memory allocated for der;
1178    RsaKey key;
1179    WC_RNG rng;
1180    long e = 65537; // standard value to use for exponent
1181    ret = wc_MakeRsaKey(&key, 2048, e, &rng); // generate 2048 bit long
1182    private key
1183    wc_InitRsaKey(&key, NULL);
1184    wc_InitRng(&rng);
1185    if(wc_RsaKeyToDer(&key, der, derSz) != 0)
1186    {
1187        // Handle the error thrown
1188    }
1189    \endcode
1190
1191    \sa wc_RsaKeyToPublicDer
1192    \sa wc_InitRsaKey
1193    \sa wc_MakeRsaKey
1194    \sa wc_InitRng
1195*/
1196int wc_RsaKeyToDer(RsaKey* key, byte* output, word32 inLen);
1197
1198/*!
1199    \ingroup RSA
1200
1201    \brief This function performs RSA encrypt while allowing the choice of
1202    which padding to use.
1203
1204    \return size On successfully encryption the size of the encrypted buffer
1205    is returned
1206    \return RSA_BUFFER_E RSA buffer error, output too small or input too large
1207
1208    \param in pointer to the buffer for encryption
1209    \param inLen length of the buffer to encrypt
1210    \param out encrypted msg created
1211    \param outLen length of buffer available to hold encrypted msg
1212    \param key initialized RSA key struct
1213    \param rng initialized WC_RNG struct
1214    \param type type of padding to use (WC_RSA_OAEP_PAD or WC_RSA_PKCSV15_PAD)
1215    \param hash type of hash to use (choices can be found in hash.h)
1216    \param mgf type of mask generation function to use
1217    \param label an optional label to associate with encrypted message
1218    \param labelSz size of the optional label used
1219
1220    _Example_
1221    \code
1222    WC_RNG rng;
1223    RsaKey key;
1224    byte in[] = “I use Turing Machines to ask questions”
1225    byte out[256];
1226    int ret;
1227    …
1228
1229    ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key, &rng,
1230    WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
1231    if (ret < 0) {
1232	    //handle error
1233    }
1234    \endcode
1235
1236    \sa wc_RsaPublicEncrypt
1237    \sa wc_RsaPrivateDecrypt_ex
1238*/
1239int  wc_RsaPublicEncrypt_ex(const byte* in, word32 inLen, byte* out,
1240                   word32 outLen, RsaKey* key, WC_RNG* rng, int type,
1241                   enum wc_HashType hash, int mgf, byte* label, word32 labelSz);
1242
1243/*!
1244    \ingroup RSA
1245
1246    \brief This function uses RSA to decrypt a message and gives the
1247    option of what padding type.
1248
1249    \return size On successful decryption, the size of the decrypted message
1250    is returned.
1251    \return MEMORY_E Returned if not enough memory on system to malloc a
1252    needed array.
1253    \return BAD_FUNC_ARG Returned if a bad argument was passed into the
1254    function.
1255
1256    \param in pointer to the buffer for decryption
1257    \param inLen length of the buffer to decrypt
1258    \param out decrypted msg created
1259    \param outLen length of buffer available to hold decrypted msg
1260    \param key initialized RSA key struct
1261    \param type type of padding to use (WC_RSA_OAEP_PAD or WC_RSA_PKCSV15_PAD)
1262    \param hash type of hash to use (choices can be found in hash.h)
1263    \param mgf type of mask generation function to use
1264    \param label an optional label to associate with encrypted message
1265    \param labelSz size of the optional label used
1266
1267    _Example_
1268    \code
1269    WC_RNG rng;
1270    RsaKey key;
1271    byte in[] = “I use Turing Machines to ask questions”
1272    byte out[256];
1273    byte plain[256];
1274    int ret;
1275    …
1276    ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key,
1277    &rng, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
1278    if (ret < 0) {
1279	    //handle error
1280    }
1281    …
1282    ret = wc_RsaPrivateDecrypt_ex(out, ret, plain, sizeof(plain), &key,
1283    WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
1284
1285    if (ret < 0) {
1286	    //handle error
1287    }
1288    \endcode
1289
1290    \sa none
1291*/
1292int  wc_RsaPrivateDecrypt_ex(const byte* in, word32 inLen,
1293                   byte* out, word32 outLen, RsaKey* key, int type,
1294                   enum wc_HashType hash, int mgf, byte* label, word32 labelSz);
1295
1296/*!
1297    \ingroup RSA
1298
1299    \brief This function uses RSA to decrypt a message inline and gives the
1300    option of what padding type. The in buffer will contain the decrypted
1301    message after being called and the out byte pointer will point to the
1302    location in the “in” buffer where the plain text is.
1303
1304    \return size On successful decryption, the size of the decrypted message
1305    is returned.
1306    \return MEMORY_E: Returned if not enough memory on system to malloc a
1307    needed array.
1308    \return RSA_PAD_E: Returned if an error in the padding was encountered.
1309    \return BAD_PADDING_E: Returned if an error happened during parsing past
1310    padding.
1311    \return BAD_FUNC_ARG: Returned if a bad argument was passed into the
1312    function.
1313
1314    \param in pointer to the buffer for decryption
1315    \param inLen length of the buffer to decrypt
1316    \param out pointer to location of decrypted message in “in” buffer
1317    \param key initialized RSA key struct
1318    \param type type of padding to use (WC_RSA_OAEP_PAD or WC_RSA_PKCSV15_PAD)
1319    \param hash type of hash to use (choices can be found in hash.h)
1320    \param mgf type of mask generation function to use
1321    \param label an optional label to associate with encrypted message
1322    \param labelSz size of the optional label used
1323
1324    _Example_
1325    \code
1326    WC_RNG rng;
1327    RsaKey key;
1328    byte in[] = “I use Turing Machines to ask questions”
1329    byte out[256];
1330    byte* plain;
1331    int ret;
1332    …
1333    ret = wc_RsaPublicEncrypt_ex(in, sizeof(in), out, sizeof(out), &key,
1334    &rng, WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
1335
1336    if (ret < 0) {
1337	    //handle error
1338    }
1339    …
1340    ret = wc_RsaPrivateDecryptInline_ex(out, ret, &plain, &key,
1341    WC_RSA_OAEP_PAD, WC_HASH_TYPE_SHA, WC_MGF1SHA1, NULL, 0);
1342
1343    if (ret < 0) {
1344	    //handle error
1345    }
1346    \endcode
1347
1348    \sa none
1349*/
1350int  wc_RsaPrivateDecryptInline_ex(byte* in, word32 inLen,
1351                      byte** out, RsaKey* key, int type, enum wc_HashType hash,
1352                      int mgf, byte* label, word32 labelSz);
1353
1354/*!
1355    \ingroup RSA
1356
1357    \brief Flattens the RsaKey structure into individual elements (e, n)
1358    used for the RSA algorithm.
1359
1360    \return 0 Returned if the function executed normally, without error.
1361    \return BAD_FUNC_ARG: Returned if any of the parameters are passed in
1362    with a null value.
1363    \return RSA_BUFFER_E: Returned if the e or n buffers passed in are not
1364    the correct size.
1365    \return MP_MEM: Returned if an internal function has memory errors.
1366    \return MP_VAL: Returned if an internal function argument is not valid.
1367
1368    \param key The key to use for verification.
1369    \param e a buffer for the value of e. e is a large positive integer in
1370    the RSA modular arithmetic operation.
1371    \param eSz the size of the e buffer.
1372    \param n a buffer for the value of n. n is a large positive integer in
1373    the RSA modular arithmetic operation.
1374    \param nSz the size of the n buffer.
1375
1376    _Example_
1377    \code
1378    Rsa key; // A valid RSA key.
1379    byte e[ buffer sz E.g. 256 ];
1380    byte n[256];
1381    int ret;
1382    word32 eSz = sizeof(e);
1383    word32 nSz = sizeof(n);
1384    ...
1385    ret = wc_RsaFlattenPublicKey(&key, e, &eSz, n, &nSz);
1386    if (ret != 0) {
1387    	// Failure case.
1388    }
1389    \endcode
1390
1391    \sa wc_InitRsaKey
1392    \sa wc_InitRsaKey_ex
1393    \sa wc_MakeRsaKey
1394*/
1395int  wc_RsaFlattenPublicKey(const RsaKey* key, byte* e, word32* eSz, byte* n,
1396                            word32* nSz);
1397
1398/*!
1399    \ingroup RSA
1400
1401    \brief Convert Rsa Public key to DER format.  Writes to output, and
1402    returns count of bytes written.
1403
1404    \return >0 Success, number of bytes written.
1405    \return BAD_FUNC_ARG Returned if key or output is null.
1406    \return MEMORY_E Returned when an error allocating memory occurs.
1407    \return <0 Error
1408
1409    \param key The RSA key structure to convert.
1410    \param output Output buffer to hold DER. (if NULL will return length only)
1411    \param inLen Length of buffer.
1412
1413    _Example_
1414    \code
1415    RsaKey key;
1416
1417    wc_InitRsaKey(&key, NULL);
1418    // Use key
1419
1420    const int BUFFER_SIZE = 1024; // Some adequate size for the buffer
1421    byte output[BUFFER_SIZE];
1422    if (wc_RsaKeyToPublicDer(&key, output, sizeof(output)) != 0) {
1423        // Handle Error
1424    }
1425    \endcode
1426
1427    \sa wc_RsaPublicKeyDerSize
1428    \sa wc_RsaKeyToPublicDer_ex
1429    \sa wc_InitRsaKey
1430*/
1431int wc_RsaKeyToPublicDer(RsaKey* key, byte* output, word32 inLen);
1432
1433/*!
1434    \ingroup RSA
1435
1436    \brief Convert RSA Public key to DER format. Writes to output, and
1437    returns count of bytes written. If with_header is 0 then only the
1438    ( seq + n + e) is returned in ASN.1 DER format and will exclude the header.
1439
1440    \return >0 Success, number of bytes written.
1441    \return BAD_FUNC_ARG Returned if key or output is null.
1442    \return MEMORY_E Returned when an error allocating memory occurs.
1443    \return <0 Error
1444
1445    \param key The RSA key structure to convert.
1446    \param output Output buffer to hold DER. (if NULL will return length only)
1447    \param inLen Length of buffer.
1448
1449    _Example_
1450    \code
1451    RsaKey key;
1452
1453    wc_InitRsaKey(&key, NULL);
1454    // Use key
1455
1456    const int BUFFER_SIZE = 1024; // Some adequate size for the buffer
1457    byte output[BUFFER_SIZE];
1458    if (wc_RsaKeyToPublicDer_ex(&key, output, sizeof(output), 0) != 0) {
1459        // Handle Error
1460    }
1461    \endcode
1462
1463    \sa wc_RsaPublicKeyDerSize
1464    \sa wc_RsaKeyToPublicDer
1465    \sa wc_InitRsaKey
1466*/
1467int wc_RsaKeyToPublicDer_ex(RsaKey* key, byte* output, word32 inLen,
1468    int with_header);
1469
1470/*!
1471    \ingroup RSA
1472
1473    \brief This function generates a RSA private key of length size (in bits)
1474    and given exponent (e). It then stores this key in the provided RsaKey
1475    structure, so that it may be used for encryption/decryption. A secure
1476    number to use for e is 65537. size is required to be greater than or equal
1477    to RSA_MIN_SIZE and less than or equal to RSA_MAX_SIZE. For this function
1478    to be available, the option WOLFSSL_KEY_GEN must be enabled at compile
1479    time.  This can be accomplished with --enable-keygen if using ./configure.
1480
1481    \return 0 Returned upon successfully generating a RSA private key
1482    \return BAD_FUNC_ARG Returned if any of the input arguments are NULL,
1483    the size parameter falls outside of the necessary bounds, or e is
1484    incorrectly chosen
1485    \return RNG_FAILURE_E Returned if there is an error generating a random
1486    block using the provided RNG structure
1487    \return MP_INIT_E
1488    \return MP_READ_E May be May be returned if there is an error in the math
1489    library used while generating the RSA key returned if there is an error
1490    in the math library used while generating the RSA key
1491    \return MP_CMP_E May be returned if there is an error in the math library
1492    used while generating the RSA key
1493    \return MP_INVMOD_E May be returned if there is an error in the math
1494    library used while generating the RSA key
1495    \return MP_EXPTMOD_E May be returned if there is an error in the math
1496    library used while generating the RSA key
1497    \return MP_MOD_E May be returned if there is an error in the math
1498    library used while generating the RSA key
1499    \return MP_MUL_E May be returned if there is an error in the math
1500    library used while generating the RSA key
1501    \return MP_ADD_E May be returned if there is an error in the math
1502    library used while generating the RSA key
1503    \return MP_MULMOD_E May be returned if there is an error in the math
1504    library used while generating the RSA key
1505    \return MP_TO_E May be returned if there is an error in the math
1506    library used while generating the RSA key
1507    \return MP_MEM May be returned if there is an error in the math
1508    library used while generating the RSA key
1509    \return MP_ZERO_E May be returned if there is an error in the math
1510    library used while generating the RSA key
1511
1512    \param key pointer to the RsaKey structure in which to store the
1513    generated private key
1514    \param size desired key length, in bits. Required to be greater than
1515    RSA_MIN_SIZE and less than RSA_MAX_SIZE
1516    \param e exponent parameter to use for generating the key. A secure
1517    choice is 65537
1518    \param rng pointer to an RNG structure to use for random number generation
1519    while making the key
1520
1521    _Example_
1522    \code
1523    RsaKey priv;
1524    WC_RNG rng;
1525    int ret = 0;
1526    long e = 65537; // standard value to use for exponent
1527
1528    wc_InitRsaKey(&priv, NULL); // not using heap hint. No custom memory
1529    wc_InitRng(&rng);
1530    // generate 2048 bit long private key
1531    ret = wc_MakeRsaKey(&priv, 2048, e, &rng);
1532    if( ret != 0 ) {
1533	    // error generating private key
1534    }
1535    \endcode
1536
1537    \sa none
1538*/
1539int wc_MakeRsaKey(RsaKey* key, int size, long e, WC_RNG* rng);
1540
1541/*!
1542    \ingroup RSA
1543
1544    \brief This function sets the non-blocking RSA context. When a RsaNb context
1545    is set it enables fast math based non-blocking exptmod, which splits the RSA
1546    function into many smaller operations.
1547    Enabled when WC_RSA_NONBLOCK is defined.
1548
1549    \return 0 Success
1550    \return BAD_FUNC_ARG Returned if key or nb is null.
1551
1552    \param key The RSA key structure
1553    \param nb The RSA non-blocking structure for this RSA key to use.
1554
1555    _Example_
1556    \code
1557    int ret, count = 0;
1558    RsaKey key;
1559    RsaNb  nb;
1560
1561    wc_InitRsaKey(&key, NULL);
1562
1563    // Enable non-blocking RSA mode - provide context
1564    ret = wc_RsaSetNonBlock(key, &nb);
1565    if (ret != 0)
1566        return ret;
1567
1568    do {
1569        ret = wc_RsaSSL_Sign(in, inLen, out, outSz, key, rng);
1570        count++; // track number of would blocks
1571        if (ret == FP_WOULDBLOCK) {
1572            // do "other" work here
1573        }
1574    } while (ret == FP_WOULDBLOCK);
1575    if (ret < 0) {
1576        return ret;
1577    }
1578
1579    printf("RSA non-block sign: size %d, %d times\n", ret, count);
1580    \endcode
1581
1582    \sa wc_RsaSetNonBlockTime
1583*/
1584int wc_RsaSetNonBlock(RsaKey* key, RsaNb* nb);
1585
1586/*!
1587    \ingroup RSA
1588
1589    \brief This function configures the maximum amount of blocking time in
1590    microseconds. It uses a pre-computed table (see tfm.c exptModNbInst) along
1591    with the CPU speed in megahertz to determine if the next operation can be
1592    completed within the maximum blocking time provided.
1593    Enabled when WC_RSA_NONBLOCK_TIME is defined.
1594
1595    \return 0 Success
1596    \return BAD_FUNC_ARG Returned if key is null or wc_RsaSetNonBlock was not
1597    previously called and key->nb is null.
1598
1599    \param key The RSA key structure.
1600    \param maxBlockUs Maximum time to block microseconds.
1601    \param cpuMHz CPU speed in megahertz.
1602
1603    _Example_
1604    \code
1605    RsaKey key;
1606    RsaNb  nb;
1607
1608    wc_InitRsaKey(&key, NULL);
1609    wc_RsaSetNonBlock(key, &nb);
1610    wc_RsaSetNonBlockTime(&key, 4000, 160); // Block Max = 4 ms, CPU = 160MHz
1611
1612    \endcode
1613
1614    \sa wc_RsaSetNonBlock
1615*/
1616int wc_RsaSetNonBlockTime(RsaKey* key, word32 maxBlockUs,
1617    word32 cpuMHz);
1618/*!
1619    \ingroup RSA
1620    \brief Initializes RSA key with heap and device ID.
1621
1622    \return 0 on success
1623    \return negative on error
1624
1625    \param key RSA key structure
1626    \param heap Heap hint
1627    \param devId Device ID
1628
1629    _Example_
1630    \code
1631    RsaKey key;
1632    int ret = wc_InitRsaKey_ex(&key, NULL, INVALID_DEVID);
1633    \endcode
1634
1635    \sa wc_InitRsaKey
1636*/
1637int wc_InitRsaKey_ex(RsaKey* key, void* heap, int devId);
1638
1639/*!
1640    \ingroup RSA
1641    \brief Allocates and initializes new RSA key. These New/Delete functions
1642    are exposed to support allocation of the structure using dynamic memory
1643    to provide better ABI compatibility.
1644
1645    \note This API is only available when WC_NO_CONSTRUCTORS is not defined.
1646    WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is
1647    defined.
1648
1649    \return RsaKey pointer on success
1650    \return NULL on failure
1651
1652    \param heap Heap hint
1653    \param devId Device ID
1654    \param result_code Result code pointer
1655
1656    _Example_
1657    \code
1658    int result;
1659    RsaKey* key = wc_NewRsaKey(NULL, INVALID_DEVID, &result);
1660    \endcode
1661
1662    \sa wc_DeleteRsaKey
1663*/
1664RsaKey* wc_NewRsaKey(void* heap, int devId, int *result_code);
1665
1666/*!
1667    \ingroup RSA
1668    \brief Deletes and frees RSA key. These New/Delete functions are exposed
1669    to support allocation of the structure using dynamic memory to provide
1670    better ABI compatibility.
1671
1672    \note This API is only available when WC_NO_CONSTRUCTORS is not defined.
1673    WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is
1674    defined.
1675
1676    \return 0 on success
1677    \return negative on error
1678
1679    \param key RSA key to delete
1680    \param key_p Pointer to key pointer
1681
1682    _Example_
1683    \code
1684    RsaKey* key;
1685    int ret = wc_DeleteRsaKey(key, &key);
1686    \endcode
1687
1688    \sa wc_NewRsaKey
1689*/
1690int wc_DeleteRsaKey(RsaKey* key, RsaKey** key_p);
1691
1692/*!
1693    \ingroup RSA
1694    \brief Initializes RSA key with label.
1695
1696    \note This API is only available when WOLF_PRIVATE_KEY_ID is defined,
1697    which is set for PKCS11 support.
1698
1699    \return 0 on success
1700    \return negative on error
1701
1702    \param key RSA key structure
1703    \param label Label string
1704    \param heap Heap hint
1705    \param devId Device ID
1706
1707    _Example_
1708    \code
1709    RsaKey key;
1710    int ret = wc_InitRsaKey_Label(&key, "mykey", NULL,
1711                                  INVALID_DEVID);
1712    \endcode
1713
1714    \sa wc_InitRsaKey_ex
1715*/
1716int wc_InitRsaKey_Label(RsaKey* key, const char* label, void* heap,
1717    int devId);
1718
1719/*!
1720    \ingroup RSA
1721    \brief Checks RSA key validity.
1722
1723    \return 0 on success
1724    \return negative on error
1725
1726    \param key RSA key to check
1727
1728    _Example_
1729    \code
1730    RsaKey key;
1731    int ret = wc_CheckRsaKey(&key);
1732    \endcode
1733
1734    \sa wc_MakeRsaKey
1735*/
1736int wc_CheckRsaKey(RsaKey* key);
1737
1738/*!
1739    \ingroup RSA
1740    \brief Uses key ID for hardware RSA.
1741
1742    \return 0 on success
1743    \return negative on error
1744
1745    \param key RSA key
1746    \param keyId Key identifier
1747    \param flags Flags
1748
1749    _Example_
1750    \code
1751    RsaKey key;
1752    int ret = wc_RsaUseKeyId(&key, 1, 0);
1753    \endcode
1754
1755    \sa wc_RsaGetKeyId
1756*/
1757int wc_RsaUseKeyId(RsaKey* key, word32 keyId, word32 flags);
1758
1759/*!
1760    \ingroup RSA
1761    \brief Gets key ID from hardware RSA key.
1762
1763    \return 0 on success
1764    \return negative on error
1765
1766    \param key RSA key
1767    \param keyId Key identifier pointer
1768
1769    _Example_
1770    \code
1771    RsaKey key;
1772    word32 keyId;
1773    int ret = wc_RsaGetKeyId(&key, &keyId);
1774    \endcode
1775
1776    \sa wc_RsaUseKeyId
1777*/
1778int wc_RsaGetKeyId(RsaKey* key, word32* keyId);
1779
1780/*!
1781    \ingroup RSA
1782    \brief Performs RSA operation.
1783
1784    \return 0 on success
1785    \return negative on error
1786
1787    \param in Input buffer
1788    \param inLen Input length
1789    \param out Output buffer
1790    \param outLen Output length pointer
1791    \param type Operation type
1792    \param key RSA key
1793    \param rng Random number generator
1794
1795    _Example_
1796    \code
1797    RsaKey key;
1798    WC_RNG rng;
1799    byte in[256], out[256];
1800    word32 outLen = sizeof(out);
1801    int ret = wc_RsaFunction(in, 256, out, &outLen,
1802                             RSA_PUBLIC_ENCRYPT, &key, &rng);
1803    \endcode
1804
1805    \sa wc_RsaPublicEncrypt
1806*/
1807int wc_RsaFunction(const byte* in, word32 inLen, byte* out,
1808    word32* outLen, int type, RsaKey* key, WC_RNG* rng);
1809
1810/*!
1811    \ingroup RSA
1812    \brief Signs with RSA-PSS extended options.
1813
1814    \return Size of signature on success
1815    \return negative on error
1816
1817    \param in Input buffer
1818    \param inLen Input length
1819    \param out Output buffer
1820    \param outLen Output buffer size
1821    \param hash Hash type
1822    \param mgf MGF type
1823    \param saltLen Salt length
1824    \param key RSA key
1825    \param rng Random number generator
1826
1827    _Example_
1828    \code
1829    RsaKey key;
1830    WC_RNG rng;
1831    byte in[32], sig[256];
1832    int ret = wc_RsaPSS_Sign_ex(in, 32, sig, sizeof(sig),
1833                                WC_HASH_TYPE_SHA256,
1834                                WC_MGF1SHA256, 32, &key, &rng);
1835    \endcode
1836
1837    \sa wc_RsaPSS_Sign
1838*/
1839int wc_RsaPSS_Sign_ex(const byte* in, word32 inLen, byte* out,
1840    word32 outLen, enum wc_HashType hash, int mgf, int saltLen,
1841    RsaKey* key, WC_RNG* rng);
1842
1843/*!
1844    \ingroup RSA
1845    \brief Verifies RSA signature with padding type.
1846
1847    \return Size of decrypted data on success
1848    \return negative on error
1849
1850    \param in Input signature
1851    \param inLen Signature length
1852    \param out Output buffer
1853    \param outLen Output buffer size
1854    \param key RSA key
1855    \param pad_type Padding type
1856
1857    _Example_
1858    \code
1859    RsaKey key;
1860    byte sig[256], out[256];
1861    int ret = wc_RsaSSL_Verify_ex(sig, 256, out, sizeof(out),
1862                                  &key, RSA_PKCS1_PADDING);
1863    \endcode
1864
1865    \sa wc_RsaSSL_Verify
1866*/
1867int wc_RsaSSL_Verify_ex(const byte* in, word32 inLen, byte* out,
1868    word32 outLen, RsaKey* key, int pad_type);
1869
1870/*!
1871    \ingroup RSA
1872    \brief Verifies RSA signature with hash type.
1873
1874    \return Size of decrypted data on success
1875    \return negative on error
1876
1877    \param in Input signature
1878    \param inLen Signature length
1879    \param out Output buffer
1880    \param outLen Output buffer size
1881    \param key RSA key
1882    \param pad_type Padding type
1883    \param hash Hash type
1884
1885    _Example_
1886    \code
1887    RsaKey key;
1888    byte sig[256], out[256];
1889    int ret = wc_RsaSSL_Verify_ex2(sig, 256, out, sizeof(out),
1890                                   &key, RSA_PKCS1_PADDING,
1891                                   WC_HASH_TYPE_SHA256);
1892    \endcode
1893
1894    \sa wc_RsaSSL_Verify_ex
1895*/
1896int wc_RsaSSL_Verify_ex2(const byte* in, word32 inLen, byte* out,
1897    word32 outLen, RsaKey* key, int pad_type,
1898    enum wc_HashType hash);
1899
1900/*!
1901    \ingroup RSA
1902    \brief Verifies RSA-PSS inline with extended options.
1903
1904    \return Size of verified data on success
1905    \return negative on error
1906
1907    \param in Input/output buffer
1908    \param inLen Input length
1909    \param out Output pointer
1910    \param hash Hash type
1911    \param mgf MGF type
1912    \param saltLen Salt length
1913    \param key RSA key
1914
1915    _Example_
1916    \code
1917    RsaKey key;
1918    byte sig[256];
1919    byte* out;
1920    int ret = wc_RsaPSS_VerifyInline_ex(sig, 256, &out,
1921                                        WC_HASH_TYPE_SHA256,
1922                                        WC_MGF1SHA256, 32, &key);
1923    \endcode
1924
1925    \sa wc_RsaPSS_VerifyInline
1926*/
1927int wc_RsaPSS_VerifyInline_ex(byte* in, word32 inLen, byte** out,
1928    enum wc_HashType hash, int mgf, int saltLen, RsaKey* key);
1929
1930/*!
1931    \ingroup RSA
1932    \brief Verifies RSA-PSS with extended options.
1933
1934    \return Size of verified data on success
1935    \return negative on error
1936
1937    \param in Input signature
1938    \param inLen Signature length
1939    \param out Output buffer
1940    \param outLen Output buffer size
1941    \param hash Hash type
1942    \param mgf MGF type
1943    \param saltLen Salt length
1944    \param key RSA key
1945
1946    _Example_
1947    \code
1948    RsaKey key;
1949    byte sig[256], out[256];
1950    int ret = wc_RsaPSS_Verify_ex(sig, 256, out, sizeof(out),
1951                                  WC_HASH_TYPE_SHA256,
1952                                  WC_MGF1SHA256, 32, &key);
1953    \endcode
1954
1955    \sa wc_RsaPSS_Verify
1956*/
1957int wc_RsaPSS_Verify_ex(const byte* in, word32 inLen, byte* out,
1958    word32 outLen, enum wc_HashType hash, int mgf, int saltLen,
1959    RsaKey* key);
1960
1961/*!
1962    \ingroup RSA
1963    \brief Checks RSA-PSS padding with extended options.
1964
1965    \return 0 on success
1966    \return negative on error
1967
1968    \param in Padded data
1969    \param inLen Padded data length
1970    \param sig Signature
1971    \param sigSz Signature size
1972    \param hashType Hash type
1973    \param saltLen Salt length
1974    \param bits Key size in bits
1975    \param heap Heap hint
1976
1977    _Example_
1978    \code
1979    byte padded[256], sig[256];
1980    int ret = wc_RsaPSS_CheckPadding_ex2(padded, 256, sig, 256,
1981                                         WC_HASH_TYPE_SHA256, 32,
1982                                         2048, NULL);
1983    \endcode
1984
1985    \sa wc_RsaPSS_CheckPadding_ex
1986*/
1987int wc_RsaPSS_CheckPadding_ex2(const byte* in, word32 inLen,
1988    const byte* sig, word32 sigSz, enum wc_HashType hashType,
1989    int saltLen, int bits, void* heap);
1990
1991/*!
1992    \ingroup RSA
1993    \brief Exports RSA key components.
1994
1995    \return 0 on success
1996    \return negative on error
1997
1998    \param key RSA key
1999    \param e Public exponent buffer
2000    \param eSz Public exponent size pointer
2001    \param n Modulus buffer
2002    \param nSz Modulus size pointer
2003    \param d Private exponent buffer
2004    \param dSz Private exponent size pointer
2005    \param p Prime p buffer
2006    \param pSz Prime p size pointer
2007    \param q Prime q buffer
2008    \param qSz Prime q size pointer
2009
2010    _Example_
2011    \code
2012    RsaKey key;
2013    byte e[3], n[256], d[256], p[128], q[128];
2014    word32 eSz = 3, nSz = 256, dSz = 256, pSz = 128, qSz = 128;
2015    int ret = wc_RsaExportKey(&key, e, &eSz, n, &nSz, d, &dSz,
2016                              p, &pSz, q, &qSz);
2017    \endcode
2018
2019    \sa wc_RsaFlattenPublicKey
2020*/
2021int wc_RsaExportKey(const RsaKey* key, byte* e, word32* eSz,
2022    byte* n, word32* nSz, byte* d, word32* dSz, byte* p,
2023    word32* pSz, byte* q, word32* qSz);
2024
2025/*!
2026    \ingroup RSA
2027    \brief Checks probable prime with extended options.
2028
2029    \return 0 on success
2030    \return negative on error
2031
2032    \param p Prime p buffer
2033    \param pSz Prime p size
2034    \param q Prime q buffer
2035    \param qSz Prime q size
2036    \param e Public exponent buffer
2037    \param eSz Public exponent size
2038    \param nlen Modulus length
2039    \param isPrime Prime result pointer
2040    \param rng Random number generator
2041
2042    _Example_
2043    \code
2044    byte p[128], q[128], e[3];
2045    int isPrime;
2046    WC_RNG rng;
2047    int ret = wc_CheckProbablePrime_ex(p, 128, q, 128, e, 3,
2048                                      2048, &isPrime, &rng);
2049    \endcode
2050
2051    \sa wc_CheckProbablePrime
2052*/
2053int wc_CheckProbablePrime_ex(const byte* p, word32 pSz,
2054    const byte* q, word32 qSz, const byte* e, word32 eSz,
2055    int nlen, int* isPrime, WC_RNG* rng);
2056
2057/*!
2058    \ingroup RSA
2059    \brief Checks probable prime.
2060
2061    \return 0 on success
2062    \return negative on error
2063
2064    \param p Prime p buffer
2065    \param pSz Prime p size
2066    \param q Prime q buffer
2067    \param qSz Prime q size
2068    \param e Public exponent buffer
2069    \param eSz Public exponent size
2070    \param nlen Modulus length
2071    \param isPrime Prime result pointer
2072
2073    _Example_
2074    \code
2075    byte p[128], q[128], e[3];
2076    int isPrime;
2077    int ret = wc_CheckProbablePrime(p, 128, q, 128, e, 3, 2048,
2078                                   &isPrime);
2079    \endcode
2080
2081    \sa wc_CheckProbablePrime_ex
2082*/
2083int wc_CheckProbablePrime(const byte* p, word32 pSz,
2084    const byte* q, word32 qSz, const byte* e, word32 eSz,
2085    int nlen, int* isPrime);
2086
2087/*!
2088    \ingroup RSA
2089    \brief Pads data with extended options.
2090
2091    \return 0 on success
2092    \return negative on error
2093
2094    \param input Input data
2095    \param inputLen Input length
2096    \param pkcsBlock Output padded block
2097    \param pkcsBlockLen Padded block size
2098    \param padValue Pad value
2099    \param rng Random number generator
2100    \param padType Padding type
2101    \param hType Hash type
2102    \param mgf MGF type
2103    \param optLabel Optional label
2104    \param labelLen Label length
2105    \param saltLen Salt length
2106    \param bits Key size in bits
2107    \param heap Heap hint
2108
2109    _Example_
2110    \code
2111    byte in[32], padded[256];
2112    WC_RNG rng;
2113    int ret = wc_RsaPad_ex(in, 32, padded, 256, 0x00, &rng,
2114                          RSA_BLOCK_TYPE_1,
2115                          WC_HASH_TYPE_SHA256, WC_MGF1SHA256,
2116                          NULL, 0, 32, 2048, NULL);
2117    \endcode
2118
2119    \sa wc_RsaUnPad_ex
2120*/
2121int wc_RsaPad_ex(const byte* input, word32 inputLen,
2122    byte* pkcsBlock, word32 pkcsBlockLen, byte padValue,
2123    WC_RNG* rng, int padType, enum wc_HashType hType, int mgf,
2124    byte* optLabel, word32 labelLen, int saltLen, int bits,
2125    void* heap);
2126
2127/*!
2128    \ingroup RSA
2129    \brief Unpads data with extended options.
2130
2131    \return Size of unpadded data on success
2132    \return negative on error
2133
2134    \param pkcsBlock Padded block
2135    \param pkcsBlockLen Padded block length
2136    \param out Output pointer
2137    \param padValue Pad value
2138    \param padType Padding type
2139    \param hType Hash type
2140    \param mgf MGF type
2141    \param optLabel Optional label
2142    \param labelLen Label length
2143    \param saltLen Salt length
2144    \param bits Key size in bits
2145    \param heap Heap hint
2146
2147    _Example_
2148    \code
2149    byte padded[256];
2150    byte* out;
2151    int ret = wc_RsaUnPad_ex(padded, 256, &out, 0x00,
2152                             RSA_BLOCK_TYPE_1,
2153                             WC_HASH_TYPE_SHA256, WC_MGF1SHA256,
2154                             NULL, 0, 32, 2048, NULL);
2155    \endcode
2156
2157    \sa wc_RsaPad_ex
2158*/
2159int wc_RsaUnPad_ex(byte* pkcsBlock, word32 pkcsBlockLen,
2160    byte** out, byte padValue, int padType,
2161    enum wc_HashType hType, int mgf, byte* optLabel,
2162    word32 labelLen, int saltLen, int bits, void* heap);
2163
2164/*!
2165    \ingroup RSA
2166    \brief Decodes raw RSA private key.
2167
2168    \return 0 on success
2169    \return negative on error
2170
2171    \param n Modulus buffer
2172    \param nSz Modulus size
2173    \param e Public exponent buffer
2174    \param eSz Public exponent size
2175    \param d Private exponent buffer
2176    \param dSz Private exponent size
2177    \param u Coefficient buffer
2178    \param uSz Coefficient size
2179    \param p Prime p buffer
2180    \param pSz Prime p size
2181    \param q Prime q buffer
2182    \param qSz Prime q size
2183    \param dP dP buffer
2184    \param dPSz dP size
2185    \param dQ dQ buffer
2186    \param dQSz dQ size
2187    \param key RSA key
2188
2189    _Example_
2190    \code
2191    RsaKey key;
2192    byte n[256], e[3], d[256], u[256], p[128], q[128];
2193    byte dP[128], dQ[128];
2194    int ret = wc_RsaPrivateKeyDecodeRaw(n, 256, e, 3, d, 256,
2195                                       u, 256, p, 128, q, 128,
2196                                       dP, 128, dQ, 128, &key);
2197    \endcode
2198
2199    \sa wc_RsaPrivateKeyDecode
2200*/
2201int wc_RsaPrivateKeyDecodeRaw(const byte* n, word32 nSz,
2202    const byte* e, word32 eSz, const byte* d, word32 dSz,
2203    const byte* u, word32 uSz, const byte* p, word32 pSz,
2204    const byte* q, word32 qSz, const byte* dP, word32 dPSz,
2205    const byte* dQ, word32 dQSz, RsaKey* key);