Document functions added as a result of DSA opacity changes

A number of getters/setters have been added for examining DSA objects, as
well as a whole set of functions for creating and buildingup DSA_METHODs.

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

diff --git a/doc/crypto/DSA_get0_pqg.pod b/doc/crypto/DSA_get0_pqg.pod
new file mode 100644 (file)
index 0000000..fc79cfd
--- /dev/null
+++ b/doc/crypto/DSA_get0_pqg.pod
@@ -0,0 +1,82 @@
+=pod
+
+=head1 NAME
+
+DSA_get0_pqg, DSA_set0_pgg, DSA_get0_key, DSA_set0_key, DSA_clear_flags,
+DSA_test_flags, DSA_set_flags, DSA_get0_engine - Routines for getting and
+setting data in a DSA object
+
+=head1 SYNOPSIS
+
+ #include <openssl/dsa.h>
+
+ void DSA_get0_pqg(const DSA *d, BIGNUM **p, BIGNUM **q, BIGNUM **g);
+ int DSA_set0_pqg(DSA *d, BIGNUM *p, BIGNUM *q, BIGNUM *g);
+ void DSA_get0_key(const DSA *d, BIGNUM **pub_key, BIGNUM **priv_key);
+ int DSA_set0_key(DSA *d, BIGNUM *pub_key, BIGNUM *priv_key);
+ void DSA_clear_flags(DSA *d, int flags);
+ int DSA_test_flags(const DSA *d, int flags);
+ void DSA_set_flags(DSA *d, int flags);
+ ENGINE *DSA_get0_engine(DSA *d);
+
+=head1 DESCRIPTION
+
+A DSA object contains the parameters B<p>, B<q> and B<g>. 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 DSA_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 DSA_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 DSA object,
+and therefore the values that have been passed in should not be freed directly
+after this function has been called.
+
+To get the public and private key values use the DSA_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 DSA_set0_key(). The public
+key must always be non-NULL. The private key may be NULL. As for DSA_set0_pqg()
+this function transfers the memory management of the key values to the DSA
+object, and therefore they should not be freed directly after this function has
+been called.
+
+DSA_set_flags() sets the flags in the B<flags> parameter on the DSA object.
+Multiple flags can be passed in one go (bitwise ORed together). Any flags that
+are already set are left set. DSA_test_flags() tests to see whether the flags
+passed in the B<flags> parameter are currently set in the DSA object. Multple
+flags can be tested in one go. All flags that are currently set are returned, or
+zero if none of the flags are set. DSA_clear_flags() clears the specified flags
+within the DSA object.
+
+DSA_get0_engine() returns a handle to the ENGINE that has been set for this DSA
+object, or NULL if no such ENGINE has been set.
+
+=head1 RETURN VALUES
+
+DSA_set0_pqg() and DSA_set0_key() return 1 on success or 0 on failure.
+
+DSA_test_flags() returns the current state of the flags in the DSA object.
+
+DSA_get0_engine() returns the ENGINE set for the DSA object or NULL if no ENGINE
+has been set.
+
+=head1 SEE ALSO
+
+L<dsa>, L<DSA_new>, L<DSA_generate_parameters>, L<DSA_generate_key>,
+L<DSA_dup_DH>, L<DSA_do_sign>, L<DSA_set_method>, L<DSA_SIG_new>, L<DSA_sign>,
+L<DSA_size>, L<DSA_meth_new>
+
+=head1 HISTORY
+
+The functions described here were added in OpenSSL version 1.1.0.
+
+=cut

