doc/crypto/DH_set_method.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 DH_set_default_openssl_method, DH_get_default_openssl_method,
   6 DH_set_method, DH_new_method, DH_OpenSSL - select DH method
   7
   8 =head1 SYNOPSIS
   9
  10  #include <openssl/dh.h>
  11  #include <openssl/engine.h>
  12
  13  void DH_set_default_openssl_method(DH_METHOD *meth);
  14
  15  DH_METHOD *DH_get_default_openssl_method(void);
  16
  17  int DH_set_method(DH *dh, ENGINE *engine);
  18
  19  DH *DH_new_method(ENGINE *engine);
  20
  21  DH_METHOD *DH_OpenSSL(void);
  22
  23 =head1 DESCRIPTION
  24
  25 A B<DH_METHOD> specifies the functions that OpenSSL uses for Diffie-Hellman
  26 operations. By modifying the method, alternative implementations
  27 such as hardware accelerators may be used.
  28
  29 Initially, the default is to use the OpenSSL internal implementation.
  30 DH_OpenSSL() returns a pointer to that method.
  31
  32 DH_set_default_openssl_method() makes B<meth> the default method for all DH
  33 structures created later. B<NB:> This is true only whilst the default engine
  34 for Diffie-Hellman operations remains as "openssl". ENGINEs provide an
  35 encapsulation for implementations of one or more algorithms, and all the DH
  36 functions mentioned here operate within the scope of the default
  37 "openssl" engine.
  38
  39 DH_get_default_openssl_method() returns a pointer to the current default
  40 method for the "openssl" engine.
  41
  42 DH_set_method() selects B<engine> as the engine that will be responsible for
  43 all operations using the structure B<dh>. If this function completes successfully,
  44 then the B<dh> structure will have its own functional reference of B<engine>, so
  45 the caller should remember to free their own reference to B<engine> when they are
  46 finished with it. NB: An ENGINE's DH_METHOD can be retrieved (or set) by
  47 ENGINE_get_DH() or ENGINE_set_DH().
  48
  49 DH_new_method() allocates and initializes a DH structure so that
  50 B<engine> will be used for the DH operations. If B<engine> is NULL,
  51 the default engine for Diffie-Hellman opertaions is used.
  52
  53 =head1 THE DH_METHOD STRUCTURE
  54
  55  typedef struct dh_meth_st
  56  {
  57      /* name of the implementation */
  58         const char *name;
  59
  60      /* generate private and public DH values for key agreement */
  61         int (*generate_key)(DH *dh);
  62
  63      /* compute shared secret */
  64         int (*compute_key)(unsigned char *key, BIGNUM *pub_key, DH *dh);
  65
  66      /* compute r = a ^ p mod m (May be NULL for some implementations) */
  67         int (*bn_mod_exp)(DH *dh, BIGNUM *r, BIGNUM *a, const BIGNUM *p,
  68                                 const BIGNUM *m, BN_CTX *ctx,
  69                                 BN_MONT_CTX *m_ctx);
  70
  71      /* called at DH_new */
  72         int (*init)(DH *dh);
  73
  74      /* called at DH_free */
  75         int (*finish)(DH *dh);
  76
  77         int flags;
  78
  79         char *app_data; /* ?? */
  80
  81  } DH_METHOD;
  82
  83 =head1 RETURN VALUES
  84
  85 DH_OpenSSL() and DH_get_default_openssl_method() return pointers to the
  86 respective B<DH_METHOD>s.
  87
  88 DH_set_default_openssl_method() returns no value.
  89
  90 DH_set_method() returns non-zero if the ENGINE associated with B<dh>
  91 was successfully changed to B<engine>.
  92
  93 DH_new_method() returns NULL and sets an error code that can be
  94 obtained by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation fails.
  95 Otherwise it returns a pointer to the newly allocated structure.
  96
  97 =head1 SEE ALSO
  98
  99 L<dh(3)|dh(3)>, L<DH_new(3)|DH_new(3)>
 100
 101 =head1 HISTORY
 102
 103 DH_set_default_method(), DH_get_default_method(), DH_set_method(),
 104 DH_new_method() and DH_OpenSSL() were added in OpenSSL 0.9.4.
 105
 106 DH_set_default_openssl_method() and DH_get_default_openssl_method()
 107 replaced DH_set_default_method() and DH_get_default_method() respectively,
 108 and DH_set_method() and DH_new_method() were altered to use B<ENGINE>s
 109 rather than B<DH_METHOD>s during development of OpenSSL 0.9.6.
 110
 111 =cut