From: Matt Caswell Date: Thu, 7 Apr 2016 14:24:23 +0000 (+0100) Subject: Add documentation for following DH and DH_METHOD opacity X-Git-Tag: OpenSSL_1_1_0-pre5~89 X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=commitdiff_plain;h=0263b992881a03bd98bfd6b76ca54626205e9229 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 --- 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 + + 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

, B and B. Note that the B +parameter is optional. It also contains a public key (B) and +(optionally) a private key (B). + +The B

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

, B and B values can be set by calling DH_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 DH object, +and therefore the values that have been passed in should not be freed directly +after this function has been called. The B 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 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 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 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, 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/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 + + 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 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 page for more +information. + +DH_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. + +DH_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. + +DH_meth_free() destroys a B 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. 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 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, 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/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 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). =head1 RETURN VALUES @@ -99,6 +72,6 @@ returns a pointer to the newly allocated structure. =head1 SEE ALSO -L, L +L, L, L =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; L describes how to perform a key agreement. -The B 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 structure consists of several BIGNUM components. The prime B

, the +generate B, the Private key B and the public key B. +Optionally there may also be an additional parameter B. Note that DH keys may use non-standard B implementations, either directly or by the use of B 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, L, L, L, L, L, L, -L, L, +L, L, L, L, L =cut