luna - wolfssl/doc/dox_comments/header

   1/*!
   2    \ingroup Diffie-Hellman
   3
   4    \brief This function initializes a Diffie-Hellman key for use in
   5    negotiating a secure secret key with the Diffie-Hellman exchange protocol.
   6
   7    \return none No returns.
   8
   9    \param key pointer to the DhKey structure to initialize for use with
  10    secure key exchanges
  11
  12    _Example_
  13    \code
  14    DhKey key;
  15    wc_InitDhKey(&key); // initialize DH key
  16    \endcode
  17
  18    \sa wc_FreeDhKey
  19    \sa wc_DhGenerateKeyPair
  20*/
  21int wc_InitDhKey(DhKey* key);
  22
  23/*!
  24    \ingroup Diffie-Hellman
  25
  26    \brief This function frees a Diffie-Hellman key after it has been used to
  27    negotiate a secure secret key with the Diffie-Hellman exchange protocol.
  28
  29    \return none No returns.
  30
  31    \param key pointer to the DhKey structure to free
  32
  33    _Example_
  34    \code
  35    DhKey key;
  36    // initialize key, perform key exchange
  37
  38    wc_FreeDhKey(&key); // free DH key to avoid memory leaks
  39    \endcode
  40
  41    \sa wc_InitDhKey
  42*/
  43int wc_FreeDhKey(DhKey* key);
  44
  45/*!
  46    \ingroup Diffie-Hellman
  47
  48    \brief This function generates a public/private key pair based on the
  49    Diffie-Hellman public parameters, storing the private key in priv and the
  50    public key in pub. It takes an initialized Diffie-Hellman key and an
  51    initialized rng structure.
  52
  53    \return BAD_FUNC_ARG Returned if there is an error parsing one of the
  54    inputs to this function
  55    \return RNG_FAILURE_E Returned if there is an error generating a random
  56    number using rng
  57    \return MP_INIT_E May be returned if there is an error in the math library
  58    while generating the public key
  59    \return MP_READ_E May be returned if there is an error in the math library
  60    while generating the public key
  61    \return MP_EXPTMOD_E May be returned if there is an error in the math
  62    library while generating the public key
  63    \return MP_TO_E May be returned if there is an error in the math library
  64    while generating the public key
  65
  66    \param key pointer to the DhKey structure from which to generate
  67    the key pair
  68    \param rng pointer to an initialized random number generator (rng) with
  69    which to generate the keys
  70    \param priv pointer to a buffer in which to store the private key
  71    \param privSz will store the size of the private key written to priv
  72    \param pub pointer to a buffer in which to store the public key
  73    \param pubSz will store the size of the private key written to pub
  74
  75    _Example_
  76    \code
  77    DhKey key;
  78    int ret;
  79    byte priv[256];
  80    byte pub[256];
  81    word32 privSz, pubSz;
  82
  83    wc_InitDhKey(&key); // initialize key
  84    // Set DH parameters using wc_DhSetKey or wc_DhKeyDecode
  85    WC_RNG rng;
  86    wc_InitRng(&rng); // initialize rng
  87    ret = wc_DhGenerateKeyPair(&key, &rng, priv, &privSz, pub, &pubSz);
  88    \endcode
  89
  90    \sa wc_InitDhKey
  91    \sa wc_DhSetKey
  92    \sa wc_DhKeyDecode
  93*/
  94int wc_DhGenerateKeyPair(DhKey* key, WC_RNG* rng, byte* priv,
  95                                 word32* privSz, byte* pub, word32* pubSz);
  96
  97/*!
  98    \ingroup Diffie-Hellman
  99
 100    \brief This function generates an agreed upon secret key based on a local
 101    private key and a received public key. If completed on both sides of an
 102    exchange, this function generates an agreed upon secret key for symmetric
 103    communication. On successfully generating a shared secret key, the size of
 104    the secret key written will be stored in agreeSz.
 105
 106    \return 0 Returned on successfully generating an agreed upon secret key
 107    \return MP_INIT_E May be returned if there is an error while generating
 108    the shared secret key
 109    \return MP_READ_E May be returned if there is an error while generating
 110    the shared secret key
 111    \return MP_EXPTMOD_E May be returned if there is an error while generating
 112    the shared secret key
 113    \return MP_TO_E May be returned if there is an error while generating the
 114    shared secret key
 115
 116    \param key pointer to the DhKey structure to use to compute the shared key
 117    \param agree pointer to the buffer in which to store the secret key
 118    \param agreeSz will hold the size of the secret key after
 119    successful generation
 120    \param priv pointer to the buffer containing the local secret key
 121    \param privSz size of the local secret key
 122    \param otherPub pointer to a buffer containing the received public key
 123    \param pubSz size of the received public key
 124
 125    _Example_
 126    \code
 127    DhKey key;
 128    int ret;
 129    byte priv[256];
 130    byte agree[256];
 131    word32 agreeSz;
 132
 133    // initialize key, set key prime and base
 134    // wc_DhGenerateKeyPair -- store private key in priv
 135    byte pub[] = { // initialized with the received public key };
 136    ret = wc_DhAgree(&key, agree, &agreeSz, priv, sizeof(priv), pub,
 137    sizeof(pub));
 138    if ( ret != 0 ) {
 139    	// error generating shared key
 140    }
 141    \endcode
 142
 143    \sa wc_DhGenerateKeyPair
 144*/
 145int wc_DhAgree(DhKey* key, byte* agree, word32* agreeSz,
 146                       const byte* priv, word32 privSz, const byte* otherPub,
 147                       word32 pubSz);
 148
 149/*!
 150    \ingroup Diffie-Hellman
 151
 152    \brief This function decodes a Diffie-Hellman key from the given input
 153    buffer containing the key in DER format. It stores the result in the
 154    DhKey structure.
 155
 156    \return 0 Returned on successfully decoding the input key
 157    \return ASN_PARSE_E Returned if there is an error parsing the sequence
 158    of the input
 159    \return ASN_DH_KEY_E Returned if there is an error reading the private
 160    key parameters from the parsed input
 161
 162    \param input pointer to the buffer containing the DER formatted
 163    Diffie-Hellman key
 164    \param inOutIdx pointer to an integer in which to store the index parsed
 165    to while decoding the key
 166    \param key pointer to the DhKey structure to initialize with the input key
 167    \param inSz length of the input buffer. Gives the max length that may
 168    be read
 169
 170    _Example_
 171    \code
 172    DhKey key;
 173    word32 idx = 0;
 174
 175    byte keyBuff[1024];
 176    // initialize with DER formatted key
 177    wc_DhKeyInit(&key);
 178    ret = wc_DhKeyDecode(keyBuff, &idx, &key, sizeof(keyBuff));
 179
 180    if ( ret != 0 ) {
 181    	// error decoding key
 182    }
 183    \endcode
 184
 185    \sa wc_DhSetKey
 186*/
 187int wc_DhKeyDecode(const byte* input, word32* inOutIdx, DhKey* key,
 188                           word32 inSz);
 189
 190/*!
 191    \ingroup Diffie-Hellman
 192
 193    \brief This function sets the key for a DhKey structure using the input
 194    private key parameters. Unlike wc_DhKeyDecode, this function does not
 195    require that the input key be formatted in DER format, and instead simply
 196    accepts the parsed input parameters p (prime) and g (base).
 197
 198    \return 0 Returned on successfully setting the key
 199    \return BAD_FUNC_ARG Returned if any of the input parameters
 200    evaluate to NULL
 201    \return MP_INIT_E Returned if there is an error initializing the key
 202    parameters for storage
 203    \return ASN_DH_KEY_E Returned if there is an error reading in the
 204    DH key parameters p and g
 205
 206    \param key pointer to the DhKey structure on which to set the key
 207    \param p pointer to the buffer containing the prime for use with the key
 208    \param pSz length of the input prime
 209    \param g pointer to the buffer containing the base for use with the key
 210    \param gSz length of the input base
 211
 212    _Example_
 213    \code
 214    DhKey key;
 215
 216    byte p[] = { // initialize with prime };
 217    byte g[] = { // initialize with base };
 218    wc_DhKeyInit(&key);
 219    ret = wc_DhSetKey(key, p, sizeof(p), g, sizeof(g));
 220
 221    if ( ret != 0 ) {
 222    	// error setting key
 223    }
 224    \endcode
 225
 226    \sa wc_DhKeyDecode
 227*/
 228int wc_DhSetKey(DhKey* key, const byte* p, word32 pSz, const byte* g,
 229                        word32 gSz);
 230
 231/*!
 232    \ingroup Diffie-Hellman
 233
 234    \brief This function loads the Diffie-Hellman parameters, p (prime)
 235    and g (base) out of the given input buffer, DER formatted.
 236
 237    \return 0 Returned on successfully extracting the DH parameters
 238    \return ASN_PARSE_E Returned if an error occurs while parsing the DER
 239    formatted DH certificate
 240    \return BUFFER_E Returned if there is inadequate space in p or g to
 241    store the parsed parameters
 242
 243    \param input pointer to a buffer containing a DER formatted
 244    Diffie-Hellman certificate to parse
 245    \param inSz size of the input buffer
 246    \param p pointer to a buffer in which to store the parsed prime
 247    \param pInOutSz pointer to a word32 object containing the available
 248    size in the p buffer. Will be overwritten with the number of bytes
 249    written to the buffer after completing the function call
 250    \param g pointer to a buffer in which to store the parsed base
 251    \param gInOutSz pointer to a word32 object containing the available size
 252    in the g buffer. Will be overwritten with the number of bytes written to
 253    the buffer after completing the function call
 254
 255    _Example_
 256    \code
 257    byte dhCert[] = { initialize with DER formatted certificate };
 258    byte p[MAX_DH_SIZE];
 259    byte g[MAX_DH_SIZE];
 260    word32 pSz = MAX_DH_SIZE;
 261    word32 gSz = MAX_DH_SIZE;
 262
 263    ret = wc_DhParamsLoad(dhCert, sizeof(dhCert), p, &pSz, g, &gSz);
 264    if ( ret != 0 ) {
 265    	// error parsing inputs
 266    }
 267    \endcode
 268
 269    \sa wc_DhSetKey
 270    \sa wc_DhKeyDecode
 271*/
 272int wc_DhParamsLoad(const byte* input, word32 inSz, byte* p,
 273                            word32* pInOutSz, byte* g, word32* gInOutSz);
 274
 275/*!
 276    \ingroup Diffie-Hellman
 277    \brief Encodes DH parameters to DER format for OpenSSL compatibility.
 278
 279    \return Length of DER encoding on success
 280    \return Negative on error
 281
 282    \param dh DH parameters to encode
 283    \param out Output buffer pointer (if *out is NULL, allocates buffer)
 284
 285    _Example_
 286    \code
 287    WOLFSSL_DH* dh = wolfSSL_DH_new();
 288    unsigned char* der = NULL;
 289    int derSz = wolfSSL_i2d_DHparams(dh, &der);
 290    if (derSz > 0) {
 291        // use der buffer
 292        XFREE(der, NULL, DYNAMIC_TYPE_OPENSSL);
 293    }
 294    \endcode
 295
 296    \sa wolfSSL_DH_new
 297*/
 298int wolfSSL_i2d_DHparams(const WOLFSSL_DH *dh, unsigned char **out);
 299
 300/*!
 301    \ingroup Diffie-Hellman
 302    \brief Allocates and initializes a new DH structure for OpenSSL
 303    compatibility.
 304
 305    \return Pointer to WOLFSSL_DH on success
 306    \return NULL on failure
 307
 308    _Example_
 309    \code
 310    WOLFSSL_DH* dh = wolfSSL_DH_new();
 311    if (dh == NULL) {
 312        // error allocating DH
 313    }
 314    // use dh
 315    wolfSSL_DH_free(dh);
 316    \endcode
 317
 318    \sa wolfSSL_DH_free
 319    \sa wolfSSL_DH_generate_key
 320*/
 321WOLFSSL_DH* wolfSSL_DH_new(void);
 322
 323/*!
 324    \ingroup Diffie-Hellman
 325    \brief Creates a new DH structure with named group parameters.
 326
 327    \return Pointer to WOLFSSL_DH on success
 328    \return NULL on failure
 329
 330    \param nid Named group identifier (e.g., NID_ffdhe2048)
 331
 332    _Example_
 333    \code
 334    WOLFSSL_DH* dh = wolfSSL_DH_new_by_nid(NID_ffdhe2048);
 335    if (dh == NULL) {
 336        // error creating DH with named group
 337    }
 338    \endcode
 339
 340    \sa wolfSSL_DH_new
 341*/
 342WOLFSSL_DH* wolfSSL_DH_new_by_nid(int nid);
 343
 344/*!
 345    \ingroup Diffie-Hellman
 346    \brief Frees a DH structure.
 347
 348    \param dh DH structure to free
 349
 350    _Example_
 351    \code
 352    WOLFSSL_DH* dh = wolfSSL_DH_new();
 353    // use dh
 354    wolfSSL_DH_free(dh);
 355    \endcode
 356
 357    \sa wolfSSL_DH_new
 358*/
 359void wolfSSL_DH_free(WOLFSSL_DH* dh);
 360
 361/*!
 362    \ingroup Diffie-Hellman
 363    \brief Duplicates a DH structure.
 364
 365    \return Pointer to new WOLFSSL_DH on success
 366    \return NULL on failure
 367
 368    \param dh DH structure to duplicate
 369
 370    _Example_
 371    \code
 372    WOLFSSL_DH* dh = wolfSSL_DH_new();
 373    WOLFSSL_DH* dhCopy = wolfSSL_DH_dup(dh);
 374    \endcode
 375
 376    \sa wolfSSL_DH_new
 377*/
 378WOLFSSL_DH* wolfSSL_DH_dup(WOLFSSL_DH* dh);
 379
 380/*!
 381    \ingroup Diffie-Hellman
 382    \brief Increments reference count for DH structure.
 383
 384    \return 1 on success
 385    \return 0 on failure
 386
 387    \param dh DH structure to increment reference
 388
 389    _Example_
 390    \code
 391    WOLFSSL_DH* dh = wolfSSL_DH_new();
 392    int ret = wolfSSL_DH_up_ref(dh);
 393    \endcode
 394
 395    \sa wolfSSL_DH_free
 396*/
 397int wolfSSL_DH_up_ref(WOLFSSL_DH* dh);
 398
 399/*!
 400    \ingroup Diffie-Hellman
 401    \brief Validates DH parameters.
 402
 403    \return 1 on success
 404    \return 0 on failure
 405
 406    \param dh DH parameters to check
 407    \param codes Output for validation error codes
 408
 409    _Example_
 410    \code
 411    WOLFSSL_DH* dh = wolfSSL_DH_new();
 412    int codes;
 413    int ret = wolfSSL_DH_check(dh, &codes);
 414    if (ret != 1 || codes != 0) {
 415        // validation failed
 416    }
 417    \endcode
 418
 419    \sa wolfSSL_DH_generate_key
 420*/
 421int wolfSSL_DH_check(const WOLFSSL_DH *dh, int *codes);
 422
 423/*!
 424    \ingroup Diffie-Hellman
 425    \brief Returns size of DH key in bytes.
 426
 427    \return Key size in bytes on success
 428    \return -1 on failure
 429
 430    \param dh DH structure
 431
 432    _Example_
 433    \code
 434    WOLFSSL_DH* dh = wolfSSL_DH_new();
 435    int size = wolfSSL_DH_size(dh);
 436    \endcode
 437
 438    \sa wolfSSL_DH_new
 439*/
 440int wolfSSL_DH_size(WOLFSSL_DH* dh);
 441
 442/*!
 443    \ingroup Diffie-Hellman
 444    \brief Generates DH public/private key pair.
 445
 446    \return 1 on success
 447    \return 0 on failure
 448
 449    \param dh DH structure with parameters set
 450
 451    _Example_
 452    \code
 453    WOLFSSL_DH* dh = wolfSSL_DH_new();
 454    // set p and g parameters
 455    int ret = wolfSSL_DH_generate_key(dh);
 456    if (ret != 1) {
 457        // key generation failed
 458    }
 459    \endcode
 460
 461    \sa wolfSSL_DH_compute_key
 462*/
 463int wolfSSL_DH_generate_key(WOLFSSL_DH* dh);
 464
 465/*!
 466    \ingroup Diffie-Hellman
 467    \brief Computes shared secret from peer's public key.
 468
 469    \return Length of shared secret on success
 470    \return -1 on failure
 471
 472    \param key Output buffer for shared secret
 473    \param pub Peer's public key
 474    \param dh DH structure with private key
 475
 476    _Example_
 477    \code
 478    WOLFSSL_DH* dh = wolfSSL_DH_new();
 479    wolfSSL_DH_generate_key(dh);
 480    byte secret[256];
 481    WOLFSSL_BIGNUM* peerPub = NULL; // peer's public key
 482    int secretSz = wolfSSL_DH_compute_key(secret, peerPub, dh);
 483    \endcode
 484
 485    \sa wolfSSL_DH_generate_key
 486*/
 487int wolfSSL_DH_compute_key(unsigned char* key,
 488                          const WOLFSSL_BIGNUM* pub, WOLFSSL_DH* dh);
 489
 490/*!
 491    \ingroup Diffie-Hellman
 492    \brief Computes shared secret with zero-padding to DH size.
 493
 494    \return Length of shared secret on success
 495    \return -1 on failure
 496
 497    \param key Output buffer for shared secret
 498    \param otherPub Peer's public key
 499    \param dh DH structure with private key
 500
 501    _Example_
 502    \code
 503    WOLFSSL_DH* dh = wolfSSL_DH_new();
 504    wolfSSL_DH_generate_key(dh);
 505    byte secret[256];
 506    WOLFSSL_BIGNUM* peerPub = NULL;
 507    int secretSz = wolfSSL_DH_compute_key_padded(secret, peerPub, dh);
 508    \endcode
 509
 510    \sa wolfSSL_DH_compute_key
 511*/
 512int wolfSSL_DH_compute_key_padded(unsigned char* key,
 513                                 const WOLFSSL_BIGNUM* otherPub,
 514                                 WOLFSSL_DH* dh);
 515
 516/*!
 517    \ingroup Diffie-Hellman
 518    \brief Loads DH parameters from DER buffer.
 519
 520    \return WOLFSSL_SUCCESS on success
 521    \return WOLFSSL_FAILURE on failure
 522
 523    \param dh DH structure to load into
 524    \param derBuf DER-encoded DH parameters
 525    \param derSz Size of DER buffer
 526
 527    _Example_
 528    \code
 529    WOLFSSL_DH* dh = wolfSSL_DH_new();
 530    byte derBuf[256];
 531    int ret = wolfSSL_DH_LoadDer(dh, derBuf, sizeof(derBuf));
 532    \endcode
 533
 534    \sa wolfSSL_DH_new
 535*/
 536int wolfSSL_DH_LoadDer(WOLFSSL_DH* dh, const unsigned char* derBuf,
 537                      int derSz);
 538
 539/*!
 540    \ingroup Diffie-Hellman
 541    \brief Sets optional private key length.
 542
 543    \return 1 on success
 544    \return 0 on failure
 545
 546    \param dh DH structure
 547    \param len Private key length in bits
 548
 549    _Example_
 550    \code
 551    WOLFSSL_DH* dh = wolfSSL_DH_new();
 552    int ret = wolfSSL_DH_set_length(dh, 256);
 553    \endcode
 554
 555    \sa wolfSSL_DH_generate_key
 556*/
 557int wolfSSL_DH_set_length(WOLFSSL_DH* dh, long len);
 558
 559/*!
 560    \ingroup Diffie-Hellman
 561    \brief Sets DH parameters p, q, and g.
 562
 563    \return 1 on success
 564    \return 0 on failure
 565
 566    \param dh DH structure
 567    \param p Prime modulus (takes ownership)
 568    \param q Subgroup order (takes ownership, can be NULL)
 569    \param g Generator (takes ownership)
 570
 571    _Example_
 572    \code
 573    WOLFSSL_DH* dh = wolfSSL_DH_new();
 574    WOLFSSL_BIGNUM *p = wolfSSL_BN_new();
 575    WOLFSSL_BIGNUM *g = wolfSSL_BN_new();
 576    // set p and g values
 577    int ret = wolfSSL_DH_set0_pqg(dh, p, NULL, g);
 578    \endcode
 579
 580    \sa wolfSSL_DH_generate_key
 581*/
 582int wolfSSL_DH_set0_pqg(WOLFSSL_DH *dh, WOLFSSL_BIGNUM *p,
 583                       WOLFSSL_BIGNUM *q, WOLFSSL_BIGNUM *g);
 584
 585/*!
 586    \ingroup Diffie-Hellman
 587    \brief Returns DH parameters for 2048-bit MODP group with 256-bit
 588    subgroup.
 589
 590    \return Pointer to WOLFSSL_DH on success
 591    \return NULL on failure
 592
 593    _Example_
 594    \code
 595    WOLFSSL_DH* dh = wolfSSL_DH_get_2048_256();
 596    if (dh == NULL) {
 597        // error getting standard group
 598    }
 599    \endcode
 600
 601    \sa wolfSSL_DH_new_by_nid
 602*/
 603WOLFSSL_DH* wolfSSL_DH_get_2048_256(void);
 604
 605/*!
 606    \ingroup Diffie-Hellman
 607    \brief Returns FFDHE 2048-bit group parameters.
 608
 609    \return Pointer to DhParams structure
 610    \return NULL if not compiled with HAVE_FFDHE_2048
 611
 612    _Example_
 613    \code
 614    const DhParams* params = wc_Dh_ffdhe2048_Get();
 615    if (params != NULL) {
 616        // use params
 617    }
 618    \endcode
 619
 620    \sa wc_Dh_ffdhe3072_Get
 621    \sa wc_Dh_ffdhe4096_Get
 622    \sa wc_Dh_ffdhe6144_Get
 623    \sa wc_Dh_ffdhe8192_Get
 624*/
 625const DhParams* wc_Dh_ffdhe2048_Get(void);
 626
 627/*!
 628    \ingroup Diffie-Hellman
 629    \brief Returns FFDHE 3072-bit group parameters.
 630
 631    \return Pointer to DhParams structure
 632    \return NULL if not compiled with HAVE_FFDHE_3072
 633
 634    _Example_
 635    \code
 636    const DhParams* params = wc_Dh_ffdhe3072_Get();
 637    if (params != NULL) {
 638        // use params
 639    }
 640    \endcode
 641
 642    \sa wc_Dh_ffdhe2048_Get
 643    \sa wc_Dh_ffdhe4096_Get
 644    \sa wc_Dh_ffdhe6144_Get
 645    \sa wc_Dh_ffdhe8192_Get
 646*/
 647const DhParams* wc_Dh_ffdhe3072_Get(void);
 648
 649/*!
 650    \ingroup Diffie-Hellman
 651    \brief Returns FFDHE 4096-bit group parameters.
 652
 653    \return Pointer to DhParams structure
 654    \return NULL if not compiled with HAVE_FFDHE_4096
 655
 656    _Example_
 657    \code
 658    const DhParams* params = wc_Dh_ffdhe4096_Get();
 659    if (params != NULL) {
 660        // use params
 661    }
 662    \endcode
 663
 664    \sa wc_Dh_ffdhe2048_Get
 665    \sa wc_Dh_ffdhe3072_Get
 666    \sa wc_Dh_ffdhe6144_Get
 667    \sa wc_Dh_ffdhe8192_Get
 668*/
 669const DhParams* wc_Dh_ffdhe4096_Get(void);
 670
 671/*!
 672    \ingroup Diffie-Hellman
 673    \brief Returns FFDHE 6144-bit group parameters.
 674
 675    \return Pointer to DhParams structure
 676    \return NULL if not compiled with HAVE_FFDHE_6144
 677
 678    _Example_
 679    \code
 680    const DhParams* params = wc_Dh_ffdhe6144_Get();
 681    if (params != NULL) {
 682        // use params
 683    }
 684    \endcode
 685
 686    \sa wc_Dh_ffdhe2048_Get
 687    \sa wc_Dh_ffdhe3072_Get
 688    \sa wc_Dh_ffdhe4096_Get
 689    \sa wc_Dh_ffdhe8192_Get
 690*/
 691const DhParams* wc_Dh_ffdhe6144_Get(void);
 692
 693/*!
 694    \ingroup Diffie-Hellman
 695    \brief Returns FFDHE 8192-bit group parameters.
 696
 697    \return Pointer to DhParams structure
 698    \return NULL if not compiled with HAVE_FFDHE_8192
 699
 700    _Example_
 701    \code
 702    const DhParams* params = wc_Dh_ffdhe8192_Get();
 703    if (params != NULL) {
 704        // use params
 705    }
 706    \endcode
 707
 708    \sa wc_Dh_ffdhe2048_Get
 709    \sa wc_Dh_ffdhe3072_Get
 710    \sa wc_Dh_ffdhe4096_Get
 711    \sa wc_Dh_ffdhe6144_Get
 712*/
 713const DhParams* wc_Dh_ffdhe8192_Get(void);
 714
 715/*!
 716    \ingroup Diffie-Hellman
 717    \brief Initializes DH key with heap hint and device ID.
 718
 719    \return 0 on success
 720    \return BAD_FUNC_ARG if key is NULL
 721
 722    \param key DH key to initialize
 723    \param heap Heap hint for memory allocation
 724    \param devId Device ID for hardware acceleration
 725
 726    _Example_
 727    \code
 728    DhKey key;
 729    int ret = wc_InitDhKey_ex(&key, NULL, INVALID_DEVID);
 730    if (ret != 0) {
 731        // error initializing key
 732    }
 733    \endcode
 734
 735    \sa wc_InitDhKey
 736    \sa wc_FreeDhKey
 737*/
 738int wc_InitDhKey_ex(DhKey* key, void* heap, int devId);
 739
 740/*!
 741    \ingroup Diffie-Hellman
 742    \brief Computes shared secret with constant-time operations.
 743
 744    \return 0 on success
 745    \return BAD_FUNC_ARG if parameters are invalid
 746    \return BUFFER_E if output buffer too small
 747
 748    \param key DH key with parameters
 749    \param agree Output buffer for shared secret
 750    \param agreeSz Input: buffer size, Output: secret size
 751    \param priv Private key
 752    \param privSz Private key size
 753    \param otherPub Peer's public key
 754    \param pubSz Peer's public key size
 755
 756    _Example_
 757    \code
 758    DhKey key;
 759    byte agree[256], priv[256], pub[256];
 760    word32 agreeSz = sizeof(agree);
 761    int ret = wc_DhAgree_ct(&key, agree, &agreeSz, priv,
 762                           sizeof(priv), pub, sizeof(pub));
 763    \endcode
 764
 765    \sa wc_DhAgree
 766*/
 767int wc_DhAgree_ct(DhKey* key, byte* agree, word32 *agreeSz,
 768                 const byte* priv, word32 privSz,
 769                 const byte* otherPub, word32 pubSz);
 770
 771/*!
 772    \ingroup Diffie-Hellman
 773    \brief Sets DH key to use named group parameters.
 774
 775    \return 0 on success
 776    \return BAD_FUNC_ARG if parameters are invalid
 777
 778    \param key DH key to configure
 779    \param name Named group identifier
 780
 781    _Example_
 782    \code
 783    DhKey key;
 784    wc_InitDhKey(&key);
 785    int ret = wc_DhSetNamedKey(&key, WC_FFDHE_2048);
 786    \endcode
 787
 788    \sa wc_DhGetNamedKeyParamSize
 789*/
 790int wc_DhSetNamedKey(DhKey* key, int name);
 791
 792/*!
 793    \ingroup Diffie-Hellman
 794    \brief Gets parameter sizes for named group.
 795
 796    \return 0 on success
 797    \return BAD_FUNC_ARG if parameters are invalid
 798
 799    \param name Named group identifier
 800    \param p Output for prime size
 801    \param g Output for generator size
 802    \param q Output for subgroup order size
 803
 804    _Example_
 805    \code
 806    word32 pSz, gSz, qSz;
 807    int ret = wc_DhGetNamedKeyParamSize(WC_FFDHE_2048, &pSz, &gSz,
 808                                       &qSz);
 809    \endcode
 810
 811    \sa wc_DhSetNamedKey
 812*/
 813int wc_DhGetNamedKeyParamSize(int name, word32* p, word32* g,
 814                              word32* q);
 815
 816/*!
 817    \ingroup Diffie-Hellman
 818    \brief Gets minimum key size for named group.
 819
 820    \return Minimum key size in bits
 821    \return 0 if invalid name
 822
 823    \param name Named group identifier
 824
 825    _Example_
 826    \code
 827    word32 minSize = wc_DhGetNamedKeyMinSize(WC_FFDHE_2048);
 828    \endcode
 829
 830    \sa wc_DhSetNamedKey
 831*/
 832word32 wc_DhGetNamedKeyMinSize(int name);
 833
 834/*!
 835    \ingroup Diffie-Hellman
 836    \brief Compares parameters against named group.
 837
 838    \return 0 if parameters match named group
 839    \return Non-zero if parameters don't match
 840
 841    \param name Named group identifier
 842    \param noQ 1 to skip q comparison
 843    \param p Prime modulus
 844    \param pSz Prime size
 845    \param g Generator
 846    \param gSz Generator size
 847    \param q Subgroup order
 848    \param qSz Subgroup order size
 849
 850    _Example_
 851    \code
 852    byte p[256], g[256];
 853    int ret = wc_DhCmpNamedKey(WC_FFDHE_2048, 1, p, sizeof(p),
 854                              g, sizeof(g), NULL, 0);
 855    \endcode
 856
 857    \sa wc_DhSetNamedKey
 858*/
 859int wc_DhCmpNamedKey(int name, int noQ, const byte* p, word32 pSz,
 860                    const byte* g, word32 gSz, const byte* q,
 861                    word32 qSz);
 862
 863/*!
 864    \ingroup Diffie-Hellman
 865    \brief Copies named group parameters to buffers.
 866
 867    \return 0 on success
 868    \return BAD_FUNC_ARG if parameters are invalid
 869    \return BUFFER_E if buffers too small
 870
 871    \param name Named group identifier
 872    \param p Output buffer for prime
 873    \param pSz Input: buffer size, Output: prime size
 874    \param g Output buffer for generator
 875    \param gSz Input: buffer size, Output: generator size
 876    \param q Output buffer for subgroup order
 877    \param qSz Input: buffer size, Output: subgroup order size
 878
 879    _Example_
 880    \code
 881    byte p[512], g[512], q[512];
 882    word32 pSz = sizeof(p), gSz = sizeof(g), qSz = sizeof(q);
 883    int ret = wc_DhCopyNamedKey(WC_FFDHE_2048, p, &pSz, g, &gSz,
 884                               q, &qSz);
 885    \endcode
 886
 887    \sa wc_DhSetNamedKey
 888*/
 889int wc_DhCopyNamedKey(int name, byte* p, word32* pSz, byte* g,
 890                     word32* gSz, byte* q, word32* qSz);
 891
 892/*!
 893    \ingroup Diffie-Hellman
 894    \brief Generates public key from private key.
 895
 896    \return 0 on success
 897    \return BAD_FUNC_ARG if parameters are invalid
 898
 899    \param key DH key with parameters set
 900    \param priv Private key
 901    \param privSz Private key size
 902    \param pub Output buffer for public key
 903    \param pubSz Input: buffer size, Output: public key size
 904
 905    _Example_
 906    \code
 907    DhKey key;
 908    byte priv[256], pub[256];
 909    word32 pubSz = sizeof(pub);
 910    int ret = wc_DhGeneratePublic(&key, priv, sizeof(priv), pub,
 911                                 &pubSz);
 912    \endcode
 913
 914    \sa wc_DhGenerateKeyPair
 915*/
 916int wc_DhGeneratePublic(DhKey* key, byte* priv, word32 privSz,
 917                       byte* pub, word32* pubSz);
 918
 919/*!
 920    \ingroup Diffie-Hellman
 921    \brief Imports private and/or public key into DH key.
 922
 923    \return 0 on success
 924    \return BAD_FUNC_ARG if parameters are invalid
 925
 926    \param key DH key to import into
 927    \param priv Private key (can be NULL)
 928    \param privSz Private key size
 929    \param pub Public key (can be NULL)
 930    \param pubSz Public key size
 931
 932    _Example_
 933    \code
 934    DhKey key;
 935    byte priv[256], pub[256];
 936    int ret = wc_DhImportKeyPair(&key, priv, sizeof(priv), pub,
 937                                sizeof(pub));
 938    \endcode
 939
 940    \sa wc_DhExportKeyPair
 941*/
 942int wc_DhImportKeyPair(DhKey* key, const byte* priv, word32 privSz,
 943                      const byte* pub, word32 pubSz);
 944
 945/*!
 946    \ingroup Diffie-Hellman
 947    \brief Exports private and public key from DH key.
 948
 949    \return 0 on success
 950    \return BAD_FUNC_ARG if parameters are invalid
 951    \return BUFFER_E if buffers too small
 952
 953    \param key DH key to export from
 954    \param priv Output buffer for private key
 955    \param pPrivSz Input: buffer size, Output: private key size
 956    \param pub Output buffer for public key
 957    \param pPubSz Input: buffer size, Output: public key size
 958
 959    _Example_
 960    \code
 961    DhKey key;
 962    byte priv[256], pub[256];
 963    word32 privSz = sizeof(priv), pubSz = sizeof(pub);
 964    int ret = wc_DhExportKeyPair(&key, priv, &privSz, pub, &pubSz);
 965    \endcode
 966
 967    \sa wc_DhImportKeyPair
 968*/
 969int wc_DhExportKeyPair(DhKey* key, byte* priv, word32* pPrivSz,
 970                      byte* pub, word32* pPubSz);
 971
 972/*!
 973    \ingroup Diffie-Hellman
 974    \brief Validates public key value.
 975
 976    \return 0 if public key is valid
 977    \return BAD_FUNC_ARG if parameters are invalid
 978    \return MP_VAL if public key is invalid
 979
 980    \param prime Prime modulus
 981    \param primeSz Prime size
 982    \param pub Public key to validate
 983    \param pubSz Public key size
 984
 985    _Example_
 986    \code
 987    byte prime[256], pub[256];
 988    int ret = wc_DhCheckPubValue(prime, sizeof(prime), pub,
 989                                 sizeof(pub));
 990    if (ret != 0) {
 991        // invalid public key
 992    }
 993    \endcode
 994
 995    \sa wc_DhCheckPubKey
 996*/
 997int wc_DhCheckPubValue(const byte* prime, word32 primeSz,
 998                      const byte* pub, word32 pubSz);
 999
