secure/lib/libcrypto/man/DSA_meth_new.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "DSA_METH_NEW 3"
 132 .TH DSA_METH_NEW 3 "2018-09-11" "1.1.1" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 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
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/dsa.h>
 143 \&
 144 \& DSA_METHOD *DSA_meth_new(const char *name, int flags);
 145 \&
 146 \& void DSA_meth_free(DSA_METHOD *dsam);
 147 \&
 148 \& DSA_METHOD *DSA_meth_dup(const DSA_METHOD *meth);
 149 \&
 150 \& const char *DSA_meth_get0_name(const DSA_METHOD *dsam);
 151 \& int DSA_meth_set1_name(DSA_METHOD *dsam, const char *name);
 152 \&
 153 \& int DSA_meth_get_flags(const DSA_METHOD *dsam);
 154 \& int DSA_meth_set_flags(DSA_METHOD *dsam, int flags);
 155 \&
 156 \& void *DSA_meth_get0_app_data(const DSA_METHOD *dsam);
 157 \& int DSA_meth_set0_app_data(DSA_METHOD *dsam, void *app_data);
 158 \&
 159 \& DSA_SIG *(*DSA_meth_get_sign(const DSA_METHOD *dsam))(const unsigned char *,
 160 \&                                                       int, DSA *);
 161 \& int DSA_meth_set_sign(DSA_METHOD *dsam, DSA_SIG *(*sign)(const unsigned char *,
 162 \&                                                          int, DSA *));
 163 \&
 164 \& int (*DSA_meth_get_sign_setup(const DSA_METHOD *dsam))(DSA *, BN_CTX *,$
 165 \&                                                        BIGNUM **, BIGNUM **);
 166 \& int DSA_meth_set_sign_setup(DSA_METHOD *dsam, int (*sign_setup)(DSA *, BN_CTX *,
 167 \&                                                                 BIGNUM **, BIGNUM **));
 168 \&
 169 \& int (*DSA_meth_get_verify(const DSA_METHOD *dsam))(const unsigned char *,
 170 \&                                                    int, DSA_SIG *, DSA *);
 171 \& int DSA_meth_set_verify(DSA_METHOD *dsam, int (*verify)(const unsigned char *,
 172 \&                                                         int, DSA_SIG *, DSA *));
 173 \&
 174 \& int (*DSA_meth_get_mod_exp(const DSA_METHOD *dsam))(DSA *dsa, BIGNUM *rr, BIGNUM *a1,
 175 \&                                                     BIGNUM *p1, BIGNUM *a2, BIGNUM *p2,
 176 \&                                                     BIGNUM *m, BN_CTX *ctx,
 177 \&                                                     BN_MONT_CTX *in_mont);
 178 \& int DSA_meth_set_mod_exp(DSA_METHOD *dsam, int (*mod_exp)(DSA *dsa, BIGNUM *rr,
 179 \&                                                           BIGNUM *a1, BIGNUM *p1,
 180 \&                                                           BIGNUM *a2, BIGNUM *p2,
 181 \&                                                           BIGNUM *m, BN_CTX *ctx,
 182 \&                                                           BN_MONT_CTX *mont));
 183 \&
 184 \& int (*DSA_meth_get_bn_mod_exp(const DSA_METHOD *dsam))(DSA *dsa, BIGNUM *r, BIGNUM *a,
 185 \&                                                        const BIGNUM *p, const BIGNUM *m,
 186 \&                                                        BN_CTX *ctx, BN_MONT_CTX *mont);
 187 \& int DSA_meth_set_bn_mod_exp(DSA_METHOD *dsam, int (*bn_mod_exp)(DSA *dsa,
 188 \&                                                                 BIGNUM *r,
 189 \&                                                                 BIGNUM *a,
 190 \&                                                                 const BIGNUM *p,
 191 \&                                                                 const BIGNUM *m,
 192 \&                                                                 BN_CTX *ctx,
 193 \&                                                                 BN_MONT_CTX *mont));
 194 \&
 195 \& int (*DSA_meth_get_init(const DSA_METHOD *dsam))(DSA *);
 196 \& int DSA_meth_set_init(DSA_METHOD *dsam, int (*init)(DSA *));
 197 \&
 198 \& int (*DSA_meth_get_finish(const DSA_METHOD *dsam))(DSA *);
 199 \& int DSA_meth_set_finish(DSA_METHOD *dsam, int (*finish)(DSA *));
 200 \&
 201 \& int (*DSA_meth_get_paramgen(const DSA_METHOD *dsam))(DSA *, int,
 202 \&                                                      const unsigned char *,
 203 \&                                                      int, int *, unsigned long *,
 204 \&                                                      BN_GENCB *);
 205 \& int DSA_meth_set_paramgen(DSA_METHOD *dsam,
 206 \&                           int (*paramgen)(DSA *, int, const unsigned char *,
 207 \&                                           int, int *, unsigned long *, BN_GENCB *));
 208 \&
 209 \& int (*DSA_meth_get_keygen(const DSA_METHOD *dsam))(DSA *);
 210 \& int DSA_meth_set_keygen(DSA_METHOD *dsam, int (*keygen)(DSA *));
 211 .Ve
 212 .SH "DESCRIPTION"
 213 .IX Header "DESCRIPTION"
 214 The \fB\s-1DSA_METHOD\s0\fR type is a structure used for the provision of custom \s-1DSA\s0
 215 implementations. It provides a set of functions used by OpenSSL for the
 216 implementation of the various \s-1DSA\s0 capabilities. See the dsa page for more
 217 information.
 218 .PP
 219 \&\fIDSA_meth_new()\fR creates a new \fB\s-1DSA_METHOD\s0\fR structure. It should be given a
 220 unique \fBname\fR and a set of \fBflags\fR. The \fBname\fR should be a \s-1NULL\s0 terminated
 221 string, which will be duplicated and stored in the \fB\s-1DSA_METHOD\s0\fR object. It is
 222 the callers responsibility to free the original string. The flags will be used
 223 during the construction of a new \fB\s-1DSA\s0\fR object based on this \fB\s-1DSA_METHOD\s0\fR. Any
 224 new \fB\s-1DSA\s0\fR object will have those flags set by default.
 225 .PP
 226 \&\fIDSA_meth_dup()\fR creates a duplicate copy of the \fB\s-1DSA_METHOD\s0\fR object passed as a
 227 parameter. This might be useful for creating a new \fB\s-1DSA_METHOD\s0\fR based on an
 228 existing one, but with some differences.
 229 .PP
 230 \&\fIDSA_meth_free()\fR destroys a \fB\s-1DSA_METHOD\s0\fR structure and frees up any memory
 231 associated with it.
 232 .PP
 233 \&\fIDSA_meth_get0_name()\fR will return a pointer to the name of this \s-1DSA_METHOD.\s0 This
 234 is a pointer to the internal name string and so should not be freed by the
 235 caller. \fIDSA_meth_set1_name()\fR sets the name of the \s-1DSA_METHOD\s0 to \fBname\fR. The
 236 string is duplicated and the copy is stored in the \s-1DSA_METHOD\s0 structure, so the
 237 caller remains responsible for freeing the memory associated with the name.
 238 .PP
 239 \&\fIDSA_meth_get_flags()\fR returns the current value of the flags associated with this
 240 \&\s-1DSA_METHOD.\s0 \fIDSA_meth_set_flags()\fR provides the ability to set these flags.
 241 .PP
 242 The functions \fIDSA_meth_get0_app_data()\fR and \fIDSA_meth_set0_app_data()\fR provide the
 243 ability to associate implementation specific data with the \s-1DSA_METHOD.\s0 It is
 244 the application's responsibility to free this data before the \s-1DSA_METHOD\s0 is
 245 freed via a call to \fIDSA_meth_free()\fR.
 246 .PP
 247 \&\fIDSA_meth_get_sign()\fR and \fIDSA_meth_set_sign()\fR get and set the function used for
 248 creating a \s-1DSA\s0 signature respectively. This function will be
 249 called in response to the application calling \fIDSA_do_sign()\fR (or \fIDSA_sign()\fR). The
 250 parameters for the function have the same meaning as for \fIDSA_do_sign()\fR.
 251 .PP
 252 \&\fIDSA_meth_get_sign_setup()\fR and \fIDSA_meth_set_sign_setup()\fR get and set the function
 253 used for precalculating the \s-1DSA\s0 signature values \fBk^\-1\fR and \fBr\fR. This function
 254 will be called in response to the application calling \fIDSA_sign_setup()\fR. The
 255 parameters for the function have the same meaning as for \fIDSA_sign_setup()\fR.
 256 .PP
 257 \&\fIDSA_meth_get_verify()\fR and \fIDSA_meth_set_verify()\fR get and set the function used
 258 for verifying a \s-1DSA\s0 signature respectively. This function will be called in
 259 response to the application calling \fIDSA_do_verify()\fR (or \fIDSA_verify()\fR). The
 260 parameters for the function have the same meaning as for \fIDSA_do_verify()\fR.
 261 .PP
 262 \&\fIDSA_meth_get_mod_exp()\fR and \fIDSA_meth_set_mod_exp()\fR get and set the function used
 263 for computing the following value:
 264 .PP
 265 .Vb 1
 266 \& rr = a1^p1 * a2^p2 mod m
 267 .Ve
 268 .PP
 269 This function will be called by the default OpenSSL method during verification
 270 of a \s-1DSA\s0 signature. The result is stored in the \fBrr\fR parameter. This function
 271 may be \s-1NULL.\s0
 272 .PP
 273 \&\fIDSA_meth_get_bn_mod_exp()\fR and \fIDSA_meth_set_bn_mod_exp()\fR get and set the function
 274 used for computing the following value:
 275 .PP
 276 .Vb 1
 277 \& r = a ^ p mod m
 278 .Ve
 279 .PP
 280 This function will be called by the default OpenSSL function for
 281 \&\fIDSA_sign_setup()\fR. The result is stored in the \fBr\fR parameter. This function
 282 may be \s-1NULL.\s0
 283 .PP
 284 \&\fIDSA_meth_get_init()\fR and \fIDSA_meth_set_init()\fR get and set the function used
 285 for creating a new \s-1DSA\s0 instance respectively. This function will be
 286 called in response to the application calling \fIDSA_new()\fR (if the current default
 287 \&\s-1DSA_METHOD\s0 is this one) or \fIDSA_new_method()\fR. The \fIDSA_new()\fR and \fIDSA_new_method()\fR
 288 functions will allocate the memory for the new \s-1DSA\s0 object, and a pointer to this
 289 newly allocated structure will be passed as a parameter to the function. This
 290 function may be \s-1NULL.\s0
 291 .PP
 292 \&\fIDSA_meth_get_finish()\fR and \fIDSA_meth_set_finish()\fR get and set the function used
 293 for destroying an instance of a \s-1DSA\s0 object respectively. This function will be
 294 called in response to the application calling \fIDSA_free()\fR. A pointer to the \s-1DSA\s0
 295 to be destroyed is passed as a parameter. The destroy function should be used
 296 for \s-1DSA\s0 implementation specific clean up. The memory for the \s-1DSA\s0 itself should
 297 not be freed by this function. This function may be \s-1NULL.\s0
 298 .PP
 299 \&\fIDSA_meth_get_paramgen()\fR and \fIDSA_meth_set_paramgen()\fR get and set the function
 300 used for generating \s-1DSA\s0 parameters respectively. This function will be called in
 301 response to the application calling \fIDSA_generate_parameters_ex()\fR (or
 302 \&\fIDSA_generate_parameters()\fR). The parameters for the function have the same
 303 meaning as for \fIDSA_generate_parameters_ex()\fR.
 304 .PP
 305 \&\fIDSA_meth_get_keygen()\fR and \fIDSA_meth_set_keygen()\fR get and set the function
 306 used for generating a new \s-1DSA\s0 key pair respectively. This function will be
 307 called in response to the application calling \fIDSA_generate_key()\fR. The parameter
 308 for the function has the same meaning as for \fIDSA_generate_key()\fR.
 309 .SH "RETURN VALUES"
 310 .IX Header "RETURN VALUES"
 311 \&\fIDSA_meth_new()\fR and \fIDSA_meth_dup()\fR return the newly allocated \s-1DSA_METHOD\s0 object
 312 or \s-1NULL\s0 on failure.
 313 .PP
 314 \&\fIDSA_meth_get0_name()\fR and \fIDSA_meth_get_flags()\fR return the name and flags
 315 associated with the \s-1DSA_METHOD\s0 respectively.
 316 .PP
 317 All other DSA_meth_get_*() functions return the appropriate function pointer
 318 that has been set in the \s-1DSA_METHOD,\s0 or \s-1NULL\s0 if no such pointer has yet been
 319 set.
 320 .PP
 321 \&\fIDSA_meth_set1_name()\fR and all DSA_meth_set_*() functions return 1 on success or
 322 0 on failure.
 323 .SH "SEE ALSO"
 324 .IX Header "SEE ALSO"
 325 \&\fIDSA_new\fR\|(3), \fIDSA_new\fR\|(3), \fIDSA_generate_parameters\fR\|(3), \fIDSA_generate_key\fR\|(3),
 326 \&\fIDSA_dup_DH\fR\|(3), \fIDSA_do_sign\fR\|(3), \fIDSA_set_method\fR\|(3), \fIDSA_SIG_new\fR\|(3),
 327 \&\fIDSA_sign\fR\|(3), \fIDSA_size\fR\|(3), \fIDSA_get0_pqg\fR\|(3)
 328 .SH "HISTORY"
 329 .IX Header "HISTORY"
 330 The functions described here were added in OpenSSL 1.1.0.
 331 .SH "COPYRIGHT"
 332 .IX Header "COPYRIGHT"
 333 Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved.
 334 .PP
 335 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 336 this file except in compliance with the License.  You can obtain a copy
 337 in the file \s-1LICENSE\s0 in the source distribution or at
 338 <https://www.openssl.org/source/license.html>.