doc/crypto/DSA_set_method.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 DSA_set_default_openssl_method, DSA_get_default_openssl_method,
   6 DSA_set_method, DSA_new_method, DSA_OpenSSL - select DSA method
   7
   8 =head1 SYNOPSIS
   9
  10  #include <openssl/dsa.h>
  11  #include <openssl/engine.h>
  12
  13  void DSA_set_default_openssl_method(DSA_METHOD *meth);
  14
  15  DSA_METHOD *DSA_get_default_openssl_method(void);
  16
  17  int DSA_set_method(DSA *dsa, ENGINE *engine);
  18
  19  DSA *DSA_new_method(ENGINE *engine);
  20
  21  DSA_METHOD *DSA_OpenSSL(void);
  22
  23 =head1 DESCRIPTION
  24
  25 A B<DSA_METHOD> specifies the functions that OpenSSL uses for DSA
  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 DSA_OpenSSL() returns a pointer to that method.
  31
  32 DSA_set_default_openssl_method() makes B<meth> the default method for
  33 all DSA structures created later. B<NB:> This is true only whilst the
  34 default engine for DSA operations remains as "openssl". ENGINEs
  35 provide an encapsulation for implementations of one or more algorithms at a
  36 time, and all the DSA functions mentioned here operate within the scope
  37 of the default "openssl" engine.
  38
  39 DSA_get_default_openssl_method() returns a pointer to the current default
  40 method for the "openssl" engine.
  41
  42 DSA_set_method() selects B<engine> for all operations using the structure B<dsa>.
  43
  44 DSA_new_method() allocates and initializes a DSA structure so that
  45 B<engine> will be used for the DSA operations. If B<engine> is NULL,
  46 the default engine for DSA operations is used.
  47
  48 =head1 THE DSA_METHOD STRUCTURE
  49
  50 struct
  51  {
  52      /* name of the implementation */
  53         const char *name;
  54
  55      /* sign */
  56         DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen,
  57                                  DSA *dsa);
  58
  59      /* pre-compute k^-1 and r */
  60         int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp,
  61                                  BIGNUM **rp);
  62
  63      /* verify */
  64         int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len,
  65                                  DSA_SIG *sig, DSA *dsa);
  66
  67      /* compute rr = a1^p1 * a2^p2 mod m (May be NULL for some
  68                                           implementations) */
  69         int (*dsa_mod_exp)(DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1,
  70                                  BIGNUM *a2, BIGNUM *p2, BIGNUM *m,
  71                                  BN_CTX *ctx, BN_MONT_CTX *in_mont);
  72
  73      /* compute r = a ^ p mod m (May be NULL for some implementations) */
  74         int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a,
  75                                  const BIGNUM *p, const BIGNUM *m,
  76                                  BN_CTX *ctx, BN_MONT_CTX *m_ctx);
  77
  78      /* called at DSA_new */
  79         int (*init)(DSA *DSA);
  80
  81      /* called at DSA_free */
  82         int (*finish)(DSA *DSA);
  83
  84         int flags;
  85
  86         char *app_data; /* ?? */
  87
  88  } DSA_METHOD;
  89
  90 =head1 RETURN VALUES
  91
  92 DSA_OpenSSL() and DSA_get_default_openssl_method() return pointers to the
  93 respective B<DSA_METHOD>s.
  94
  95 DSA_set_default_openssl_method() returns no value.
  96
  97 DSA_set_method() returns non-zero if the ENGINE associated with B<dsa>
  98 was successfully changed to B<engine>.
  99
 100 DSA_new_method() returns NULL and sets an error code that can be
 101 obtained by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation
 102 fails. Otherwise it returns a pointer to the newly allocated structure.
 103
 104 =head1 SEE ALSO
 105
 106 L<dsa(3)|dsa(3)>, L<DSA_new(3)|DSA_new(3)>
 107
 108 =head1 HISTORY
 109
 110 DSA_set_default_method(), DSA_get_default_method(), DSA_set_method(),
 111 DSA_new_method() and DSA_OpenSSL() were added in OpenSSL 0.9.4.
 112
 113 DSA_set_default_openssl_method() and DSA_get_default_openssl_method()
 114 replaced DSA_set_default_method() and DSA_get_default_method() respectively,
 115 and DSA_set_method() and DSA_new_method() were altered to use B<ENGINE>s
 116 rather than B<DSA_METHOD>s during development of OpenSSL 0.9.6.
 117
 118 =cut