NAME

DH_get0_pqg, DH_get0_p, DH_get0_q, DH_get0_g, DH_set0_pqg, DH_get0_key, DH_get0_pub_key, DH_get0_priv_key, DH_set0_key, DH_clear_flags, DH_test_flags, DH_set_flags, DH_get0_engine, DH_set_length — get data from and set data in a DH object

SYNOPSIS

#include <openssl/dh.h>

void
DH_get0_pqg(const DH *dh, const BIGNUM **p, const BIGNUM **q, const BIGNUM **g);

const BIGNUM *
DH_get0_p(const DH *dh);

const BIGNUM *
DH_get0_q(const DH *dh);

const BIGNUM *
DH_get0_g(const DH *dh);

int
DH_set0_pqg(DH *dh, BIGNUM *p, BIGNUM *q, BIGNUM *g);

void
DH_get0_key(const DH *dh, const BIGNUM **pub_key, const BIGNUM **priv_key);

const BIGNUM *
DH_get0_pub_key(const DH *dh);

const BIGNUM *
DH_get0_priv_key(const DH *dh);

int
DH_set0_key(DH *dh, BIGNUM *pub_key, BIGNUM *priv_key);

void
DH_clear_flags(DH *dh, int flags);

int
DH_test_flags(const DH *dh, int flags);

void
DH_set_flags(DH *dh, int flags);

ENGINE *
DH_get0_engine(DH *d);

int
DH_set_length(DH *dh, long length);

DESCRIPTION

A DH object contains the parameters p, g, and optionally q. It also contains a public key pub_key and an optional private key priv_key.

The p, q, and g parameters can be obtained by calling DH_get0_pqg(). If the parameters have not yet been set, then *p, *q, and *g are set to NULL. Otherwise, they are set to pointers to the internal representations of the values that should not be freed by the application. Any of the out parameters p, q, and g can be NULL, in which case no value is returned for that parameter.

The p, q, and g values can be set by calling DH_set0_pqg(). Calling this function transfers the memory management of the values to dh, and therefore they should not be freed by the caller. The q argument may be NULL.

The DH_get0_key() function stores pointers to the internal representations of the public key in *pub_key and to the private key in *priv_key. Either may be NULL if it has not yet been set. If the private key has been set, then the public key must be. Any of the out parameters pub_key and priv_key can be NULL, in which case no value is returned for that parameter.

The public and private key values can be set using DH_set0_key(). Either parameter may be NULL, which means the corresponding DH field is left untouched. This function transfers the memory management of the key values to dh, and therefore they should not be freed by the caller.

Values retrieved with DH_get0_pqg() and DH_get0_key() are owned by the DH object and may therefore not be passed to DH_set0_pqg() or DH_set0_key(). If needed, duplicate the received values using BN_dup(3) and pass the duplicates.

Any of the values p, q, g, pub_key, and priv_key can also be retrieved separately by the corresponding functions DH_get0_p(), DH_get0_q(), DH_get0_g(), DH_get0_pub_key(), and DH_get0_priv_key(), respectively. The pointers are owned by the DH object.

DH_clear_flags() clears the specified flags in dh. DH_test_flags() tests the flags in dh. DH_set_flags() sets the flags in dh; any flags already set remain set. For all three functions, multiple flags can be passed in one call, OR'ed together bitwise.

DH_set_length() sets the optional length attribute of dh, indicating the length of the secret exponent (private key) in bits. If the length attribute is non-zero, it is used, otherwise it is ignored.

RETURN VALUES

+.Fn DH_get0_p , +.Fn DH_get0_q , +.Fn DH_get0_g , +.Fn DH_get0_pub_key , +and +.Fn DH_get0_priv_key , +return a pointer owned by the +.Vt DH +object if the corresponding value has been set, +otherwise they return +.Dv NULL . DH_set0_pqg(), DH_set0_key(), and DH_set_length() return 1 on success or 0 on failure.

DH_test_flags() return those of the given flags currently set in dh or 0 if none of the given flags are set.

DH_get0_engine() always returns NULL.

SEE ALSO

DH_generate_key(3), DH_generate_parameters(3), DH_new(3), DH_security_bits(3), DH_size(3), DHparams_print(3)

HISTORY

DH_get0_pqg(), DH_set0_pqg(), DH_get0_key(), DH_set0_key(), DH_clear_flags(), DH_test_flags(), DH_set_flags(), DH_get0_engine(), and DH_set_length() first appeared in OpenSSL 1.1.0 and have been available since OpenBSD 6.3.

DH_get0_p(), DH_get0_q(), DH_get0_g(), DH_get0_pub_key(), and DH_get0_priv_key() first appeared in OpenSSL 1.1.1 and have been available since OpenBSD 7.1.