dh.h

Functions

	Name
int	wc_InitDhKey(DhKey * key) This function initializes a Diffie-Hellman key for use in negotiating a secure secret key with the Diffie-Hellman exchange protocol.
int	wc_FreeDhKey(DhKey * key) This function frees a Diffie-Hellman key after it has been used to negotiate a secure secret key with the Diffie-Hellman exchange protocol.
int	wc_DhGenerateKeyPair(DhKey * key, WC_RNG * rng, byte * priv, word32 * privSz, byte * pub, word32 * pubSz) This function generates a public/private key pair based on the Diffie-Hellman public parameters, storing the private key in priv and the public key in pub. It takes an initialized Diffie-Hellman key and an initialized rng structure.
int	wc_DhAgree(DhKey * key, byte * agree, word32 * agreeSz, const byte * priv, word32 privSz, const byte * otherPub, word32 pubSz) This function generates an agreed upon secret key based on a local private key and a received public key. If completed on both sides of an exchange, this function generates an agreed upon secret key for symmetric communication. On successfully generating a shared secret key, the size of the secret key written will be stored in agreeSz.
int	wc_DhKeyDecode(const byte * input, word32 * inOutIdx, DhKey * key, word32 inSz) This function decodes a Diffie-Hellman key from the given input buffer containing the key in DER format. It stores the result in the DhKey structure.
int	wc_DhSetKey(DhKey * key, const byte * p, word32 pSz, const byte * g, word32 gSz) This function sets the key for a DhKey structure using the input private key parameters. Unlike wc_DhKeyDecode, this function does not require that the input key be formatted in DER format, and instead simply accepts the parsed input parameters p (prime) and g (base).
int	wc_DhParamsLoad(const byte * input, word32 inSz, byte * p, word32 * pInOutSz, byte * g, word32 * gInOutSz) This function loads the Diffie_Hellman parameters, p (prime) and g (base) out of the given input buffer, DER formatted.
int	wolfSSL_i2d_DHparams(const WOLFSSL_DH * dh, unsigned char ** out) Encodes DH parameters to DER format for OpenSSL compatibility.
WOLFSSL_DH *	wolfSSL_DH_new(void ) Allocates and initializes a new DH structure for OpenSSL compatibility.
WOLFSSL_DH *	wolfSSL_DH_new_by_nid(int nid) Creates a new DH structure with named group parameters.
void	wolfSSL_DH_free(WOLFSSL_DH * dh) Frees a DH structure.
WOLFSSL_DH *	wolfSSL_DH_dup(WOLFSSL_DH * dh) Duplicates a DH structure.
int	wolfSSL_DH_up_ref(WOLFSSL_DH * dh) Increments reference count for DH structure.
int	wolfSSL_DH_check(const WOLFSSL_DH * dh, int * codes) Validates DH parameters.
int	wolfSSL_DH_size(WOLFSSL_DH * dh) Returns size of DH key in bytes.
int	wolfSSL_DH_generate_key(WOLFSSL_DH * dh) Generates DH public/private key pair.
int	wolfSSL_DH_compute_key(unsigned char * key, const WOLFSSL_BIGNUM * pub, WOLFSSL_DH * dh) Computes shared secret from peer's public key.
int	wolfSSL_DH_compute_key_padded(unsigned char * key, const WOLFSSL_BIGNUM * otherPub, WOLFSSL_DH * dh) Computes shared secret with zero-padding to DH size.
int	wolfSSL_DH_LoadDer(WOLFSSL_DH * dh, const unsigned char * derBuf, int derSz) Loads DH parameters from DER buffer.
int	wolfSSL_DH_set_length(WOLFSSL_DH * dh, long len) Sets optional private key length.
int	wolfSSL_DH_set0_pqg(WOLFSSL_DH * dh, WOLFSSL_BIGNUM * p, WOLFSSL_BIGNUM * q, WOLFSSL_BIGNUM * g) Sets DH parameters p, q, and g.
WOLFSSL_DH *	wolfSSL_DH_get_2048_256(void ) Returns DH parameters for 2048-bit MODP group with 256-bit subgroup.
const DhParams *	wc_Dh_ffdhe2048_Get(void ) Returns FFDHE 2048-bit group parameters.
const DhParams *	wc_Dh_ffdhe3072_Get(void ) Returns FFDHE 3072-bit group parameters.
const DhParams *	wc_Dh_ffdhe4096_Get(void ) Returns FFDHE 4096-bit group parameters.
const DhParams *	wc_Dh_ffdhe6144_Get(void ) Returns FFDHE 6144-bit group parameters.
const DhParams *	wc_Dh_ffdhe8192_Get(void ) Returns FFDHE 8192-bit group parameters.
int	wc_InitDhKey_ex(DhKey * key, void * heap, int devId) Initializes DH key with heap hint and device ID.
int	wc_DhAgree_ct(DhKey * key, byte * agree, word32 * agreeSz, const byte * priv, word32 privSz, const byte * otherPub, word32 pubSz) Computes shared secret with constant-time operations.
int	wc_DhSetNamedKey(DhKey * key, int name) Sets DH key to use named group parameters.
int	wc_DhGetNamedKeyParamSize(int name, word32 * p, word32 * g, word32 * q) Gets parameter sizes for named group.
word32	wc_DhGetNamedKeyMinSize(int name) Gets minimum key size for named group.
int	wc_DhCmpNamedKey(int name, int noQ, const byte * p, word32 pSz, const byte * g, word32 gSz, const byte * q, word32 qSz) Compares parameters against named group.
int	wc_DhCopyNamedKey(int name, byte * p, word32 * pSz, byte * g, word32 * gSz, byte * q, word32 * qSz) Copies named group parameters to buffers.
int	wc_DhGeneratePublic(DhKey * key, byte * priv, word32 privSz, byte * pub, word32 * pubSz) Generates public key from private key.
int	wc_DhImportKeyPair(DhKey * key, const byte * priv, word32 privSz, const byte * pub, word32 pubSz) Imports private and/or public key into DH key.
int	wc_DhExportKeyPair(DhKey * key, byte * priv, word32 * pPrivSz, byte * pub, word32 * pPubSz) Exports private and public key from DH key.
int	wc_DhCheckPubValue(const byte * prime, word32 primeSz, const byte * pub, word32 pubSz) Validates public key value.
int	wc_DhCheckKeyPair(DhKey * key, const byte * pub, word32 pubSz, const byte * priv, word32 privSz) Checks DH keys for pair_wise consistency per process in SP 800_56Ar3, section 5.6.2.1.4, method (b) for FFC.
int	wc_DhCheckPrivKey(DhKey * key, const byte * priv, word32 pubSz) Check DH private key for invalid numbers.
int	wc_DhCheckPrivKey_ex(DhKey * key, const byte * priv, word32 pubSz, const byte * prime, word32 primeSz)
int	wc_DhCheckPubKey(DhKey * key, const byte * pub, word32 pubSz)
int	wc_DhCheckPubKey_ex(DhKey * key, const byte * pub, word32 pubSz, const byte * prime, word32 primeSz)
int	wc_DhExportParamsRaw(DhKey * dh, byte * p, word32 * pSz, byte * q, word32 * qSz, byte * g, word32 * gSz)
int	wc_DhGenerateParams(WC_RNG * rng, int modSz, DhKey * dh)
int	wc_DhSetCheckKey(DhKey * key, const byte * p, word32 pSz, const byte * g, word32 gSz, const byte * q, word32 qSz, int trusted, WC_RNG * rng)
int	wc_DhSetKey_ex(DhKey * key, const byte * p, word32 pSz, const byte * g, word32 gSz, const byte * q, word32 qSz)

