1*2175Sjp161948=pod 2*2175Sjp161948 3*2175Sjp161948=head1 NAME 4*2175Sjp161948 5*2175Sjp161948DH_set_default_method, DH_get_default_method, 6*2175Sjp161948DH_set_method, DH_new_method, DH_OpenSSL - select DH method 7*2175Sjp161948 8*2175Sjp161948=head1 SYNOPSIS 9*2175Sjp161948 10*2175Sjp161948 #include <openssl/dh.h> 11*2175Sjp161948 #include <openssl/engine.h> 12*2175Sjp161948 13*2175Sjp161948 void DH_set_default_method(const DH_METHOD *meth); 14*2175Sjp161948 15*2175Sjp161948 const DH_METHOD *DH_get_default_method(void); 16*2175Sjp161948 17*2175Sjp161948 int DH_set_method(DH *dh, const DH_METHOD *meth); 18*2175Sjp161948 19*2175Sjp161948 DH *DH_new_method(ENGINE *engine); 20*2175Sjp161948 21*2175Sjp161948 const DH_METHOD *DH_OpenSSL(void); 22*2175Sjp161948 23*2175Sjp161948=head1 DESCRIPTION 24*2175Sjp161948 25*2175Sjp161948A B<DH_METHOD> specifies the functions that OpenSSL uses for Diffie-Hellman 26*2175Sjp161948operations. By modifying the method, alternative implementations 27*2175Sjp161948such as hardware accelerators may be used. IMPORTANT: See the NOTES section for 28*2175Sjp161948important information about how these DH API functions are affected by the use 29*2175Sjp161948of B<ENGINE> API calls. 30*2175Sjp161948 31*2175Sjp161948Initially, the default DH_METHOD is the OpenSSL internal implementation, as 32*2175Sjp161948returned by DH_OpenSSL(). 33*2175Sjp161948 34*2175Sjp161948DH_set_default_method() makes B<meth> the default method for all DH 35*2175Sjp161948structures created later. B<NB>: This is true only whilst no ENGINE has been set 36*2175Sjp161948as a default for DH, so this function is no longer recommended. 37*2175Sjp161948 38*2175Sjp161948DH_get_default_method() returns a pointer to the current default DH_METHOD. 39*2175Sjp161948However, the meaningfulness of this result is dependant on whether the ENGINE 40*2175Sjp161948API is being used, so this function is no longer recommended. 41*2175Sjp161948 42*2175Sjp161948DH_set_method() selects B<meth> to perform all operations using the key B<dh>. 43*2175Sjp161948This will replace the DH_METHOD used by the DH key and if the previous method 44*2175Sjp161948was supplied by an ENGINE, the handle to that ENGINE will be released during the 45*2175Sjp161948change. It is possible to have DH keys that only work with certain DH_METHOD 46*2175Sjp161948implementations (eg. from an ENGINE module that supports embedded 47*2175Sjp161948hardware-protected keys), and in such cases attempting to change the DH_METHOD 48*2175Sjp161948for the key can have unexpected results. 49*2175Sjp161948 50*2175Sjp161948DH_new_method() allocates and initializes a DH structure so that B<engine> will 51*2175Sjp161948be used for the DH operations. If B<engine> is NULL, the default ENGINE for DH 52*2175Sjp161948operations is used, and if no default ENGINE is set, the DH_METHOD controlled by 53*2175Sjp161948DH_set_default_method() is used. 54*2175Sjp161948 55*2175Sjp161948=head1 THE DH_METHOD STRUCTURE 56*2175Sjp161948 57*2175Sjp161948 typedef struct dh_meth_st 58*2175Sjp161948 { 59*2175Sjp161948 /* name of the implementation */ 60*2175Sjp161948 const char *name; 61*2175Sjp161948 62*2175Sjp161948 /* generate private and public DH values for key agreement */ 63*2175Sjp161948 int (*generate_key)(DH *dh); 64*2175Sjp161948 65*2175Sjp161948 /* compute shared secret */ 66*2175Sjp161948 int (*compute_key)(unsigned char *key, BIGNUM *pub_key, DH *dh); 67*2175Sjp161948 68*2175Sjp161948 /* compute r = a ^ p mod m (May be NULL for some implementations) */ 69*2175Sjp161948 int (*bn_mod_exp)(DH *dh, BIGNUM *r, BIGNUM *a, const BIGNUM *p, 70*2175Sjp161948 const BIGNUM *m, BN_CTX *ctx, 71*2175Sjp161948 BN_MONT_CTX *m_ctx); 72*2175Sjp161948 73*2175Sjp161948 /* called at DH_new */ 74*2175Sjp161948 int (*init)(DH *dh); 75*2175Sjp161948 76*2175Sjp161948 /* called at DH_free */ 77*2175Sjp161948 int (*finish)(DH *dh); 78*2175Sjp161948 79*2175Sjp161948 int flags; 80*2175Sjp161948 81*2175Sjp161948 char *app_data; /* ?? */ 82*2175Sjp161948 83*2175Sjp161948 } DH_METHOD; 84*2175Sjp161948 85*2175Sjp161948=head1 RETURN VALUES 86*2175Sjp161948 87*2175Sjp161948DH_OpenSSL() and DH_get_default_method() return pointers to the respective 88*2175Sjp161948B<DH_METHOD>s. 89*2175Sjp161948 90*2175Sjp161948DH_set_default_method() returns no value. 91*2175Sjp161948 92*2175Sjp161948DH_set_method() returns non-zero if the provided B<meth> was successfully set as 93*2175Sjp161948the method for B<dh> (including unloading the ENGINE handle if the previous 94*2175Sjp161948method was supplied by an ENGINE). 95*2175Sjp161948 96*2175Sjp161948DH_new_method() returns NULL and sets an error code that can be obtained by 97*2175Sjp161948L<ERR_get_error(3)|ERR_get_error(3)> if the allocation fails. Otherwise it 98*2175Sjp161948returns a pointer to the newly allocated structure. 99*2175Sjp161948 100*2175Sjp161948=head1 NOTES 101*2175Sjp161948 102*2175Sjp161948As of version 0.9.7, DH_METHOD implementations are grouped together with other 103*2175Sjp161948algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a 104*2175Sjp161948default ENGINE is specified for DH functionality using an ENGINE API function, 105*2175Sjp161948that will override any DH defaults set using the DH API (ie. 106*2175Sjp161948DH_set_default_method()). For this reason, the ENGINE API is the recommended way 107*2175Sjp161948to control default implementations for use in DH and other cryptographic 108*2175Sjp161948algorithms. 109*2175Sjp161948 110*2175Sjp161948=head1 SEE ALSO 111*2175Sjp161948 112*2175Sjp161948L<dh(3)|dh(3)>, L<DH_new(3)|DH_new(3)> 113*2175Sjp161948 114*2175Sjp161948=head1 HISTORY 115*2175Sjp161948 116*2175Sjp161948DH_set_default_method(), DH_get_default_method(), DH_set_method(), 117*2175Sjp161948DH_new_method() and DH_OpenSSL() were added in OpenSSL 0.9.4. 118*2175Sjp161948 119*2175Sjp161948DH_set_default_openssl_method() and DH_get_default_openssl_method() replaced 120*2175Sjp161948DH_set_default_method() and DH_get_default_method() respectively, and 121*2175Sjp161948DH_set_method() and DH_new_method() were altered to use B<ENGINE>s rather than 122*2175Sjp161948B<DH_METHOD>s during development of the engine version of OpenSSL 0.9.6. For 123*2175Sjp1619480.9.7, the handling of defaults in the ENGINE API was restructured so that this 124*2175Sjp161948change was reversed, and behaviour of the other functions resembled more closely 125*2175Sjp161948the previous behaviour. The behaviour of defaults in the ENGINE API now 126*2175Sjp161948transparently overrides the behaviour of defaults in the DH API without 127*2175Sjp161948requiring changing these function prototypes. 128*2175Sjp161948 129*2175Sjp161948=cut 130