Add documentation for following DH and DH_METHOD opacity

A number of new functions have been added following the DH and DH_METHOD
opacity commits. This commit provides documentation for those functions.

Reviewed-by: Richard Levitte <levitte@openssl.org>

5 files changed, 249 insertions, 45 deletions

diff --git a/crypto/dh/dh_locl.h b/crypto/dh/dh_locl.h
index 80d09d04e3..46e4bc79d9 100644
--- a/crypto/dh/dh_locl.h
+++ b/crypto/dh/dh_locl.h
@@ -42,6 +42,7 @@ struct dh_method {
     /* Methods here */
     int (*generate_key) (DH *dh);
     int (*compute_key) (unsigned char *key, const BIGNUM *pub_key, DH *dh);
+
     /* Can be null */
     int (*bn_mod_exp) (const DH *dh, BIGNUM *r, const BIGNUM *a,
                        const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx,
diff --git a/doc/crypto/DH_get0_pqg.pod b/doc/crypto/DH_get0_pqg.pod
new file mode 100644
index 0000000000..bcbecf37a6
--- /dev/null
+++ b/doc/crypto/DH_get0_pqg.pod
@@ -0,0 +1,92 @@
+=pod
+
+=head1 NAME
+
+DH_get0_pqg, DH_set0_pqg, DH_get0_key, DH_set0_key, DH_clear_flags,
+DH_test_flags, DH_set_flags, DH_get0_engine, DH_get_length,
+DH_set_length - Routines for getting and setting data in a DH object
+
+=head1 SYNOPSIS
+
+ #include <openssl/dh.h>
+
+ void DH_get0_pqg(const DH *dh, BIGNUM **p, BIGNUM **q, BIGNUM **g);
+ int DH_set0_pqg(DH *dh, BIGNUM *p, BIGNUM *q, BIGNUM *g);
+ void DH_get0_key(const DH *dh, BIGNUM **pub_key, BIGNUM **priv_key);
+ 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);
+ long DH_get_length(const DH *dh);
+ int DH_set_length(DH *dh, long length);
+
+=head1 DESCRIPTION
+
+A DH object contains the parameters B<p>, B<q> and B<g>. Note that the B<q>
+parameter is optional. It also contains a public key (B<pub_key>) and
+(optionally) a private key (B<priv_key>).
+
+The B<p>, B<q> and B<g> parameters can be obtained by calling DH_get0_pqg().
+If the parameters have not yet been set then B<*p>, B<*q> and B<*g> will be set
+to NULL. Otherwise they are set to pointers to their respective values. These
+point directly to the internal representations of the values and therefore
+should not be freed directly.
+
+The B<p>, B<q> and B<g> values can be set by calling DH_set0_pqg() and passing
+the new values for B<p>, B<q> and B<g> as parameters to the function. Calling
+this function transfers the memory management of the values to the DH object,
+and therefore the values that have been passed in should not be freed directly
+after this function has been called. The B<q> parameter may be NULL.
+
+To get the public and private key values use the DH_get0_key() function. A
+pointer to the public key will be stored in B<*pub_key>, and a pointer to the
+private key will be stored in B<*priv_key>. Either may be NULL if they have not
+been set yet, although if the private key has been set then the public key must
+be. The values point to the internal representation of the public key and
+private key values. This memory should not be freed directly.
+
+The public and private key values can be set using DH_set0_key(). The public
+key must always be non-NULL. The private key may be NULL. As for DH_set0_pqg()
+this function transfers the memory management of the key values to the DH
+object, and therefore they should not be freed directly after this function has
+been called.
+
+DH_set_flags() sets the flags in the B<flags> parameter on the DH object.
+Multiple flags can be passed in one go (bitwise ORed together). Any flags that
+are already set are left set. DH_test_flags() tests to see whether the flags
+passed in the B<flags> parameter are currently set in the DH object. Multiple
+flags can be tested in one go. All flags that are currently set are returned, or
+zero if none of the flags are set. DH_clear_flags() clears the specified flags
+within the DH object.
+
+DH_get0_engine() returns a handle to the ENGINE that has been set for this DH
+object, or NULL if no such ENGINE has been set.
+
+The DH_get_length() and DH_set_length() functions get and set the optional
+length parameter associated with this DH object. If the length is non-zero then
+it is used, otherwise it is ignored. The B<length> parameter indicates the
+length of the secret exponent (private key) in bits.
+
+=head1 RETURN VALUES
+
+DH_set0_pqg() and DH_set0_key() return 1 on success or 0 on failure.
+
+DH_test_flags() returns the current state of the flags in the DH object.
+
+DH_get0_engine() returns the ENGINE set for the DH object or NULL if no ENGINE
+has been set.
+
+DH_get_length() returns the length of the secret exponent (private key) in bits,
+or zero if no such length has been explicitly set.
+
+=head1 SEE ALSO
+
+L<dh(3)>, L<DH_new(3)>, L<DH_generate_parameters(3)>, L<DH_generate_key(3)>,
+L<DH_set_method(3)>, L<DH_size(3)>, L<DH_meth_new(3)>
+
+=head1 HISTORY
+
+The functions described here were added in OpenSSL version 1.1.0.
+
+=cut
diff --git a/doc/crypto/DH_meth_new.pod b/doc/crypto/DH_meth_new.pod
new file mode 100644
index 0000000000..73222be7e4
--- /dev/null
+++ b/doc/crypto/DH_meth_new.pod
@@ -0,0 +1,148 @@
+=pod
+
+=head1 NAME
+
+DH_meth_new, DH_meth_free, DH_meth_dup, DH_meth_get0_name, DH_meth_set1_name,
+DH_meth_get_flags, DH_meth_set_flags, DH_meth_get0_app_data,
+DH_meth_set0_app_data, DH_meth_get_generate_key, DH_meth_set_generate_key,
+DH_meth_get_compute_key, DH_meth_set_compute_key, DH_meth_get_bn_mod_exp,
+DH_meth_set_bn_mod_exp, DH_meth_get_init, DH_meth_set_init, DH_meth_get_finish,
+DH_meth_set_finish, DH_meth_get_generate_params,
+DH_meth_set_generate_params - Routines to build up DH methods
+
+=head1 SYNOPSIS
+
+ #include <openssl/dh.h>
+
+ DH_METHOD *DH_meth_new(const char *name, int flags);
+ void DH_meth_free(DH_METHOD *dhm);
+ DH_METHOD *DH_meth_dup(const DH_METHOD *dhm);
+ const char *DH_meth_get0_name(const DH_METHOD *dhm);
+ int DH_meth_set1_name(DH_METHOD *dhm, const char *name);
+ int DH_meth_get_flags(DH_METHOD *dhm);
+ int DH_meth_set_flags(DH_METHOD *dhm, int flags);
+ void *DH_meth_get0_app_data(const DH_METHOD *dhm);
+ int DH_meth_set0_app_data(DH_METHOD *dhm, void *app_data);
+ int (*DH_meth_get_generate_key(const DH_METHOD *dhm)) (DH *);
+ int DH_meth_set_generate_key(DH_METHOD *dhm, int (*generate_key) (DH *));
+ int (*DH_meth_get_compute_key(const DH_METHOD *dhm))
+         (unsigned char *key, const BIGNUM *pub_key, DH *dh);
+ int DH_meth_set_compute_key(DH_METHOD *dhm,
+         int (*compute_key) (unsigned char *key, const BIGNUM *pub_key, DH *dh));
+ int (*DH_meth_get_bn_mod_exp(const DH_METHOD *dhm))
+     (const DH *dh, BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
+      const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);
+ int DH_meth_set_bn_mod_exp(DH_METHOD *dhm,
+     int (*bn_mod_exp) (const DH *dh, BIGNUM *r, const BIGNUM *a,
+                        const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx,
+                        BN_MONT_CTX *m_ctx));
+ int (*DH_meth_get_init(const DH_METHOD *dhm))(DH *);
+ int DH_meth_set_init(DH_METHOD *dhm, int (*init)(DH *));
+ int (*DH_meth_get_finish(const DH_METHOD *dhm)) (DH *);
+ int DH_meth_set_finish(DH_METHOD *dhm, int (*finish) (DH *));
+ int (*DH_meth_get_generate_params(const DH_METHOD *dhm))
+         (DH *, int, int, BN_GENCB *);
+ int DH_meth_set_generate_params(DH_METHOD *dhm,
+         int (*generate_params) (DH *, int, int, BN_GENCB *));
+
+=head1 DESCRIPTION
+
+The B<DH_METHOD> type is a structure used for the provision of custom DH
+implementations. It provides a set of of functions used by OpenSSL for the
+implementation of the various DH capabilities. See the L<dh(3)> page for more
+information.
+
+DH_meth_new() creates a new B<DH_METHOD> structure. It should be given a
+unique B<name> and a set of B<flags>. The B<name> should be a NULL terminated
+string, which will be duplicated and stored in the B<DH_METHOD> object. It is
+the callers responsibility to free the original string. The flags will be used
+during the construction of a new B<DH> object based on this B<DH_METHOD>. Any
+new B<DH> object will have those flags set by default.
+
+DH_meth_dup() creates a duplicate copy of the B<DH_METHOD> object passed as a
+parameter. This might be useful for creating a new B<DH_METHOD> based on an
+existing one, but with some differences.
+
+DH_meth_free() destroys a B<DH_METHOD> structure and frees up any memory
+associated with it.
+
+DH_meth_get0_name() will return a pointer to the name of this DH_METHOD. This
+is a pointer to the internal name string and so should not be freed by the
+caller. DH_meth_set1_name() sets the name of the DH_METHOD to B<name>. The
+string is duplicated and the copy is stored in the DH_METHOD structure, so the
+caller remains responsible for freeing the memory associated with the name.
+
+DH_meth_get_flags() returns the current value of the flags associated with this
+DH_METHOD. DH_meth_set_flags() provides the ability to set these flags.
+
+The functions DH_meth_get0_app_data() and DH_meth_set0_app_data() provide the
+ability to associate implementation specific data with the DH_METHOD. It is
+the application's responsibility to free this data before the DH_METHOD is
+freed via a call to DH_meth_free().
+
+DH_meth_get_generate_key() and DH_meth_set_generate_key() get and set the
+function used for generating a new DH key pair respectively. This function will
+be called in response to the application calling DH_generate_key(). The
+parameter for the function has the same meaning as for DH_generate_key().
+
+DH_meth_get_compute_key() and DH_meth_set_compute_key() get and set the
+function used for computing a new DH shared secret respectively. This function
+will be called in response to the application calling DH_compute_key(). The
+parameters for the function have the same meaning as for DH_compute_key().
+
+DH_meth_get_bn_mod_exp() and DH_meth_set_bn_mod_exp() get and set the function
+used for computing the following value:
+
+ r = a ^ p mod m
+
+This function will be called by the default OpenSSL function for
+DH_generate_key(). The result is stored in the B<r> parameter. This function
+may be NULL unless using the default generate key function, in which case it
+must be present.
+
+DH_meth_get_init() and DH_meth_set_init() get and set the function used
+for creating a new DH instance respectively. This function will be
+called in response to the application calling DH_new() (if the current default
+DH_METHOD is this one) or DH_new_method(). The DH_new() and DH_new_method()
+functions will allocate the memory for the new DH object, and a pointer to this
+newly allocated structure will be passed as a parameter to the function. This
+function may be NULL.
+
+DH_meth_get_finish() and DH_meth_set_finish() get and set the function used
+for destroying an instance of a DH object respectively. This function will be
+called in response to the application calling DH_free(). A pointer to the DH
+to be destroyed is passed as a parameter. The destroy function should be used
+for DH implementation specific clean up. The memory for the DH itself should
+not be freed by this function. This function may be NULL.
+
+DH_meth_get_generate_params() and DH_meth_set_generate_params() get and set the
+function used for generating DH parameters respectively. This function will be
+called in response to the application calling DH_generate_parameters_ex() (or
+DH_generate_parameters()). The parameters for the function have the same
+meaning as for DH_generate_parameters_ex(). This function may be NULL.
+
+=head1 RETURN VALUES
+
+DH_meth_new() and DH_meth_dup() return the newly allocated DH_METHOD object
+or NULL on failure.
+
+DH_meth_get0_name() and DH_meth_get_flags() return the name and flags
+associated with the DH_METHOD respectively.
+
+All other DH_meth_get_*() functions return the appropriate function pointer
+that has been set in the DH_METHOD, or NULL if no such pointer has yet been
+set.
+
+DH_meth_set1_name() and all DH_meth_set_*() functions return 1 on success or
+0 on failure.
+
+=head1 SEE ALSO
+
+L<dh(3)>, L<DH_new(3)>, L<DH_generate_parameters(3)>, L<DH_generate_key(3)>,
+L<DH_set_method(3)>, L<DH_size(3)>, L<DH_get0_pqg(3)>
+
+=head1 HISTORY
+
+The functions described here were added in OpenSSL version 1.1.0.
+
+=cut
diff --git a/doc/crypto/DH_set_method.pod b/doc/crypto/DH_set_method.pod
index 62d1ee192b..fe26b01483 100644
--- a/doc/crypto/DH_set_method.pod
+++ b/doc/crypto/DH_set_method.pod
@@ -52,35 +52,8 @@ be used for the DH operations. If B<engine> is NULL, the default ENGINE for DH
 operations is used, and if no default ENGINE is set, the DH_METHOD controlled by
 DH_set_default_method() is used.
 
-=head1 THE DH_METHOD STRUCTURE
-
- typedef struct dh_meth_st
- {
-     /* name of the implementation */
-	const char *name;
-
-     /* generate private and public DH values for key agreement */
-        int (*generate_key)(DH *dh);
-
-     /* compute shared secret */
-        int (*compute_key)(unsigned char *key, BIGNUM *pub_key, DH *dh);
-
-     /* compute r = a ^ p mod m (May be NULL for some implementations) */
-        int (*bn_mod_exp)(DH *dh, BIGNUM *r, BIGNUM *a, const BIGNUM *p,
-                                const BIGNUM *m, BN_CTX *ctx,
-                                BN_MONT_CTX *m_ctx);
-
-     /* called at DH_new */
-        int (*init)(DH *dh);
-
-     /* called at DH_free */
-        int (*finish)(DH *dh);
-
-        int flags;
-
-        char *app_data; /* ?? */
-
- } DH_METHOD;
+A new DH_METHOD object may be constructed using DH_meth_new() (see
+L<DH_meth_new(3)>).
 
 =head1 RETURN VALUES
 
@@ -99,6 +72,6 @@ returns a pointer to the newly allocated structure.
 
 =head1 SEE ALSO
 
-L<dh(3)>, L<DH_new(3)>
+L<dh(3)>, L<DH_new(3)>, L<DH_meth_new(3)>
 
 =cut
diff --git a/doc/crypto/dh.pod b/doc/crypto/dh.pod
index ce6a110895..b1eaa480b7 100644
--- a/doc/crypto/dh.pod
+++ b/doc/crypto/dh.pod
@@ -38,25 +38,15 @@ The generation of shared DH parameters is described in
 L<DH_generate_parameters(3)>; L<DH_generate_key(3)> describes how
 to perform a key agreement.
 
-The B<DH> structure consists of several BIGNUM components.
-
- struct
-        {
-        BIGNUM *p;		// prime number (shared)
-        BIGNUM *g;		// generator of Z_p (shared)
-        BIGNUM *priv_key;	// private DH value x
-        BIGNUM *pub_key;	// public DH value g^x
-        // ...
-        };
- DH
+The B<DH> structure consists of several BIGNUM components. The prime B<p>, the
+generate B<g>, the Private key B<priv_key> and the public key B<pub_key>.
+Optionally there may also be an additional parameter B<q>.
 
 Note that DH keys may use non-standard B<DH_METHOD> implementations,
 either directly or by the use of B<ENGINE> modules. In some cases (eg. an
 ENGINE providing support for hardware-embedded keys), these BIGNUM values
 will not be used by the implementation or may be used for alternative data
-storage. For this reason, applications should generally avoid using DH
-structure elements directly and instead use API functions to query or
-modify keys.
+storage.
 
 =head1 SEE ALSO
 
@@ -65,7 +55,7 @@ L<rand(3)>, L<rsa(3)>, L<engine(3)>,
 L<DH_set_method(3)>, L<DH_new(3)>,
 L<DH_get_ex_new_index(3)>,
 L<DH_generate_parameters(3)>,
-L<DH_compute_key(3)>, L<d2i_DHparams(3)>,
+L<DH_compute_key(3)>, L<DH_get0_pqg(3)>, L<DH_meth_new(3)>, L<d2i_DHparams(3)>,
 L<RSA_print(3)> 
 
 =cut