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. |
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. |
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 ) 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. |
const DhParams * | wc_Dh_ffdhe2048_Get(void ) This function returns ... and requires that HAVE_FFDHE_2048 be defined. |
const DhParams * | wc_Dh_ffdhe3072_Get(void ) This function returns ... and requires that HAVE_FFDHE_3072 be defined. |
const DhParams * | wc_Dh_ffdhe4096_Get(void ) This function returns ... and requires that HAVE_FFDHE_4096 be defined. |
const DhParams * | wc_Dh_ffdhe6144_Get(void ) This function returns ... and requires that HAVE_FFDHE_6144 be defined. |
const DhParams * | wc_Dh_ffdhe8192_Get(void ) This function returns ... and requires that HAVE_FFDHE_8192 be defined. |
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:
Return: none No returns.
Example
DhKey key;
wc_InitDhKey(&key); // initialize DH key
function wc_FreeDhKey
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.
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:
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
)
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:
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 wc_Dh_ffdhe2048_Get
const DhParams * wc_Dh_ffdhe2048_Get(
void
)
This function returns ... and requires that HAVE_FFDHE_2048 be defined.
See:
function wc_Dh_ffdhe3072_Get
const DhParams * wc_Dh_ffdhe3072_Get(
void
)
This function returns ... and requires that HAVE_FFDHE_3072 be defined.
See:
function wc_Dh_ffdhe4096_Get
const DhParams * wc_Dh_ffdhe4096_Get(
void
)
This function returns ... and requires that HAVE_FFDHE_4096 be defined.
See:
function wc_Dh_ffdhe6144_Get
const DhParams * wc_Dh_ffdhe6144_Get(
void
)
This function returns ... and requires that HAVE_FFDHE_6144 be defined.
See:
function wc_Dh_ffdhe8192_Get
const DhParams * wc_Dh_ffdhe8192_Get(
void
)
This function returns ... and requires that HAVE_FFDHE_8192 be defined.
See:
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);
void 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);
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);
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_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 2024-11-07 at 01:17:40 +0000