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

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

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
)

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 2025-12-31 at 01:16:03 +0000