diff --git a/doc/crypto/DSA_meth_new.pod b/doc/crypto/DSA_meth_new.pod
new file mode 100644 (file)
index 0000000..278008d
--- /dev/null
+++ b/doc/crypto/DSA_meth_new.pod
@@ -0,0 +1,177 @@
+=pod
+
+=head1 NAME
+
+DSA_meth_new, DSA_meth_free, DSA_meth_dup, DSA_meth_get_name, DSA_meth_set_name,
+DSA_meth_get_flags, DSA_meth_set_flags, DSA_meth_get_app_data,
+DSA_meth_set_app_data, DSA_meth_get_sign, DSA_meth_set_sign,
+DSA_meth_get_sign_setup, DSA_meth_set_sign_setup, DSA_meth_get_verify,
+DSA_meth_set_verify, DSA_meth_get_mod_exp, DSA_meth_set_mod_exp,
+DSA_meth_get_bn_mod_exp, DSA_meth_set_bn_mod_exp, DSA_meth_get_init,
+DSA_meth_set_init, DSA_meth_get_finish, DSA_meth_set_finish,
+DSA_meth_get_paramgen, DSA_meth_set_paramgen, DSA_meth_get_keygen,
+DSA_meth_set_keygen  - Routines to build up DSA methods
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+
+ DSA_METHOD *DSA_meth_new(const char *name, int flags);
+ void DSA_meth_free(DSA_METHOD *dsam);
+ DSA_METHOD *DSA_meth_dup(const DSA_METHOD *meth);
+ const char *DSA_meth_get_name(const DSA_METHOD *dsam);
+ int DSA_meth_set_name(DSA_METHOD *dsam, const char *name);
+ int DSA_meth_get_flags(DSA_METHOD *dsam);
+ int DSA_meth_set_flags(DSA_METHOD *dsam, int flags);
+ void *DSA_meth_get_app_data(const DSA_METHOD *dsam);
+ int DSA_meth_set_app_data(DSA_METHOD *dsam, void *app_data);
+ DSA_SIG *(*DSA_meth_get_sign(const DSA_METHOD *dsam))
+         (const unsigned char *, int, DSA *);
+ int DSA_meth_set_sign(DSA_METHOD *dsam,
+                       DSA_SIG *(*sign) (const unsigned char *, int, DSA *));
+ int (*DSA_meth_get_sign_setup(const DSA_METHOD *dsam))
+         (DSA *, BN_CTX *, BIGNUM **, BIGNUM **);
+ int DSA_meth_set_sign_setup(DSA_METHOD *dsam,
+         int (*sign_setup) (DSA *, BN_CTX *, BIGNUM **, BIGNUM **));
+ int (*DSA_meth_get_verify(const DSA_METHOD *dsam))
+         (const unsigned char *, int , DSA_SIG *, DSA *);
+ int DSA_meth_set_verify(DSA_METHOD *dsam,
+     int (*verify) (const unsigned char *, int, DSA_SIG *, DSA *));
+ int (*DSA_meth_get_mod_exp(const DSA_METHOD *dsam))
+        (DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1, BIGNUM *a2, BIGNUM *p2,
+         BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *in_mont);
+ int DSA_meth_set_mod_exp(DSA_METHOD *dsam,
+     int (*mod_exp) (DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1, BIGNUM *a2,
+                     BIGNUM *p2, BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *mont));
+ int (*DSA_meth_get_bn_mod_exp(const DSA_METHOD *dsam))
+     (DSA *dsa, BIGNUM *r, BIGNUM *a, const BIGNUM *p, const BIGNUM *m,
+      BN_CTX *ctx, BN_MONT_CTX *mont);
+ int DSA_meth_set_bn_mod_exp(DSA_METHOD *dsam,
+     int (*bn_mod_exp) (DSA *dsa, BIGNUM *r, BIGNUM *a, const BIGNUM *p,
+                        const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *mont));
+ int (*DSA_meth_get_init(const DSA_METHOD *dsam))(DSA *);
+ int DSA_meth_set_init(DSA_METHOD *dsam, int (*init)(DSA *));
+ int (*DSA_meth_get_finish(const DSA_METHOD *dsam)) (DSA *);
+ int DSA_meth_set_finish(DSA_METHOD *dsam, int (*finish) (DSA *));
+ int (*DSA_meth_get_paramgen(const DSA_METHOD *dsam))
+         (DSA *, int, const unsigned char *, int, int *, unsigned long *,
+          BN_GENCB *);
+ int DSA_meth_set_paramgen(DSA_METHOD *dsam,
+         int (*paramgen) (DSA *, int, const unsigned char *, int, int *,
+                          unsigned long *, BN_GENCB *));
+ int (*DSA_meth_get_keygen(const DSA_METHOD *dsam)) (DSA *);
+ int DSA_meth_set_keygen(DSA_METHOD *dsam, int (*keygen) (DSA *));
+
+=head1 DESCRIPTION
+
+The B<DSA_METHOD> type is a structure used for the provision of custom DSA
+implementations. It provides a set of of functions used by OpenSSL for the
+implementation of the various DSA capabilities. See the L<dsa> page for more
+information.
+
+DSA_meth_new() creates a new B<DSA_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<DSA_METHOD> object. It is
+the callers responsibility to free the original string. The flags will be used
+during the construction of a new B<DSA> object based on this B<DSA_METHOD>. Any
+new B<DSA> object will have those flags set by default.
+
+DSA_meth_dup() creates a duplicate copy of the B<DSA_METHOD> object passed as a
+parameter. This might be useful for creating a new B<DSA_METHOD> based on an
+existing one, but with some differences.
+
+DSA_meth_free() destroys a B<DSA_METHOD> structure and frees up any memory
+associated with it.
+
+DSA_meth_get_flags() returns the current value of the flags associated with this
+DSA_METHOD. DSA_meth_set_flags() provides the ability to set these flags.
+
+The functions DSA_meth_get_app_data() and DSA_meth_set_app_data() provide the
+ability to associate implementation specific data with the DSA_METHOD. It is
+the application's responsibility to free this data before the DSA_METHOD is
+freed via a call to DSA_meth_free().
+
+DSA_meth_get_sign() and DSA_meth_set_sign() get and set the function used for
+creating a DSA signature respectively. This function will be
+called in response to the application calling DSA_do_sign() (or DSA_sign()). The
+parameters for the function have the same meaning as for DSA_do_sign().
+
+DSA_meth_get_sign_setup() and DSA_meth_set_sign_setup() get and set the function
+used for precalculating the DSA signature values B<k^-1> and B<r>. This function
+will be called in response to the application calling DSA_sign_setup(). The
+parameters for the function have the same meaning as for DSA_sign_setup().
+
+DSA_meth_get_verify() and DSA_meth_set_verify() get and set the function used
+for verifying a DSA signature respectively. This function will be called in
+response to the application calling DSA_do_verify() (or DSA_verify()). The
+parameters for the function have the same meaning as for DSA_do_verify().
+
+DSA_meth_get_mod_exp() and DSA_meth_set_mod_exp() get and set the function used
+for computing the following value:
+
+ rr = a1^p1 * a2^p2 mod m
+
+This function will be called by the default OpenSSL method during verification
+of a DSA signature. The result is stored in the B<rr> parameter. This function
+may be NULL.
+
+DSA_meth_get_bn_mod_exp() and DSA_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
+DSA_sign_setup(). The result is stored in the B<r> parameter. This function
+may be NULL.
+
+DSA_meth_get_init() and DSA_meth_set_init() get and set the function used
+for creating a new DSA instance respectively. This function will be
+called in response to the application calling DSA_new() (if the current default
+DSA_METHOD is this one) or DSA_new_method(). The DSA_new() and DSA_new_method()
+functions will allocate the memory for the new DSA object, and a pointer to this
+newly allocated structure will be passed as a parameter to the function. This
+function may be NULL.
+
+DSA_meth_get_finish() and DSA_meth_set_finish() get and set the function used
+for destroying an instance of a DSA object respectively. This function will be
+called in response to the application calling DSA_free(). A pointer to the DSA
+to be destroyed is passed as a parameter. The destroy function should be used
+for DSA implementation specific clean up. The memory for the DSA itself should
+not be freed by this function. This function may be NULL.
+
+DSA_meth_get_paramgen() and DSA_meth_set_paramgen() get and set the function
+used for generating DSA parameters respectively. This function will be called in
+response to the application calling DSA_generate_parameters_ex() (or
+DSA_generate_parameters()). The parameters for the function have the same
+meaning as for DSA_generate_parameters_ex().
+
+DSA_meth_get_keygen() and DSA_meth_set_keygen() get and set the function
+used for generating a new DSA key pair respectively. This function will be
+called in response to the application calling DSA_generate_key(). The parameter
+for the function has the same meaning as for DSA_generate_key().
+
+=head1 RETURN VALUES
+
+DSA_meth_new() and DSA_meth_dup() return the newly allocated DSA_METHOD object
+or NULL on failure.
+
+DSA_meth_get_name() and DSA_meth_get_flags() return the name and flags
+associated with the DSA_METHOD respectively.
+
+All other DSA_meth_get_*() functions return the appropriate function pointer
+that has been set in the DSA_METHOD, or NULL if no such pointer has yet been
+set.
+
+All DSA_meth_set_*() functions return 1 on success or 0 on failure.
+
+=head1 SEE ALSO
+
+L<dsa>, L<DSA_new>, L<DSA_generate_parameters>, L<DSA_generate_key>,
+L<DSA_dup_DH>, L<DSA_do_sign>, L<DSA_set_method>, L<DSA_SIG_new>, L<DSA_sign>,
+L<DSA_size>, L<DSA_get0_p>
+
+=head1 HISTORY
+
+The functions described here were added in OpenSSL version 1.1.0.
+
+=cut

