159191Skris=pod 259191Skris 359191Skris=head1 NAME 459191Skris 5109998SmarkmDH_set_default_method, DH_get_default_method, 6109998SmarkmDH_set_method, DH_new_method, DH_OpenSSL - select DH method 759191Skris 859191Skris=head1 SYNOPSIS 959191Skris 1059191Skris #include <openssl/dh.h> 11109998Smarkm #include <openssl/engine.h> 1259191Skris 13109998Smarkm void DH_set_default_method(const DH_METHOD *meth); 1459191Skris 15109998Smarkm const DH_METHOD *DH_get_default_method(void); 1659191Skris 17109998Smarkm int DH_set_method(DH *dh, const DH_METHOD *meth); 1859191Skris 19109998Smarkm DH *DH_new_method(ENGINE *engine); 2059191Skris 21109998Smarkm const DH_METHOD *DH_OpenSSL(void); 2259191Skris 2359191Skris=head1 DESCRIPTION 2459191Skris 2559191SkrisA B<DH_METHOD> specifies the functions that OpenSSL uses for Diffie-Hellman 2659191Skrisoperations. By modifying the method, alternative implementations 27109998Smarkmsuch as hardware accelerators may be used. IMPORTANT: See the NOTES section for 28109998Smarkmimportant information about how these DH API functions are affected by the use 29109998Smarkmof B<ENGINE> API calls. 3059191Skris 31109998SmarkmInitially, the default DH_METHOD is the OpenSSL internal implementation, as 32109998Smarkmreturned by DH_OpenSSL(). 3359191Skris 34109998SmarkmDH_set_default_method() makes B<meth> the default method for all DH 35109998Smarkmstructures created later. B<NB>: This is true only whilst no ENGINE has been set 36109998Smarkmas a default for DH, so this function is no longer recommended. 3759191Skris 38109998SmarkmDH_get_default_method() returns a pointer to the current default DH_METHOD. 39194206SsimonHowever, the meaningfulness of this result is dependent on whether the ENGINE 40109998SmarkmAPI is being used, so this function is no longer recommended. 4159191Skris 42109998SmarkmDH_set_method() selects B<meth> to perform all operations using the key B<dh>. 43109998SmarkmThis will replace the DH_METHOD used by the DH key and if the previous method 44109998Smarkmwas supplied by an ENGINE, the handle to that ENGINE will be released during the 45109998Smarkmchange. It is possible to have DH keys that only work with certain DH_METHOD 46109998Smarkmimplementations (eg. from an ENGINE module that supports embedded 47109998Smarkmhardware-protected keys), and in such cases attempting to change the DH_METHOD 48109998Smarkmfor the key can have unexpected results. 4959191Skris 50109998SmarkmDH_new_method() allocates and initializes a DH structure so that B<engine> will 51109998Smarkmbe used for the DH operations. If B<engine> is NULL, the default ENGINE for DH 52109998Smarkmoperations is used, and if no default ENGINE is set, the DH_METHOD controlled by 53109998SmarkmDH_set_default_method() is used. 5459191Skris 5559191Skris=head1 THE DH_METHOD STRUCTURE 5659191Skris 5759191Skris typedef struct dh_meth_st 5859191Skris { 5959191Skris /* name of the implementation */ 6059191Skris const char *name; 6159191Skris 6259191Skris /* generate private and public DH values for key agreement */ 6359191Skris int (*generate_key)(DH *dh); 6459191Skris 6559191Skris /* compute shared secret */ 6659191Skris int (*compute_key)(unsigned char *key, BIGNUM *pub_key, DH *dh); 6759191Skris 6859191Skris /* compute r = a ^ p mod m (May be NULL for some implementations) */ 6959191Skris int (*bn_mod_exp)(DH *dh, BIGNUM *r, BIGNUM *a, const BIGNUM *p, 7059191Skris const BIGNUM *m, BN_CTX *ctx, 7159191Skris BN_MONT_CTX *m_ctx); 7259191Skris 7359191Skris /* called at DH_new */ 7459191Skris int (*init)(DH *dh); 7559191Skris 7659191Skris /* called at DH_free */ 7759191Skris int (*finish)(DH *dh); 7859191Skris 7959191Skris int flags; 8059191Skris 8159191Skris char *app_data; /* ?? */ 8259191Skris 8359191Skris } DH_METHOD; 8459191Skris 8559191Skris=head1 RETURN VALUES 8659191Skris 8768651SkrisDH_OpenSSL() and DH_get_default_method() return pointers to the respective 8868651SkrisB<DH_METHOD>s. 8959191Skris 9059191SkrisDH_set_default_method() returns no value. 9159191Skris 92109998SmarkmDH_set_method() returns non-zero if the provided B<meth> was successfully set as 93109998Smarkmthe method for B<dh> (including unloading the ENGINE handle if the previous 94109998Smarkmmethod was supplied by an ENGINE). 9559191Skris 96109998SmarkmDH_new_method() returns NULL and sets an error code that can be obtained by 97109998SmarkmL<ERR_get_error(3)|ERR_get_error(3)> if the allocation fails. Otherwise it 9859191Skrisreturns a pointer to the newly allocated structure. 9959191Skris 100109998Smarkm=head1 NOTES 101109998Smarkm 102109998SmarkmAs of version 0.9.7, DH_METHOD implementations are grouped together with other 103109998Smarkmalgorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a 104109998Smarkmdefault ENGINE is specified for DH functionality using an ENGINE API function, 105109998Smarkmthat will override any DH defaults set using the DH API (ie. 106109998SmarkmDH_set_default_method()). For this reason, the ENGINE API is the recommended way 107109998Smarkmto control default implementations for use in DH and other cryptographic 108109998Smarkmalgorithms. 109109998Smarkm 11059191Skris=head1 SEE ALSO 11159191Skris 11259191SkrisL<dh(3)|dh(3)>, L<DH_new(3)|DH_new(3)> 11359191Skris 11459191Skris=head1 HISTORY 11559191Skris 11659191SkrisDH_set_default_method(), DH_get_default_method(), DH_set_method(), 11759191SkrisDH_new_method() and DH_OpenSSL() were added in OpenSSL 0.9.4. 11859191Skris 119109998SmarkmDH_set_default_openssl_method() and DH_get_default_openssl_method() replaced 120109998SmarkmDH_set_default_method() and DH_get_default_method() respectively, and 121109998SmarkmDH_set_method() and DH_new_method() were altered to use B<ENGINE>s rather than 122109998SmarkmB<DH_METHOD>s during development of the engine version of OpenSSL 0.9.6. For 123109998Smarkm0.9.7, the handling of defaults in the ENGINE API was restructured so that this 124109998Smarkmchange was reversed, and behaviour of the other functions resembled more closely 125109998Smarkmthe previous behaviour. The behaviour of defaults in the ENGINE API now 126109998Smarkmtransparently overrides the behaviour of defaults in the DH API without 127109998Smarkmrequiring changing these function prototypes. 128109998Smarkm 12959191Skris=cut 130