Functions Documentation

function wc_InitDhKey

int wc_InitDhKey(
    DhKey * key
)

This function initializes a Diffie-Hellman key for use in negotiating a secure secret key with the Diffie-Hellman exchange protocol.

Parameters:

• key pointer to the DhKey structure to initialize for use with secure key exchanges

See:

• wc_FreeDhKey
• wc_DhGenerateKeyPair

Return: none No returns.

Example

DhKey key;
wc_InitDhKey(&key); // initialize DH key

function wc_FreeDhKey

int wc_FreeDhKey(
    DhKey * key
)

This function frees a Diffie-Hellman key after it has been used to negotiate a secure secret key with the Diffie-Hellman exchange protocol.

Parameters:

• key pointer to the DhKey structure to free

See: wc_InitDhKey

Return: none No returns.

Example

DhKey key;
// initialize key, perform key exchange

wc_FreeDhKey(&key); // free DH key to avoid memory leaks

function wc_DhGenerateKeyPair

int wc_DhGenerateKeyPair(
    DhKey * key,
    WC_RNG * rng,
    byte * priv,
    word32 * privSz,
    byte * pub,
    word32 * pubSz
)

This function generates a public/private key pair based on the Diffie-Hellman public parameters, storing the private key in priv and the public key in pub. It takes an initialized Diffie-Hellman key and an initialized rng structure.

Parameters:

• key pointer to the DhKey structure from which to generate the key pair
• rng pointer to an initialized random number generator (rng) with which to generate the keys
• priv pointer to a buffer in which to store the private key
• privSz will store the size of the private key written to priv
• pub pointer to a buffer in which to store the public key
• pubSz will store the size of the private key written to pub

See:

• wc_InitDhKey
• wc_DhSetKey
• wc_DhKeyDecode

Return:

• BAD_FUNC_ARG Returned if there is an error parsing one of the inputs to this function
• RNG_FAILURE_E Returned if there is an error generating a random number using rng
• MP_INIT_E May be returned if there is an error in the math library while generating the public key
• MP_READ_E May be returned if there is an error in the math library while generating the public key
• MP_EXPTMOD_E May be returned if there is an error in the math library while generating the public key
• MP_TO_E May be returned if there is an error in the math library while generating the public key

Example

DhKey key;
int ret;
byte priv[256];
byte pub[256];
word32 privSz, pubSz;

wc_InitDhKey(&key); // initialize key
// Set DH parameters using wc_DhSetKey or wc_DhKeyDecode
WC_RNG rng;
wc_InitRng(&rng); // initialize rng
ret = wc_DhGenerateKeyPair(&key, &rng, priv, &privSz, pub, &pubSz);

function wc_DhAgree

int wc_DhAgree(
    DhKey * key,
    byte * agree,
    word32 * agreeSz,
    const byte * priv,
    word32 privSz,
    const byte * otherPub,
    word32 pubSz
)

This function generates an agreed upon secret key based on a local private key and a received public key. If completed on both sides of an exchange, this function generates an agreed upon secret key for symmetric communication. On successfully generating a shared secret key, the size of the secret key written will be stored in agreeSz.