diff --git a/doc/crypto/DSA_set_method.pod b/doc/crypto/DSA_set_method.pod
index 632aadbfd3e35ad849a9a274b42bd077a78b969d..1d56ccaab289642b7a1f6a3e8b78cd8b8363419e 100644 (file)
--- a/doc/crypto/DSA_set_method.pod
+++ b/doc/crypto/DSA_set_method.pod
@@ -47,55 +47,14 @@ be released during the change. It is possible to have DSA keys that only
 work with certain DSA_METHOD implementations (eg. from an ENGINE module
 that supports embedded hardware-protected keys), and in such cases
 attempting to change the DSA_METHOD for the key can have unexpected
-results.
+results. See L<DSA_meth_new> for information on constructing custom DSA_METHOD
+objects;
 
 DSA_new_method() allocates and initializes a DSA structure so that B<engine>
 will be used for the DSA operations. If B<engine> is NULL, the default engine
 for DSA operations is used, and if no default ENGINE is set, the DSA_METHOD
 controlled by DSA_set_default_method() is used.
 
-=head1 THE DSA_METHOD STRUCTURE
-
-struct
- {
-     /* name of the implementation */
-        const char *name;
-
-     /* sign */
-       DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen,
-                                 DSA *dsa);
-
-     /* pre-compute k^-1 and r */
-       int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp,
-                                 BIGNUM **rp);
-
-     /* verify */
-       int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len,
-                                 DSA_SIG *sig, DSA *dsa);
-
-     /* compute rr = a1^p1 * a2^p2 mod m (May be NULL for some
-                                          implementations) */
-       int (*dsa_mod_exp)(DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1,
-                                 BIGNUM *a2, BIGNUM *p2, BIGNUM *m,
-                                 BN_CTX *ctx, BN_MONT_CTX *in_mont);
-
-     /* compute r = a ^ p mod m (May be NULL for some implementations) */
-        int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a,
-                                 const BIGNUM *p, const BIGNUM *m,
-                                 BN_CTX *ctx, BN_MONT_CTX *m_ctx);
-
-     /* called at DSA_new */
-        int (*init)(DSA *DSA);
-
-     /* called at DSA_free */
-        int (*finish)(DSA *DSA);
-
-        int flags;
-
-        char *app_data; /* ?? */
-
- } DSA_METHOD;
-
 =head1 RETURN VALUES
 
 DSA_OpenSSL() and DSA_get_default_method() return pointers to the respective
@@ -113,6 +72,6 @@ fails. Otherwise it returns a pointer to the newly allocated structure.
 
 =head1 SEE ALSO
 
-L<dsa(3)>, L<DSA_new(3)>
+L<dsa(3)>, L<DSA_new(3)>, L<DSA_meth_new(3)>
 
 =cut