secure/lib/libcrypto/man/man3/DSA_meth_new.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "DSA_METH_NEW 3"
 136 .TH DSA_METH_NEW 3 "2020-09-22" "1.1.1h" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 DSA_meth_new, DSA_meth_free, DSA_meth_dup, DSA_meth_get0_name, DSA_meth_set1_name, DSA_meth_get_flags, DSA_meth_set_flags, DSA_meth_get0_app_data, DSA_meth_set0_app_data, DSA_meth_get_sign, DSA_meth_set_sign, DSA_meth_get_sign_setup, DSA_meth_set_sign_setup, DSA_meth_get_verify, DSA_meth_set_verify, DSA_meth_get_mod_exp, DSA_meth_set_mod_exp, DSA_meth_get_bn_mod_exp, DSA_meth_set_bn_mod_exp, DSA_meth_get_init, DSA_meth_set_init, DSA_meth_get_finish, DSA_meth_set_finish, DSA_meth_get_paramgen, DSA_meth_set_paramgen, DSA_meth_get_keygen, DSA_meth_set_keygen \- Routines to build up DSA methods
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/dsa.h>
 147 \&
 148 \& DSA_METHOD *DSA_meth_new(const char *name, int flags);
 149 \&
 150 \& void DSA_meth_free(DSA_METHOD *dsam);
 151 \&
 152 \& DSA_METHOD *DSA_meth_dup(const DSA_METHOD *meth);
 153 \&
 154 \& const char *DSA_meth_get0_name(const DSA_METHOD *dsam);
 155 \& int DSA_meth_set1_name(DSA_METHOD *dsam, const char *name);
 156 \&
 157 \& int DSA_meth_get_flags(const DSA_METHOD *dsam);
 158 \& int DSA_meth_set_flags(DSA_METHOD *dsam, int flags);
 159 \&
 160 \& void *DSA_meth_get0_app_data(const DSA_METHOD *dsam);
 161 \& int DSA_meth_set0_app_data(DSA_METHOD *dsam, void *app_data);
 162 \&
 163 \& DSA_SIG *(*DSA_meth_get_sign(const DSA_METHOD *dsam))(const unsigned char *,
 164 \&                                                       int, DSA *);
 165 \& int DSA_meth_set_sign(DSA_METHOD *dsam, DSA_SIG *(*sign)(const unsigned char *,
 166 \&                                                          int, DSA *));
 167 \&
 168 \& int (*DSA_meth_get_sign_setup(const DSA_METHOD *dsam))(DSA *, BN_CTX *,$
 169 \&                                                        BIGNUM **, BIGNUM **);
 170 \& int DSA_meth_set_sign_setup(DSA_METHOD *dsam, int (*sign_setup)(DSA *, BN_CTX *,
 171 \&                                                                 BIGNUM **, BIGNUM **));
 172 \&
 173 \& int (*DSA_meth_get_verify(const DSA_METHOD *dsam))(const unsigned char *,
 174 \&                                                    int, DSA_SIG *, DSA *);
 175 \& int DSA_meth_set_verify(DSA_METHOD *dsam, int (*verify)(const unsigned char *,
 176 \&                                                         int, DSA_SIG *, DSA *));
 177 \&
 178 \& int (*DSA_meth_get_mod_exp(const DSA_METHOD *dsam))(DSA *dsa, BIGNUM *rr, BIGNUM *a1,
 179 \&                                                     BIGNUM *p1, BIGNUM *a2, BIGNUM *p2,
 180 \&                                                     BIGNUM *m, BN_CTX *ctx,
 181 \&                                                     BN_MONT_CTX *in_mont);
 182 \& int DSA_meth_set_mod_exp(DSA_METHOD *dsam, int (*mod_exp)(DSA *dsa, BIGNUM *rr,
 183 \&                                                           BIGNUM *a1, BIGNUM *p1,
 184 \&                                                           BIGNUM *a2, BIGNUM *p2,
 185 \&                                                           BIGNUM *m, BN_CTX *ctx,
 186 \&                                                           BN_MONT_CTX *mont));
 187 \&
 188 \& int (*DSA_meth_get_bn_mod_exp(const DSA_METHOD *dsam))(DSA *dsa, BIGNUM *r, BIGNUM *a,
 189 \&                                                        const BIGNUM *p, const BIGNUM *m,
 190 \&                                                        BN_CTX *ctx, BN_MONT_CTX *mont);
 191 \& int DSA_meth_set_bn_mod_exp(DSA_METHOD *dsam, int (*bn_mod_exp)(DSA *dsa,
 192 \&                                                                 BIGNUM *r,
 193 \&                                                                 BIGNUM *a,
 194 \&                                                                 const BIGNUM *p,
 195 \&                                                                 const BIGNUM *m,
 196 \&                                                                 BN_CTX *ctx,
 197 \&                                                                 BN_MONT_CTX *mont));
 198 \&
 199 \& int (*DSA_meth_get_init(const DSA_METHOD *dsam))(DSA *);
 200 \& int DSA_meth_set_init(DSA_METHOD *dsam, int (*init)(DSA *));
 201 \&
 202 \& int (*DSA_meth_get_finish(const DSA_METHOD *dsam))(DSA *);
 203 \& int DSA_meth_set_finish(DSA_METHOD *dsam, int (*finish)(DSA *));
 204 \&
 205 \& int (*DSA_meth_get_paramgen(const DSA_METHOD *dsam))(DSA *, int,
 206 \&                                                      const unsigned char *,
 207 \&                                                      int, int *, unsigned long *,
 208 \&                                                      BN_GENCB *);
 209 \& int DSA_meth_set_paramgen(DSA_METHOD *dsam,
 210 \&                           int (*paramgen)(DSA *, int, const unsigned char *,
 211 \&                                           int, int *, unsigned long *, BN_GENCB *));
 212 \&
 213 \& int (*DSA_meth_get_keygen(const DSA_METHOD *dsam))(DSA *);
 214 \& int DSA_meth_set_keygen(DSA_METHOD *dsam, int (*keygen)(DSA *));
 215 .Ve
 216 .SH "DESCRIPTION"
 217 .IX Header "DESCRIPTION"
 218 The \fB\s-1DSA_METHOD\s0\fR type is a structure used for the provision of custom \s-1DSA\s0
 219 implementations. It provides a set of functions used by OpenSSL for the
 220 implementation of the various \s-1DSA\s0 capabilities. See the dsa page for more
 221 information.
 222 .PP
 223 \&\fBDSA_meth_new()\fR creates a new \fB\s-1DSA_METHOD\s0\fR structure. It should be given a
 224 unique \fBname\fR and a set of \fBflags\fR. The \fBname\fR should be a \s-1NULL\s0 terminated
 225 string, which will be duplicated and stored in the \fB\s-1DSA_METHOD\s0\fR object. It is
 226 the callers responsibility to free the original string. The flags will be used
 227 during the construction of a new \fB\s-1DSA\s0\fR object based on this \fB\s-1DSA_METHOD\s0\fR. Any
 228 new \fB\s-1DSA\s0\fR object will have those flags set by default.
 229 .PP
 230 \&\fBDSA_meth_dup()\fR creates a duplicate copy of the \fB\s-1DSA_METHOD\s0\fR object passed as a
 231 parameter. This might be useful for creating a new \fB\s-1DSA_METHOD\s0\fR based on an
 232 existing one, but with some differences.
 233 .PP
 234 \&\fBDSA_meth_free()\fR destroys a \fB\s-1DSA_METHOD\s0\fR structure and frees up any memory
 235 associated with it.
 236 .PP
 237 \&\fBDSA_meth_get0_name()\fR will return a pointer to the name of this \s-1DSA_METHOD.\s0 This
 238 is a pointer to the internal name string and so should not be freed by the
 239 caller. \fBDSA_meth_set1_name()\fR sets the name of the \s-1DSA_METHOD\s0 to \fBname\fR. The
 240 string is duplicated and the copy is stored in the \s-1DSA_METHOD\s0 structure, so the
 241 caller remains responsible for freeing the memory associated with the name.
 242 .PP
 243 \&\fBDSA_meth_get_flags()\fR returns the current value of the flags associated with this
 244 \&\s-1DSA_METHOD.\s0 \fBDSA_meth_set_flags()\fR provides the ability to set these flags.
 245 .PP
 246 The functions \fBDSA_meth_get0_app_data()\fR and \fBDSA_meth_set0_app_data()\fR provide the
 247 ability to associate implementation specific data with the \s-1DSA_METHOD.\s0 It is
 248 the application's responsibility to free this data before the \s-1DSA_METHOD\s0 is
 249 freed via a call to \fBDSA_meth_free()\fR.
 250 .PP
 251 \&\fBDSA_meth_get_sign()\fR and \fBDSA_meth_set_sign()\fR get and set the function used for
 252 creating a \s-1DSA\s0 signature respectively. This function will be
 253 called in response to the application calling \fBDSA_do_sign()\fR (or \fBDSA_sign()\fR). The
 254 parameters for the function have the same meaning as for \fBDSA_do_sign()\fR.
 255 .PP
 256 \&\fBDSA_meth_get_sign_setup()\fR and \fBDSA_meth_set_sign_setup()\fR get and set the function
 257 used for precalculating the \s-1DSA\s0 signature values \fBk^\-1\fR and \fBr\fR. This function
 258 will be called in response to the application calling \fBDSA_sign_setup()\fR. The
 259 parameters for the function have the same meaning as for \fBDSA_sign_setup()\fR.
 260 .PP
 261 \&\fBDSA_meth_get_verify()\fR and \fBDSA_meth_set_verify()\fR get and set the function used
 262 for verifying a \s-1DSA\s0 signature respectively. This function will be called in
 263 response to the application calling \fBDSA_do_verify()\fR (or \fBDSA_verify()\fR). The
 264 parameters for the function have the same meaning as for \fBDSA_do_verify()\fR.
 265 .PP
 266 \&\fBDSA_meth_get_mod_exp()\fR and \fBDSA_meth_set_mod_exp()\fR get and set the function used
 267 for computing the following value:
 268 .PP
 269 .Vb 1
 270 \& rr = a1^p1 * a2^p2 mod m
 271 .Ve
 272 .PP
 273 This function will be called by the default OpenSSL method during verification
 274 of a \s-1DSA\s0 signature. The result is stored in the \fBrr\fR parameter. This function
 275 may be \s-1NULL.\s0
 276 .PP
 277 \&\fBDSA_meth_get_bn_mod_exp()\fR and \fBDSA_meth_set_bn_mod_exp()\fR get and set the function
 278 used for computing the following value:
 279 .PP
 280 .Vb 1
 281 \& r = a ^ p mod m
 282 .Ve
 283 .PP
 284 This function will be called by the default OpenSSL function for
 285 \&\fBDSA_sign_setup()\fR. The result is stored in the \fBr\fR parameter. This function
 286 may be \s-1NULL.\s0
 287 .PP
 288 \&\fBDSA_meth_get_init()\fR and \fBDSA_meth_set_init()\fR get and set the function used
 289 for creating a new \s-1DSA\s0 instance respectively. This function will be
 290 called in response to the application calling \fBDSA_new()\fR (if the current default
 291 \&\s-1DSA_METHOD\s0 is this one) or \fBDSA_new_method()\fR. The \fBDSA_new()\fR and \fBDSA_new_method()\fR
 292 functions will allocate the memory for the new \s-1DSA\s0 object, and a pointer to this
 293 newly allocated structure will be passed as a parameter to the function. This
 294 function may be \s-1NULL.\s0
 295 .PP
 296 \&\fBDSA_meth_get_finish()\fR and \fBDSA_meth_set_finish()\fR get and set the function used
 297 for destroying an instance of a \s-1DSA\s0 object respectively. This function will be
 298 called in response to the application calling \fBDSA_free()\fR. A pointer to the \s-1DSA\s0
 299 to be destroyed is passed as a parameter. The destroy function should be used
 300 for \s-1DSA\s0 implementation specific clean up. The memory for the \s-1DSA\s0 itself should
 301 not be freed by this function. This function may be \s-1NULL.\s0
 302 .PP
 303 \&\fBDSA_meth_get_paramgen()\fR and \fBDSA_meth_set_paramgen()\fR get and set the function
 304 used for generating \s-1DSA\s0 parameters respectively. This function will be called in
 305 response to the application calling \fBDSA_generate_parameters_ex()\fR (or
 306 \&\fBDSA_generate_parameters()\fR). The parameters for the function have the same
 307 meaning as for \fBDSA_generate_parameters_ex()\fR.
 308 .PP
 309 \&\fBDSA_meth_get_keygen()\fR and \fBDSA_meth_set_keygen()\fR get and set the function
 310 used for generating a new \s-1DSA\s0 key pair respectively. This function will be
 311 called in response to the application calling \fBDSA_generate_key()\fR. The parameter
 312 for the function has the same meaning as for \fBDSA_generate_key()\fR.
 313 .SH "RETURN VALUES"
 314 .IX Header "RETURN VALUES"
 315 \&\fBDSA_meth_new()\fR and \fBDSA_meth_dup()\fR return the newly allocated \s-1DSA_METHOD\s0 object
 316 or \s-1NULL\s0 on failure.
 317 .PP
 318 \&\fBDSA_meth_get0_name()\fR and \fBDSA_meth_get_flags()\fR return the name and flags
 319 associated with the \s-1DSA_METHOD\s0 respectively.
 320 .PP
 321 All other DSA_meth_get_*() functions return the appropriate function pointer
 322 that has been set in the \s-1DSA_METHOD,\s0 or \s-1NULL\s0 if no such pointer has yet been
 323 set.
 324 .PP
 325 \&\fBDSA_meth_set1_name()\fR and all DSA_meth_set_*() functions return 1 on success or
 326 0 on failure.
 327 .SH "SEE ALSO"
 328 .IX Header "SEE ALSO"
 329 \&\fBDSA_new\fR\|(3), \fBDSA_new\fR\|(3), \fBDSA_generate_parameters\fR\|(3), \fBDSA_generate_key\fR\|(3),
 330 \&\fBDSA_dup_DH\fR\|(3), \fBDSA_do_sign\fR\|(3), \fBDSA_set_method\fR\|(3), \fBDSA_SIG_new\fR\|(3),
 331 \&\fBDSA_sign\fR\|(3), \fBDSA_size\fR\|(3), \fBDSA_get0_pqg\fR\|(3)
 332 .SH "HISTORY"
 333 .IX Header "HISTORY"
 334 The functions described here were added in OpenSSL 1.1.0.
 335 .SH "COPYRIGHT"
 336 .IX Header "COPYRIGHT"
 337 Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved.
 338 .PP
 339 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 340 this file except in compliance with the License.  You can obtain a copy
 341 in the file \s-1LICENSE\s0 in the source distribution or at
 342 <https://www.openssl.org/source/license.html>.