luna - wolfssl/doc/dox_comments/header

   1/*!
   2    \ingroup ED25519
   3
   4    \brief This function generates the Ed25519 public key from the private key,
   5    stored in the ed25519_key object. It stores the public key in the buffer
   6    pubKey.
   7
   8    \return 0 Returned upon successfully making the public key.
   9    \return BAD_FUNC_ARG Returned if key or pubKey evaluate to NULL, or if the
  10    specified key size is not 32 bytes (Ed25519 has 32 byte keys).
  11    \return ECC_PRIV_KEY_E returned if the ed25519_key object does not have
  12    the private key in it.
  13    \return MEMORY_E Returned if there is an error allocating memory
  14    during function execution.
  15
  16    \param [in] key Pointer to the ed25519_key for which to generate a key.
  17    \param [out] pubKey Pointer to the buffer in which to store the public key.
  18    \param [in] pubKeySz Size of the public key. Should be ED25519_PUB_KEY_SIZE.
  19
  20    _Example_
  21    \code
  22    int ret;
  23
  24    ed25519_key key;
  25    byte priv[] = { initialize with 32 byte private key };
  26    byte pub[32];
  27    word32 pubSz = sizeof(pub);
  28
  29    wc_ed25519_init(&key);
  30    wc_ed25519_import_private_only(priv, sizeof(priv), &key);
  31    ret = wc_ed25519_make_public(&key, pub, &pubSz);
  32    if (ret != 0) {
  33        // error making public key
  34    }
  35    \endcode
  36
  37    \sa wc_ed25519_init
  38    \sa wc_ed25519_import_private_only
  39    \sa wc_ed25519_make_key
  40*/
  41
  42int wc_ed25519_make_public(ed25519_key* key, unsigned char* pubKey,
  43                           word32 pubKeySz);
  44
  45/*!
  46    \ingroup ED25519
  47
  48    \brief This function generates a new Ed25519 key and stores it in key.
  49
  50    \return 0 Returned upon successfully making an ed25519_key.
  51    \return BAD_FUNC_ARG Returned if rng or key evaluate to NULL, or if the
  52    specified key size is not 32 bytes (Ed25519 has 32 byte keys).
  53    \return MEMORY_E Returned if there is an error allocating memory
  54    during function execution.
  55
  56    \param [in] rng Pointer to an initialized RNG object with which to
  57    generate the key.
  58    \param [in] keysize Length of key to generate. Should always be 32 for
  59    Ed25519.
  60    \param [in,out] key Pointer to the ed25519_key for which to generate a key.
  61
  62    _Example_
  63    \code
  64    int ret;
  65
  66    WC_RNG rng;
  67    ed25519_key key;
  68
  69    wc_InitRng(&rng);
  70    wc_ed25519_init(&key);
  71    wc_ed25519_make_key(&rng, 32, &key);
  72    if (ret != 0) {
  73        // error making key
  74    }
  75    \endcode
  76
  77    \sa wc_ed25519_init
  78*/
  79
  80int wc_ed25519_make_key(WC_RNG* rng, int keysize, ed25519_key* key);
  81
  82/*!
  83    \ingroup ED25519
  84
  85    \brief This function signs a message using an ed25519_key object
  86    to guarantee authenticity.
  87
  88    \return 0 Returned upon successfully generating a signature for the
  89    message.
  90    \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to
  91    NULL, or if the output buffer is too small to store the generated signature.
  92    \return MEMORY_E Returned if there is an error allocating memory during
  93    function execution.
  94
  95    \param [in] in Pointer to the buffer containing the message to sign.
  96    \param [in] inlen Length of the message to sign.
  97    \param [out] out Buffer in which to store the generated signature.
  98    \param [in,out] outlen Maximum length of the output buffer. Will store the
  99    bytes written to out upon successfully generating a message signature.
 100    \param [in] key Pointer to a private ed25519_key with which to generate the
 101    signature.
 102
 103    _Example_
 104    \code
 105    ed25519_key key;
 106    WC_RNG rng;
 107    int ret, sigSz;
 108
 109    byte sig[64]; // will hold generated signature
 110    sigSz = sizeof(sig);
 111    byte message[] = { initialize with message };
 112
 113    wc_InitRng(&rng); // initialize rng
 114    wc_ed25519_init(&key); // initialize key
 115    wc_ed25519_make_key(&rng, 32, &key); // make public/private key pair
 116    ret = wc_ed25519_sign_msg(message, sizeof(message), sig, &sigSz, &key);
 117    if (ret != 0) {
 118        // error generating message signature
 119    }
 120    \endcode
 121
 122    \sa wc_ed25519ctx_sign_msg
 123    \sa wc_ed25519ph_sign_hash
 124    \sa wc_ed25519ph_sign_msg
 125    \sa wc_ed25519_verify_msg
 126*/
 127
 128int wc_ed25519_sign_msg(const byte* in, word32 inlen, byte* out,
 129                        word32 *outlen, ed25519_key* key);
 130
 131/*!
 132    \ingroup ED25519
 133
 134    \brief This function signs a message using an ed25519_key object
 135    to guarantee authenticity. The context is part of the data signed.
 136
 137    \return 0 Returned upon successfully generating a signature for the
 138    message.
 139    \return BAD_FUNC_ARG Returned any of the input parameters evaluate to
 140    NULL, or if the output buffer is too small to store the generated signature.
 141    \return MEMORY_E Returned if there is an error allocating memory during
 142    function execution.
 143
 144    \param [in] in Pointer to the buffer containing the message to sign.
 145    \param [in] inlen Length of the message to sign.
 146    \param [out] out Buffer in which to store the generated signature.
 147    \param [in,out] outlen Maximum length of the output buffer. Will store the
 148    bytes written to out upon successfully generating a message signature.
 149    \param [in] key Pointer to a private ed25519_key with which to generate the
 150    signature.
 151    \param [in] context Pointer to the buffer containing the context for which
 152    message is being signed.
 153    \param [in] contextLen Length of the context buffer.
 154
 155    _Example_
 156    \code
 157    ed25519_key key;
 158    WC_RNG rng;
 159    int ret, sigSz;
 160
 161    byte sig[64]; // will hold generated signature
 162    sigSz = sizeof(sig);
 163    byte message[] = { initialize with message };
 164    byte context[] = { initialize with context of signing };
 165
 166    wc_InitRng(&rng); // initialize rng
 167    wc_ed25519_init(&key); // initialize key
 168    wc_ed25519_make_key(&rng, 32, &key); // make public/private key pair
 169    ret = wc_ed25519ctx_sign_msg(message, sizeof(message), sig, &sigSz, &key,
 170            context, sizeof(context));
 171    if (ret != 0) {
 172        // error generating message signature
 173    }
 174    \endcode
 175
 176    \sa wc_ed25519_sign_msg
 177    \sa wc_ed25519ph_sign_hash
 178    \sa wc_ed25519ph_sign_msg
 179    \sa wc_ed25519_verify_msg
 180*/
 181
 182int wc_ed25519ctx_sign_msg(const byte* in, word32 inlen, byte* out,
 183                        word32 *outlen, ed25519_key* key,
 184                        const byte* context, byte contextLen);
 185
 186/*!
 187    \ingroup ED25519
 188
 189    \brief This function signs a message digest using an ed25519_key object
 190    to guarantee authenticity. The context is included as part of the data
 191    signed. The message is pre-hashed before signature calculation.
 192
 193    \return 0 Returned upon successfully generating a signature for the
 194    message digest.
 195    \return BAD_FUNC_ARG Returned any of the input parameters evaluate to
 196    NULL, or if the output buffer is too small to store the generated signature.
 197    \return MEMORY_E Returned if there is an error allocating memory during
 198    function execution.
 199
 200    \param [in] hash Pointer to the buffer containing the hash of the message
 201    to sign.
 202    \param [in] hashLen Length of the hash of the message to sign.
 203    \param [out] out Buffer in which to store the generated signature.
 204    \param [in,out] outLen Maximum length of the output buffer. Will store the
 205    bytes written to out upon successfully generating a message signature.
 206    \param [in] key Pointer to a private ed25519_key with which to generate the
 207    signature.
 208    \param [in] context Pointer to the buffer containing the context for which
 209    message is being signed.
 210    \param [in] contextLen Length of the context buffer.
 211
 212    _Example_
 213    \code
 214    ed25519_key key;
 215    WC_RNG rng;
 216    int ret, sigSz;
 217
 218    byte sig[64]; // will hold generated signature
 219    sigSz = sizeof(sig);
 220    byte hash[] = { initialize with SHA-512 hash of message };
 221    byte context[] = { initialize with context of signing };
 222
 223    wc_InitRng(&rng); // initialize rng
 224    wc_ed25519_init(&key); // initialize key
 225    wc_ed25519_make_key(&rng, 32, &key); // make public/private key pair
 226    ret = wc_ed25519ph_sign_hash(hash, sizeof(hash), sig, &sigSz, &key,
 227            context, sizeof(context));
 228    if (ret != 0) {
 229        // error generating message signature
 230    }
 231    \endcode
 232
 233    \sa wc_ed25519_sign_msg
 234    \sa wc_ed25519ctx_sign_msg
 235    \sa wc_ed25519ph_sign_msg
 236    \sa wc_ed25519_verify_msg
 237*/
 238
 239int wc_ed25519ph_sign_hash(const byte* hash, word32 hashLen, byte* out,
 240                           word32 *outLen, ed25519_key* key,
 241                           const byte* context, byte contextLen);
 242
 243/*!
 244    \ingroup ED25519
 245
 246    \brief This function signs a message using an ed25519_key object
 247    to guarantee authenticity. The context is included as part of the data
 248    signed. The message is pre-hashed before signature calculation.
 249
 250    \return 0 Returned upon successfully generating a signature for the
 251    message.
 252    \return BAD_FUNC_ARG Returned any of the input parameters evaluate to
 253    NULL, or if the output buffer is too small to store the generated signature.
 254    \return MEMORY_E Returned if there is an error allocating memory during
 255    function execution.
 256
 257    \param [in] in Pointer to the buffer containing the message to sign.
 258    \param [in] inlen Length of the message to sign.
 259    \param [out] out Buffer in which to store the generated signature.
 260    \param [in,out] outlen Maximum length of the output buffer. Will store the
 261    bytes written to out upon successfully generating a message signature.
 262    \param [in] key Pointer to a private ed25519_key with which to generate the
 263    signature.
 264    \param [in] context Pointer to the buffer containing the context for which
 265    message is being signed.
 266    \param [in] contextLen Length of the context buffer.
 267
 268    _Example_
 269    \code
 270    ed25519_key key;
 271    WC_RNG rng;
 272    int ret, sigSz;
 273
 274    byte sig[64]; // will hold generated signature
 275    sigSz = sizeof(sig);
 276    byte message[] = { initialize with message };
 277    byte context[] = { initialize with context of signing };
 278
 279    wc_InitRng(&rng); // initialize rng
 280    wc_ed25519_init(&key); // initialize key
 281    wc_ed25519_make_key(&rng, 32, &key); // make public/private key pair
 282    ret = wc_ed25519ph_sign_msg(message, sizeof(message), sig, &sigSz, &key,
 283            context, sizeof(context));
 284    if (ret != 0) {
 285        // error generating message signature
 286    }
 287    \endcode
 288
 289    \sa wc_ed25519_sign_msg
 290    \sa wc_ed25519ctx_sign_msg
 291    \sa wc_ed25519ph_sign_hash
 292    \sa wc_ed25519_verify_msg
 293*/
 294
 295int wc_ed25519ph_sign_msg(const byte* in, word32 inlen, byte* out,
 296                        word32 *outlen, ed25519_key* key,
 297                        const byte* context, byte contextLen);
 298
 299/*!
 300    \ingroup ED25519
 301
 302    \brief This function verifies the Ed25519 signature of a message to ensure
 303    authenticity. It returns the answer through ret, with 1 corresponding to
 304    a valid signature, and 0 corresponding to an invalid signature.
 305
 306    \return 0 Returned upon successfully performing the signature
 307    verification and authentication.
 308    \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to
 309    NULL, or if the siglen does not match the actual length of a signature.
 310    \return SIG_VERIFY_E Returned if verification completes, but the signature
 311    generated does not match the signature provided.
 312
 313    \param [in] sig Pointer to the buffer containing the signature to verify.
 314    \param [in] siglen Length of the signature to verify.
 315    \param [in] msg Pointer to the buffer containing the message to verify.
 316    \param [in] msgLen Length of the message to verify.
 317    \param [out] ret Pointer to the result of the verification. 1 indicates the
 318    message was successfully verified.
 319    \param [in] key Pointer to a public Ed25519 key with which to verify the
 320    signature.
 321
 322    _Example_
 323    \code
 324    ed25519_key key;
 325    int ret, verified = 0;
 326
 327    byte sig[] { initialize with received signature };
 328    byte msg[] = { initialize with message };
 329    // initialize key with received public key
 330    ret = wc_ed25519_verify_msg(sig, sizeof(sig), msg, sizeof(msg), &verified,
 331            &key);
 332    if (ret < 0) {
 333        // error performing verification
 334    } else if (verified == 0)
 335        // the signature is invalid
 336    }
 337    \endcode
 338
 339    \sa wc_ed25519ctx_verify_msg
 340    \sa wc_ed25519ph_verify_hash
 341    \sa wc_ed25519ph_verify_msg
 342    \sa wc_ed25519_sign_msg
 343*/
 344
 345int wc_ed25519_verify_msg(const byte* sig, word32 siglen, const byte* msg,
 346                          word32 msgLen, int* ret, ed25519_key* key);
 347
 348/*!
 349    \ingroup ED25519
 350
 351    \brief This function verifies the Ed25519 signature of a message to ensure
 352    authenticity. The context is included as part of the data
 353    verified. It returns the answer through ret, with 1 corresponding to
 354    a valid signature, and 0 corresponding to an invalid signature.
 355
 356    \return 0 Returned upon successfully performing the signature
 357    verification and authentication.
 358    \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to
 359    NULL, or if the siglen does not match the actual length of a signature.
 360    \return SIG_VERIFY_E Returned if verification completes, but the signature
 361    generated does not match the signature provided.
 362
 363    \param [in] sig Pointer to the buffer containing the signature to verify.
 364    \param [in] siglen Length of the signature to verify.
 365    \param [in] msg Pointer to the buffer containing the message to verify.
 366    \param [in] msgLen Length of the message to verify.
 367    \param [out] ret Pointer to the result of the verification. 1 indicates the
 368    message was successfully verified.
 369    \param [in] key Pointer to a public Ed25519 key with which to verify the
 370    signature.
 371    \param [in] context Pointer to the buffer containing the context for which
 372    the message was signed.
 373    \param [in] contextLen Length of the context buffer.
 374
 375    _Example_
 376    \code
 377    ed25519_key key;
 378    int ret, verified = 0;
 379
 380    byte sig[] { initialize with received signature };
 381    byte msg[] = { initialize with message };
 382    byte context[] = { initialize with context of signature };
 383    // initialize key with received public key
 384    ret = wc_ed25519ctx_verify_msg(sig, sizeof(sig), msg, sizeof(msg),
 385            &verified, &key, );
 386    if (ret < 0) {
 387        // error performing verification
 388    } else if (verified == 0)
 389        // the signature is invalid
 390    }
 391    \endcode
 392
 393    \sa wc_ed25519_verify_msg
 394    \sa wc_ed25519ph_verify_hash
 395    \sa wc_ed25519ph_verify_msg
 396    \sa wc_ed25519_sign_msg
 397*/
 398
 399int wc_ed25519ctx_verify_msg(const byte* sig, word32 siglen, const byte* msg,
 400                             word32 msgLen, int* ret, ed25519_key* key,
 401                             const byte* context, byte contextLen);
 402
 403/*!
 404    \ingroup ED25519
 405
 406    \brief This function verifies the Ed25519 signature of the digest of a
 407    message to ensure authenticity. The context is included as part of the data
 408    verified. The hash is the pre-hashed message before signature calculation.
 409    The hash algorithm used to create message digest must be SHA-512.
 410    The answer is returned through ret, with 1 corresponding to a valid
 411    signature, and 0 corresponding to an invalid signature.
 412
 413
 414    \return 0 Returned upon successfully performing the signature
 415    verification and authentication.
 416    \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to
 417    NULL, or if the siglen does not match the actual length of a signature.
 418    \return SIG_VERIFY_E Returned if verification completes, but the signature
 419    generated does not match the signature provided.
 420
 421    \param [in] sig Pointer to the buffer containing the signature to verify.
 422    \param [in] siglen Length of the signature to verify.
 423    \param [in] hash Pointer to the buffer containing the hash of the message
 424    to verify.
 425    \param [in] hashLen Length of the hash to verify.
 426    \param [out] ret Pointer to the result of the verification. 1 indicates the
 427    message was successfully verified.
 428    \param [in] key Pointer to a public Ed25519 key with which to verify the
 429    signature.
 430    \param [in] context Pointer to the buffer containing the context for which
 431    the message was signed.
 432    \param [in] contextLen Length of the context buffer.
 433
 434    _Example_
 435    \code
 436    ed25519_key key;
 437    int ret, verified = 0;
 438
 439    byte sig[] { initialize with received signature };
 440    byte hash[] = { initialize with SHA-512 hash of message };
 441    byte context[] = { initialize with context of signature };
 442    // initialize key with received public key
 443    ret = wc_ed25519ph_verify_hash(sig, sizeof(sig), hash, sizeof(hash),
 444            &verified, &key, context, sizeof(context));
 445    if (ret < 0) {
 446        // error performing verification
 447    } else if (verified == 0)
 448        // the signature is invalid
 449    }
 450    \endcode
 451
 452    \sa wc_ed25519_verify_msg
 453    \sa wc_ed25519ctx_verify_msg
 454    \sa wc_ed25519ph_verify_msg
 455    \sa wc_ed25519_sign_msg
 456*/
 457
 458int wc_ed25519ph_verify_hash(const byte* sig, word32 siglen, const byte* hash,
 459                             word32 hashLen, int* ret, ed25519_key* key,
 460                             const byte* context, byte contextLen);
 461
 462/*!
 463    \ingroup ED25519
 464
 465    \brief This function verifies the Ed25519 signature of a message to ensure
 466    authenticity. The context is included as part of the data
 467    verified. The message is pre-hashed before verification. It returns the
 468    answer through ret, with 1 corresponding to a valid signature, and 0
 469    corresponding to an invalid signature.
 470
 471    \return 0 Returned upon successfully performing the signature
 472    verification and authentication.
 473    \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to
 474    NULL, or if the siglen does not match the actual length of a signature.
 475    \return SIG_VERIFY_E Returned if verification completes, but the signature
 476    generated does not match the signature provided.
 477
 478    \param [in] sig Pointer to the buffer containing the signature to verify.
 479    \param [in] siglen Length of the signature to verify.
 480    \param [in] msg Pointer to the buffer containing the message to verify.
 481    \param [in] msgLen Length of the message to verify.
 482    \param [out] ret Pointer to the result of the verification. 1 indicates the
 483    message was successfully verified.
 484    \param [in] key Pointer to a public Ed25519 key with which to verify the
 485    signature.
 486    \param [in] context Pointer to the buffer containing the context for which
 487    the message was signed.
 488    \param [in] contextLen Length of the context buffer.
 489
 490    _Example_
 491    \code
 492    ed25519_key key;
 493    int ret, verified = 0;
 494
 495    byte sig[] { initialize with received signature };
 496    byte msg[] = { initialize with message };
 497    byte context[] = { initialize with context of signature };
 498    // initialize key with received public key
 499    ret = wc_ed25519ph_verify_msg(sig, sizeof(sig), msg, sizeof(msg),
 500            &verified, &key, context, sizeof(context));
 501    if (ret < 0) {
 502        // error performing verification
 503    } else if (verified == 0)
 504        // the signature is invalid
 505    }
 506    \endcode
 507
 508    \sa wc_ed25519_verify_msg
 509    \sa wc_ed25519ctx_verify_msg
 510    \sa wc_ed25519ph_verify_hash
 511    \sa wc_ed25519_sign_msg
 512*/
 513
 514int wc_ed25519ph_verify_msg(const byte* sig, word32 siglen, const byte* msg,
 515                            word32 msgLen, int* ret, ed25519_key* key,
 516                            const byte* context, byte contextLen);
 517
 518/*!
 519    \ingroup ED25519
 520
 521    \brief This function initializes an ed25519_key object for future use
 522    with message verification.
 523
 524    \return 0 Returned upon successfully initializing the ed25519_key object.
 525    \return BAD_FUNC_ARG Returned if key is NULL.
 526
 527    \param [in,out] key Pointer to the ed25519_key object to initialize.
 528
 529    _Example_
 530    \code
 531    ed25519_key key;
 532    wc_ed25519_init(&key);
 533    \endcode
 534
 535    \sa wc_ed25519_make_key
 536    \sa wc_ed25519_free
 537*/
 538
 539int wc_ed25519_init(ed25519_key* key);
 540
 541/*!
 542    \ingroup ED25519
 543
 544    \brief This function frees an Ed25519 object after it has been used.
 545
 546    \param [in,out] key Pointer to the ed25519_key object to free
 547
 548    _Example_
 549    \code
 550    ed25519_key key;
 551    // initialize key and perform secure exchanges
 552    ...
 553    wc_ed25519_free(&key);
 554    \endcode
 555
 556    \sa wc_ed25519_init
 557*/
 558
 559void wc_ed25519_free(ed25519_key* key);
 560
 561/*!
 562    \ingroup ED25519
 563
 564    \brief This function imports a public ed25519_key from a buffer
 565    containing the public key. This function will handle both compressed and
 566    uncompressed keys. The public key is checked that it matches the private
 567    key when one is present.
 568
 569    \return 0 Returned on successfully importing the ed25519_key.
 570    \return BAD_FUNC_ARG Returned if in or key evaluate to NULL, or inLen is
 571    less than the size of an Ed25519 key.
 572
 573    \param [in] in Pointer to the buffer containing the public key.
 574    \param [in] inLen Length of the buffer containing the public key.
 575    \param [in,out] key Pointer to the ed25519_key object in which to store the
 576    public key.
 577
 578    _Example_
 579    \code
 580    int ret;
 581    byte pub[] = { initialize Ed25519 public key };
 582
 583    ed_25519 key;
 584    wc_ed25519_init_key(&key);
 585    ret = wc_ed25519_import_public(pub, sizeof(pub), &key);
 586    if (ret != 0) {
 587        // error importing key
 588    }
 589    \endcode
 590
 591    \sa wc_ed25519_import_public_ex
 592    \sa wc_ed25519_import_private_key
 593    \sa wc_ed25519_import_private_key_ex
 594    \sa wc_ed25519_export_public
 595*/
 596
 597int wc_ed25519_import_public(const byte* in, word32 inLen, ed25519_key* key);
 598
 599/*!
 600    \ingroup ED25519
 601
 602    \brief This function imports a public ed25519_key from a buffer
 603    containing the public key. This function will handle both compressed and
 604    uncompressed keys. Check public key matches private key, when present,
 605    when not trusted.
 606
 607    \return 0 Returned on successfully importing the ed25519_key.
 608    \return BAD_FUNC_ARG Returned if in or key evaluate to NULL, or inLen is
 609    less than the size of an Ed25519 key.
 610
 611    \param [in] in Pointer to the buffer containing the public key.
 612    \param [in] inLen Length of the buffer containing the public key.
 613    \param [in,out] key Pointer to the ed25519_key object in which to store the
 614    public key.
 615    \param [in] trusted Public key data is trusted or not.
 616
 617    _Example_
 618    \code
 619    int ret;
 620    byte pub[] = { initialize Ed25519 public key };
 621
 622    ed_25519 key;
 623    wc_ed25519_init_key(&key);
 624    ret = wc_ed25519_import_public_ex(pub, sizeof(pub), &key, 1);
 625    if (ret != 0) {
 626        // error importing key
 627    }
 628    \endcode
 629
 630    \sa wc_ed25519_import_public
 631    \sa wc_ed25519_import_private_key
 632    \sa wc_ed25519_import_private_key_ex
 633    \sa wc_ed25519_export_public
 634*/
 635
 636int wc_ed25519_import_public_ex(const byte* in, word32 inLen, ed25519_key* key,
 637    int trusted);
 638
 639/*!
 640    \ingroup ED25519
 641
 642    \brief This function imports an Ed25519 private key only from a
 643    buffer.
 644
 645    \return 0 Returned on successfully importing the Ed25519 key.
 646    \return BAD_FUNC_ARG Returned if priv or key evaluate to NULL, or if
 647    privSz is not equal to ED25519_KEY_SIZE.
 648
 649    \param [in] priv Pointer to the buffer containing the private key.
 650    \param [in] privSz Length of the private key.
 651    \param [in,out] key Pointer to the ed25519_key object in which to store the
 652    imported private key.
 653
 654    _Example_
 655    \code
 656    int ret;
 657    byte priv[] = { initialize with 32 byte private key };
 658
 659    ed25519_key key;
 660    wc_ed25519_init_key(&key);
 661    ret = wc_ed25519_import_private_only(priv, sizeof(priv), &key);
 662    if (ret != 0) {
 663        // error importing private key
 664    }
 665    \endcode
 666
 667    \sa wc_ed25519_import_public
 668    \sa wc_ed25519_import_public_ex
 669    \sa wc_ed25519_import_private_key
 670    \sa wc_ed25519_import_private_key_ex
 671    \sa wc_ed25519_export_private_only
 672*/
 673
 674int wc_ed25519_import_private_only(const byte* priv, word32 privSz,
 675                                   ed25519_key* key);
 676
 677/*!
 678    \ingroup ED25519
 679
 680    \brief This function imports a public/private Ed25519 key pair from a
 681    pair of buffers. This function will handle both compressed and
 682    uncompressed keys. The public key is assumed to be untrusted and is
 683    checked against the private key.
 684
 685    \return 0 Returned on successfully importing the ed25519_key.
 686    \return BAD_FUNC_ARG Returned if priv or key evaluate to NULL; or if
 687    either privSz is not equal to ED25519_KEY_SIZE nor ED25519_PRV_KEY_SIZE, or
 688    pubSz is less than ED25519_PUB_KEY_SIZE.
 689
 690    \param [in] priv Pointer to the buffer containing the private key.
 691    \param [in] privSz Length of the private key.
 692    \param [in] pub Pointer to the buffer containing the public key.
 693    \param [in] pubSz Length of the public key.
 694    \param [in,out] key Pointer to the ed25519_key object in which to store the
 695    imported private/public key pair.
 696
 697    _Example_
 698    \code
 699    int ret;
 700    byte priv[] = { initialize with 32 byte private key };
 701    byte pub[]  = { initialize with the corresponding public key };
 702
 703    ed25519_key key;
 704    wc_ed25519_init_key(&key);
 705    ret = wc_ed25519_import_private_key(priv, sizeof(priv), pub, sizeof(pub),
 706            &key);
 707    if (ret != 0) {
 708        // error importing key
 709    }
 710    \endcode
 711
 712    \sa wc_ed25519_import_public
 713    \sa wc_ed25519_import_public_ex
 714    \sa wc_ed25519_import_private_only
 715    \sa wc_ed25519_import_private_key_ex
 716    \sa wc_ed25519_export_private
 717*/
 718
 719int wc_ed25519_import_private_key(const byte* priv, word32 privSz,
 720                               const byte* pub, word32 pubSz, ed25519_key* key);
 721
 722/*!
 723    \ingroup ED25519
 724
 725    \brief This function imports a public/private Ed25519 key pair from a
 726    pair of buffers. This function will handle both compressed and
 727    uncompressed keys. The public is checked against private key if not trusted.
 728
 729    \return 0 Returned on successfully importing the ed25519_key.
 730    \return BAD_FUNC_ARG Returned if priv or key evaluate to NULL; or if
 731    either privSz is not equal to ED25519_KEY_SIZE nor ED25519_PRV_KEY_SIZE, or
 732    pubSz is less than ED25519_PUB_KEY_SIZE.
 733
 734    \param [in] priv Pointer to the buffer containing the private key.
 735    \param [in] privSz Length of the private key.
 736    \param [in] pub Pointer to the buffer containing the public key.
 737    \param [in] pubSz Length of the public key.
 738    \param [in,out] key Pointer to the ed25519_key object in which to store the
 739    imported private/public key pair.
 740    \param [in] trusted Public key data is trusted or not.
 741
 742    _Example_
 743    \code
 744    int ret;
 745    byte priv[] = { initialize with 32 byte private key };
 746    byte pub[]  = { initialize with the corresponding public key };
 747
 748    ed25519_key key;
 749    wc_ed25519_init_key(&key);
 750    ret = wc_ed25519_import_private_key_ex(priv, sizeof(priv), pub, sizeof(pub),
 751            &key, 1);
 752    if (ret != 0) {
 753        // error importing key
 754    }
 755    \endcode
 756
 757    \sa wc_ed25519_import_public
 758    \sa wc_ed25519_import_public_ex
 759    \sa wc_ed25519_import_private_only
 760    \sa wc_ed25519_import_private_key
 761    \sa wc_ed25519_export_private
 762*/
 763
 764int wc_ed25519_import_private_key_ex(const byte* priv, word32 privSz,
 765    const byte* pub, word32 pubSz, ed25519_key* key, int trusted);
 766
 767/*!
 768    \ingroup ED25519
 769
 770    \brief This function exports the public key from an ed25519_key
 771    structure. It stores the public key in the buffer out, and sets the bytes
 772    written to this buffer in outLen.
 773
 774    \return 0 Returned upon successfully exporting the public key.
 775    \return BAD_FUNC_ARG Returned if any of the input values evaluate to NULL.
 776    \return BUFFER_E Returned if the buffer provided is not large enough to
 777    store the public key. Upon returning this error, the function sets the
 778    size required in outLen.
 779
 780    \param [in] key Pointer to an ed25519_key structure from which to export the
 781    public key.
 782    \param [out] out Pointer to the buffer in which to store the public key.
 783    \param [in,out] outLen Pointer to a word32 object with the size available
 784    in out. Set with the number of bytes written to out after successfully
 785    exporting the public key.
 786
 787    _Example_
 788    \code
 789    int ret;
 790    ed25519_key key;
 791    // initialize key, make key
 792
 793    char pub[32];
 794    word32 pubSz = sizeof(pub);
 795
 796    ret = wc_ed25519_export_public(&key, pub, &pubSz);
 797    if (ret != 0) {
 798        // error exporting public key
 799    }
 800    \endcode
 801
 802    \sa wc_ed25519_import_public
 803    \sa wc_ed25519_import_public_ex
 804    \sa wc_ed25519_export_private
 805    \sa wc_ed25519_export_private_only
 806*/
 807
 808int wc_ed25519_export_public(const ed25519_key* key, byte* out, word32* outLen);
 809
 810/*!
 811    \ingroup ED25519
 812
 813    \brief This function exports only the private key from an ed25519_key
 814    structure. It stores the private key in the buffer out, and sets
 815    the bytes written to this buffer in outLen.
 816
 817    \return 0 Returned upon successfully exporting the private key.
 818    \return BAD_FUNC_ARG Returned if any of the input values evaluate to NULL.
 819    \return BUFFER_E Returned if the buffer provided is not large enough
 820    to store the private key.
 821
 822    \param [in] key Pointer to an ed25519_key structure from which to export
 823    the private key.
 824    \param [out] out Pointer to the buffer in which to store the private key.
 825    \param [in,out] outLen Pointer to a word32 object with the size available in
 826    out. Set with the number of bytes written to out after successfully
 827    exporting the private key.
 828
 829    _Example_
 830    \code
 831    int ret;
 832    ed25519_key key;
 833    // initialize key, make key
 834
 835    char priv[32]; // 32 bytes because only private key
 836    word32 privSz = sizeof(priv);
 837    ret = wc_ed25519_export_private_only(&key, priv, &privSz);
 838    if (ret != 0) {
 839        // error exporting private key
 840    }
 841    \endcode
 842
 843    \sa wc_ed25519_export_public
 844    \sa wc_ed25519_export_private
 845    \sa wc_ed25519_import_private_key
 846    \sa wc_ed25519_import_private_key_ex
 847*/
 848
 849int wc_ed25519_export_private_only(const ed25519_key* key, byte* out, word32* outLen);
 850
 851/*!
 852    \ingroup ED25519
 853
 854    \brief This function exports the key pair from an ed25519_key
 855    structure. It stores the key pair in the buffer out, and sets
 856    the bytes written to this buffer in outLen.
 857
 858    \return 0 Returned upon successfully exporting the key pair.
 859    \return BAD_FUNC_ARG Returned if any of the input values evaluate to NULL.
 860    \return BUFFER_E Returned if the buffer provided is not large enough
 861    to store the key pair.
 862
 863    \param [in] key Pointer to an ed25519_key structure from which to export
 864    the key pair.
 865    \param [out] out Pointer to the buffer in which to store the key pair.
 866    \param [in,out] outLen Pointer to a word32 object with the size available in
 867    out. Set with the number of bytes written to out after successfully
 868    exporting the key pair.
 869
 870    _Example_
 871    \code
 872    ed25519_key key;
 873    wc_ed25519_init(&key);
 874
 875    WC_RNG rng;
 876    wc_InitRng(&rng);
 877
 878    wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte Ed25519 key
 879
 880    byte out[64]; // out needs to be a sufficient buffer size
 881    word32 outLen = sizeof(out);
 882    int key_size = wc_ed25519_export_private(&key, out, &outLen);
 883    if (key_size == BUFFER_E) {
 884        // Check size of out compared to outLen to see if function reset outLen
 885    }
 886    \endcode
 887
 888    \sa wc_ed25519_import_private_key
 889    \sa wc_ed25519_import_private_key_ex
 890    \sa wc_ed25519_export_private_only
 891*/
 892
 893int wc_ed25519_export_private(const ed25519_key* key, byte* out, word32* outLen);
 894
 895/*!
 896    \ingroup ED25519
 897
 898    \brief This function exports the private and public key separately from an
 899    ed25519_key structure. It stores the private key in the buffer priv, and
 900    sets the bytes written to this buffer in privSz. It stores the public key
 901    in the buffer pub, and sets the bytes written to this buffer in pubSz.
 902
 903    \return 0 Returned upon successfully exporting the key pair.
 904    \return BAD_FUNC_ARG Returned if any of the input values evaluate to NULL.
 905    \return BUFFER_E Returned if the buffer provided is not large enough
 906    to store the key pair.
 907
 908    \param [in] key Pointer to an ed25519_key structure from which to export
 909    the key pair.
 910    \param [out] priv Pointer to the buffer in which to store the private key.
 911    \param [in,out] privSz Pointer to a word32 object with the size available in
 912    out. Set with the number of bytes written to out after successfully
 913    exporting the private key.
 914    \param [out] pub Pointer to the buffer in which to store the public key.
 915    \param [in,out] pubSz Pointer to a word32 object with the size available in
 916    out. Set with the number of bytes written to out after successfully
 917    exporting the public key.
 918
 919    _Example_
 920    \code
 921    int ret;
 922    ed25519_key key;
 923    // initialize key, make key
 924
 925    char pub[32];
 926    word32 pubSz = sizeof(pub);
 927    char priv[32];
 928    word32 privSz = sizeof(priv);
 929
 930    ret = wc_ed25519_export_key(&key, priv, &pubSz, pub, &pubSz);
 931    if (ret != 0) {
 932        // error exporting public key
 933    }
 934    \endcode
 935
 936    \sa wc_ed25519_export_private
 937    \sa wc_ed25519_export_public
 938*/
 939
 940int wc_ed25519_export_key(const ed25519_key* key,
 941                          byte* priv, word32 *privSz,
 942                          byte* pub, word32 *pubSz);
 943
 944/*!
 945    \ingroup ED25519
 946
 947    \brief This function checks the public key in ed25519_key structure matches
 948    the private key.
 949
 950    \return 0 Returned if the private and public key matched.
 951    \return BAD_FUNC_ARG Returned if the given key is NULL.
 952    \return PUBLIC_KEY_E Returned if the no public key available or is invalid.
 953
 954    \param [in] key Pointer to an ed25519_key structure holding a private and
 955    public key.
 956
 957    _Example_
 958    \code
 959    int ret;
 960    byte priv[] = { initialize with 57 byte private key };
 961    byte pub[]  = { initialize with the corresponding public key };
 962
 963    ed25519_key key;
 964    wc_ed25519_init_key(&key);
 965    wc_ed25519_import_private_key_ex(priv, sizeof(priv), pub, sizeof(pub), &key,
 966        1);
 967    ret = wc_ed25519_check_key(&key);
 968    if (ret != 0) {
 969        // error checking key
 970    }
 971    \endcode
 972
 973    \sa wc_ed25519_import_private_key
 974    \sa wc_ed25519_import_private_key_ex
 975*/
 976
 977int wc_ed25519_check_key(ed25519_key* key);
 978
 979/*!
 980    \ingroup ED25519
 981
 982    \brief This function returns the size of an Ed25519 - 32 bytes.
 983
 984    \return ED25519_KEY_SIZE The size of a valid private key (32 bytes).
 985    \return BAD_FUNC_ARG Returned if the given key is NULL.
 986
 987    \param [in] key Pointer to an ed25519_key structure for which to get the
 988    key size.
 989
 990    _Example_
 991    \code
 992    int keySz;
 993    ed25519_key key;
 994    // initialize key, make key
 995    keySz = wc_ed25519_size(&key);
 996    if (keySz == 0) {
 997        // error determining key size
 998    }
 999    \endcode
1000
1001    \sa wc_ed25519_make_key
1002*/
1003
1004int wc_ed25519_size(const ed25519_key* key);
1005
1006/*!
1007    \ingroup ED25519
1008
1009    \brief This function returns the private key size (secret + public) in
1010    bytes.
1011
1012    \return ED25519_PRV_KEY_SIZE The size of the private key (64 bytes).
1013    \return BAD_FUNC_ARG Returned if key argument is NULL.
1014
1015    \param [in] key Pointer to an ed25519_key structure for which to get the
1016    key size.
1017
1018    _Example_
1019    \code
1020    ed25519_key key;
1021    wc_ed25519_init(&key);
1022
1023    WC_RNG rng;
1024    wc_InitRng(&rng);
1025
1026    wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte Ed25519 key
1027    int key_size = wc_ed25519_priv_size(&key);
1028    \endcode
1029
1030    \sa wc_ed25519_pub_size
1031*/
1032
1033int wc_ed25519_priv_size(const ed25519_key* key);
1034
1035/*!
1036    \ingroup ED25519
1037
1038    \brief This function returns the compressed key size in bytes (public key).
1039
1040    \return ED25519_PUB_KEY_SIZE The size of the compressed public key
1041    (32 bytes).
1042    \return BAD_FUNC_ARG Returns if key argument is NULL.
1043
1044    \param [in] key Pointer to an ed25519_key structure for which to get the
1045    key size.
1046
1047    _Example_
1048    \code
1049    ed25519_key key;
1050    wc_ed25519_init(&key);
1051    WC_RNG rng;
1052    wc_InitRng(&rng);
1053
1054    wc_ed25519_make_key(&rng, 32, &key); // initialize 32 byte Ed25519 key
1055    int key_size = wc_ed25519_pub_size(&key);
1056    \endcode
1057
1058    \sa wc_ed25519_priv_size
1059*/
1060
1061int wc_ed25519_pub_size(const ed25519_key* key);
1062
1063/*!
1064    \ingroup ED25519
1065
1066    \brief This function returns the size of an Ed25519 signature (64 in bytes).
1067
1068    \return ED25519_SIG_SIZE The size of an Ed25519 signature (64 bytes).
1069    \return BAD_FUNC_ARG Returns if key argument is NULL.
1070
1071    \param [in] key Pointer to an ed25519_key structure for which to get the
1072    signature size.
1073
1074    _Example_
1075    \code
1076    int sigSz;
1077    ed25519_key key;
1078    // initialize key, make key
1079
1080    sigSz = wc_ed25519_sig_size(&key);
1081    if (sigSz == 0) {
1082        // error determining sig size
1083    }
1084    \endcode
1085
1086    \sa wc_ed25519_sign_msg
1087*/
1088
1089int wc_ed25519_sig_size(const ed25519_key* key);
1090/*!
1091    \ingroup ED25519
1092    \brief Signs message with extended parameters.
1093
1094    \return 0 on success
1095    \return negative on failure
1096
1097    \param in Input message
1098    \param inLen Input message length
1099    \param out Output signature buffer
1100    \param outLen Output signature length pointer
1101    \param key Ed25519 key
1102    \param type Signature type
1103    \param context Context buffer
1104    \param contextLen Context length
1105
1106    _Example_
1107    \code
1108    byte msg[] = "message";
1109    byte sig[ED25519_SIG_SIZE];
1110    word32 sigLen = sizeof(sig);
1111    int ret = wc_ed25519_sign_msg_ex(msg, sizeof(msg), sig, &sigLen,
1112                                     &key, Ed25519, NULL, 0);
1113    \endcode
1114
1115    \sa wc_ed25519_sign_msg
1116*/
1117int wc_ed25519_sign_msg_ex(const byte* in, word32 inLen, byte* out,
1118    word32 *outLen, ed25519_key* key, byte type, const byte* context,
1119    byte contextLen);
1120
1121/*!
1122    \ingroup ED25519
1123    \brief Verifies signature with extended parameters.
1124
1125    \return 0 on success
1126    \return negative on failure
1127
1128    \param sig Signature buffer
1129    \param sigLen Signature length
1130    \param msg Message buffer
1131    \param msgLen Message length
1132    \param res Verification result pointer
1133    \param key Ed25519 key
1134    \param type Signature type
1135    \param context Context buffer
1136    \param contextLen Context length
1137
1138    _Example_
1139    \code
1140    byte msg[] = "message";
1141    byte sig[ED25519_SIG_SIZE];
1142    int res;
1143    int ret = wc_ed25519_verify_msg_ex(sig, sizeof(sig), msg,
1144                                       sizeof(msg), &res, &key,
1145                                       Ed25519, NULL, 0);
1146    \endcode
1147
1148    \sa wc_ed25519_verify_msg
1149*/
1150int wc_ed25519_verify_msg_ex(const byte* sig, word32 sigLen,
1151    const byte* msg, word32 msgLen, int* res, ed25519_key* key,
1152    byte type, const byte* context, byte contextLen);
1153
1154/*!
1155    \ingroup ED25519
1156    \brief Initializes streaming verification.
1157
1158    \return 0 on success
1159    \return negative on failure
1160
1161    \param sig Signature buffer
1162    \param sigLen Signature length
1163    \param key Ed25519 key
1164    \param type Signature type
1165    \param context Context buffer
1166    \param contextLen Context length
1167
1168    _Example_
1169    \code
1170    byte sig[ED25519_SIG_SIZE];
1171    int ret = wc_ed25519_verify_msg_init(sig, sizeof(sig), &key,
1172                                         Ed25519, NULL, 0);
1173    \endcode
1174
1175    \sa wc_ed25519_verify_msg_update
1176    \sa wc_ed25519_verify_msg_final
1177*/
1178int wc_ed25519_verify_msg_init(const byte* sig, word32 sigLen,
1179    ed25519_key* key, byte type, const byte* context,
1180    byte contextLen);
1181
1182/*!
1183    \ingroup ED25519
1184    \brief Updates streaming verification with message segment.
1185
1186    \return 0 on success
1187    \return negative on failure
1188
1189    \param msgSegment Message segment buffer
1190    \param msgSegmentLen Message segment length
1191    \param key Ed25519 key
1192
1193    _Example_
1194    \code
1195    byte msgPart[] = "part";
1196    int ret = wc_ed25519_verify_msg_update(msgPart, sizeof(msgPart),
1197                                           &key);
1198    \endcode
1199
1200    \sa wc_ed25519_verify_msg_init
1201    \sa wc_ed25519_verify_msg_final
1202*/
1203int wc_ed25519_verify_msg_update(const byte* msgSegment,
1204    word32 msgSegmentLen, ed25519_key* key);
1205
1206/*!
1207    \ingroup ED25519
1208    \brief Finalizes streaming verification.
1209
1210    \return 0 on success
1211    \return negative on failure
1212
1213    \param sig Signature buffer
1214    \param sigLen Signature length
1215    \param res Verification result pointer
1216    \param key Ed25519 key
1217
1218    _Example_
1219    \code
1220    byte sig[ED25519_SIG_SIZE];
1221    int res;
1222    int ret = wc_ed25519_verify_msg_final(sig, sizeof(sig), &res,
1223                                          &key);
1224    \endcode
1225
1226    \sa wc_ed25519_verify_msg_init
1227    \sa wc_ed25519_verify_msg_update
1228*/
1229int wc_ed25519_verify_msg_final(const byte* sig, word32 sigLen,
1230    int* res, ed25519_key* key);
1231
1232/*!
1233    \ingroup ED25519
1234    \brief Initializes Ed25519 key with extended parameters.
1235
1236    \return 0 on success
1237    \return negative on failure
1238
1239    \param key Ed25519 key structure
1240    \param heap Heap hint for memory allocation
1241    \param devId Device ID for hardware acceleration
1242
1243    _Example_
1244    \code
1245    ed25519_key key;
1246    int ret = wc_ed25519_init_ex(&key, NULL, INVALID_DEVID);
1247    \endcode
1248
1249    \sa wc_ed25519_init
1250*/
1251int wc_ed25519_init_ex(ed25519_key* key, void* heap, int devId);
1252
1253/*!
1254    \ingroup ED25519
1255    \brief Allocates and initializes new Ed25519 key. These New/Delete
1256    functions are exposed to support allocation of the structure using
1257    dynamic memory to provide better ABI compatibility.
1258
1259    \note This API is only available when WC_NO_CONSTRUCTORS is not defined.
1260    WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is
1261    defined.
1262
1263    \return ed25519_key pointer on success
1264    \return NULL on failure
1265
1266    \param heap Heap hint for memory allocation
1267    \param devId Device ID for hardware acceleration
1268    \param result_code Result code pointer
1269
1270    _Example_
1271    \code
1272    int result;
1273    ed25519_key* key = wc_ed25519_new(NULL, INVALID_DEVID, &result);
1274    \endcode
1275
1276    \sa wc_ed25519_delete
1277*/
1278ed25519_key* wc_ed25519_new(void* heap, int devId, int *result_code);
1279
1280/*!
1281    \ingroup ED25519
1282    \brief Frees and deletes Ed25519 key. These New/Delete functions are
1283    exposed to support allocation of the structure using dynamic memory
1284    to provide better ABI compatibility.
1285
1286    \note This API is only available when WC_NO_CONSTRUCTORS is not defined.
1287    WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is
1288    defined.
1289
1290    \return 0 on success
1291    \return negative on failure
1292
1293    \param key Ed25519 key to delete
1294    \param key_p Pointer to key pointer (set to NULL after delete)
1295
1296    _Example_
1297    \code
1298    ed25519_key* key = wc_ed25519_new(NULL, INVALID_DEVID, NULL);
1299    int ret = wc_ed25519_delete(key, &key);
1300    \endcode
1301
1302    \sa wc_ed25519_new
1303*/
1304int wc_ed25519_delete(ed25519_key* key, ed25519_key** key_p);