My Project
Functions
Algorithms - Diffie-Hellman

Functions

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. More...
 
void 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. More...
 
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. More...
 
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. More...
 
int wc_DhKeyDecode (const byte *input, word32 *inOutIdx, DhKey *key, word32)
 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. More...
 
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). More...
 
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. More...
 
const DhParams * wc_Dh_ffdhe2048_Get (void)
 This function returns ... and requires that HAVE_FFDHE_2048 be defined. More...
 
const DhParams * wc_Dh_ffdhe3072_Get (void)
 This function returns ... and requires that HAVE_FFDHE_3072 be defined. More...
 
const DhParams * wc_Dh_ffdhe4096_Get (void)
 This function returns ... and requires that HAVE_FFDHE_4096 be defined. More...
 
const DhParams * wc_Dh_ffdhe6144_Get (void)
 This function returns ... and requires that HAVE_FFDHE_6144 be defined. More...
 
const DhParams * wc_Dh_ffdhe8192_Get (void)
 This function returns ... and requires that HAVE_FFDHE_8192 be defined. More...
 
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. More...
 
int wc_DhCheckPrivKey (DhKey *key, const byte *priv, word32 pubSz)
 Check DH private key for invalid numbers. More...
 
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)
 

Detailed Description

Function Documentation

◆ wc_Dh_ffdhe2048_Get()

const DhParams* wc_Dh_ffdhe2048_Get ( void  )

This function returns ... and requires that HAVE_FFDHE_2048 be defined.

See also
wc_Dh_ffdhe3072_Get
wc_Dh_ffdhe4096_Get
wc_Dh_ffdhe6144_Get
wc_Dh_ffdhe8192_Get

◆ wc_Dh_ffdhe3072_Get()

const DhParams* wc_Dh_ffdhe3072_Get ( void  )

This function returns ... and requires that HAVE_FFDHE_3072 be defined.

See also
wc_Dh_ffdhe2048_Get
wc_Dh_ffdhe4096_Get
wc_Dh_ffdhe6144_Get
wc_Dh_ffdhe8192_Get

◆ wc_Dh_ffdhe4096_Get()

const DhParams* wc_Dh_ffdhe4096_Get ( void  )

This function returns ... and requires that HAVE_FFDHE_4096 be defined.

See also
wc_Dh_ffdhe2048_Get
wc_Dh_ffdhe3072_Get
wc_Dh_ffdhe6144_Get
wc_Dh_ffdhe8192_Get

◆ wc_Dh_ffdhe6144_Get()

const DhParams* wc_Dh_ffdhe6144_Get ( void  )

This function returns ... and requires that HAVE_FFDHE_6144 be defined.

See also
wc_Dh_ffdhe2048_Get
wc_Dh_ffdhe3072_Get
wc_Dh_ffdhe4096_Get
wc_Dh_ffdhe8192_Get

◆ wc_Dh_ffdhe8192_Get()

const DhParams* wc_Dh_ffdhe8192_Get ( void  )

This function returns ... and requires that HAVE_FFDHE_8192 be defined.

See also
wc_Dh_ffdhe2048_Get
wc_Dh_ffdhe3072_Get
wc_Dh_ffdhe4096_Get
wc_Dh_ffdhe6144_Get

◆ 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.

Returns
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
Parameters
keypointer to the DhKey structure to use to compute the shared key
agreepointer to the buffer in which to store the secret key
agreeSzwill hold the size of the secret key after successful generation
privpointer to the buffer containing the local secret key
privSzsize of the local secret key
otherPubpointer to a buffer containing the received public key
pubSzsize of the received public 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
}
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 ...
See also
wc_DhGenerateKeyPair

◆ 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.

◆ wc_DhCheckPrivKey()

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

Check DH private key for invalid numbers.

◆ wc_DhCheckPrivKey_ex()

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

◆ wc_DhCheckPubKey()

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

◆ wc_DhCheckPubKey_ex()

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

◆ wc_DhExportParamsRaw()

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

◆ 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.

Returns
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
Parameters
keypointer to the DhKey structure from which to generate the key pair
rngpointer to an initialized random number generator (rng) with which to generate the keys
privpointer to a buffer in which to store the private key
privSzwill store the size of the private key written to priv
pubpointer to a buffer in which to store the public key
pubSzwill store the size of the private key written to pub

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);
int wc_InitDhKey(DhKey *key)
This function initializes a Diffie-Hellman key for use in negotiating a secure secret key with the Di...
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,...
int wc_InitRng(WC_RNG *)
Gets the seed (from OS) and key cipher for rng. rng->drbg (deterministic random bit generator) alloca...
See also
wc_InitDhKey
wc_DhSetKey
wc_DhKeyDecode

◆ wc_DhGenerateParams()

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

◆ wc_DhKeyDecode()

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

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.

Returns
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
Parameters
inputpointer to the buffer containing the DER formatted Diffie-Hellman key
inOutIdxpointer to an integer in which to store the index parsed to while decoding the key
keypointer to the DhKey structure to initialize with the input key
inSzlength of the input buffer. Gives the max length that may be read

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
}
int wc_DhKeyDecode(const byte *input, word32 *inOutIdx, DhKey *key, word32)
This function decodes a Diffie-Hellman key from the given input buffer containing the key in DER form...
See also
wc_DhSetKey

◆ 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.

Returns
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
Parameters
inputpointer to a buffer containing a DER formatted Diffie-Hellman certificate to parse
inSzsize of the input buffer
ppointer to a buffer in which to store the parsed prime
pInOutSzpointer 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
gpointer to a buffer in which to store the parsed base
gInOutSzpointer 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

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
}
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 buff...
See also
wc_DhSetKey
wc_DhKeyDecode

◆ 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 
)

◆ 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).

Returns
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
Parameters
keypointer to the DhKey structure on which to set the key
ppointer to the buffer containing the prime for use with the key
pSzlength of the input prime
gpointer to the buffer containing the base for use with the key
gSzlength of the input base

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
}
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....
See also
wc_DhKeyDecode

◆ wc_DhSetKey_ex()

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

◆ 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.

Returns
none No returns.
Parameters
keypointer to the DhKey structure to free

Example

DhKey key;
// initialize key, perform key exchange
wc_FreeDhKey(&key); // free DH key to avoid memory leaks
void wc_FreeDhKey(DhKey *key)
This function frees a Diffie-Hellman key after it has been used to negotiate a secure secret key with...
See also
wc_InitDhKey

◆ 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.

Returns
none No returns.
Parameters
keypointer to the DhKey structure to initialize for use with secure key exchanges

Example

DhKey key;
wc_InitDhKey(&key); // initialize DH key
See also
wc_FreeDhKey
wc_DhGenerateKeyPair