"Diffie-Hellman functions" 3 "11 Jan 2012" "Version 1.5.2" "Heimdal crypto library" \" -*- nroff -*-
 NAME
Diffie-Hellman functions - 

 "Functions"

 "const DH_METHOD * DH_ltm_method (void)" 

 "DH * DH_new (void)" 

 "DH * DH_new_method (ENGINE *engine)" 

 "void DH_free (DH *dh)" 

 "int DH_up_ref (DH *dh)" 

 "int DH_size (const DH *dh)" 

 "int DH_set_ex_data (DH *dh, int idx, void *data)" 

 "void * DH_get_ex_data (DH *dh, int idx)" 

 "int DH_generate_parameters_ex (DH *dh, int prime_len, int generator, BN_GENCB *cb)" 

 "int DH_check_pubkey (const DH *dh, const BIGNUM *pub_key, int *codes)" 

 "int DH_generate_key (DH *dh)" 

 "int DH_compute_key (unsigned char *shared_key, const BIGNUM *peer_pub_key, DH *dh)" 

 "int DH_set_method (DH *dh, const DH_METHOD *method)" 

 "const DH_METHOD * DH_null_method (void)" 

 "void DH_set_default_method (const DH_METHOD *meth)" 

 "const DH_METHOD * DH_get_default_method (void)" 


 "Detailed Description"
 
See the DH - Diffie-Hellman key exchange for description and examples. 

 "Function Documentation"
 

 "int DH_check_pubkey (const DH * dh, const BIGNUM * pub_key, int * codes)"

Check that the public key is sane.


Parameters:


dh the local peer DH parameters. 


pub_key the remote peer public key parameters. 


codes return that the failures of the pub_key are.




Returns:


1 on success, 0 on failure and *codes is set the the combined fail check for the public key 







Checks that the function performs are:

 "\(bu" 2
pub_key is not negative





 "\(bu" 2
pub_key > 1 and pub_key < p - 1, to avoid small subgroups attack.





 "\(bu" 2
if g == 2, pub_key have more then one bit set, if bits set is 1, log_2(pub_key) is trival 




 "int DH_compute_key (unsigned char * shared_key, const BIGNUM * peer_pub_key, DH * dh)"

Complute the shared secret key.


Parameters:


shared_key the resulting shared key, need to be at least DH_size() large. 


peer_pub_key the peer's public key. 


dh the dh key pair.




Returns:


1 on success. 







Checks that the pubkey passed in is valid using DH_check_pubkey(). 

 "void DH_free (DH * dh)"

Free a DH object and release related resources, like ENGINE, that the object was using.


Parameters:


dh object to be freed. 






 "int DH_generate_key (DH * dh)"

Generate a new DH private-public key pair. The dh parameter must be allocted first with DH_new(). dh->p and dp->g must be set.


Parameters:


dh dh parameter.




Returns:


1 on success. 






 "int DH_generate_parameters_ex (DH * dh, int prime_len, int generator, BN_GENCB * cb)"

Generate DH parameters for the DH object give parameters.


Parameters:


dh The DH object to generate parameters for. 


prime_len length of the prime 


generator generator, g 


cb Callback parameters to show progress, can be NULL.




Returns:


the maximum size in bytes of the out data. 






 "const DH_METHOD* DH_get_default_method (void)"

Return the default DH implementation.


Returns:


pointer to a DH_METHOD. 






 "void* DH_get_ex_data (DH * dh, int idx)"

Get the data for index idx in the DH object.


Parameters:


dh DH object. 


idx index to get the data for.




Returns:


the object store in index idx 






 "const DH_METHOD* DH_ltm_method (void)"

DH implementation using libtommath.


Returns:


the DH_METHOD for the DH implementation using libtommath. 






 "DH* DH_new (void)"

Create a new DH object using DH_new_method(NULL), see DH_new_method().


Returns:


a newly allocated DH object. 






 "DH* DH_new_method (ENGINE * engine)"

Create a new DH object from the given engine, if the NULL is used, the default engine is used. Free the DH object with DH_free().


Parameters:


engine The engine to use to allocate the DH object.




Returns:


a newly allocated DH object. 






 "const DH_METHOD* DH_null_method (void)"

Return the dummy DH implementation.


Returns:


pointer to a DH_METHOD. 






 "void DH_set_default_method (const DH_METHOD * meth)"

Set the default DH implementation.


Parameters:


meth pointer to a DH_METHOD. 






 "int DH_set_ex_data (DH * dh, int idx, void * data)"

Set the data index idx in the DH object to data.


Parameters:


dh DH object. 


idx index to set the data for. 


data data to store for the index idx.




Returns:


1 on success. 






 "int DH_set_method (DH * dh, const DH_METHOD * method)"

Set a new method for the DH keypair.


Parameters:


dh dh parameter. 


method the new method for the DH parameter.




Returns:


1 on success. 






 "int DH_size (const DH * dh)"

The maximum output size of the DH_compute_key() function.


Parameters:


dh The DH object to get the size from.




Returns:


the maximum size in bytes of the out data. 






 "int DH_up_ref (DH * dh)"

Add a reference to the DH object. The object should be free with DH_free() to drop the reference.


Parameters:


dh the object to increase the reference count too.




Returns:


the updated reference count, can't safely be used except for debug printing.