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

DH_check_pubkey()

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:

• pub_key is not negative
• pub_key > 1 and pub_key < p - 1, to avoid small subgroups attack.
• if g == 2, pub_key have more then one bit set, if bits set is 1, log_2(pub_key) is trival

DH_compute_key()

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

DH_free()

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.

DH_generate_key()

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.

DH_generate_parameters_ex()

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.

DH_get_default_method()

const DH_METHOD* DH_get_default_method

(

void

)

Return the default DH implementation.

Returns

pointer to a DH_METHOD.

DH_get_ex_data()

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

DH_ltm_method()

const DH_METHOD* DH_ltm_method

(

void

)

DH implementation using libtommath.

Returns

the DH_METHOD for the DH implementation using libtommath.

DH_new()

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_new_method()

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.

DH_null_method()

const DH_METHOD* DH_null_method

(

void

)

Return the dummy DH implementation.

Returns

pointer to a DH_METHOD.

DH_set_default_method()

void DH_set_default_method

(

const DH_METHOD *

meth

)

Set the default DH implementation.

Parameters

meth	pointer to a DH_METHOD.

DH_set_ex_data()

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.

DH_set_method()

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.

DH_size()

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.

DH_up_ref()

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.