1000/*!
1001    \ingroup Diffie-Hellman
1002
1003    \brief Checks DH keys for pair-wise consistency per process in SP 800-56Ar3,
1004    section 5.6.2.1.4, method (b) for FFC.
1005*/
1006int wc_DhCheckKeyPair(DhKey* key, const byte* pub, word32 pubSz,
1007                        const byte* priv, word32 privSz);
1008
1009/*!
1010    \ingroup Diffie-Hellman
1011
1012    \brief Check DH private key for invalid numbers
1013*/
1014int wc_DhCheckPrivKey(DhKey* key, const byte* priv, word32 pubSz);
1015
1016/*!
1017    \ingroup Diffie-Hellman
1018*/
1019int wc_DhCheckPrivKey_ex(DhKey* key, const byte* priv, word32 pubSz,
1020                            const byte* prime, word32 primeSz);
1021
1022/*!
1023    \ingroup Diffie-Hellman
1024*/
1025int wc_DhCheckPubKey(DhKey* key, const byte* pub, word32 pubSz);
1026
1027/*!
1028    \ingroup Diffie-Hellman
1029*/
1030int wc_DhCheckPubKey_ex(DhKey* key, const byte* pub, word32 pubSz,
1031                            const byte* prime, word32 primeSz);
1032
1033/*!
1034    \ingroup Diffie-Hellman
1035*/
1036int wc_DhExportParamsRaw(DhKey* dh, byte* p, word32* pSz,
1037                       byte* q, word32* qSz, byte* g, word32* gSz);
1038
1039/*!
1040    \ingroup Diffie-Hellman
1041*/
1042int wc_DhGenerateParams(WC_RNG *rng, int modSz, DhKey *dh);
1043
1044/*!
1045    \ingroup Diffie-Hellman
1046*/
1047int wc_DhSetCheckKey(DhKey* key, const byte* p, word32 pSz,
1048                        const byte* g, word32 gSz, const byte* q, word32 qSz,
1049                        int trusted, WC_RNG* rng);
1050
1051/*!
1052    \ingroup Diffie-Hellman
1053*/
1054int wc_DhSetKey_ex(DhKey* key, const byte* p, word32 pSz,
1055                        const byte* g, word32 gSz, const byte* q, word32 qSz);
1056
1057/*!
1058    \ingroup Diffie-Hellman
1059 */
1060int wc_FreeDhKey(DhKey* key);