Parameters:

• key pointer to the DhKey structure to use to compute the shared key
• agree pointer to the buffer in which to store the secret key
• agreeSz will hold the size of the secret key after successful generation
• priv pointer to the buffer containing the local secret key
• privSz size of the local secret key
• otherPub pointer to a buffer containing the received public key
• pubSz size of the received public key

See:

• wc_DhGenerateKeyPair
• wc_DhAgree_ct

Return:

• 0 Returned on successfully generating an agreed upon secret key
• MP_INIT_E May be returned if there is an error while generating the shared secret key
• MP_READ_E May be returned if there is an error while generating the shared secret key
• MP_EXPTMOD_E May be returned if there is an error while generating the shared secret key
• MP_TO_E May be returned if there is an error while generating the shared secret key

The value of agreeSz on input is not checked. The agree buffer must be at least as large as the prime, in bytes. Use wc_DhAgree_ct() to have the buffer size checked.

Example

DhKey key;
int ret;
byte priv[256];
byte agree[256];
word32 agreeSz;

// initialize key, set key prime and base
// wc_DhGenerateKeyPair -- store private key in priv
byte pub[] = { // initialized with the received public key };
ret = wc_DhAgree(&key, agree, &agreeSz, priv, sizeof(priv), pub,
sizeof(pub));
if ( ret != 0 ) {
    // error generating shared key
}

function wc_DhKeyDecode

int wc_DhKeyDecode(
    const byte * input,
    word32 * inOutIdx,
    DhKey * key,
    word32 inSz
)

This function decodes a Diffie-Hellman key from the given input buffer containing the key in DER format. It stores the result in the DhKey structure.

Parameters:

• input pointer to the buffer containing the DER formatted Diffie-Hellman key
• inOutIdx pointer to an integer in which to store the index parsed to while decoding the key
• key pointer to the DhKey structure to initialize with the input key
• inSz length of the input buffer. Gives the max length that may be read

See: wc_DhSetKey

Return:

• 0 Returned on successfully decoding the input key
• ASN_PARSE_E Returned if there is an error parsing the sequence of the input
• ASN_DH_KEY_E Returned if there is an error reading the private key parameters from the parsed input

Example

DhKey key;
word32 idx = 0;

byte keyBuff[1024];
// initialize with DER formatted key
wc_DhKeyInit(&key);
ret = wc_DhKeyDecode(keyBuff, &idx, &key, sizeof(keyBuff));

if ( ret != 0 ) {
    // error decoding key
}

function wc_DhSetKey

int wc_DhSetKey(
    DhKey * key,
    const byte * p,
    word32 pSz,
    const byte * g,
    word32 gSz
)

This function sets the key for a DhKey structure using the input private key parameters. Unlike wc_DhKeyDecode, this function does not require that the input key be formatted in DER format, and instead simply accepts the parsed input parameters p (prime) and g (base).

Parameters:

• key pointer to the DhKey structure on which to set the key
• p pointer to the buffer containing the prime for use with the key
• pSz length of the input prime
• g pointer to the buffer containing the base for use with the key
• gSz length of the input base

See: wc_DhKeyDecode

Return:

• 0 Returned on successfully setting the key
• BAD_FUNC_ARG Returned if any of the input parameters evaluate to NULL
• MP_INIT_E Returned if there is an error initializing the key parameters for storage
• ASN_DH_KEY_E Returned if there is an error reading in the DH key parameters p and g

Example

DhKey key;

byte p[] = { // initialize with prime };
byte g[] = { // initialize with base };
wc_DhKeyInit(&key);
ret = wc_DhSetKey(key, p, sizeof(p), g, sizeof(g));

if ( ret != 0 ) {
    // error setting key
}

function wc_DhParamsLoad

int wc_DhParamsLoad(
    const byte * input,
    word32 inSz,
    byte * p,
    word32 * pInOutSz,
    byte * g,
    word32 * gInOutSz
)

This function loads the Diffie-Hellman parameters, p (prime) and g (base) out of the given input buffer, DER formatted.

Parameters:

• input pointer to a buffer containing a DER formatted Diffie-Hellman certificate to parse
• inSz size of the input buffer
• p pointer to a buffer in which to store the parsed prime
• pInOutSz pointer to a word32 object containing the available size in the p buffer. Will be overwritten with the number of bytes written to the buffer after completing the function call
• g pointer to a buffer in which to store the parsed base
• gInOutSz pointer to a word32 object containing the available size in the g buffer. Will be overwritten with the number of bytes written to the buffer after completing the function call

See:

• wc_DhSetKey
• wc_DhKeyDecode

Return:

• 0 Returned on successfully extracting the DH parameters
• ASN_PARSE_E Returned if an error occurs while parsing the DER formatted DH certificate
• BUFFER_E Returned if there is inadequate space in p or g to store the parsed parameters

Example

byte dhCert[] = { initialize with DER formatted certificate };
byte p[MAX_DH_SIZE];
byte g[MAX_DH_SIZE];
word32 pSz = MAX_DH_SIZE;
word32 gSz = MAX_DH_SIZE;

ret = wc_DhParamsLoad(dhCert, sizeof(dhCert), p, &pSz, g, &gSz);
if ( ret != 0 ) {
    // error parsing inputs
}

function wolfSSL_i2d_DHparams

int wolfSSL_i2d_DHparams(
    const WOLFSSL_DH * dh,
    unsigned char ** out
)

Encodes DH parameters to DER format for OpenSSL compatibility.

Parameters:

• dh DH parameters to encode
• out Output buffer pointer (if *out is NULL, allocates buffer)

See: wolfSSL_DH_new

Return:

• Length of DER encoding on success
• Negative on error

Example

WOLFSSL_DH* dh = wolfSSL_DH_new();
unsigned char* der = NULL;
int derSz = wolfSSL_i2d_DHparams(dh, &der);
if (derSz > 0) {
    // use der buffer
    XFREE(der, NULL, DYNAMIC_TYPE_OPENSSL);
}

function wolfSSL_DH_new

WOLFSSL_DH * wolfSSL_DH_new(
    void 
)

Allocates and initializes a new DH structure for OpenSSL compatibility.

See:

• wolfSSL_DH_free
• wolfSSL_DH_generate_key

Return:

• Pointer to WOLFSSL_DH on success
• NULL on failure

Example

WOLFSSL_DH* dh = wolfSSL_DH_new();
if (dh == NULL) {
    // error allocating DH
}
// use dh
wolfSSL_DH_free(dh);

function wolfSSL_DH_new_by_nid

WOLFSSL_DH * wolfSSL_DH_new_by_nid(
    int nid
)

Creates a new DH structure with named group parameters.

Parameters:

• nid Named group identifier (e.g., NID_ffdhe2048)

See: wolfSSL_DH_new

Return:

• Pointer to WOLFSSL_DH on success
• NULL on failure

Example

WOLFSSL_DH* dh = wolfSSL_DH_new_by_nid(NID_ffdhe2048);
if (dh == NULL) {
    // error creating DH with named group
}

function wolfSSL_DH_free

void wolfSSL_DH_free(
    WOLFSSL_DH * dh
)

Frees a DH structure.

Parameters:

• dh DH structure to free

See: wolfSSL_DH_new

Example

WOLFSSL_DH* dh = wolfSSL_DH_new();
// use dh
wolfSSL_DH_free(dh);

function wolfSSL_DH_dup

WOLFSSL_DH * wolfSSL_DH_dup(
    WOLFSSL_DH * dh
)

Duplicates a DH structure.

Parameters:

• dh DH structure to duplicate

See: wolfSSL_DH_new

Return:

• Pointer to new WOLFSSL_DH on success
• NULL on failure

Example

WOLFSSL_DH* dh = wolfSSL_DH_new();
WOLFSSL_DH* dhCopy = wolfSSL_DH_dup(dh);

function wolfSSL_DH_up_ref

int wolfSSL_DH_up_ref(
    WOLFSSL_DH * dh
)

Increments reference count for DH structure.

Parameters:

• dh DH structure to increment reference

See: wolfSSL_DH_free

Return:

• 1 on success
• 0 on failure

Example

WOLFSSL_DH* dh = wolfSSL_DH_new();
int ret = wolfSSL_DH_up_ref(dh);

function wolfSSL_DH_check

int wolfSSL_DH_check(
    const WOLFSSL_DH * dh,
    int * codes
)

Validates DH parameters.

Parameters:

• dh DH parameters to check
• codes Output for validation error codes

See: wolfSSL_DH_generate_key

Return:

• 1 on success
• 0 on failure

Example

WOLFSSL_DH* dh = wolfSSL_DH_new();
int codes;
int ret = wolfSSL_DH_check(dh, &codes);
if (ret != 1 || codes != 0) {
    // validation failed
}

function wolfSSL_DH_size

int wolfSSL_DH_size(
    WOLFSSL_DH * dh
)

Returns size of DH key in bytes.

Parameters:

• dh DH structure

See: wolfSSL_DH_new

Return:

• Key size in bytes on success
• -1 on failure

Example

WOLFSSL_DH* dh = wolfSSL_DH_new();
int size = wolfSSL_DH_size(dh);

function wolfSSL_DH_generate_key

int wolfSSL_DH_generate_key(
    WOLFSSL_DH * dh
)

Generates DH public/private key pair.

Parameters:

• dh DH structure with parameters set

See: wolfSSL_DH_compute_key

Return:

• 1 on success
• 0 on failure

Example

WOLFSSL_DH* dh = wolfSSL_DH_new();
// set p and g parameters
int ret = wolfSSL_DH_generate_key(dh);
if (ret != 1) {
    // key generation failed
}

function wolfSSL_DH_compute_key

int wolfSSL_DH_compute_key(
    unsigned char * key,
    const WOLFSSL_BIGNUM * pub,
    WOLFSSL_DH * dh
)

Computes shared secret from peer's public key.

Parameters:

• key Output buffer for shared secret
• pub Peer's public key
• dh DH structure with private key

See: wolfSSL_DH_generate_key

Return:

• Length of shared secret on success
• -1 on failure

Example

WOLFSSL_DH* dh = wolfSSL_DH_new();
wolfSSL_DH_generate_key(dh);
byte secret[256];
WOLFSSL_BIGNUM* peerPub = NULL; // peer's public key
int secretSz = wolfSSL_DH_compute_key(secret, peerPub, dh);

function wolfSSL_DH_compute_key_padded

int wolfSSL_DH_compute_key_padded(
    unsigned char * key,
    const WOLFSSL_BIGNUM * otherPub,
    WOLFSSL_DH * dh
)

Computes shared secret with zero-padding to DH size.

Parameters:

• key Output buffer for shared secret
• otherPub Peer's public key
• dh DH structure with private key

See: wolfSSL_DH_compute_key

Return:

• Length of shared secret on success
• -1 on failure

Example

WOLFSSL_DH* dh = wolfSSL_DH_new();
wolfSSL_DH_generate_key(dh);
byte secret[256];
WOLFSSL_BIGNUM* peerPub = NULL;
int secretSz = wolfSSL_DH_compute_key_padded(secret, peerPub, dh);

function wolfSSL_DH_LoadDer

int wolfSSL_DH_LoadDer(
    WOLFSSL_DH * dh,
    const unsigned char * derBuf,
    int derSz
)

Loads DH parameters from DER buffer.

Parameters:

• dh DH structure to load into
• derBuf DER-encoded DH parameters
• derSz Size of DER buffer

See: wolfSSL_DH_new

Return:

• WOLFSSL_SUCCESS on success
• WOLFSSL_FAILURE on failure

Example

WOLFSSL_DH* dh = wolfSSL_DH_new();
byte derBuf[256];
int ret = wolfSSL_DH_LoadDer(dh, derBuf, sizeof(derBuf));

function wolfSSL_DH_set_length

int wolfSSL_DH_set_length(
    WOLFSSL_DH * dh,
    long len
)

Sets optional private key length.

Parameters:

• dh DH structure
• len Private key length in bits

See: wolfSSL_DH_generate_key

Return:

• 1 on success
• 0 on failure

Example

WOLFSSL_DH* dh = wolfSSL_DH_new();
int ret = wolfSSL_DH_set_length(dh, 256);

function wolfSSL_DH_set0_pqg

int wolfSSL_DH_set0_pqg(
    WOLFSSL_DH * dh,
    WOLFSSL_BIGNUM * p,
    WOLFSSL_BIGNUM * q,
    WOLFSSL_BIGNUM * g
)

Sets DH parameters p, q, and g.

Parameters:

• dh DH structure
• p Prime modulus (takes ownership)
• q Subgroup order (takes ownership, can be NULL)
• g Generator (takes ownership)

See: wolfSSL_DH_generate_key

Return:

• 1 on success
• 0 on failure

Example

WOLFSSL_DH* dh = wolfSSL_DH_new();
WOLFSSL_BIGNUM *p = wolfSSL_BN_new();
WOLFSSL_BIGNUM *g = wolfSSL_BN_new();
// set p and g values
int ret = wolfSSL_DH_set0_pqg(dh, p, NULL, g);

function wolfSSL_DH_get_2048_256

WOLFSSL_DH * wolfSSL_DH_get_2048_256(
    void 
)

Returns DH parameters for 2048-bit MODP group with 256-bit subgroup.

See: wolfSSL_DH_new_by_nid

Return:

• Pointer to WOLFSSL_DH on success
• NULL on failure

Example

WOLFSSL_DH* dh = wolfSSL_DH_get_2048_256();
if (dh == NULL) {
    // error getting standard group
}

function wc_Dh_ffdhe2048_Get

const DhParams * wc_Dh_ffdhe2048_Get(
    void 
)

Returns FFDHE 2048-bit group parameters.

See:

• wc_Dh_ffdhe3072_Get
• wc_Dh_ffdhe4096_Get
• wc_Dh_ffdhe6144_Get
• wc_Dh_ffdhe8192_Get

Return:

• Pointer to DhParams structure
• NULL if not compiled with HAVE_FFDHE_2048

Example

const DhParams* params = wc_Dh_ffdhe2048_Get();
if (params != NULL) {
    // use params
}

function wc_Dh_ffdhe3072_Get

const DhParams * wc_Dh_ffdhe3072_Get(
    void 
)

Returns FFDHE 3072-bit group parameters.

See:

• wc_Dh_ffdhe2048_Get
• wc_Dh_ffdhe4096_Get
• wc_Dh_ffdhe6144_Get
• wc_Dh_ffdhe8192_Get

Return:

• Pointer to DhParams structure
• NULL if not compiled with HAVE_FFDHE_3072

Example

const DhParams* params = wc_Dh_ffdhe3072_Get();
if (params != NULL) {
    // use params
}

function wc_Dh_ffdhe4096_Get

const DhParams * wc_Dh_ffdhe4096_Get(
    void 
)

Returns FFDHE 4096-bit group parameters.

See:

• wc_Dh_ffdhe2048_Get
• wc_Dh_ffdhe3072_Get
• wc_Dh_ffdhe6144_Get
• wc_Dh_ffdhe8192_Get

Return:

• Pointer to DhParams structure
• NULL if not compiled with HAVE_FFDHE_4096

Example

const DhParams* params = wc_Dh_ffdhe4096_Get();
if (params != NULL) {
    // use params
}

function wc_Dh_ffdhe6144_Get

const DhParams * wc_Dh_ffdhe6144_Get(
    void 
)

Returns FFDHE 6144-bit group parameters.

See:

• wc_Dh_ffdhe2048_Get
• wc_Dh_ffdhe3072_Get
• wc_Dh_ffdhe4096_Get
• wc_Dh_ffdhe8192_Get

Return:

• Pointer to DhParams structure
• NULL if not compiled with HAVE_FFDHE_6144

Example

const DhParams* params = wc_Dh_ffdhe6144_Get();
if (params != NULL) {
    // use params
}

function wc_Dh_ffdhe8192_Get

const DhParams * wc_Dh_ffdhe8192_Get(
    void 
)

Returns FFDHE 8192-bit group parameters.

See:

• wc_Dh_ffdhe2048_Get
• wc_Dh_ffdhe3072_Get
• wc_Dh_ffdhe4096_Get
• wc_Dh_ffdhe6144_Get

Return:

• Pointer to DhParams structure
• NULL if not compiled with HAVE_FFDHE_8192

Example

const DhParams* params = wc_Dh_ffdhe8192_Get();
if (params != NULL) {
    // use params
}

function wc_InitDhKey_ex

int wc_InitDhKey_ex(
    DhKey * key,
    void * heap,
    int devId
)

Initializes DH key with heap hint and device ID.

Parameters:

• key DH key to initialize
• heap Heap hint for memory allocation
• devId Device ID for hardware acceleration

See:

• wc_InitDhKey
• wc_FreeDhKey

Return:

• 0 on success
• BAD_FUNC_ARG if key is NULL

Example

DhKey key;
int ret = wc_InitDhKey_ex(&key, NULL, INVALID_DEVID);
if (ret != 0) {
    // error initializing key
}

function wc_DhAgree_ct

int wc_DhAgree_ct(
    DhKey * key,
    byte * agree,
    word32 * agreeSz,
    const byte * priv,
    word32 privSz,
    const byte * otherPub,
    word32 pubSz
)

Computes shared secret with constant-time operations.

Parameters:

• key DH key with parameters
• agree Output buffer for shared secret
• agreeSz Input: buffer size, Output: secret size
• priv Private key
• privSz Private key size
• otherPub Peer's public key
• pubSz Peer's public key size

See: wc_DhAgree

Return:

• 0 on success
• BAD_FUNC_ARG if parameters are invalid
• BUFFER_E if output buffer too small

Example

DhKey key;
byte agree[256], priv[256], pub[256];
word32 agreeSz = sizeof(agree);
int ret = wc_DhAgree_ct(&key, agree, &agreeSz, priv,
                       sizeof(priv), pub, sizeof(pub));

function wc_DhSetNamedKey

int wc_DhSetNamedKey(
    DhKey * key,
    int name
)

Sets DH key to use named group parameters.

Parameters:

• key DH key to configure
• name Named group identifier

See: wc_DhGetNamedKeyParamSize

Return:

• 0 on success
• BAD_FUNC_ARG if parameters are invalid

Example

DhKey key;
wc_InitDhKey(&key);
int ret = wc_DhSetNamedKey(&key, WC_FFDHE_2048);

function wc_DhGetNamedKeyParamSize

int wc_DhGetNamedKeyParamSize(
    int name,
    word32 * p,
    word32 * g,
    word32 * q
)

Gets parameter sizes for named group.

Parameters:

• name Named group identifier
• p Output for prime size
• g Output for generator size
• q Output for subgroup order size

See: wc_DhSetNamedKey

Return:

• 0 on success
• BAD_FUNC_ARG if parameters are invalid

Example

word32 pSz, gSz, qSz;
int ret = wc_DhGetNamedKeyParamSize(WC_FFDHE_2048, &pSz, &gSz,
                                   &qSz);

function wc_DhGetNamedKeyMinSize

word32 wc_DhGetNamedKeyMinSize(
    int name
)

Gets minimum key size for named group.

Parameters:

• name Named group identifier

See: wc_DhSetNamedKey

Return:

• Minimum key size in bits
• 0 if invalid name

Example

word32 minSize = wc_DhGetNamedKeyMinSize(WC_FFDHE_2048);

function wc_DhCmpNamedKey

int wc_DhCmpNamedKey(
    int name,
    int noQ,
    const byte * p,
    word32 pSz,
    const byte * g,
    word32 gSz,
    const byte * q,
    word32 qSz
)

Compares parameters against named group.

Parameters:

• name Named group identifier
• noQ 1 to skip q comparison
• p Prime modulus
• pSz Prime size
• g Generator
• gSz Generator size
• q Subgroup order
• qSz Subgroup order size

See: wc_DhSetNamedKey

Return:

• 0 if parameters match named group
• Non-zero if parameters don't match

Example

byte p[256], g[256];
int ret = wc_DhCmpNamedKey(WC_FFDHE_2048, 1, p, sizeof(p),
                          g, sizeof(g), NULL, 0);

function wc_DhCopyNamedKey

int wc_DhCopyNamedKey(
    int name,
    byte * p,
    word32 * pSz,
    byte * g,
    word32 * gSz,
    byte * q,
    word32 * qSz
)

Copies named group parameters to buffers.

Parameters:

• name Named group identifier
• p Output buffer for prime
• pSz Input: buffer size, Output: prime size
• g Output buffer for generator
• gSz Input: buffer size, Output: generator size
• q Output buffer for subgroup order
• qSz Input: buffer size, Output: subgroup order size

See: wc_DhSetNamedKey

Return:

• 0 on success
• BAD_FUNC_ARG if parameters are invalid
• BUFFER_E if buffers too small

Example

byte p[512], g[512], q[512];
word32 pSz = sizeof(p), gSz = sizeof(g), qSz = sizeof(q);
int ret = wc_DhCopyNamedKey(WC_FFDHE_2048, p, &pSz, g, &gSz,
                           q, &qSz);

function wc_DhGeneratePublic

int wc_DhGeneratePublic(
    DhKey * key,
    byte * priv,
    word32 privSz,
    byte * pub,
    word32 * pubSz
)

Generates public key from private key.

Parameters:

• key DH key with parameters set
• priv Private key
• privSz Private key size
• pub Output buffer for public key
• pubSz Input: buffer size, Output: public key size

See: wc_DhGenerateKeyPair

Return:

• 0 on success
• BAD_FUNC_ARG if parameters are invalid

Example

DhKey key;
byte priv[256], pub[256];
word32 pubSz = sizeof(pub);
int ret = wc_DhGeneratePublic(&key, priv, sizeof(priv), pub,
                             &pubSz);

function wc_DhImportKeyPair

int wc_DhImportKeyPair(
    DhKey * key,
    const byte * priv,
    word32 privSz,
    const byte * pub,
    word32 pubSz
)

Imports private and/or public key into DH key.

Parameters:

• key DH key to import into
• priv Private key (can be NULL)
• privSz Private key size
• pub Public key (can be NULL)
• pubSz Public key size

See: wc_DhExportKeyPair

Return:

• 0 on success
• BAD_FUNC_ARG if parameters are invalid

Example

DhKey key;
byte priv[256], pub[256];
int ret = wc_DhImportKeyPair(&key, priv, sizeof(priv), pub,
                            sizeof(pub));

function wc_DhExportKeyPair

int wc_DhExportKeyPair(
    DhKey * key,
    byte * priv,
    word32 * pPrivSz,
    byte * pub,
    word32 * pPubSz
)

Exports private and public key from DH key.

Parameters:

• key DH key to export from
• priv Output buffer for private key
• pPrivSz Input: buffer size, Output: private key size
• pub Output buffer for public key
• pPubSz Input: buffer size, Output: public key size

See: wc_DhImportKeyPair

Return:

• 0 on success
• BAD_FUNC_ARG if parameters are invalid
• BUFFER_E if buffers too small

Example

DhKey key;
byte priv[256], pub[256];
word32 privSz = sizeof(priv), pubSz = sizeof(pub);
int ret = wc_DhExportKeyPair(&key, priv, &privSz, pub, &pubSz);

function wc_DhCheckPubValue

int wc_DhCheckPubValue(
    const byte * prime,
    word32 primeSz,
    const byte * pub,
    word32 pubSz
)

Validates public key value.

Parameters:

• prime Prime modulus
• primeSz Prime size
• pub Public key to validate
• pubSz Public key size

See: wc_DhCheckPubKey

Return:

• 0 if public key is valid
• BAD_FUNC_ARG if parameters are invalid
• MP_VAL if public key is invalid

Example

byte prime[256], pub[256];
int ret = wc_DhCheckPubValue(prime, sizeof(prime), pub,
                             sizeof(pub));
if (ret != 0) {
    // invalid public key
}

function wc_DhCheckKeyPair

int wc_DhCheckKeyPair(
    DhKey * key,
    const byte * pub,
    word32 pubSz,
    const byte * priv,
    word32 privSz
)

Checks DH keys for pair-wise consistency per process in SP 800-56Ar3, section 5.6.2.1.4, method (b) for FFC.

function wc_DhCheckPrivKey

int wc_DhCheckPrivKey(
    DhKey * key,
    const byte * priv,
    word32 pubSz
)

Check DH private key for invalid numbers.

function wc_DhCheckPrivKey_ex

int wc_DhCheckPrivKey_ex(
    DhKey * key,
    const byte * priv,
    word32 pubSz,
    const byte * prime,
    word32 primeSz
)

function wc_DhCheckPubKey

int wc_DhCheckPubKey(
    DhKey * key,
    const byte * pub,
    word32 pubSz
)

function wc_DhCheckPubKey_ex

int wc_DhCheckPubKey_ex(
    DhKey * key,
    const byte * pub,
    word32 pubSz,
    const byte * prime,
    word32 primeSz
)

function wc_DhExportParamsRaw

int wc_DhExportParamsRaw(
    DhKey * dh,
    byte * p,
    word32 * pSz,
    byte * q,
    word32 * qSz,
    byte * g,
    word32 * gSz
)

function wc_DhGenerateParams

int wc_DhGenerateParams(
    WC_RNG * rng,
    int modSz,
    DhKey * dh
)

function wc_DhSetCheckKey

int wc_DhSetCheckKey(
    DhKey * key,
    const byte * p,
    word32 pSz,
    const byte * g,
    word32 gSz,
    const byte * q,
    word32 qSz,
    int trusted,
    WC_RNG * rng
)

function wc_DhSetKey_ex

int wc_DhSetKey_ex(
    DhKey * key,
    const byte * p,
    word32 pSz,
    const byte * g,
    word32 gSz,
    const byte * q,
    word32 qSz
)

Note: Parameters that are not one of the built-in FFDHE groups are untrusted, so the modulus is tested for primality with random Miller-Rabin witnesses. This function takes no RNG, so it instantiates a temporary one, which allocates memory and consumes entropy on every such call. When neither is available the test falls back to fixed witness bases, which a purpose-built composite can defeat. Call wc_DhSetCheckKey() with an initialized WC_RNG to supply your own.

Source code

int wc_InitDhKey(DhKey* key);

int wc_FreeDhKey(DhKey* key);

int wc_DhGenerateKeyPair(DhKey* key, WC_RNG* rng, byte* priv,
                                 word32* privSz, byte* pub, word32* pubSz);

int wc_DhAgree(DhKey* key, byte* agree, word32* agreeSz,
                       const byte* priv, word32 privSz, const byte* otherPub,
                       word32 pubSz);

int wc_DhKeyDecode(const byte* input, word32* inOutIdx, DhKey* key,
                           word32 inSz);

int wc_DhSetKey(DhKey* key, const byte* p, word32 pSz, const byte* g,
                        word32 gSz);

int wc_DhParamsLoad(const byte* input, word32 inSz, byte* p,
                            word32* pInOutSz, byte* g, word32* gInOutSz);

int wolfSSL_i2d_DHparams(const WOLFSSL_DH *dh, unsigned char **out);

WOLFSSL_DH* wolfSSL_DH_new(void);

WOLFSSL_DH* wolfSSL_DH_new_by_nid(int nid);

void wolfSSL_DH_free(WOLFSSL_DH* dh);

WOLFSSL_DH* wolfSSL_DH_dup(WOLFSSL_DH* dh);

int wolfSSL_DH_up_ref(WOLFSSL_DH* dh);

int wolfSSL_DH_check(const WOLFSSL_DH *dh, int *codes);

int wolfSSL_DH_size(WOLFSSL_DH* dh);

int wolfSSL_DH_generate_key(WOLFSSL_DH* dh);

int wolfSSL_DH_compute_key(unsigned char* key,
                          const WOLFSSL_BIGNUM* pub, WOLFSSL_DH* dh);

int wolfSSL_DH_compute_key_padded(unsigned char* key,
                                 const WOLFSSL_BIGNUM* otherPub,
                                 WOLFSSL_DH* dh);

int wolfSSL_DH_LoadDer(WOLFSSL_DH* dh, const unsigned char* derBuf,
                      int derSz);

int wolfSSL_DH_set_length(WOLFSSL_DH* dh, long len);

int wolfSSL_DH_set0_pqg(WOLFSSL_DH *dh, WOLFSSL_BIGNUM *p,
                       WOLFSSL_BIGNUM *q, WOLFSSL_BIGNUM *g);

WOLFSSL_DH* wolfSSL_DH_get_2048_256(void);

const DhParams* wc_Dh_ffdhe2048_Get(void);

const DhParams* wc_Dh_ffdhe3072_Get(void);

const DhParams* wc_Dh_ffdhe4096_Get(void);

const DhParams* wc_Dh_ffdhe6144_Get(void);

const DhParams* wc_Dh_ffdhe8192_Get(void);

int wc_InitDhKey_ex(DhKey* key, void* heap, int devId);

int wc_DhAgree_ct(DhKey* key, byte* agree, word32 *agreeSz,
                 const byte* priv, word32 privSz,
                 const byte* otherPub, word32 pubSz);

int wc_DhSetNamedKey(DhKey* key, int name);

int wc_DhGetNamedKeyParamSize(int name, word32* p, word32* g,
                              word32* q);

word32 wc_DhGetNamedKeyMinSize(int name);

int wc_DhCmpNamedKey(int name, int noQ, const byte* p, word32 pSz,
                    const byte* g, word32 gSz, const byte* q,
                    word32 qSz);

int wc_DhCopyNamedKey(int name, byte* p, word32* pSz, byte* g,
                     word32* gSz, byte* q, word32* qSz);

int wc_DhGeneratePublic(DhKey* key, byte* priv, word32 privSz,
                       byte* pub, word32* pubSz);

int wc_DhImportKeyPair(DhKey* key, const byte* priv, word32 privSz,
                      const byte* pub, word32 pubSz);

int wc_DhExportKeyPair(DhKey* key, byte* priv, word32* pPrivSz,
                      byte* pub, word32* pPubSz);

int wc_DhCheckPubValue(const byte* prime, word32 primeSz,
                      const byte* pub, word32 pubSz);

int wc_DhCheckKeyPair(DhKey* key, const byte* pub, word32 pubSz,
                        const byte* priv, word32 privSz);

int wc_DhCheckPrivKey(DhKey* key, const byte* priv, word32 pubSz);

int wc_DhCheckPrivKey_ex(DhKey* key, const byte* priv, word32 pubSz,
                            const byte* prime, word32 primeSz);

int wc_DhCheckPubKey(DhKey* key, const byte* pub, word32 pubSz);

int wc_DhCheckPubKey_ex(DhKey* key, const byte* pub, word32 pubSz,
                            const byte* prime, word32 primeSz);

int wc_DhExportParamsRaw(DhKey* dh, byte* p, word32* pSz,
                       byte* q, word32* qSz, byte* g, word32* gSz);

int wc_DhGenerateParams(WC_RNG *rng, int modSz, DhKey *dh);

int wc_DhSetCheckKey(DhKey* key, const byte* p, word32 pSz,
                        const byte* g, word32 gSz, const byte* q, word32 qSz,
                        int trusted, WC_RNG* rng);

int wc_DhSetKey_ex(DhKey* key, const byte* p, word32 pSz,
                        const byte* g, word32 gSz, const byte* q, word32 qSz);

int wc_FreeDhKey(DhKey* key);

---

Updated on 2026-11-11 at 01:17:44 +0000