lib/libcrypto/man/DSA_set_method.3

   1 .\"     $OpenBSD: DSA_set_method.3,v 1.9 2018/04/18 01:09:01 schwarze Exp $
   2 .\"     OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
   3 .\"
   4 .\" This file was written by Ulf Moeller <ulf@openssl.org>.
   5 .\" Copyright (c) 2000, 2002, 2007 The OpenSSL Project.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\"
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in
  16 .\"    the documentation and/or other materials provided with the
  17 .\"    distribution.
  18 .\"
  19 .\" 3. All advertising materials mentioning features or use of this
  20 .\"    software must display the following acknowledgment:
  21 .\"    "This product includes software developed by the OpenSSL Project
  22 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  23 .\"
  24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  25 .\"    endorse or promote products derived from this software without
  26 .\"    prior written permission. For written permission, please contact
  27 .\"    openssl-core@openssl.org.
  28 .\"
  29 .\" 5. Products derived from this software may not be called "OpenSSL"
  30 .\"    nor may "OpenSSL" appear in their names without prior written
  31 .\"    permission of the OpenSSL Project.
  32 .\"
  33 .\" 6. Redistributions of any form whatsoever must retain the following
  34 .\"    acknowledgment:
  35 .\"    "This product includes software developed by the OpenSSL Project
  36 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  37 .\"
  38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  41 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  50 .\"
  51 .Dd $Mdocdate: April 18 2018 $
  52 .Dt DSA_SET_METHOD 3
  53 .Os
  54 .Sh NAME
  55 .Nm DSA_set_default_method ,
  56 .Nm DSA_get_default_method ,
  57 .Nm DSA_set_method ,
  58 .Nm DSA_new_method ,
  59 .Nm DSA_OpenSSL
  60 .Nd select DSA method
  61 .Sh SYNOPSIS
  62 .In openssl/dsa.h
  63 .Ft void
  64 .Fo DSA_set_default_method
  65 .Fa "const DSA_METHOD *meth"
  66 .Fc
  67 .Ft const DSA_METHOD *
  68 .Fn DSA_get_default_method void
  69 .Ft int
  70 .Fo DSA_set_method
  71 .Fa "DSA *dsa"
  72 .Fa "const DSA_METHOD *meth"
  73 .Fc
  74 .Ft DSA *
  75 .Fo DSA_new_method
  76 .Fa "ENGINE *engine"
  77 .Fc
  78 .Ft DSA_METHOD *
  79 .Fn DSA_OpenSSL void
  80 .Sh DESCRIPTION
  81 A
  82 .Vt DSA_METHOD
  83 object contains pointers to the functions used for DSA operations.
  84 By default, the internal implementation returned by
  85 .Fn DSA_OpenSSL
  86 is used.
  87 By selecting another method, alternative implementations
  88 such as hardware accelerators may be used.
  89 .Pp
  90 .Fn DSA_set_default_method
  91 selects
  92 .Fa meth
  93 as the default method for all
  94 .Vt DSA
  95 structures created later.
  96 If any
  97 .Vt ENGINE
  98 was registered with
  99 .Xr ENGINE_register_DSA 3
 100 that can be successfully initialized, it overrides the default.
 101 .Pp
 102 .Fn DSA_get_default_method
 103 returns a pointer to the current default method,
 104 even if it is actually overridded by an
 105 .Vt ENGINE .
 106 .Pp
 107 .Fn DSA_set_method
 108 selects
 109 .Fa meth
 110 to perform all operations using the key
 111 .Fa dsa .
 112 This replaces the
 113 .Vt DSA_METHOD
 114 used by the DSA key and if the previous method was supplied by an
 115 .Vt ENGINE ,
 116 .Xr ENGINE_finish 3
 117 is called on it.
 118 It is possible to have DSA keys that only work with certain
 119 .Vt DSA_METHOD
 120 implementations (e.g. from an
 121 .Vt ENGINE
 122 module that supports embedded hardware-protected keys),
 123 and in such cases attempting to change the
 124 .Vt DSA_METHOD
 125 for the key can have unexpected results.
 126 .Pp
 127 .Fn DSA_new_method
 128 allocates and initializes a
 129 .Vt DSA
 130 structure so that
 131 .Fa engine
 132 is used for the DSA operations.
 133 If
 134 .Fa engine
 135 is
 136 .Dv NULL ,
 137 .Xr ENGINE_get_default_DSA 3
 138 is used.
 139 If that returns
 140 .Dv NULL ,
 141 the default method controlled by
 142 .Fn DSA_set_default_method
 143 is used.
 144 .Pp
 145 The
 146 .Vt DSA_METHOD
 147 structure is defined as follows:
 148 .Bd -literal
 149 struct
 150 {
 151      /* name of the implementation */
 152         const char *name;
 153
 154      /* sign */
 155         DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen,
 156                                  DSA *dsa);
 157
 158      /* pre-compute k^-1 and r */
 159         int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp,
 160                                  BIGNUM **rp);
 161
 162      /* verify */
 163         int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len,
 164                                  DSA_SIG *sig, DSA *dsa);
 165
 166      /* compute rr = a1^p1 * a2^p2 mod m (May be NULL for some
 167                                           implementations) */
 168         int (*dsa_mod_exp)(DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1,
 169                                  BIGNUM *a2, BIGNUM *p2, BIGNUM *m,
 170                                  BN_CTX *ctx, BN_MONT_CTX *in_mont);
 171
 172      /* compute r = a ^ p mod m (May be NULL for some implementations) */
 173         int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a,
 174                                  const BIGNUM *p, const BIGNUM *m,
 175                                  BN_CTX *ctx, BN_MONT_CTX *m_ctx);
 176
 177      /* called at DSA_new */
 178         int (*init)(DSA *DSA);
 179
 180      /* called at DSA_free */
 181         int (*finish)(DSA *DSA);
 182
 183         int flags;
 184
 185         char *app_data; /* ?? */
 186
 187 } DSA_METHOD;
 188 .Ed
 189 .Sh RETURN VALUES
 190 .Fn DSA_OpenSSL
 191 and
 192 .Fn DSA_get_default_method
 193 return pointers to the respective
 194 .Vt DSA_METHOD .
 195 .Pp
 196 .Fn DSA_set_method
 197 returns 1 on success or 0 on failure.
 198 Currently, it cannot fail.
 199 .Pp
 200 .Fn DSA_new_method
 201 returns
 202 .Dv NULL
 203 and sets an error code that can be obtained by
 204 .Xr ERR_get_error 3
 205 if the allocation fails.
 206 Otherwise it returns a pointer to the newly allocated structure.
 207 .Sh SEE ALSO
 208 .Xr DSA_meth_new 3 ,
 209 .Xr DSA_new 3 ,
 210 .Xr ENGINE_get_default_DSA 3 ,
 211 .Xr ENGINE_register_DSA 3 ,
 212 .Xr ENGINE_set_default_DSA 3
 213 .Sh HISTORY
 214 .Fn DSA_set_default_method ,
 215 .Fn DSA_get_default_method ,
 216 .Fn DSA_set_method ,
 217 .Fn DSA_new_method ,
 218 and
 219 .Fn DSA_OpenSSL
 220 first appeared in OpenSSL 0.9.5 and have been available since
 221 .Ox 2.7 .