From fbaedfdd4748bec057a39141faff6b396e25eac7 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Thu, 31 Mar 2016 14:22:39 +0100 Subject: [PATCH] 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 Reviewed-by: Stephen Henson --- doc/crypto/DSA_get0_pqg.pod | 82 ++++++++++++++++ doc/crypto/DSA_meth_new.pod | 177 ++++++++++++++++++++++++++++++++++ doc/crypto/DSA_set_method.pod | 47 +-------- 3 files changed, 262 insertions(+), 44 deletions(-) create mode 100644 doc/crypto/DSA_get0_pqg.pod create mode 100644 doc/crypto/DSA_meth_new.pod diff --git a/doc/crypto/DSA_get0_pqg.pod b/doc/crypto/DSA_get0_pqg.pod new file mode 100644 index 0000000000..fc79cfdebe --- /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 + + 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

, B and B. It also contains a +public key (B) and (optionally) a private key (B). + +The B

, B and B 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

, B and B values can be set by calling DSA_set0_pqg() and passing +the new values for B

, B and B 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 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 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, L, L, L, +L, L, L, L, L, +L, L + +=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 index 0000000000..278008d8c0 --- /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 + + 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 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 page for more +information. + +DSA_meth_new() creates a new B structure. It should be given a +unique B and a set of B. The B should be a NULL terminated +string, which will be duplicated and stored in the B object. It is +the callers responsibility to free the original string. The flags will be used +during the construction of a new B object based on this B. Any +new B object will have those flags set by default. + +DSA_meth_dup() creates a duplicate copy of the B object passed as a +parameter. This might be useful for creating a new B based on an +existing one, but with some differences. + +DSA_meth_free() destroys a B 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 and B. 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 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 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, L, L, L, +L, L, L, L, L, +L, L + +=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 632aadbfd3..1d56ccaab2 100644 --- 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 for information on constructing custom DSA_METHOD +objects; DSA_new_method() allocates and initializes a DSA structure so that B will be used for the DSA operations. If B 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, L +L, L, L =cut -- 2.34.1