luna - wolfssl/doc/dox_comments/header

   1/*!
   2    \ingroup ECC
   3
   4    \brief This function generates a new ecc_key and stores it in key.
   5
   6    \return 0 Returned on success.
   7    \return ECC_BAD_ARG_E Returned if rng or key evaluate to NULL
   8    \return BAD_FUNC_ARG Returned if the specified key size is not in the
   9    correct range of supported keys
  10    \return MEMORY_E Returned if there is an error allocating memory while
  11    computing the ecc key
  12    \return MP_INIT_E may be returned if there is an error while computing
  13    the ecc key
  14    \return MP_READ_E may be returned if there is an error while computing
  15    the ecc key
  16    \return MP_CMP_E may be returned if there is an error while computing the
  17    ecc key
  18    \return MP_INVMOD_E may be returned if there is an error while computing
  19    the ecc key
  20    \return MP_EXPTMOD_E may be returned if there is an error while computing
  21    the ecc key
  22    \return MP_MOD_E may be returned if there is an error while computing the
  23    ecc key
  24    \return MP_MUL_E may be returned if there is an error while computing the
  25    ecc key
  26    \return MP_ADD_E may be returned if there is an error while computing the
  27    ecc key
  28    \return MP_MULMOD_E may be returned if there is an error while computing
  29    the ecc key
  30    \return MP_TO_E may be returned if there is an error while computing the
  31    ecc key
  32    \return MP_MEM may be returned if there is an error while computing the
  33    ecc key
  34
  35    \param rng pointer to an initialized RNG object with which to generate
  36    the key
  37    \param keysize desired length for the ecc_key
  38    \param key pointer to the ecc_key for which to generate a key
  39
  40    _Example_
  41    \code
  42    ecc_key key;
  43    wc_ecc_init(&key);
  44    WC_RNG rng;
  45    wc_InitRng(&rng);
  46    wc_ecc_make_key(&rng, 32, &key); // initialize 32 byte ecc key
  47    \endcode
  48
  49    \sa wc_ecc_init
  50    \sa wc_ecc_shared_secret
  51*/
  52
  53int wc_ecc_make_key(WC_RNG* rng, int keysize, ecc_key* key);
  54
  55/*!
  56    \ingroup ECC
  57
  58    \brief This function generates a new ecc_key and stores it in key.
  59
  60    \return 0 Returned on success.
  61    \return ECC_BAD_ARG_E Returned if rng or key evaluate to NULL
  62    \return BAD_FUNC_ARG Returned if the specified key size is not in the
  63    correct range of supported keys
  64    \return MEMORY_E Returned if there is an error allocating memory while
  65    computing the ecc key
  66    \return MP_INIT_E may be returned if there is an error while computing
  67    the ecc key
  68    \return MP_READ_E may be returned if there is an error while computing
  69    the ecc key
  70    \return MP_CMP_E may be returned if there is an error while computing the
  71    ecc key
  72    \return MP_INVMOD_E may be returned if there is an error while computing
  73    the ecc key
  74    \return MP_EXPTMOD_E may be returned if there is an error while computing
  75    the ecc key
  76    \return MP_MOD_E may be returned if there is an error while computing the
  77    ecc key
  78    \return MP_MUL_E may be returned if there is an error while computing the
  79    ecc key
  80    \return MP_ADD_E may be returned if there is an error while computing the
  81    ecc key
  82    \return MP_MULMOD_E may be returned if there is an error while computing
  83    the ecc key
  84    \return MP_TO_E may be returned if there is an error while computing the
  85    ecc key
  86    \return MP_MEM may be returned if there is an error while computing the
  87    ecc key
  88
  89    \param key Pointer to store the created key.
  90    \param keysize size of key to be created in bytes, set based on curveId
  91    \param rng Rng to be used in key creation
  92    \param curve_id Curve to use for key
  93
  94    _Example_
  95    \code
  96    ecc_key key;
  97    int ret;
  98    WC_RNG rng;
  99    wc_ecc_init(&key);
 100    wc_InitRng(&rng);
 101    int curveId = ECC_SECP521R1;
 102    int keySize = wc_ecc_get_curve_size_from_id(curveId);
 103    ret = wc_ecc_make_key_ex(&rng, keySize, &key, curveId);
 104    if (ret != MP_OKAY) {
 105        // error handling
 106    }
 107
 108    \endcode
 109
 110    \sa wc_ecc_make_key
 111    \sa wc_ecc_get_curve_size_from_id
 112*/
 113
 114int wc_ecc_make_key_ex(WC_RNG* rng, int keysize, ecc_key* key, int curve_id);
 115
 116/*!
 117    \ingroup ECC
 118
 119    \brief wc_ecc_make_pub computes the public component from an ecc_key with an
 120    existing private component.  If pubOut is supplied, the computed public key
 121    is stored there, else it is stored in the supplied ecc_key public component
 122    slot.
 123
 124    \return 0 Returned on success.
 125    \return ECC_BAD_ARG_E Returned if key is NULL
 126    \return BAD_FUNC_ARG Returned if the supplied key is not a valid ecc_key.
 127    \return MEMORY_E Returned if there is an error allocating memory while
 128    computing the public key
 129    \return MP_INIT_E may be returned if there is an error while computing
 130    the public key
 131    \return MP_READ_E may be returned if there is an error while computing
 132    the public key
 133    \return MP_CMP_E may be returned if there is an error while computing the
 134    public key
 135    \return MP_INVMOD_E may be returned if there is an error while computing
 136    the public key
 137    \return MP_EXPTMOD_E may be returned if there is an error while computing
 138    the public key
 139    \return MP_MOD_E may be returned if there is an error while computing the
 140    public key
 141    \return MP_MUL_E may be returned if there is an error while computing the
 142    public key
 143    \return MP_ADD_E may be returned if there is an error while computing the
 144    public key
 145    \return MP_MULMOD_E may be returned if there is an error while computing
 146    the public key
 147    \return MP_TO_E may be returned if there is an error while computing the
 148    public key
 149    \return MP_MEM may be returned if there is an error while computing the
 150    public key
 151    \return ECC_OUT_OF_RANGE_E may be returned if there is an error while computing the
 152    public key
 153    \return ECC_PRIV_KEY_E may be returned if there is an error while computing the
 154    public key
 155    \return ECC_INF_E may be returned if there is an error while computing the
 156    public key
 157
 158    \param key Pointer to an ecc_key containing a valid private component
 159    \param pubOut Optional pointer to an ecc_point struct in which to store
 160    the computed public key
 161
 162    \sa wc_ecc_make_pub_ex
 163    \sa wc_ecc_make_key
 164*/
 165
 166int wc_ecc_make_pub(ecc_key* key, ecc_point* pubOut);
 167
 168/*!
 169    \ingroup ECC
 170
 171    \brief wc_ecc_make_pub_ex computes the public component from an ecc_key with
 172    an existing private component.  If pubOut is supplied, the computed public
 173    key is stored there, else it is stored in the supplied ecc_key public
 174    component slot.  The supplied rng, if non-NULL, is used to blind the private
 175    key value used in the computation.
 176
 177    \return 0 Returned on success.
 178    \return ECC_BAD_ARG_E Returned if key is NULL
 179    \return BAD_FUNC_ARG Returned if the supplied key is not a valid ecc_key.
 180    \return MEMORY_E Returned if there is an error allocating memory while
 181    computing the public key
 182    \return MP_INIT_E may be returned if there is an error while computing
 183    the public key
 184    \return MP_READ_E may be returned if there is an error while computing
 185    the public key
 186    \return MP_CMP_E may be returned if there is an error while computing the
 187    public key
 188    \return MP_INVMOD_E may be returned if there is an error while computing
 189    the public key
 190    \return MP_EXPTMOD_E may be returned if there is an error while computing
 191    the public key
 192    \return MP_MOD_E may be returned if there is an error while computing the
 193    public key
 194    \return MP_MUL_E may be returned if there is an error while computing the
 195    public key
 196    \return MP_ADD_E may be returned if there is an error while computing the
 197    public key
 198    \return MP_MULMOD_E may be returned if there is an error while computing
 199    the public key
 200    \return MP_TO_E may be returned if there is an error while computing the
 201    public key
 202    \return MP_MEM may be returned if there is an error while computing the
 203    public key
 204    \return ECC_OUT_OF_RANGE_E may be returned if there is an error while computing the
 205    public key
 206    \return ECC_PRIV_KEY_E may be returned if there is an error while computing the
 207    public key
 208    \return ECC_INF_E may be returned if there is an error while computing the
 209    public key
 210
 211    \param key Pointer to an ecc_key containing a valid private component
 212    \param pubOut Optional pointer to an ecc_point struct in which to store
 213    the computed public key
 214    \param rng Rng to be used in the public key computation
 215
 216    \sa wc_ecc_make_pub
 217    \sa wc_ecc_make_key
 218    \sa wc_InitRng
 219*/
 220
 221int wc_ecc_make_pub_ex(ecc_key* key, ecc_point* pubOut, WC_RNG* rng);
 222
 223/*!
 224    \ingroup ECC
 225
 226    \brief Perform sanity checks on ecc key validity.
 227
 228    \return MP_OKAY Success, key is OK.
 229    \return BAD_FUNC_ARG Returns if key is NULL.
 230    \return ECC_INF_E Returns if wc_ecc_point_is_at_infinity returns 1.
 231
 232    \param key Pointer to key to check.
 233
 234    _Example_
 235    \code
 236    ecc_key key;
 237    WC_RNG rng;
 238    int check_result;
 239    wc_ecc_init(&key);
 240    wc_InitRng(&rng);
 241    wc_ecc_make_key(&rng, 32, &key);
 242    check_result = wc_ecc_check_key(&key);
 243
 244    if (check_result == MP_OKAY)
 245    {
 246        // key check succeeded
 247    }
 248    else
 249    {
 250        // key check failed
 251    }
 252    \endcode
 253
 254    \sa wc_ecc_point_is_at_infinity
 255*/
 256
 257int wc_ecc_check_key(ecc_key* key);
 258
 259/*!
 260    \ingroup ECC
 261
 262    \brief This function frees an ecc_key key after it has been used.
 263
 264
 265    \param key pointer to the ecc_key structure to free
 266
 267    _Example_
 268    \code
 269    // initialize key and perform ECC operations
 270    ...
 271    wc_ecc_key_free(&key);
 272    \endcode
 273
 274    \sa wc_ecc_key_new
 275    \sa wc_ecc_init_ex
 276*/
 277
 278void wc_ecc_key_free(ecc_key* key);
 279
 280/*!
 281    \ingroup ECC
 282
 283    \brief This function generates a new secret key using a local private key
 284    and a received public key. It stores this shared secret key in the buffer
 285    out and updates outlen to hold the number of bytes written to the output
 286    buffer.
 287
 288    \return 0 Returned upon successfully generating a shared secret key
 289    \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to
 290    NULL
 291    \return ECC_BAD_ARG_E Returned if the type of the private key given as
 292    argument, private_key, is not ECC_PRIVATEKEY, or if the public and private
 293    key types (given by ecc->dp) are not equivalent
 294    \return MEMORY_E Returned if there is an error generating a new ecc point
 295    \return BUFFER_E Returned if the generated shared secret key is too long
 296    to store in the provided buffer
 297    \return MP_INIT_E may be returned if there is an error while computing the
 298    shared key
 299    \return MP_READ_E may be returned if there is an error while computing the
 300    shared key
 301    \return MP_CMP_E may be returned if there is an error while computing the
 302    shared key
 303    \return MP_INVMOD_E may be returned if there is an error while computing
 304    the shared key
 305    \return MP_EXPTMOD_E may be returned if there is an error while computing
 306    the shared key
 307    \return MP_MOD_E may be returned if there is an error while computing the
 308    shared key
 309    \return MP_MUL_E may be returned if there is an error while computing the
 310    shared key
 311    \return MP_ADD_E may be returned if there is an error while computing the
 312    shared key
 313    \return MP_MULMOD_E may be returned if there is an error while computing
 314    the shared key
 315    \return MP_TO_E may be returned if there is an error while computing the
 316    shared key
 317    \return MP_MEM may be returned if there is an error while computing the
 318    shared key
 319
 320    \param private_key pointer to the ecc_key structure containing the local
 321    private key
 322    \param public_key pointer to the ecc_key structure containing the received
 323    public key
 324    \param out pointer to an output buffer in which to store the generated
 325    shared secret key
 326    \param outlen pointer to the word32 object containing the length of the
 327    output buffer. Will be overwritten with the length written to the output
 328    buffer upon successfully generating a shared secret key
 329
 330    _Example_
 331    \code
 332    ecc_key priv, pub;
 333    WC_RNG rng;
 334    byte secret[1024]; // can hold 1024 byte shared secret key
 335    word32 secretSz = sizeof(secret);
 336    int ret;
 337
 338    wc_InitRng(&rng); // initialize rng
 339    wc_ecc_init(&priv); // initialize key
 340    wc_ecc_make_key(&rng, 32, &priv); // make public/private key pair
 341    // receive public key, and initialise into pub
 342    ret = wc_ecc_shared_secret(&priv, &pub, secret, &secretSz);
 343    // generate secret key
 344    if ( ret != 0 ) {
 345    	// error generating shared secret key
 346    }
 347    \endcode
 348
 349    \sa wc_ecc_init
 350    \sa wc_ecc_make_key
 351*/
 352
 353int wc_ecc_shared_secret(ecc_key* private_key, ecc_key* public_key, byte* out,
 354                      word32* outlen);
 355
 356/*!
 357    \ingroup ECC
 358
 359    \brief Create an ECC shared secret between private key and public point.
 360
 361    \return MP_OKAY Indicates success.
 362    \return BAD_FUNC_ARG Error returned when any arguments are null.
 363    \return ECC_BAD_ARG_E Error returned if private_key->type is not
 364    ECC_PRIVATEKEY or private_key->idx fails to validate.
 365    \return BUFFER_E Error when outlen is too small.
 366    \return MEMORY_E Error to create a new point.
 367    \return MP_VAL possible when an initialization failure occurs.
 368    \return MP_MEM possible when an initialization failure occurs.
 369
 370    \param private_key The private ECC key.
 371    \param point The point to use (public key).
 372    \param out Output destination of the shared secret. Conforms to
 373    EC-DH from ANSI X9.63.
 374    \param outlen Input the max size and output the resulting size of
 375    the shared secret.
 376
 377    _Example_
 378    \code
 379    ecc_key key;
 380    ecc_point* point;
 381    byte shared_secret[];
 382    int secret_size;
 383    int result;
 384
 385    point = wc_ecc_new_point();
 386
 387    result = wc_ecc_shared_secret_ex(&key, point,
 388    &shared_secret, &secret_size);
 389
 390    if (result != MP_OKAY)
 391    {
 392        // Handle error
 393    }
 394    \endcode
 395
 396    \sa wc_ecc_verify_hash_ex
 397*/
 398
 399int wc_ecc_shared_secret_ex(ecc_key* private_key, ecc_point* point,
 400                             byte* out, word32 *outlen);
 401
 402/*!
 403    \ingroup ECC
 404
 405    \brief This function signs a message digest using an ecc_key object to
 406    guarantee authenticity.
 407
 408    \return 0 Returned upon successfully generating a signature for the
 409    message digest
 410    \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to
 411    NULL, or if the output buffer is too small to store the generated signature
 412    \return ECC_BAD_ARG_E Returned if the input key is not a private key, or
 413    if the ECC OID is invalid
 414    \return RNG_FAILURE_E Returned if the rng cannot successfully generate a
 415    satisfactory key
 416    \return MP_INIT_E may be returned if there is an error while computing
 417    the message signature
 418    \return MP_READ_E may be returned if there is an error while computing
 419    the message signature
 420    \return MP_CMP_E may be returned if there is an error while computing the
 421    message signature
 422    \return MP_INVMOD_E may be returned if there is an error while computing
 423    the message signature
 424    \return MP_EXPTMOD_E may be returned if there is an error while computing
 425    the message signature
 426    \return MP_MOD_E may be returned if there is an error while computing the
 427    message signature
 428    \return MP_MUL_E may be returned if there is an error while computing the
 429    message signature
 430    \return MP_ADD_E may be returned if there is an error while computing the
 431    message signature
 432    \return MP_MULMOD_E may be returned if there is an error while computing
 433    the message signature
 434    \return MP_TO_E may be returned if there is an error while computing the
 435    message signature
 436    \return MP_MEM may be returned if there is an error while computing the
 437    message signature
 438
 439    \param in pointer to the buffer containing the message hash to sign
 440    \param inlen length of the message hash to sign
 441    \param out buffer in which to store the generated signature
 442    \param outlen max length of the output buffer. Will store the bytes
 443    written to out upon successfully generating a message signature
 444    \param key pointer to a private ECC key with which to generate the
 445    signature
 446
 447    _Example_
 448    \code
 449    ecc_key key;
 450    WC_RNG rng;
 451    int ret, sigSz;
 452
 453    byte sig[512]; // will hold generated signature
 454    sigSz = sizeof(sig);
 455    byte digest[] = { // initialize with message hash };
 456    wc_InitRng(&rng); // initialize rng
 457    wc_ecc_init(&key); // initialize key
 458    wc_ecc_make_key(&rng, 32, &key); // make public/private key pair
 459    ret = wc_ecc_sign_hash(digest, sizeof(digest), sig, &sigSz, &key);
 460    if ( ret != 0 ) {
 461	    // error generating message signature
 462    }
 463    \endcode
 464
 465    \sa wc_ecc_verify_hash
 466*/
 467
 468int wc_ecc_sign_hash(const byte* in, word32 inlen, byte* out, word32 *outlen,
 469                     WC_RNG* rng, ecc_key* key);
 470
 471/*!
 472    \ingroup ECC
 473
 474    \brief Sign a message digest.
 475
 476    \return MP_OKAY Returned upon successfully generating a signature for the
 477    message digest
 478    \return ECC_BAD_ARG_E Returned if the input key is not a private key, or
 479    if the ECC IDX is invalid, or if any of the input parameters evaluate to
 480    NULL, or if the output buffer is too small to store the generated signature
 481    \return RNG_FAILURE_E Returned if the rng cannot successfully generate a
 482    satisfactory key
 483    \return MP_INIT_E may be returned if there is an error while computing the
 484    message signature
 485    \return MP_READ_E may be returned if there is an error while computing the
 486    message signature
 487    \return MP_CMP_E may be returned if there is an error while computing the
 488    message signature
 489    \return MP_INVMOD_E may be returned if there is an error while computing
 490    the message signature
 491    \return MP_EXPTMOD_E may be returned if there is an error while computing
 492    the message signature
 493    \return MP_MOD_E may be returned if there is an error while computing the
 494    message signature
 495    \return MP_MUL_E may be returned if there is an error while computing the
 496    message signature
 497    \return MP_ADD_E may be returned if there is an error while computing the
 498    message signature
 499    \return MP_MULMOD_E may be returned if there is an error while computing
 500    the message signature
 501    \return MP_TO_E may be returned if there is an error while computing the
 502    message signature
 503    \return MP_MEM may be returned if there is an error while computing the
 504    message signature
 505
 506    \param in The message digest to sign.
 507    \param inlen The length of the digest.
 508    \param rng Pointer to WC_RNG struct.
 509    \param key A private ECC key.
 510    \param r The destination for r component of the signature.
 511    \param s The destination for s component of the signature.
 512
 513    _Example_
 514    \code
 515    ecc_key key;
 516    WC_RNG rng;
 517    int ret, sigSz;
 518    mp_int r; // destination for r component of signature.
 519    mp_int s; // destination for s component of signature.
 520
 521    byte sig[512]; // will hold generated signature
 522    sigSz = sizeof(sig);
 523    byte digest[] = { initialize with message hash };
 524    wc_InitRng(&rng); // initialize rng
 525    wc_ecc_init(&key); // initialize key
 526    mp_init(&r); // initialize r component
 527    mp_init(&s); // initialize s component
 528    wc_ecc_make_key(&rng, 32, &key); // make public/private key pair
 529    ret = wc_ecc_sign_hash_ex(digest, sizeof(digest), &rng, &key, &r, &s);
 530
 531    if ( ret != MP_OKAY ) {
 532    	// error generating message signature
 533    }
 534    \endcode
 535
 536    \sa wc_ecc_verify_hash_ex
 537*/
 538
 539int wc_ecc_sign_hash_ex(const byte* in, word32 inlen, WC_RNG* rng,
 540                        ecc_key* key, mp_int *r, mp_int *s);
 541
 542/*!
 543    \ingroup ECC
 544
 545    \brief This function verifies the ECC signature of a hash to ensure
 546    authenticity. It returns the answer through res, with 1 corresponding
 547    to a valid signature, and 0 corresponding to an invalid signature.
 548
 549    \return 0 Returned upon successfully performing the signature
 550    verification. Note: This does not mean that the signature is verified.
 551    The authenticity information is stored instead in res
 552    \return BAD_FUNC_ARG Returned any of the input parameters evaluate to NULL
 553    \return MEMORY_E Returned if there is an error allocating memory
 554    \return MP_INIT_E  may be returned if there is an error while computing
 555    the message signature
 556    \return MP_READ_E  may be returned if there is an error while computing
 557    the message signature
 558    \return MP_CMP_E  may be returned if there is an error while computing
 559    the message signature
 560    \return MP_INVMOD_E  may be returned if there is an error while computing
 561    the message signature
 562    \return MP_EXPTMOD_E  may be returned if there is an error while
 563    computing the message signature
 564    \return MP_MOD_E  may be returned if there is an error while computing
 565    the message signature
 566    \return MP_MUL_E  may be returned if there is an error while computing
 567    the message signature
 568    \return MP_ADD_E  may be returned if there is an error while computing
 569    the message signature
 570    \return MP_MULMOD_E  may be returned if there is an error while computing
 571    the message signature
 572    \return MP_TO_E  may be returned if there is an error while computing the
 573    message signature
 574    \return MP_MEM may be returned if there is an error while computing the
 575    message signature
 576
 577    \param sig pointer to the buffer containing the signature to verify
 578    \param siglen length of the signature to verify
 579    \param hash pointer to the buffer containing the hash of the message
 580    verified
 581    \param hashlen length of the hash of the message verified
 582    \param res pointer to the result of the verification. 1 indicates the
 583    message was successfully verified
 584    \param key pointer to a public ECC key with which to verify the signature
 585
 586    _Example_
 587    \code
 588    ecc_key key;
 589    int ret, verified = 0;
 590
 591    byte sig[1024] { initialize with received signature };
 592    byte digest[] = { initialize with message hash };
 593    // initialize key with received public key
 594    ret = wc_ecc_verify_hash(sig, sizeof(sig), digest,sizeof(digest),
 595    &verified, &key);
 596    if ( ret != 0 ) {
 597	    // error performing verification
 598    } else if ( verified == 0 ) {
 599	    // the signature is invalid
 600    }
 601    \endcode
 602
 603    \sa wc_ecc_sign_hash
 604    \sa wc_ecc_verify_hash_ex
 605*/
 606
 607int wc_ecc_verify_hash(const byte* sig, word32 siglen, const byte* hash,
 608                    word32 hashlen, int* res, ecc_key* key);
 609
 610/*!
 611    \ingroup ECC
 612
 613    \brief Verify an ECC signature.  Result is written to res.
 614    1 is valid, 0 is invalid.
 615    Note: Do not use the return value to test for valid.  Only use res.
 616
 617    \return MP_OKAY If successful (even if the signature is not valid)
 618    \return ECC_BAD_ARG_E Returns if arguments are null or if
 619    key-idx is invalid.
 620    \return MEMORY_E Error allocating ints or points.
 621
 622    \param r The signature R component to verify
 623    \param s The signature S component to verify
 624    \param hash The hash (message digest) that was signed
 625    \param hashlen The length of the hash (octets)
 626    \param res Result of signature, 1==valid, 0==invalid
 627    \param key The corresponding public ECC key
 628
 629    _Example_
 630    \code
 631    mp_int r;
 632    mp_int s;
 633    int res;
 634    byte hash[] = { Some hash }
 635    ecc_key key;
 636
 637    if(wc_ecc_verify_hash_ex(&r, &s, hash, hashlen, &res, &key) == MP_OKAY)
 638    {
 639        // Check res
 640    }
 641    \endcode
 642
 643    \sa wc_ecc_verify_hash
 644*/
 645
 646int wc_ecc_verify_hash_ex(mp_int *r, mp_int *s, const byte* hash,
 647                          word32 hashlen, int* res, ecc_key* key);
 648
 649/*!
 650    \ingroup ECC
 651
 652    \brief This function initializes an ecc_key object for future
 653    use with message verification or key negotiation.
 654
 655    \return 0 Returned upon successfully initializing the ecc_key object
 656    \return MEMORY_E Returned if there is an error allocating memory
 657
 658    \param key pointer to the ecc_key object to initialize
 659
 660    _Example_
 661    \code
 662    ecc_key key;
 663    wc_ecc_init(&key);
 664    \endcode
 665
 666    \sa wc_ecc_make_key
 667    \sa wc_ecc_free
 668*/
 669
 670int wc_ecc_init(ecc_key* key);
 671
 672/*!
 673    \ingroup ECC
 674
 675    \brief This function initializes an ecc_key object for future
 676    use with message verification or key negotiation.
 677
 678    \return 0 Returned upon successfully initializing the ecc_key object
 679    \return MEMORY_E Returned if there is an error allocating memory
 680
 681    \param key pointer to the ecc_key object to initialize
 682    \param heap pointer to a heap identifier
 683    \param devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used
 684
 685    _Example_
 686    \code
 687    ecc_key key;
 688    wc_ecc_init_ex(&key, heap, devId);
 689    \endcode
 690
 691    \sa wc_ecc_make_key
 692    \sa wc_ecc_free
 693    \sa wc_ecc_init
 694*/
 695
 696int wc_ecc_init_ex(ecc_key* key, void* heap, int devId);
 697
 698/*!
 699    \ingroup ECC
 700
 701    \brief This function uses a user defined heap and allocates space for the
 702    key structure.
 703
 704    \return 0 Returned upon successfully initializing the ecc_key object
 705    \return MEMORY_E Returned if there is an error allocating memory
 706
 707
 708    _Example_
 709    \code
 710    wc_ecc_key_new(&heap);
 711    \endcode
 712
 713    \sa wc_ecc_make_key
 714    \sa wc_ecc_key_free
 715    \sa wc_ecc_init
 716*/
 717
 718ecc_key* wc_ecc_key_new(void* heap);
 719
 720/*!
 721    \ingroup ECC
 722
 723    \brief This function frees an ecc_key object after it has been used.
 724
 725    \return int integer returned indicating wolfSSL error or success status.
 726
 727    \param key pointer to the ecc_key object to free
 728
 729    _Example_
 730    \code
 731    // initialize key and perform secure exchanges
 732    ...
 733    wc_ecc_free(&key);
 734    \endcode
 735
 736    \sa wc_ecc_init
 737*/
 738
 739int wc_ecc_free(ecc_key* key);
 740
 741/*!
 742    \ingroup ECC
 743
 744    \brief This function frees the fixed-point cache, which can be used
 745    with ecc to speed up computation times. To use this functionality,
 746    FP_ECC (fixed-point ecc), should be defined. Threaded applications should
 747    call this function before exiting the thread.
 748
 749    \return none No returns.
 750
 751    \param none No parameters.
 752
 753    _Example_
 754    \code
 755    ecc_key key;
 756    // initialize key and perform secure exchanges
 757    ...
 758
 759    wc_ecc_fp_free();
 760    \endcode
 761
 762    \sa wc_ecc_free
 763*/
 764
 765void wc_ecc_fp_free(void);
 766
 767/*!
 768    \ingroup ECC
 769
 770    \brief Checks if an ECC idx is valid.
 771
 772    \return 1 Return if valid.
 773    \return 0 Return if not valid.
 774
 775    \param n The idx number to check.
 776
 777    _Example_
 778    \code
 779    ecc_key key;
 780    WC_RNG rng;
 781    int is_valid;
 782    wc_ecc_init(&key);
 783    wc_InitRng(&rng);
 784    wc_ecc_make_key(&rng, 32, &key);
 785    is_valid = wc_ecc_is_valid_idx(key.idx);
 786    if (is_valid == 1)
 787    {
 788        // idx is valid
 789    }
 790    else if (is_valid == 0)
 791    {
 792        // idx is not valid
 793    }
 794    \endcode
 795
 796    \sa none
 797*/
 798
 799int wc_ecc_is_valid_idx(int n);
 800
 801/*!
 802    \ingroup ECC
 803
 804    \brief Allocate a new ECC point.
 805
 806    \return p A newly allocated point.
 807    \return NULL Returns NULL on error.
 808
 809    \param none No parameters.
 810
 811    _Example_
 812    \code
 813    ecc_point* point;
 814    point = wc_ecc_new_point();
 815    if (point == NULL)
 816    {
 817        // Handle point creation error
 818    }
 819    // Do stuff with point
 820    \endcode
 821
 822    \sa wc_ecc_del_point
 823    \sa wc_ecc_cmp_point
 824    \sa wc_ecc_copy_point
 825*/
 826
 827ecc_point* wc_ecc_new_point(void);
 828
 829/*!
 830    \ingroup ECC
 831
 832    \brief Free an ECC point from memory.
 833
 834    \return none No returns.
 835
 836    \param p The point to free.
 837
 838    _Example_
 839    \code
 840    ecc_point* point;
 841    point = wc_ecc_new_point();
 842    if (point == NULL)
 843    {
 844        // Handle point creation error
 845    }
 846    // Do stuff with point
 847    wc_ecc_del_point(point);
 848    \endcode
 849
 850    \sa wc_ecc_new_point
 851    \sa wc_ecc_cmp_point
 852    \sa wc_ecc_copy_point
 853*/
 854
 855void wc_ecc_del_point(ecc_point* p);
 856
 857/*!
 858    \ingroup ECC
 859
 860    \brief Copy the value of one point to another one.
 861
 862    \return ECC_BAD_ARG_E Error thrown when p or r is null.
 863    \return MP_OKAY Point copied successfully
 864    \return ret Error from internal functions.  Can be...
 865
 866    \param p The point to copy.
 867    \param r The created point.
 868
 869    _Example_
 870    \code
 871    ecc_point* point;
 872    ecc_point* copied_point;
 873    int copy_return;
 874
 875    point = wc_ecc_new_point();
 876    copy_return = wc_ecc_copy_point(point, copied_point);
 877    if (copy_return != MP_OKAY)
 878    {
 879        // Handle error
 880    }
 881    \endcode
 882
 883    \sa wc_ecc_new_point
 884    \sa wc_ecc_cmp_point
 885    \sa wc_ecc_del_point
 886*/
 887
 888int wc_ecc_copy_point(const ecc_point* p, ecc_point *r);
 889
 890/*!
 891    \ingroup ECC
 892
 893    \brief Compare the value of a point with another one.
 894
 895    \return BAD_FUNC_ARG One or both arguments are NULL.
 896    \return MP_EQ The points are equal.
 897    \return ret Either MP_LT or MP_GT and signifies that the
 898    points are not equal.
 899
 900    \param a First point to compare.
 901    \param b Second point to compare.
 902
 903    _Example_
 904    \code
 905    ecc_point* point;
 906    ecc_point* point_to_compare;
 907    int cmp_result;
 908
 909    point = wc_ecc_new_point();
 910    point_to_compare = wc_ecc_new_point();
 911    cmp_result = wc_ecc_cmp_point(point, point_to_compare);
 912    if (cmp_result == BAD_FUNC_ARG)
 913    {
 914        // arguments are invalid
 915    }
 916    else if (cmp_result == MP_EQ)
 917    {
 918        // Points are equal
 919    }
 920    else
 921    {
 922        // Points are not equal
 923    }
 924    \endcode
 925
 926    \sa wc_ecc_new_point
 927    \sa wc_ecc_del_point
 928    \sa wc_ecc_copy_point
 929*/
 930
 931int wc_ecc_cmp_point(ecc_point* a, ecc_point *b);
 932
 933/*!
 934    \ingroup ECC
 935
 936    \brief Checks if a point is at infinity.  Returns 1 if point is
 937    at infinity, 0 if not, < 0 on error
 938
 939    \return 1 p is at infinity.
 940    \return 0 p is not at infinity.
 941    \return <0 Error.
 942
 943    \param p The point to check.
 944
 945    _Example_
 946    \code
 947    ecc_point* point;
 948    int is_infinity;
 949    point = wc_ecc_new_point();
 950
 951    is_infinity = wc_ecc_point_is_at_infinity(point);
 952    if (is_infinity < 0)
 953    {
 954        // Handle error
 955    }
 956    else if (is_infinity == 0)
 957    {
 958        // Point is not at infinity
 959    }
 960    else if (is_infinity == 1)
 961    {
 962        // Point is at infinity
 963    }
 964    \endcode
 965
 966    \sa wc_ecc_new_point
 967    \sa wc_ecc_del_point
 968    \sa wc_ecc_cmp_point
 969    \sa wc_ecc_copy_point
 970*/
 971
 972int wc_ecc_point_is_at_infinity(ecc_point *p);
 973
 974/*!
 975    \ingroup ECC
 976
 977    \brief Perform ECC Fixed Point multiplication.
 978
 979    \return MP_OKAY Returns on successful operation.
 980    \return MP_INIT_E Returned if there is an error initializing an integer
 981    for use with the multiple precision integer (mp_int) library.
 982
 983    \param k The multiplicand.
 984    \param G Base point to multiply.
 985    \param R Destination of product.
 986    \param a ECC curve parameter a.
 987    \param modulus The modulus for the curve.
 988    \param map If non-zero maps the point back to affine coordinates,
 989    otherwise it's left in jacobian-montgomery form.
 990
 991    _Example_
 992    \code
 993    ecc_point* base;
 994    ecc_point* destination;
 995    // Initialize points
 996    base = wc_ecc_new_point();
 997    destination = wc_ecc_new_point();
 998    // Setup other arguments
 999    mp_int multiplicand;
1000    mp_int modulus;
1001    mp_int a;
1002    int map;
1003    int rc;
1004    rc = wc_ecc_mulmod(&multiplicand, base, destination, &a, &modulus, map);
1005    \endcode
1006
1007    \sa none
1008*/
1009
1010int wc_ecc_mulmod(const mp_int* k, ecc_point *G, ecc_point *R,
1011                  mp_int* a, mp_int* modulus, int map);
1012
1013/*!
1014    \ingroup ECC
1015
1016    \brief This function exports the ECC key from the ecc_key structure,
1017    storing the result in out. The key will be stored in ANSI X9.63 format.
1018    It stores the bytes written to the output buffer in outLen.
1019
1020    \return 0 Returned on successfully exporting the ecc_key
1021    \return LENGTH_ONLY_E Returned if the output buffer evaluates to NULL,
1022    but the other two input parameters are valid. Indicates that the function
1023    is only returning the length required to store the key
1024    \return ECC_BAD_ARG_E Returned if any of the input parameters are NULL,
1025    or the key is unsupported (has an invalid index)
1026    \return BUFFER_E Returned if the output buffer is too small to store the
1027    ecc key. If the output buffer is too small, the size needed will be
1028    returned in outLen
1029    \return MEMORY_E Returned if there is an error allocating memory with
1030    XMALLOC
1031    \return MP_INIT_E may be returned if there is an error processing the
1032    ecc_key
1033    \return MP_READ_E may be returned if there is an error processing the
1034    ecc_key
1035    \return MP_CMP_E may be returned if there is an error processing the
1036    ecc_key
1037    \return MP_INVMOD_E may be returned if there is an error processing the
1038    ecc_key
1039    \return MP_EXPTMOD_E may be returned if there is an error processing the
1040    ecc_key
1041    \return MP_MOD_E may be returned if there is an error processing the
1042    ecc_key
1043    \return MP_MUL_E may be returned if there is an error processing the
1044    ecc_key
1045    \return MP_ADD_E may be returned if there is an error processing the
1046    ecc_key
1047    \return MP_MULMOD_E may be returned if there is an error processing the
1048    ecc_key
1049    \return MP_TO_E may be returned if there is an error processing the ecc_key
1050    \return MP_MEM may be returned if there is an error processing the ecc_key
1051
1052    \param key pointer to the ecc_key object to export
1053    \param out pointer to the buffer in which to store the ANSI X9.63
1054    formatted key
1055    \param outLen size of the output buffer. On successfully storing the
1056    key, will hold the bytes written to the output buffer
1057
1058    _Example_
1059    \code
1060    int ret;
1061    byte buff[1024];
1062    word32 buffSz = sizeof(buff);
1063
1064    ecc_key key;
1065    // initialize key, make key
1066    ret = wc_ecc_export_x963(&key, buff, &buffSz);
1067    if ( ret != 0) {
1068    	// error exporting key
1069    }
1070    \endcode
1071
1072    \sa wc_ecc_export_x963_ex
1073    \sa wc_ecc_import_x963
1074    \sa wc_ecc_make_pub
1075*/
1076
1077int wc_ecc_export_x963(ecc_key* key, byte* out, word32* outLen);
1078
1079/*!
1080    \ingroup ECC
1081
1082    \brief This function exports the public key from the ecc_key structure,
1083    storing the result in out. The key will be stored in ANSI X9.63 format.
1084    It stores the bytes written to the output buffer in outLen. This function
1085    allows the additional option of compressing the certificate through the
1086    compressed parameter. When this parameter is true, the key will be stored
1087    in ANSI X9.63 compressed format.
1088
1089    \return 0 Returned on successfully exporting the ecc_key public component
1090    \return ECC_PRIVATEKEY_ONLY Returned if the ecc_key public component is
1091    missing
1092    \return NOT_COMPILED_IN Returned if the HAVE_COMP_KEY was not enabled at
1093    compile time, but the key was requested in compressed format
1094    \return LENGTH_ONLY_E Returned if the output buffer evaluates to NULL, but
1095    the other two input parameters are valid. Indicates that the function is
1096    only returning the length required to store the public key
1097    \return ECC_BAD_ARG_E Returned if any of the input parameters are NULL, or
1098    the key is unsupported (has an invalid index)
1099    \return BUFFER_E Returned if the output buffer is too small to store the
1100    public key. If the output buffer is too small, the size needed will be
1101    returned in outLen
1102    \return MEMORY_E Returned if there is an error allocating memory with
1103    XMALLOC
1104    \return MP_INIT_E may be returned if there is an error processing the
1105    ecc_key
1106    \return MP_READ_E may be returned if there is an error processing the
1107    ecc_key
1108    \return MP_CMP_E may be returned if there is an error processing the
1109    ecc_key
1110    \return MP_INVMOD_E may be returned if there is an error processing the
1111    ecc_key
1112    \return MP_EXPTMOD_E may be returned if there is an error processing
1113    the ecc_key
1114    \return MP_MOD_E may be returned if there is an error processing the
1115    ecc_key
1116    \return MP_MUL_E may be returned if there is an error processing the
1117    ecc_key
1118    \return MP_ADD_E may be returned if there is an error processing the
1119    ecc_key
1120    \return MP_MULMOD_E may be returned if there is an error processing
1121    the ecc_key
1122    \return MP_TO_E may be returned if there is an error processing the ecc_key
1123    \return MP_MEM may be returned if there is an error processing the ecc_key
1124
1125    \param key pointer to the ecc_key object to export
1126    \param out pointer to the buffer in which to store the ANSI X9.63
1127    formatted public key
1128    \param outLen size of the output buffer. On successfully storing the
1129    public key, will hold the bytes written to the output buffer
1130    \param compressed indicator of whether to store the key in compressed
1131    format. 1==compressed, 0==uncompressed
1132
1133    _Example_
1134    \code
1135    int ret;
1136    byte buff[1024];
1137    word32 buffSz = sizeof(buff);
1138    ecc_key key;
1139    // initialize key, make key
1140    ret = wc_ecc_export_x963_ex(&key, buff, &buffSz, 1);
1141    if ( ret != 0) {
1142	    // error exporting key
1143    }
1144    \endcode
1145
1146    \sa wc_ecc_export_x963
1147    \sa wc_ecc_import_x963
1148    \sa wc_ecc_make_pub
1149*/
1150
1151int wc_ecc_export_x963_ex(ecc_key* key, byte* out, word32* outLen, int compressed);
1152
1153/*!
1154    \ingroup ECC
1155
1156    \brief This function imports a public ECC key from a buffer containing the
1157    key stored in ANSI X9.63 format. This function will handle both compressed
1158    and uncompressed keys, as long as compressed keys are enabled at compile
1159    time through the HAVE_COMP_KEY option.
1160
1161    \return 0 Returned on successfully importing the ecc_key
1162    \return NOT_COMPILED_IN Returned if the HAVE_COMP_KEY was not enabled at
1163    compile time, but the key is stored in compressed format
1164    \return ECC_BAD_ARG_E Returned if in or key evaluate to NULL, or the
1165    inLen is even (according to the x9.63 standard, the key must be odd)
1166    \return MEMORY_E Returned if there is an error allocating memory
1167    \return ASN_PARSE_E Returned if there is an error parsing the ECC key;
1168    may indicate that the ECC key is not stored in valid ANSI X9.63 format
1169    \return IS_POINT_E Returned if the public key exported is not a point
1170    on the ECC curve
1171    \return MP_INIT_E may be returned if there is an error processing the
1172    ecc_key
1173    \return MP_READ_E may be returned if there is an error processing the
1174    ecc_key
1175    \return MP_CMP_E may be returned if there is an error processing the
1176    ecc_key
1177    \return MP_INVMOD_E may be returned if there is an error processing the
1178    ecc_key
1179    \return MP_EXPTMOD_E may be returned if there is an error processing the
1180    ecc_key
1181    \return MP_MOD_E may be returned if there is an error processing the
1182    ecc_key
1183    \return MP_MUL_E may be returned if there is an error processing the
1184    ecc_key
1185    \return MP_ADD_E may be returned if there is an error processing the
1186    ecc_key
1187    \return MP_MULMOD_E may be returned if there is an error processing the
1188    ecc_key
1189    \return MP_TO_E may be returned if there is an error processing the ecc_key
1190    \return MP_MEM may be returned if there is an error processing the ecc_key
1191
1192    \param in pointer to the buffer containing the ANSI x9.63 formatted ECC key
1193    \param inLen length of the input buffer
1194    \param key pointer to the ecc_key object in which to store the imported key
1195
1196    _Example_
1197    \code
1198    int ret;
1199    byte buff[] = { initialize with ANSI X9.63 formatted key };
1200
1201    ecc_key pubKey;
1202    wc_ecc_init(&pubKey);
1203
1204    ret = wc_ecc_import_x963(buff, sizeof(buff), &pubKey);
1205    if ( ret != 0) {
1206    	// error importing key
1207    }
1208    \endcode
1209
1210    \sa wc_ecc_export_x963
1211    \sa wc_ecc_import_private_key
1212*/
1213
1214int wc_ecc_import_x963(const byte* in, word32 inLen, ecc_key* key);
1215
1216/*!
1217    \ingroup ECC
1218
1219    \brief This function imports a public/private ECC key pair from a buffer
1220    containing the raw private key, and a second buffer containing the ANSI
1221    X9.63 formatted public key. This function will handle both compressed and
1222    uncompressed keys, as long as compressed keys are enabled at compile time
1223    through the HAVE_COMP_KEY option.
1224
1225    \return 0 Returned on successfully importing the ecc_key
1226    NOT_COMPILED_IN Returned if the HAVE_COMP_KEY was not enabled at compile
1227    time, but the key is stored in compressed format
1228    \return ECC_BAD_ARG_E Returned if in or key evaluate to NULL, or the
1229    inLen is even (according to the x9.63 standard, the key must be odd)
1230    \return MEMORY_E Returned if there is an error allocating memory
1231    \return ASN_PARSE_E Returned if there is an error parsing the ECC key;
1232    may indicate that the ECC key is not stored in valid ANSI X9.63 format
1233    \return IS_POINT_E Returned if the public key exported is not a point
1234    on the ECC curve
1235    \return MP_INIT_E may be returned if there is an error processing the
1236    ecc_key
1237    \return MP_READ_E may be returned if there is an error processing the
1238    ecc_key
1239    \return MP_CMP_E may be returned if there is an error processing the
1240    ecc_key
1241    \return MP_INVMOD_E may be returned if there is an error processing
1242    the ecc_key
1243    \return MP_EXPTMOD_E may be returned if there is an error processing
1244    the ecc_key
1245    \return MP_MOD_E may be returned if there is an error processing the
1246    ecc_key
1247    \return MP_MUL_E may be returned if there is an error processing the
1248    ecc_key
1249    \return MP_ADD_E may be returned if there is an error processing the
1250    ecc_key
1251    \return MP_MULMOD_E may be returned if there is an error processing
1252    the ecc_key
1253    \return MP_TO_E may be returned if there is an error processing the ecc_key
1254    \return MP_MEM may be returned if there is an error processing the ecc_key
1255
1256    \param priv pointer to the buffer containing the raw private key
1257    \param privSz size of the private key buffer
1258    \param pub pointer to the buffer containing the ANSI x9.63 formatted ECC
1259    public key
1260    \param pubSz length of the public key input buffer
1261    \param key pointer to the ecc_key object in which to store the imported
1262    private/public key pair
1263
1264    _Example_
1265    \code
1266    int ret;
1267    byte pub[] = { initialize with ANSI X9.63 formatted key };
1268    byte priv[] = { initialize with the raw private key };
1269
1270    ecc_key key;
1271    wc_ecc_init(&key);
1272    ret = wc_ecc_import_private_key(priv, sizeof(priv), pub, sizeof(pub),
1273    &key);
1274    if ( ret != 0) {
1275    	// error importing key
1276    }
1277    \endcode
1278
1279    \sa wc_ecc_export_x963
1280    \sa wc_ecc_import_private_key
1281*/
1282
1283int wc_ecc_import_private_key(const byte* priv, word32 privSz, const byte* pub,
1284                           word32 pubSz, ecc_key* key);
1285
1286/*!
1287    \ingroup ECC
1288
1289    \brief This function converts the R and S portions of an ECC signature
1290    into a DER-encoded ECDSA signature. This function also stores the length
1291    written to the output buffer, out, in outlen.
1292
1293    \return 0 Returned on successfully converting the signature
1294    \return ECC_BAD_ARG_E Returned if any of the input parameters evaluate
1295    to NULL, or if the input buffer is not large enough to hold the
1296    DER-encoded ECDSA signature
1297    \return MP_INIT_E may be returned if there is an error processing
1298    the ecc_key
1299    \return MP_READ_E may be returned if there is an error processing
1300    the ecc_key
1301    \return MP_CMP_E may be returned if there is an error processing
1302    the ecc_key
1303    \return MP_INVMOD_E may be returned if there is an error processing
1304    the ecc_key
1305    \return MP_EXPTMOD_E may be returned if there is an error processing
1306    the ecc_key
1307    \return MP_MOD_E may be returned if there is an error processing the
1308    ecc_key
1309    \return MP_MUL_E may be returned if there is an error processing the
1310    ecc_key
1311    \return MP_ADD_E may be returned if there is an error processing the
1312    ecc_key
1313    \return MP_MULMOD_E may be returned if there is an error processing
1314    the ecc_key
1315    \return MP_TO_E may be returned if there is an error processing the ecc_key
1316    \return MP_MEM may be returned if there is an error processing the ecc_key
1317
1318    \param r pointer to the buffer containing the R portion of the signature
1319    as a string
1320    \param s pointer to the buffer containing the S portion of the signature
1321    as a string
1322    \param out pointer to the buffer in which to store the DER-encoded ECDSA
1323    signature
1324    \param outlen length of the output buffer available. Will store the bytes
1325    written to the buffer after successfully converting the signature to
1326    ECDSA format
1327
1328    _Example_
1329    \code
1330    int ret;
1331    ecc_key key;
1332    // initialize key, generate R and S
1333
1334    char r[] = { initialize with R };
1335    char s[] = { initialize with S };
1336    byte sig[wc_ecc_sig_size(key)];
1337    // signature size will be 2 * ECC key size + ~10 bytes for ASN.1 overhead
1338    word32 sigSz = sizeof(sig);
1339    ret = wc_ecc_rs_to_sig(r, s, sig, &sigSz);
1340    if ( ret != 0) {
1341    	// error converting parameters to signature
1342    }
1343    \endcode
1344
1345    \sa wc_ecc_sign_hash
1346    \sa wc_ecc_sig_size
1347*/
1348
1349int wc_ecc_rs_to_sig(const char* r, const char* s, byte* out, word32* outlen);
1350
1351/*!
1352    \ingroup ECC
1353
1354    \brief This function fills an ecc_key structure with the raw components
1355    of an ECC signature.
1356
1357    \return 0 Returned upon successfully importing into the ecc_key structure
1358    \return ECC_BAD_ARG_E Returned if any of the input values evaluate to NULL
1359    \return MEMORY_E Returned if there is an error initializing space to
1360    store the parameters of the ecc_key
1361    \return ASN_PARSE_E Returned if the input curveName is not defined
1362    in ecc_sets
1363    \return MP_INIT_E may be returned if there is an error processing the
1364    input parameters
1365    \return MP_READ_E may be returned if there is an error processing the
1366    input parameters
1367    \return MP_CMP_E may be returned if there is an error processing the
1368    input parameters
1369    \return MP_INVMOD_E may be returned if there is an error processing the
1370    input parameters
1371    \return MP_EXPTMOD_E may be returned if there is an error processing the
1372    input parameters
1373    \return MP_MOD_E may be returned if there is an error processing the
1374    input parameters
1375    \return MP_MUL_E may be returned if there is an error processing the
1376    input parameters
1377    \return MP_ADD_E may be returned if there is an error processing the
1378    input parameters
1379    \return MP_MULMOD_E may be returned if there is an error processing
1380    the input parameters
1381    \return MP_TO_E may be returned if there is an error processing the
1382    input parameters
1383    \return MP_MEM may be returned if there is an error processing the
1384    input parameters
1385
1386    \param key pointer to an ecc_key structure to fill
1387    \param qx pointer to a buffer containing the x component of the base
1388    point as an ASCII hex string
1389    \param qy pointer to a buffer containing the y component of the base
1390    point as an ASCII hex string
1391    \param d pointer to a buffer containing the private key as an ASCII
1392    hex string
1393    \param curveName pointer to a string containing the ECC curve name,
1394    as found in ecc_sets
1395
1396    _Example_
1397    \code
1398    int ret;
1399    ecc_key key;
1400    wc_ecc_init(&key);
1401
1402    char qx[] = { initialize with x component of base point };
1403    char qy[] = { initialize with y component of base point };
1404    char d[]  = { initialize with private key };
1405    ret = wc_ecc_import_raw(&key,qx, qy, d, "ECC-256");
1406    if ( ret != 0) {
1407    	// error initializing key with given inputs
1408    }
1409    \endcode
1410
1411    \sa wc_ecc_import_private_key
1412*/
1413
1414int wc_ecc_import_raw(ecc_key* key, const char* qx, const char* qy,
1415                   const char* d, const char* curveName);
1416
1417/*!
1418    \ingroup ECC
1419
1420    \brief This function exports only the private key from an ecc_key
1421    structure. It stores the private key in the buffer out, and sets
1422    the bytes written to this buffer in outLen.
1423
1424    \return 0 Returned upon successfully exporting the private key
1425    \return ECC_BAD_ARG_E Returned if any of the input values evaluate to NULL
1426    \return MEMORY_E Returned if there is an error initializing space
1427    to store the parameters of the ecc_key
1428    \return ASN_PARSE_E Returned if the input curveName is not defined
1429    in ecc_sets
1430    \return MP_INIT_E may be returned if there is an error processing
1431    the input parameters
1432    \return MP_READ_E may be returned if there is an error processing the
1433    input parameters
1434    \return MP_CMP_E may be returned if there is an error processing the
1435    input parameters
1436    \return MP_INVMOD_E may be returned if there is an error processing
1437    the input parameters
1438    \return MP_EXPTMOD_E may be returned if there is an error processing
1439    the input parameters
1440    \return MP_MOD_E may be returned if there is an error processing the
1441    input parameters
1442    \return MP_MUL_E may be returned if there is an error processing the
1443    input parameters
1444    \return MP_ADD_E may be returned if there is an error processing the
1445    input parameters
1446    \return MP_MULMOD_E may be returned if there is an error processing
1447    the input parameters
1448    \return MP_TO_E may be returned if there is an error processing the
1449    input parameters
1450    \return MP_MEM may be returned if there is an error processing the
1451    input parameters
1452
1453    \param key pointer to an ecc_key structure from which to export the
1454    private key
1455    \param out pointer to the buffer in which to store the private key
1456    \param outLen pointer to a word32 object with the size available in
1457    out. Set with the number of bytes written to out after successfully
1458    exporting the private key
1459
1460    _Example_
1461    \code
1462    int ret;
1463    ecc_key key;
1464    // initialize key, make key
1465
1466    char priv[ECC_KEY_SIZE];
1467    word32 privSz = sizeof(priv);
1468    ret = wc_ecc_export_private_only(&key, priv, &privSz);
1469    if ( ret != 0) {
1470    	// error exporting private key
1471    }
1472    \endcode
1473
1474    \sa wc_ecc_import_private_key
1475*/
1476
1477int wc_ecc_export_private_only(ecc_key* key, byte* out, word32* outLen);
1478
1479/*!
1480    \ingroup ECC
1481
1482    \brief Export point to der.
1483
1484    \return 0 Returned on success.
1485    \return ECC_BAD_ARG_E Returns if curve_idx is less than 0 or
1486    invalid.  Also returns when
1487    \return LENGTH_ONLY_E outLen is set but nothing else.
1488    \return BUFFER_E Returns if outLen is less than 1 + 2 * the curve size.
1489    \return MEMORY_E Returns if there is a problem allocating memory.
1490
1491    \param curve_idx Index of the curve used from ecc_sets.
1492    \param point Point to export to der.
1493    \param out Destination for the output.
1494    \param outLen Maxsize allowed for output, destination for
1495    final size of output
1496
1497    _Example_
1498    \code
1499    int curve_idx;
1500    ecc_point* point;
1501    byte out[];
1502    word32 outLen;
1503    wc_ecc_export_point_der(curve_idx, point, out, &outLen);
1504    \endcode
1505
1506    \sa wc_ecc_import_point_der
1507*/
1508
1509int wc_ecc_export_point_der(const int curve_idx, ecc_point* point,
1510                            byte* out, word32* outLen);
1511
1512/*!
1513    \ingroup ECC
1514
1515    \brief Import point from der format.
1516
1517    \return ECC_BAD_ARG_E Returns if any arguments are null or if
1518    inLen is even.
1519    \return MEMORY_E Returns if there is an error initializing
1520    \return NOT_COMPILED_IN Returned if HAVE_COMP_KEY is not true
1521    and in is a compressed cert
1522    \return MP_OKAY Successful operation.
1523
1524    \param in der buffer to import point from.
1525    \param inLen Length of der buffer.
1526    \param curve_idx Index of curve.
1527    \param point Destination for point.
1528
1529    _Example_
1530    \code
1531    byte in[];
1532    word32 inLen;
1533    int curve_idx;
1534    ecc_point* point;
1535    wc_ecc_import_point_der(in, inLen, curve_idx, point);
1536    \endcode
1537
1538    \sa wc_ecc_export_point_der
1539*/
1540
1541int wc_ecc_import_point_der(const byte* in, word32 inLen, const int curve_idx,
1542                            ecc_point* point);
1543
1544/*!
1545    \ingroup ECC
1546
1547    \brief This function returns the key size of an ecc_key
1548    structure in octets.
1549
1550    \return Given a valid key, returns the key size in octets
1551    \return 0 Returned if the given key is NULL
1552
1553    \param key pointer to an ecc_key structure for which to get the key size
1554
1555    _Example_
1556    \code
1557    int keySz;
1558    ecc_key key;
1559    // initialize key, make key
1560    keySz = wc_ecc_size(&key);
1561    if ( keySz == 0) {
1562    	// error determining key size
1563    }
1564    \endcode
1565
1566    \sa wc_ecc_make_key
1567*/
1568
1569int wc_ecc_size(ecc_key* key);
1570
1571/*!
1572    \ingroup ECC
1573
1574    \brief This function returns the worst case size for an ECC signature,
1575    given by: (keySz * 2) + SIG_HEADER_SZ + ECC_MAX_PAD_SZ.
1576    The actual signature size can be computed with wc_ecc_sign_hash.
1577
1578    \return returns the maximum signature
1579    size, in octets
1580
1581    \param key size
1582
1583    _Example_
1584    \code
1585    int sigSz = wc_ecc_sig_size_calc(32);
1586    if ( sigSz == 0) {
1587    	// error determining sig size
1588    }
1589    \endcode
1590
1591    \sa wc_ecc_sign_hash
1592    \sa wc_ecc_sig_size
1593*/
1594
1595int wc_ecc_sig_size_calc(int sz);
1596
1597
1598/*!
1599    \ingroup ECC
1600
1601    \brief This function returns the worst case size for an ECC signature,
1602    given by: (keySz * 2) + SIG_HEADER_SZ + ECC_MAX_PAD_SZ.
1603    The actual signature size can be computed with wc_ecc_sign_hash.
1604
1605    \return Success Given a valid key, returns the maximum signature
1606    size, in octets
1607    \return 0 Returned if the given key is NULL
1608
1609    \param key pointer to an ecc_key structure for which to get the
1610    signature size
1611
1612    _Example_
1613    \code
1614    int sigSz;
1615    ecc_key key;
1616    // initialize key, make key
1617
1618    sigSz = wc_ecc_sig_size(&key);
1619    if ( sigSz == 0) {
1620        // error determining sig size
1621    }
1622    \endcode
1623
1624    \sa wc_ecc_sign_hash
1625    \sa wc_ecc_sig_size_calc
1626*/
1627
1628int wc_ecc_sig_size(const ecc_key* key);
1629
1630
1631/*!
1632    \ingroup ECC
1633
1634    \brief This function allocates and initializes space for a new ECC
1635    context object to allow secure message exchange with ECC.
1636
1637    \return Success On successfully generating a new ecEncCtx object,
1638    returns a pointer to that object
1639    \return NULL Returned if the function fails to generate a new
1640    ecEncCtx object
1641
1642    \param flags indicate whether this is a server or client context
1643    Options are: REQ_RESP_CLIENT, and REQ_RESP_SERVER
1644    \param rng pointer to a RNG object with which to generate a salt
1645
1646    _Example_
1647    \code
1648    ecEncCtx* ctx;
1649    WC_RNG rng;
1650    wc_InitRng(&rng);
1651    ctx = wc_ecc_ctx_new(REQ_RESP_CLIENT, &rng);
1652    if(ctx == NULL) {
1653        // error generating new ecEncCtx object
1654    }
1655    \endcode
1656
1657    \sa wc_ecc_encrypt
1658    \sa wc_ecc_encrypt_ex
1659    \sa wc_ecc_decrypt
1660*/
1661
1662ecEncCtx* wc_ecc_ctx_new(int flags, WC_RNG* rng);
1663
1664/*!
1665    \ingroup ECC
1666
1667    \brief This function frees the ecEncCtx object used for encrypting
1668    and decrypting messages.
1669
1670    \return none Returns.
1671
1672    \param ctx pointer to the ecEncCtx object to free
1673
1674    _Example_
1675    \code
1676    ecEncCtx* ctx;
1677    WC_RNG rng;
1678    wc_InitRng(&rng);
1679    ctx = wc_ecc_ctx_new(REQ_RESP_CLIENT, &rng);
1680    // do secure communication
1681    ...
1682    wc_ecc_ctx_free(&ctx);
1683    \endcode
1684
1685    \sa wc_ecc_ctx_new
1686*/
1687
1688void wc_ecc_ctx_free(ecEncCtx* ctx);
1689
1690/*!
1691    \ingroup ECC
1692
1693    \brief This function resets an ecEncCtx structure to avoid having
1694    to free and allocate a new context object.
1695
1696    \return 0 Returned if the ecEncCtx structure is successfully reset
1697    \return BAD_FUNC_ARG Returned if either rng or ctx is NULL
1698    \return RNG_FAILURE_E Returned if there is an error generating a
1699    new salt for the ECC object
1700
1701    \param ctx pointer to the ecEncCtx object to reset
1702    \param rng pointer to an RNG object with which to generate a new salt
1703
1704    _Example_
1705    \code
1706    ecEncCtx* ctx;
1707    WC_RNG rng;
1708    wc_InitRng(&rng);
1709    ctx = wc_ecc_ctx_new(REQ_RESP_CLIENT, &rng);
1710    // do secure communication
1711    ...
1712    wc_ecc_ctx_reset(&ctx, &rng);
1713    // do more secure communication
1714    \endcode
1715
1716    \sa wc_ecc_ctx_new
1717*/
1718
1719int wc_ecc_ctx_reset(ecEncCtx* ctx, WC_RNG* rng);  /* reset for use again w/o alloc/free */
1720
1721/*!
1722    \ingroup ECC
1723
1724    \brief This function can optionally be called after
1725    wc_ecc_ctx_new. It sets the encryption, KDF, and MAC algorithms
1726    into an ecEncCtx object.
1727
1728    \return 0 Returned upon successfully setting the information
1729    for the ecEncCtx object.
1730    \return BAD_FUNC_ARG Returned if the given ecEncCtx object is
1731    NULL.
1732
1733    \param ctx pointer to the ecEncCtx for which to set the info
1734    \param encAlgo encryption algorithm to use.
1735    \param kdfAlgo KDF algorithm to use.
1736    \param macAlgo MAC algorithm to use.
1737
1738    _Example_
1739    \code
1740    ecEncCtx* ctx;
1741    // initialize ctx
1742    if(wc_ecc_ctx_set_algo(&ctx, ecAES_128_CTR, ecHKDF_SHA256, ecHMAC_SHA256))) {
1743	    // error setting info
1744    }
1745    \endcode
1746
1747    \sa wc_ecc_ctx_new
1748*/
1749
1750int wc_ecc_ctx_set_algo(ecEncCtx* ctx, byte encAlgo, byte kdfAlgo,
1751    byte macAlgo);
1752
1753/*!
1754    \ingroup ECC
1755
1756    \brief This function returns the salt of an ecEncCtx object. This
1757    function should only be called when the ecEncCtx's state is
1758    ecSRV_INIT or ecCLI_INIT.
1759
1760    \return Success On success, returns the ecEncCtx salt
1761    \return NULL Returned if the ecEncCtx object is NULL, or the ecEncCtx's
1762    state is not ecSRV_INIT or ecCLI_INIT. In the latter two cases, this
1763    function also sets the ecEncCtx's state to ecSRV_BAD_STATE or
1764    ecCLI_BAD_STATE, respectively
1765
1766    \param ctx pointer to the ecEncCtx object from which to get the salt
1767
1768    _Example_
1769    \code
1770    ecEncCtx* ctx;
1771    WC_RNG rng;
1772    const byte* salt;
1773    wc_InitRng(&rng);
1774    ctx = wc_ecc_ctx_new(REQ_RESP_CLIENT, &rng);
1775    salt = wc_ecc_ctx_get_own_salt(&ctx);
1776    if(salt == NULL) {
1777    	// error getting salt
1778    }
1779    \endcode
1780
1781    \sa wc_ecc_ctx_new
1782    \sa wc_ecc_ctx_set_peer_salt
1783    \sa wc_ecc_ctx_set_kdf_salt
1784*/
1785
1786const byte* wc_ecc_ctx_get_own_salt(ecEncCtx* ctx);
1787
1788/*!
1789    \ingroup ECC
1790
1791    \brief This function sets the peer salt of an ecEncCtx object.
1792
1793    \return 0 Returned upon successfully setting the peer salt for the
1794    ecEncCtx object.
1795    \return BAD_FUNC_ARG Returned if the given ecEncCtx object is NULL
1796    or has an invalid protocol, or if the given salt is NULL
1797    \return BAD_ENC_STATE_E Returned if the ecEncCtx's state is
1798    ecSRV_SALT_GET or ecCLI_SALT_GET. In the latter two cases, this
1799    function also sets the ecEncCtx's state to ecSRV_BAD_STATE or
1800    ecCLI_BAD_STATE, respectively
1801
1802    \param ctx pointer to the ecEncCtx for which to set the salt
1803    \param salt pointer to the peer's salt
1804
1805    _Example_
1806    \code
1807    ecEncCtx* cliCtx, srvCtx;
1808    WC_RNG rng;
1809    const byte* cliSalt, srvSalt;
1810    int ret;
1811
1812    wc_InitRng(&rng);
1813    cliCtx = wc_ecc_ctx_new(REQ_RESP_CLIENT, &rng);
1814    srvCtx = wc_ecc_ctx_new(REQ_RESP_SERVER, &rng);
1815
1816    cliSalt = wc_ecc_ctx_get_own_salt(&cliCtx);
1817    srvSalt = wc_ecc_ctx_get_own_salt(&srvCtx);
1818    ret = wc_ecc_ctx_set_peer_salt(&cliCtx, srvSalt);
1819    \endcode
1820
1821    \sa wc_ecc_ctx_get_own_salt
1822    \sa wc_ecc_ctx_set_kdf_salt
1823*/
1824
1825int wc_ecc_ctx_set_peer_salt(ecEncCtx* ctx, const byte* salt);
1826
1827/*!
1828    \ingroup ECC
1829
1830    \brief This function sets the salt pointer and length to use with KDF
1831    into the ecEncCtx object.
1832
1833    \return 0 Returned upon successfully setting the salt for the
1834    ecEncCtx object.
1835    \return BAD_FUNC_ARG Returned if the given ecEncCtx object is NULL
1836    or if the given salt is NULL and length is not NULL.
1837
1838    \param ctx pointer to the ecEncCtx for which to set the salt
1839    \param salt pointer to salt buffer
1840    \param sz length salt in bytes
1841
1842    _Example_
1843    \code
1844    ecEncCtx* srvCtx;
1845    WC_RNG rng;
1846    byte cliSalt[] = { fixed salt data };
1847    word32 cliSaltLen = (word32)sizeof(cliSalt);
1848    int ret;
1849
1850    wc_InitRng(&rng);
1851    cliCtx = wc_ecc_ctx_new(REQ_RESP_SERVER, &rng);
1852
1853    ret = wc_ecc_ctx_set_kdf_salt(&cliCtx, cliSalt, cliSaltLen);
1854    \endcode
1855
1856    \sa wc_ecc_ctx_get_own_salt
1857    \sa wc_ecc_ctx_get_peer_salt
1858*/
1859
1860int wc_ecc_ctx_set_kdf_salt(ecEncCtx* ctx, const byte* salt, word32 sz);
1861
1862/*!
1863    \ingroup ECC
1864
1865    \brief This function can optionally be called before or after
1866    wc_ecc_ctx_set_peer_salt. It sets optional information for
1867    an ecEncCtx object.
1868
1869    \return 0 Returned upon successfully setting the information
1870    for the ecEncCtx object.
1871    \return BAD_FUNC_ARG Returned if the given ecEncCtx object is
1872    NULL, the input info is NULL or it's size is invalid
1873
1874    \param ctx pointer to the ecEncCtx for which to set the info
1875    \param info pointer to a buffer containing the info to set
1876    \param sz size of the info buffer
1877
1878    _Example_
1879    \code
1880    ecEncCtx* ctx;
1881    byte info[] = { initialize with information };
1882    // initialize ctx, get salt,
1883    if(wc_ecc_ctx_set_info(&ctx, info, sizeof(info))) {
1884	    // error setting info
1885    }
1886    \endcode
1887
1888    \sa wc_ecc_ctx_new
1889*/
1890
1891int wc_ecc_ctx_set_info(ecEncCtx* ctx, const byte* info, int sz);
1892
1893/*!
1894    \ingroup ECC
1895
1896    \brief This function encrypts the given input message from msg
1897    to out. This function takes an optional ctx object as parameter.
1898    When supplied, encryption proceeds based on the ecEncCtx's
1899    encAlgo, kdfAlgo, and macAlgo. If ctx is not supplied, processing
1900    completes with the default algorithms, ecAES_128_CBC,
1901    ecHKDF_SHA256 and ecHMAC_SHA256. This function requires that
1902    the messages are padded according to the encryption type specified by ctx.
1903
1904    \return 0 Returned upon successfully encrypting the input message
1905    \return BAD_FUNC_ARG Returned if privKey, pubKey, msg, msgSz, out,
1906    or outSz are NULL, or the ctx object specifies an unsupported
1907    encryption type
1908    \return BAD_ENC_STATE_E Returned if the ctx object given is in a
1909    state that is not appropriate for encryption
1910    \return BUFFER_E Returned if the supplied output buffer is too
1911    small to store the encrypted ciphertext
1912    \return MEMORY_E Returned if there is an error allocating memory
1913    for the shared secret key
1914
1915    \param privKey pointer to the ecc_key object containing the
1916    private key to use for encryption
1917    \param pubKey pointer to the ecc_key object containing the public
1918    key of the peer with whom one wishes to communicate
1919    \param msg pointer to the buffer holding the message to encrypt
1920    \param msgSz size of the buffer to encrypt
1921    \param out pointer to the buffer in which to store the encrypted
1922    ciphertext
1923    \param outSz pointer to a word32 object containing the available
1924    size in the out buffer. Upon successfully encrypting the message,
1925    holds the number of bytes written to the output buffer
1926    \param ctx Optional: pointer to an ecEncCtx object specifying different
1927    encryption algorithms to use
1928
1929    _Example_
1930    \code
1931    byte msg[] = { initialize with msg to encrypt. Ensure padded to block size };
1932    byte out[sizeof(msg)];
1933    word32 outSz = sizeof(out);
1934    int ret;
1935    ecc_key cli, serv;
1936    // initialize cli with private key
1937    // initialize serv with received public key
1938
1939    ecEncCtx* cliCtx, servCtx;
1940    // initialize cliCtx and servCtx
1941    // exchange salts
1942    ret = wc_ecc_encrypt(&cli, &serv, msg, sizeof(msg), out, &outSz, cliCtx);
1943    if(ret != 0) {
1944    	// error encrypting message
1945    }
1946    \endcode
1947
1948    \sa wc_ecc_encrypt_ex
1949    \sa wc_ecc_decrypt
1950*/
1951
1952int wc_ecc_encrypt(ecc_key* privKey, ecc_key* pubKey, const byte* msg,
1953                word32 msgSz, byte* out, word32* outSz, ecEncCtx* ctx);
1954
1955/*!
1956    \ingroup ECC
1957
1958    \brief This function encrypts the given input message from msg
1959    to out. This function takes an optional ctx object as parameter.
1960    When supplied, encryption proceeds based on the ecEncCtx's
1961    encAlgo, kdfAlgo, and macAlgo. If ctx is not supplied, processing
1962    completes with the default algorithms, ecAES_128_CBC,
1963    ecHKDF_SHA256 and ecHMAC_SHA256. This function requires that
1964    the messages are padded according to the encryption type specified by ctx.
1965
1966    \return 0 Returned upon successfully encrypting the input message
1967    \return BAD_FUNC_ARG Returned if privKey, pubKey, msg, msgSz, out,
1968    or outSz are NULL, or the ctx object specifies an unsupported
1969    encryption type
1970    \return BAD_ENC_STATE_E Returned if the ctx object given is in a
1971    state that is not appropriate for encryption
1972    \return BUFFER_E Returned if the supplied output buffer is too
1973    small to store the encrypted ciphertext
1974    \return MEMORY_E Returned if there is an error allocating memory
1975    for the shared secret key
1976
1977    \param privKey pointer to the ecc_key object containing the
1978    private key to use for encryption
1979    \param pubKey pointer to the ecc_key object containing the public
1980    key of the peer with whom one wishes to communicate
1981    \param msg pointer to the buffer holding the message to encrypt
1982    \param msgSz size of the buffer to encrypt
1983    \param out pointer to the buffer in which to store the encrypted
1984    ciphertext
1985    \param outSz pointer to a word32 object containing the available
1986    size in the out buffer. Upon successfully encrypting the message,
1987    holds the number of bytes written to the output buffer
1988    \param ctx Optional: pointer to an ecEncCtx object specifying different
1989    encryption algorithms to use
1990    \param compressed Public key field is to be output in compressed format.
1991
1992    _Example_
1993    \code
1994    byte msg[] = { initialize with msg to encrypt. Ensure padded to block size };
1995    byte out[sizeof(msg)];
1996    word32 outSz = sizeof(out);
1997    int ret;
1998    ecc_key cli, serv;
1999    // initialize cli with private key
2000    // initialize serv with received public key
2001
2002    ecEncCtx* cliCtx, servCtx;
2003    // initialize cliCtx and servCtx
2004    // exchange salts
2005    ret = wc_ecc_encrypt_ex(&cli, &serv, msg, sizeof(msg), out, &outSz, cliCtx,
2006        1);
2007    if(ret != 0) {
2008    	// error encrypting message
2009    }
2010    \endcode
2011
2012    \sa wc_ecc_encrypt
2013    \sa wc_ecc_decrypt
2014*/
2015
2016int wc_ecc_encrypt_ex(ecc_key* privKey, ecc_key* pubKey, const byte* msg,
2017    word32 msgSz, byte* out, word32* outSz, ecEncCtx* ctx, int compressed);
2018
2019/*!
2020    \ingroup ECC
2021
2022    \brief This function decrypts the ciphertext from msg to out. This
2023    function takes an optional ctx object as parameter. When supplied,
2024    encryption proceeds based on the ecEncCtx's encAlgo, kdfAlgo, and
2025    macAlgo. If ctx is not supplied, processing completes with the
2026    default algorithms, ecAES_128_CBC, ecHKDF_SHA256 and ecHMAC_SHA256.
2027    This function requires that the messages are padded according to
2028    the encryption type specified by ctx.
2029
2030    \return 0 Returned upon successfully decrypting the input message
2031    \return BAD_FUNC_ARG Returned if privKey, pubKey, msg, msgSz, out,
2032    or outSz are NULL, or the ctx object specifies an unsupported
2033    encryption type
2034    \return BAD_ENC_STATE_E Returned if the ctx object given is in
2035    a state that is not appropriate for decryption
2036    \return BUFFER_E Returned if the supplied output buffer is too
2037    small to store the decrypted plaintext
2038    \return MEMORY_E Returned if there is an error allocating memory
2039    for the shared secret key
2040
2041    \param privKey pointer to the ecc_key object containing the private
2042    key to use for decryption
2043    \param pubKey pointer to the ecc_key object containing the public
2044    key of the peer with whom one wishes to communicate
2045    \param msg pointer to the buffer holding the ciphertext to decrypt
2046    \param msgSz size of the buffer to decrypt
2047    \param out pointer to the buffer in which to store the decrypted plaintext
2048    \param outSz pointer to a word32 object containing the available
2049    size in the out buffer. Upon successfully decrypting the
2050    ciphertext, holds the number of bytes written to the output buffer
2051    \param ctx Optional: pointer to an ecEncCtx object specifying
2052    different decryption algorithms to use
2053
2054    _Example_
2055    \code
2056    byte cipher[] = { initialize with
2057    ciphertext to decrypt. Ensure padded to block size };
2058    byte plain[sizeof(cipher)];
2059    word32 plainSz = sizeof(plain);
2060    int ret;
2061    ecc_key cli, serv;
2062    // initialize cli with private key
2063    // initialize serv with received public key
2064    ecEncCtx* cliCtx, servCtx;
2065    // initialize cliCtx and servCtx
2066    // exchange salts
2067    ret = wc_ecc_decrypt(&cli, &serv, cipher, sizeof(cipher),
2068    plain, &plainSz, cliCtx);
2069
2070    if(ret != 0) {
2071    	// error decrypting message
2072    }
2073    \endcode
2074
2075    \sa wc_ecc_encrypt
2076    \sa wc_ecc_encrypt_ex
2077*/
2078
2079int wc_ecc_decrypt(ecc_key* privKey, ecc_key* pubKey, const byte* msg,
2080                word32 msgSz, byte* out, word32* outSz, ecEncCtx* ctx);
2081
2082
2083/*!
2084    \ingroup ECC
2085
2086    \brief Enable ECC support for non-blocking operations. Supported for
2087        Single Precision (SP) math with the following build options:
2088            WOLFSSL_SP_NONBLOCK
2089            WOLFSSL_SP_SMALL
2090            WOLFSSL_SP_NO_MALLOC
2091            WC_ECC_NONBLOCK
2092
2093    \return 0 Returned upon successfully setting the callback context the input message
2094
2095    \param key pointer to the ecc_key object
2096    \param ctx pointer to ecc nb_ctx_t structure with stack data cache for SP
2097
2098    _Example_
2099    \code
2100    int ret;
2101    ecc_key ecc;
2102    ecc_nb_ctx_t nb_ctx;
2103
2104    ret = wc_ecc_init(&ecc);
2105    if (ret == 0) {
2106        ret = wc_ecc_set_nonblock(&ecc, &nb_ctx);
2107        if (ret == 0) {
2108            do {
2109                ret = wc_ecc_verify_hash_ex(
2110                    &r, &s,       // r/s as mp_int
2111                    hash, hashSz, // computed hash digest
2112                    &verify_res,  // verification result 1=success
2113                    &key
2114                );
2115
2116                // TODO: Real-time work can be called here
2117            } while (ret == FP_WOULDBLOCK);
2118        }
2119        wc_ecc_free(&key);
2120    }
2121    \endcode
2122*/
2123int wc_ecc_set_nonblock(ecc_key *key, ecc_nb_ctx_t* ctx);
2124
2125/*!
2126    \ingroup ECC
2127
2128    \brief Compare a curve which has larger key than specified size or the curve matched curve ID,
2129         set a curve with smaller key size to the key.
2130
2131    \return 0 Returned upon successfully setting the key
2132
2133    \param keysize Key size in bytes
2134    \param curve_id Curve ID
2135
2136                                                                                                        _Example_
2137    \code int ret;
2138    ecc_key ecc;
2139
2140    ret = wc_ecc_init(&ecc);
2141    if (ret != 0)
2142        return ret;
2143        ret = wc_ecc_set_curve(&ecc, 32, ECC_SECP256R1));
2144        if (ret != 0)
2145            return ret;
2146
2147    \endcode
2148*/
2149int wc_ecc_set_curve(ecc_key *key, int keysize, int curve_id);
2150
2151/*!
2152    \ingroup ECC
2153    \brief Gets private key mp_int from ECC key.
2154
2155    \return mp_int pointer on success
2156    \return NULL on failure
2157
2158    \param key ECC key structure
2159
2160    _Example_
2161    \code
2162    ecc_key key;
2163    mp_int* priv = wc_ecc_key_get_priv(&key);
2164    \endcode
2165
2166    \sa wc_ecc_init
2167*/
2168mp_int* wc_ecc_key_get_priv(ecc_key* key);
2169
2170/*!
2171    \ingroup ECC
2172    \brief Allocates and initializes new ECC key.
2173
2174    \return ecc_key pointer on success
2175    \return NULL on failure
2176
2177    \param heap Heap hint for memory allocation
2178
2179    _Example_
2180    \code
2181    ecc_key* key = wc_ecc_key_new(NULL);
2182    if (key != NULL) {
2183        // use key
2184        wc_ecc_key_free(key);
2185    }
2186    \endcode
2187
2188    \sa wc_ecc_key_free
2189*/
2190ecc_key* wc_ecc_key_new(void* heap);
2191
2192/*!
2193    \ingroup ECC
2194    \brief Returns number of supported ECC curve sets.
2195
2196    \return Number of curve sets
2197
2198    _Example_
2199    \code
2200    size_t count = wc_ecc_get_sets_count();
2201    \endcode
2202
2203    \sa wc_ecc_get_curve_params
2204*/
2205size_t wc_ecc_get_sets_count(void);
2206
2207/*!
2208    \ingroup ECC
2209    \brief Gets curve name from curve ID.
2210
2211    \return Curve name string on success
2212    \return NULL on failure
2213
2214    \param curve_id Curve identifier
2215
2216    _Example_
2217    \code
2218    const char* name = wc_ecc_get_name(ECC_SECP256R1);
2219    \endcode
2220
2221    \sa wc_ecc_get_curve_id
2222*/
2223const char* wc_ecc_get_name(int curve_id);
2224
2225/*!
2226    \ingroup ECC
2227    \brief Makes ECC key with extended options.
2228
2229    \return 0 on success
2230    \return negative on error
2231
2232    \param rng Random number generator
2233    \param keysize Key size in bytes
2234    \param key ECC key structure
2235    \param curve_id Curve identifier
2236    \param flags Additional flags
2237
2238    _Example_
2239    \code
2240    WC_RNG rng;
2241    ecc_key key;
2242    int ret = wc_ecc_make_key_ex2(&rng, 32, &key,
2243                                  ECC_SECP256R1, 0);
2244    \endcode
2245
2246    \sa wc_ecc_make_key_ex
2247*/
2248int wc_ecc_make_key_ex2(WC_RNG* rng, int keysize, ecc_key* key,
2249    int curve_id, int flags);
2250
2251/*!
2252    \ingroup ECC
2253    \brief Checks if point is on curve.
2254
2255    \return 1 if point is on curve
2256    \return 0 if not on curve
2257    \return negative on error
2258
2259    \param ecp ECC point
2260    \param a Curve parameter a
2261    \param b Curve parameter b
2262    \param prime Curve prime
2263
2264    _Example_
2265    \code
2266    ecc_point* point;
2267    mp_int a, b, prime;
2268    int ret = wc_ecc_is_point(point, &a, &b, &prime);
2269    \endcode
2270
2271    \sa wc_ecc_point_is_on_curve
2272*/
2273int wc_ecc_is_point(ecc_point* ecp, mp_int* a, mp_int* b,
2274    mp_int* prime);
2275
2276/*!
2277    \ingroup ECC
2278    \brief Gets generator point for curve.
2279
2280    \return 0 on success
2281    \return negative on error
2282
2283    \param ecp ECC point to store generator
2284    \param curve_idx Curve index
2285
2286    _Example_
2287    \code
2288    ecc_point* gen = wc_ecc_new_point();
2289    int ret = wc_ecc_get_generator(gen, 0);
2290    \endcode
2291
2292    \sa wc_ecc_get_curve_params
2293*/
2294int wc_ecc_get_generator(ecc_point* ecp, int curve_idx);
2295
2296/*!
2297    \ingroup ECC
2298    \brief Sets deterministic signing mode.
2299
2300    \return 0 on success
2301    \return negative on error
2302
2303    \param key ECC key
2304    \param flag Enable/disable flag
2305
2306    _Example_
2307    \code
2308    ecc_key key;
2309    int ret = wc_ecc_set_deterministic(&key, 1);
2310    \endcode
2311
2312    \sa wc_ecc_set_deterministic_ex
2313*/
2314int wc_ecc_set_deterministic(ecc_key* key, byte flag);
2315
2316/*!
2317    \ingroup ECC
2318    \brief Sets deterministic signing with hash type.
2319
2320    \return 0 on success
2321    \return negative on error
2322
2323    \param key ECC key
2324    \param flag Enable/disable flag
2325    \param hashType Hash algorithm type
2326
2327    _Example_
2328    \code
2329    ecc_key key;
2330    int ret = wc_ecc_set_deterministic_ex(&key, 1, WC_HASH_TYPE_SHA256);
2331    \endcode
2332
2333    \sa wc_ecc_set_deterministic
2334*/
2335int wc_ecc_set_deterministic_ex(ecc_key* key, byte flag,
2336    enum wc_HashType hashType);
2337
2338/*!
2339    \ingroup ECC
2340    \brief Generates deterministic k value for signing.
2341
2342    \return 0 on success
2343    \return negative on error
2344
2345    \param hash Hash value
2346    \param hashSz Hash size
2347    \param hashType Hash algorithm type
2348    \param priv Private key
2349    \param k Output k value
2350    \param order Curve order
2351    \param heap Heap hint
2352
2353    _Example_
2354    \code
2355    byte hash[32];
2356    mp_int priv, k, order;
2357    int ret = wc_ecc_gen_deterministic_k(hash, 32,
2358                                         WC_HASH_TYPE_SHA256,
2359                                         &priv, &k, &order, NULL);
2360    \endcode
2361
2362    \sa wc_ecc_sign_set_k
2363*/
2364int wc_ecc_gen_deterministic_k(const byte* hash, word32 hashSz,
2365    enum wc_HashType hashType, mp_int* priv, mp_int* k,
2366    mp_int* order, void* heap);
2367
2368/*!
2369    \ingroup ECC
2370    \brief Sets k value for signing.
2371
2372    \return 0 on success
2373    \return negative on error
2374
2375    \param k K value buffer
2376    \param klen K value length
2377    \param key ECC key
2378
2379    _Example_
2380    \code
2381    byte k[32];
2382    ecc_key key;
2383    int ret = wc_ecc_sign_set_k(k, sizeof(k), &key);
2384    \endcode
2385
2386    \sa wc_ecc_gen_deterministic_k
2387*/
2388int wc_ecc_sign_set_k(const byte* k, word32 klen, ecc_key* key);
2389
2390/*!
2391    \ingroup ECC
2392    \brief Initializes ECC key with ID.
2393
2394    \note This API is only available when WOLF_PRIVATE_KEY_ID is defined,
2395    which is set for PKCS11 support.
2396
2397    \return 0 on success
2398    \return negative on error
2399
2400    \param key ECC key
2401    \param id ID buffer
2402    \param len ID length
2403    \param heap Heap hint
2404    \param devId Device ID
2405
2406    _Example_
2407    \code
2408    ecc_key key;
2409    unsigned char id[] = "mykey";
2410    int ret = wc_ecc_init_id(&key, id, sizeof(id), NULL,
2411                             INVALID_DEVID);
2412    \endcode
2413
2414    \sa wc_ecc_init_label
2415*/
2416int wc_ecc_init_id(ecc_key* key, unsigned char* id, int len,
2417    void* heap, int devId);
2418
2419/*!
2420    \ingroup ECC
2421    \brief Initializes ECC key with label.
2422
2423    \note This API is only available when WOLF_PRIVATE_KEY_ID is defined,
2424    which is set for PKCS11 support.
2425
2426    \return 0 on success
2427    \return negative on error
2428
2429    \param key ECC key
2430    \param label Label string
2431    \param heap Heap hint
2432    \param devId Device ID
2433
2434    _Example_
2435    \code
2436    ecc_key key;
2437    int ret = wc_ecc_init_label(&key, "mykey", NULL,
2438                                INVALID_DEVID);
2439    \endcode
2440
2441    \sa wc_ecc_init_id
2442*/
2443int wc_ecc_init_label(ecc_key* key, const char* label, void* heap,
2444    int devId);
2445
2446/*!
2447    \ingroup ECC
2448    \brief Sets flags on ECC key.
2449
2450    \return 0 on success
2451    \return negative on error
2452
2453    \param key ECC key
2454    \param flags Flags to set
2455
2456    _Example_
2457    \code
2458    ecc_key key;
2459    int ret = wc_ecc_set_flags(&key, WC_ECC_FLAG_COFACTOR);
2460    \endcode
2461
2462    \sa wc_ecc_init
2463*/
2464int wc_ecc_set_flags(ecc_key* key, word32 flags);
2465
2466/*!
2467    \ingroup ECC
2468    \brief Initializes fixed-point cache.
2469
2470    \return none No returns
2471
2472    _Example_
2473    \code
2474    wc_ecc_fp_init();
2475    \endcode
2476
2477    \sa wc_ecc_init
2478*/
2479void wc_ecc_fp_init(void);
2480
2481/*!
2482    \ingroup ECC
2483    \brief Sets RNG for ECC key.
2484
2485    \return 0 on success
2486    \return negative on error
2487
2488    \param key ECC key
2489    \param rng Random number generator
2490
2491    _Example_
2492    \code
2493    ecc_key key;
2494    WC_RNG rng;
2495    int ret = wc_ecc_set_rng(&key, &rng);
2496    \endcode
2497
2498    \sa wc_ecc_make_key
2499*/
2500int wc_ecc_set_rng(ecc_key* key, WC_RNG* rng);
2501
2502/*!
2503    \ingroup ECC
2504    \brief Gets curve index from curve ID.
2505
2506    \return Curve index on success
2507    \return negative on error
2508
2509    \param curve_id Curve identifier
2510
2511    _Example_
2512    \code
2513    int idx = wc_ecc_get_curve_idx(ECC_SECP256R1);
2514    \endcode
2515
2516    \sa wc_ecc_get_curve_id
2517*/
2518int wc_ecc_get_curve_idx(int curve_id);
2519
2520/*!
2521    \ingroup ECC
2522    \brief Gets curve ID from curve index.
2523
2524    \return Curve ID on success
2525    \return negative on error
2526
2527    \param curve_idx Curve index
2528
2529    _Example_
2530    \code
2531    int id = wc_ecc_get_curve_id(0);
2532    \endcode
2533
2534    \sa wc_ecc_get_curve_idx
2535*/
2536int wc_ecc_get_curve_id(int curve_idx);
2537
2538/*!
2539    \ingroup ECC
2540    \brief Gets curve size from curve ID.
2541
2542    \return Key size in bytes on success
2543    \return negative on error
2544
2545    \param curve_id Curve identifier
2546
2547    _Example_
2548    \code
2549    int size = wc_ecc_get_curve_size_from_id(ECC_SECP256R1);
2550    \endcode
2551
2552    \sa wc_ecc_get_curve_id
2553*/
2554int wc_ecc_get_curve_size_from_id(int curve_id);
2555
2556/*!
2557    \ingroup ECC
2558    \brief Gets curve index from curve name.
2559
2560    \return Curve index on success
2561    \return negative on error
2562
2563    \param curveName Curve name string
2564
2565    _Example_
2566    \code
2567    int idx = wc_ecc_get_curve_idx_from_name("SECP256R1");
2568    \endcode
2569
2570    \sa wc_ecc_get_name
2571*/
2572int wc_ecc_get_curve_idx_from_name(const char* curveName);
2573
2574/*!
2575    \ingroup ECC
2576    \brief Gets curve size from curve name.
2577
2578    \return Key size in bytes on success
2579    \return negative on error
2580
2581    \param curveName Curve name string
2582
2583    _Example_
2584    \code
2585    int size = wc_ecc_get_curve_size_from_name("SECP256R1");
2586    \endcode
2587
2588    \sa wc_ecc_get_curve_idx_from_name
2589*/
2590int wc_ecc_get_curve_size_from_name(const char* curveName);
2591
2592/*!
2593    \ingroup ECC
2594    \brief Gets curve ID from curve name.
2595
2596    \return Curve ID on success
2597    \return negative on error
2598
2599    \param curveName Curve name string
2600
2601    _Example_
2602    \code
2603    int id = wc_ecc_get_curve_id_from_name("SECP256R1");
2604    \endcode
2605
2606    \sa wc_ecc_get_name
2607*/
2608int wc_ecc_get_curve_id_from_name(const char* curveName);
2609
2610/*!
2611    \ingroup ECC
2612    \brief Gets curve ID from curve parameters.
2613
2614    \return Curve ID on success
2615    \return negative on error
2616
2617    \param fieldSize Field size
2618    \param prime Prime modulus
2619    \param primeSz Prime size
2620    \param Af Curve parameter A
2621    \param AfSz A size
2622    \param Bf Curve parameter B
2623    \param BfSz B size
2624    \param order Curve order
2625    \param orderSz Order size
2626    \param Gx Generator X coordinate
2627    \param GxSz Gx size
2628    \param Gy Generator Y coordinate
2629    \param GySz Gy size
2630    \param cofactor Curve cofactor
2631
2632    _Example_
2633    \code
2634    int id = wc_ecc_get_curve_id_from_params(256, prime, 32,
2635                                             Af, 32, Bf, 32,
2636                                             order, 32, Gx, 32,
2637                                             Gy, 32, 1);
2638    \endcode
2639
2640    \sa wc_ecc_get_curve_params
2641*/
2642int wc_ecc_get_curve_id_from_params(int fieldSize,
2643    const byte* prime, word32 primeSz, const byte* Af, word32 AfSz,
2644    const byte* Bf, word32 BfSz, const byte* order, word32 orderSz,
2645    const byte* Gx, word32 GxSz, const byte* Gy, word32 GySz,
2646    int cofactor);
2647
2648/*!
2649    \ingroup ECC
2650    \brief Gets curve ID from domain parameters.
2651
2652    \return Curve ID on success
2653    \return negative on error
2654
2655    \param dp Domain parameters
2656
2657    _Example_
2658    \code
2659    const ecc_set_type* dp;
2660    int id = wc_ecc_get_curve_id_from_dp_params(dp);
2661    \endcode
2662
2663    \sa wc_ecc_get_curve_params
2664*/
2665int wc_ecc_get_curve_id_from_dp_params(const ecc_set_type* dp);
2666
2667/*!
2668    \ingroup ECC
2669    \brief Gets curve ID from OID.
2670
2671    \return Curve ID on success
2672    \return negative on error
2673
2674    \param oid OID buffer
2675    \param len OID length
2676
2677    _Example_
2678    \code
2679    byte oid[] = {0x2A, 0x86, 0x48, 0xCE, 0x3D, 0x03, 0x01, 0x07};
2680    int id = wc_ecc_get_curve_id_from_oid(oid, sizeof(oid));
2681    \endcode
2682
2683    \sa wc_ecc_get_oid
2684*/
2685int wc_ecc_get_curve_id_from_oid(const byte* oid, word32 len);
2686
2687/*!
2688    \ingroup ECC
2689    \brief Gets curve parameters from curve index.
2690
2691    \return ecc_set_type pointer on success
2692    \return NULL on failure
2693
2694    \param curve_idx Curve index
2695
2696    _Example_
2697    \code
2698    const ecc_set_type* params = wc_ecc_get_curve_params(0);
2699    \endcode
2700
2701    \sa wc_ecc_get_curve_idx
2702*/
2703const ecc_set_type* wc_ecc_get_curve_params(int curve_idx);
2704
2705/*!
2706    \ingroup ECC
2707    \brief Allocates new ECC point.
2708
2709    \return ecc_point pointer on success
2710    \return NULL on failure
2711
2712    _Example_
2713    \code
2714    ecc_point* point = wc_ecc_new_point();
2715    if (point != NULL) {
2716        // use point
2717        wc_ecc_del_point(point);
2718    }
2719    \endcode
2720
2721    \sa wc_ecc_del_point
2722*/
2723ecc_point* wc_ecc_new_point(void);
2724
2725/*!
2726    \ingroup ECC
2727    \brief Allocates new ECC point with heap hint.
2728
2729    \return ecc_point pointer on success
2730    \return NULL on failure
2731
2732    \param h Heap hint
2733
2734    _Example_
2735    \code
2736    ecc_point* point = wc_ecc_new_point_h(NULL);
2737    if (point != NULL) {
2738        // use point
2739        wc_ecc_del_point_h(point, NULL);
2740    }
2741    \endcode
2742
2743    \sa wc_ecc_del_point_h
2744*/
2745ecc_point* wc_ecc_new_point_h(void* h);
2746
2747/*!
2748    \ingroup ECC
2749    \brief Frees ECC point with heap hint.
2750
2751    \return none No returns
2752
2753    \param p ECC point to free
2754    \param h Heap hint
2755
2756    _Example_
2757    \code
2758    ecc_point* point = wc_ecc_new_point_h(NULL);
2759    // use point
2760    wc_ecc_del_point_h(point, NULL);
2761    \endcode
2762
2763    \sa wc_ecc_new_point_h
2764*/
2765void wc_ecc_del_point_h(ecc_point* p, void* h);
2766
2767/*!
2768    \ingroup ECC
2769    \brief Securely zeros ECC point.
2770
2771    \return none No returns
2772
2773    \param p ECC point to zero
2774
2775    _Example_
2776    \code
2777    ecc_point* point;
2778    wc_ecc_forcezero_point(point);
2779    \endcode
2780
2781    \sa wc_ecc_del_point
2782*/
2783void wc_ecc_forcezero_point(ecc_point* p);
2784
2785/*!
2786    \ingroup ECC
2787    \brief Checks if point is on curve.
2788
2789    \return 1 if on curve
2790    \return 0 if not on curve
2791    \return negative on error
2792
2793    \param p ECC point
2794    \param curve_idx Curve index
2795
2796    _Example_
2797    \code
2798    ecc_point* point;
2799    int ret = wc_ecc_point_is_on_curve(point, 0);
2800    \endcode
2801
2802    \sa wc_ecc_is_point
2803*/
2804int wc_ecc_point_is_on_curve(ecc_point *p, int curve_idx);
2805
2806/*!
2807    \ingroup ECC
2808    \brief Imports X9.63 format with curve ID.
2809
2810    \return 0 on success
2811    \return negative on error
2812
2813    \param in Input buffer
2814    \param inLen Input length
2815    \param key ECC key
2816    \param curve_id Curve identifier
2817
2818    _Example_
2819    \code
2820    byte x963[65];
2821    ecc_key key;
2822    int ret = wc_ecc_import_x963_ex(x963, sizeof(x963), &key,
2823                                    ECC_SECP256R1);
2824    \endcode
2825
2826    \sa wc_ecc_import_x963
2827*/
2828int wc_ecc_import_x963_ex(const byte* in, word32 inLen,
2829    ecc_key* key, int curve_id);
2830
2831/*!
2832    \ingroup ECC
2833    \brief Imports private key with curve ID.
2834
2835    \return 0 on success
2836    \return negative on error
2837
2838    \param priv Private key buffer
2839    \param privSz Private key size
2840    \param pub Public key buffer
2841    \param pubSz Public key size
2842    \param key ECC key
2843    \param curve_id Curve identifier
2844
2845    _Example_
2846    \code
2847    byte priv[32], pub[65];
2848    ecc_key key;
2849    int ret = wc_ecc_import_private_key_ex(priv, 32, pub, 65,
2850                                           &key, ECC_SECP256R1);
2851    \endcode
2852
2853    \sa wc_ecc_import_private_key
2854*/
2855int wc_ecc_import_private_key_ex(const byte* priv, word32 privSz,
2856    const byte* pub, word32 pubSz, ecc_key* key, int curve_id);
2857
2858/*!
2859    \ingroup ECC
2860    \brief Converts raw r,s to signature.
2861
2862    \return 0 on success
2863    \return negative on error
2864
2865    \param r R value buffer
2866    \param rSz R value size
2867    \param s S value buffer
2868    \param sSz S value size
2869    \param out Output signature buffer
2870    \param outlen Output signature length
2871
2872    _Example_
2873    \code
2874    byte r[32], s[32], sig[72];
2875    word32 sigLen = sizeof(sig);
2876    int ret = wc_ecc_rs_raw_to_sig(r, 32, s, 32, sig, &sigLen);
2877    \endcode
2878
2879    \sa wc_ecc_sig_to_rs
2880*/
2881int wc_ecc_rs_raw_to_sig(const byte* r, word32 rSz, const byte* s,
2882    word32 sSz, byte* out, word32* outlen);
2883
2884/*!
2885    \ingroup ECC
2886    \brief Converts signature to raw r,s.
2887
2888    \return 0 on success
2889    \return negative on error
2890
2891    \param sig Signature buffer
2892    \param sigLen Signature length
2893    \param r R value buffer
2894    \param rLen R value length
2895    \param s S value buffer
2896    \param sLen S value length
2897
2898    _Example_
2899    \code
2900    byte sig[72], r[32], s[32];
2901    word32 rLen = 32, sLen = 32;
2902    int ret = wc_ecc_sig_to_rs(sig, 72, r, &rLen, s, &sLen);
2903    \endcode
2904
2905    \sa wc_ecc_rs_raw_to_sig
2906*/
2907int wc_ecc_sig_to_rs(const byte* sig, word32 sigLen, byte* r,
2908    word32* rLen, byte* s, word32* sLen);
2909
2910/*!
2911    \ingroup ECC
2912    \brief Imports raw key with curve ID.
2913
2914    \return 0 on success
2915    \return negative on error
2916
2917    \param key ECC key
2918    \param qx X coordinate string
2919    \param qy Y coordinate string
2920    \param d Private key string
2921    \param curve_id Curve identifier
2922
2923    _Example_
2924    \code
2925    ecc_key key;
2926    int ret = wc_ecc_import_raw_ex(&key, qxStr, qyStr, dStr,
2927                                   ECC_SECP256R1);
2928    \endcode
2929
2930    \sa wc_ecc_import_raw
2931*/
2932int wc_ecc_import_raw_ex(ecc_key* key, const char* qx,
2933    const char* qy, const char* d, int curve_id);
2934
2935/*!
2936    \ingroup ECC
2937    \brief Imports unsigned key with curve ID.
2938
2939    \return 0 on success
2940    \return negative on error
2941
2942    \param key ECC key
2943    \param qx X coordinate buffer
2944    \param qy Y coordinate buffer
2945    \param d Private key buffer
2946    \param curve_id Curve identifier
2947
2948    _Example_
2949    \code
2950    ecc_key key;
2951    byte qx[32], qy[32], d[32];
2952    int ret = wc_ecc_import_unsigned(&key, qx, qy, d,
2953                                     ECC_SECP256R1);
2954    \endcode
2955
2956    \sa wc_ecc_import_raw_ex
2957*/
2958int wc_ecc_import_unsigned(ecc_key* key, const byte* qx,
2959    const byte* qy, const byte* d, int curve_id);
2960
2961/*!
2962    \ingroup ECC
2963    \brief Exports key with encoding type.
2964
2965    \return 0 on success
2966    \return negative on error
2967
2968    \param key ECC key
2969    \param qx X coordinate buffer
2970    \param qxLen X coordinate length
2971    \param qy Y coordinate buffer
2972    \param qyLen Y coordinate length
2973    \param d Private key buffer
2974    \param dLen Private key length
2975    \param encType Encoding type
2976
2977    _Example_
2978    \code
2979    ecc_key key;
2980    byte qx[32], qy[32], d[32];
2981    word32 qxLen = 32, qyLen = 32, dLen = 32;
2982    int ret = wc_ecc_export_ex(&key, qx, &qxLen, qy, &qyLen,
2983                               d, &dLen, 0);
2984    \endcode
2985
2986    \sa wc_ecc_export_public_raw
2987*/
2988int wc_ecc_export_ex(ecc_key* key, byte* qx, word32* qxLen,
2989    byte* qy, word32* qyLen, byte* d, word32* dLen, int encType);
2990
2991/*!
2992    \ingroup ECC
2993    \brief Exports public key in raw format.
2994
2995    \return 0 on success
2996    \return negative on error
2997
2998    \param key ECC key
2999    \param qx X coordinate buffer
3000    \param qxLen X coordinate length
3001    \param qy Y coordinate buffer
3002    \param qyLen Y coordinate length
3003
3004    _Example_
3005    \code
3006    ecc_key key;
3007    byte qx[32], qy[32];
3008    word32 qxLen = 32, qyLen = 32;
3009    int ret = wc_ecc_export_public_raw(&key, qx, &qxLen, qy,
3010                                       &qyLen);
3011    \endcode
3012
3013    \sa wc_ecc_export_private_raw
3014*/
3015int wc_ecc_export_public_raw(ecc_key* key, byte* qx,
3016    word32* qxLen, byte* qy, word32* qyLen);
3017
3018/*!
3019    \ingroup ECC
3020    \brief Exports private key in raw format.
3021
3022    \return 0 on success
3023    \return negative on error
3024
3025    \param key ECC key
3026    \param qx X coordinate buffer
3027    \param qxLen X coordinate length
3028    \param qy Y coordinate buffer
3029    \param qyLen Y coordinate length
3030    \param d Private key buffer
3031    \param dLen Private key length
3032
3033    _Example_
3034    \code
3035    ecc_key key;
3036    byte qx[32], qy[32], d[32];
3037    word32 qxLen = 32, qyLen = 32, dLen = 32;
3038    int ret = wc_ecc_export_private_raw(&key, qx, &qxLen, qy,
3039                                        &qyLen, d, &dLen);
3040    \endcode
3041
3042    \sa wc_ecc_export_public_raw
3043*/
3044int wc_ecc_export_private_raw(ecc_key* key, byte* qx,
3045    word32* qxLen, byte* qy, word32* qyLen, byte* d, word32* dLen);
3046
3047/*!
3048    \ingroup ECC
3049    \brief Exports point in DER format with compression.
3050
3051    \return Size on success
3052    \return negative on error
3053
3054    \param curve_idx Curve index
3055    \param point ECC point
3056    \param out Output buffer
3057    \param outLen Output length
3058    \param compressed Compression flag
3059
3060    _Example_
3061    \code
3062    ecc_point* point;
3063    byte out[65];
3064    word32 outLen = sizeof(out);
3065    int ret = wc_ecc_export_point_der_ex(0, point, out, &outLen,
3066                                         0);
3067    \endcode
3068
3069    \sa wc_ecc_export_point_der
3070*/
3071int wc_ecc_export_point_der_ex(const int curve_idx,
3072    ecc_point* point, byte* out, word32* outLen, int compressed);
3073
3074/*!
3075    \ingroup ECC
3076    \brief Imports point from DER format.
3077
3078    \return 0 on success
3079    \return negative on error
3080
3081    \param in Input buffer
3082    \param inLen Input length
3083    \param curve_idx Curve index
3084    \param point ECC point
3085    \param shortKeySize Short key size flag
3086
3087    _Example_
3088    \code
3089    byte der[65];
3090    ecc_point* point = wc_ecc_new_point();
3091    int ret = wc_ecc_import_point_der_ex(der, sizeof(der), 0,
3092                                         point, 0);
3093    \endcode
3094
3095    \sa wc_ecc_import_point_der
3096*/
3097int wc_ecc_import_point_der_ex(const byte* in, word32 inLen,
3098    const int curve_idx, ecc_point* point, int shortKeySize);
3099
3100/*!
3101    \ingroup ECC
3102    \brief Gets OID for curve.
3103
3104    \return 0 on success
3105    \return negative on error
3106
3107    \param oidSum OID sum
3108    \param oid OID buffer pointer
3109    \param oidSz OID size pointer
3110
3111    _Example_
3112    \code
3113    const byte* oid;
3114    word32 oidSz;
3115    int ret = wc_ecc_get_oid(0x2A8648CE3D030107, &oid, &oidSz);
3116    \endcode
3117
3118    \sa wc_ecc_get_curve_id_from_oid
3119*/
3120int wc_ecc_get_oid(word32 oidSum, const byte** oid, word32* oidSz);
3121
3122/*!
3123    \ingroup ECC
3124    \brief Sets custom curve parameters.
3125
3126    \return 0 on success
3127    \return negative on error
3128
3129    \param key ECC key
3130    \param dp Domain parameters
3131
3132    _Example_
3133    \code
3134    ecc_key key;
3135    ecc_set_type dp;
3136    int ret = wc_ecc_set_custom_curve(&key, &dp);
3137    \endcode
3138
3139    \sa wc_ecc_get_curve_params
3140*/
3141int wc_ecc_set_custom_curve(ecc_key* key, const ecc_set_type* dp);
3142
3143/*!
3144    \ingroup ECC
3145    \brief Creates new ECC encryption context.
3146
3147    \return ecEncCtx pointer on success
3148    \return NULL on failure
3149
3150    \param flags Context flags
3151    \param rng Random number generator
3152
3153    _Example_
3154    \code
3155    WC_RNG rng;
3156    ecEncCtx* ctx = wc_ecc_ctx_new(0, &rng);
3157    \endcode
3158
3159    \sa wc_ecc_ctx_free
3160*/
3161ecEncCtx* wc_ecc_ctx_new(int flags, WC_RNG* rng);
3162
3163/*!
3164    \ingroup ECC
3165    \brief Creates new ECC encryption context with heap.
3166
3167    \return ecEncCtx pointer on success
3168    \return NULL on failure
3169
3170    \param flags Context flags
3171    \param rng Random number generator
3172    \param heap Heap hint
3173
3174    _Example_
3175    \code
3176    WC_RNG rng;
3177    ecEncCtx* ctx = wc_ecc_ctx_new_ex(0, &rng, NULL);
3178    \endcode
3179
3180    \sa wc_ecc_ctx_new
3181*/
3182ecEncCtx* wc_ecc_ctx_new_ex(int flags, WC_RNG* rng, void* heap);
3183
3184/*!
3185    \ingroup ECC
3186    \brief Resets ECC encryption context.
3187
3188    \return 0 on success
3189    \return negative on error
3190
3191    \param ctx ECC encryption context
3192    \param rng Random number generator
3193
3194    _Example_
3195    \code
3196    ecEncCtx* ctx;
3197    WC_RNG rng;
3198    int ret = wc_ecc_ctx_reset(ctx, &rng);
3199    \endcode
3200
3201    \sa wc_ecc_ctx_new
3202*/
3203int wc_ecc_ctx_reset(ecEncCtx* ctx, WC_RNG* rng);
3204
3205/*!
3206    \ingroup ECC
3207    \brief Gets own salt from context.
3208
3209    \return Salt pointer on success
3210    \return NULL on failure
3211
3212    \param ctx ECC encryption context
3213
3214    _Example_
3215    \code
3216    ecEncCtx* ctx;
3217    const byte* salt = wc_ecc_ctx_get_own_salt(ctx);
3218    \endcode
3219
3220    \sa wc_ecc_ctx_set_own_salt
3221*/
3222const byte* wc_ecc_ctx_get_own_salt(ecEncCtx* ctx);
3223
3224/*!
3225    \ingroup ECC
3226    \brief Sets own salt in context.
3227
3228    \return 0 on success
3229    \return negative on error
3230
3231    \param ctx ECC encryption context
3232    \param salt Salt buffer
3233    \param sz Salt size
3234
3235    _Example_
3236    \code
3237    ecEncCtx* ctx;
3238    byte salt[16];
3239    int ret = wc_ecc_ctx_set_own_salt(ctx, salt, sizeof(salt));
3240    \endcode
3241
3242    \sa wc_ecc_ctx_get_own_salt
3243*/
3244int wc_ecc_ctx_set_own_salt(ecEncCtx* ctx, const byte* salt,
3245    word32 sz);
3246
3247/*!
3248    \ingroup ECC
3249    \brief X9.63 Key Derivation Function.
3250
3251    \return 0 on success
3252    \return negative on error
3253
3254    \param type Hash type
3255    \param secret Shared secret
3256    \param secretSz Secret size
3257    \param sinfo Shared info
3258    \param sinfoSz Shared info size
3259    \param out Output buffer
3260    \param outSz Output size
3261
3262    _Example_
3263    \code
3264    byte secret[32], sinfo[10], out[32];
3265    int ret = wc_X963_KDF(WC_HASH_TYPE_SHA256, secret, 32,
3266                          sinfo, 10, out, 32);
3267    \endcode
3268
3269    \sa wc_ecc_shared_secret
3270*/
3271int wc_X963_KDF(enum wc_HashType type, const byte* secret,
3272    word32 secretSz, const byte* sinfo, word32 sinfoSz,
3273    byte* out, word32 outSz);
3274
3275/*!
3276    \ingroup ECC
3277    \brief Initializes curve cache.
3278
3279    \return 0 on success
3280    \return negative on error
3281
3282    _Example_
3283    \code
3284    int ret = wc_ecc_curve_cache_init();
3285    \endcode
3286
3287    \sa wc_ecc_curve_cache_free
3288*/
3289int wc_ecc_curve_cache_init(void);
3290
3291/*!
3292    \ingroup ECC
3293    \brief Frees curve cache.
3294
3295    \return none No returns
3296
3297    _Example_
3298    \code
3299    wc_ecc_curve_cache_free();
3300    \endcode
3301
3302    \sa wc_ecc_curve_cache_init
3303*/
3304void wc_ecc_curve_cache_free(void);
3305
3306/*!
3307    \ingroup ECC
3308    \brief Generates random k value.
3309
3310    \return 0 on success
3311    \return negative on error
3312
3313    \param rng Random number generator
3314    \param size Key size
3315    \param k Output k value
3316    \param order Curve order
3317
3318    _Example_
3319    \code
3320    WC_RNG rng;
3321    mp_int k, order;
3322    int ret = wc_ecc_gen_k(&rng, 32, &k, &order);
3323    \endcode
3324
3325    \sa wc_ecc_sign_hash
3326*/
3327int wc_ecc_gen_k(WC_RNG* rng, int size, mp_int* k, mp_int* order);
3328
3329/*!
3330    \ingroup ECC
3331    \brief Sets remote handle for hardware.
3332
3333    \return 0 on success
3334    \return negative on error
3335
3336    \param key ECC key
3337    \param handle Remote handle
3338
3339    _Example_
3340    \code
3341    ecc_key key;
3342    remote_handle64 handle = 0x1234;
3343    int ret = wc_ecc_set_handle(&key, handle);
3344    \endcode
3345
3346    \sa wc_ecc_init
3347*/
3348int wc_ecc_set_handle(ecc_key* key, remote_handle64 handle);
3349
3350/*!
3351    \ingroup ECC
3352    \brief Uses key ID for hardware.
3353
3354    \return 0 on success
3355    \return negative on error
3356
3357    \param key ECC key
3358    \param keyId Key identifier
3359    \param flags Flags
3360
3361    _Example_
3362    \code
3363    ecc_key key;
3364    int ret = wc_ecc_use_key_id(&key, 1, 0);
3365    \endcode
3366
3367    \sa wc_ecc_get_key_id
3368*/
3369int wc_ecc_use_key_id(ecc_key* key, word32 keyId, word32 flags);
3370
3371/*!
3372    \ingroup ECC
3373    \brief Gets key ID from hardware key.
3374
3375    \return 0 on success
3376    \return negative on error
3377
3378    \param key ECC key
3379    \param keyId Key identifier pointer
3380
3381    _Example_
3382    \code
3383    ecc_key key;
3384    word32 keyId;
3385    int ret = wc_ecc_get_key_id(&key, &keyId);
3386    \endcode
3387
3388    \sa wc_ecc_use_key_id
3389*/
3390int wc_ecc_get_key_id(ecc_key* key, word32* keyId);