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

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
   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 "DH_METH_NEW 3"
 136 .TH DH_METH_NEW 3 "2022-05-03" "1.1.1o" "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 DH_meth_new, DH_meth_free, DH_meth_dup, DH_meth_get0_name, DH_meth_set1_name, DH_meth_get_flags, DH_meth_set_flags, DH_meth_get0_app_data, DH_meth_set0_app_data, DH_meth_get_generate_key, DH_meth_set_generate_key, DH_meth_get_compute_key, DH_meth_set_compute_key, DH_meth_get_bn_mod_exp, DH_meth_set_bn_mod_exp, DH_meth_get_init, DH_meth_set_init, DH_meth_get_finish, DH_meth_set_finish, DH_meth_get_generate_params, DH_meth_set_generate_params \- Routines to build up DH methods
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/dh.h>
 147 \&
 148 \& DH_METHOD *DH_meth_new(const char *name, int flags);
 149 \&
 150 \& void DH_meth_free(DH_METHOD *dhm);
 151 \&
 152 \& DH_METHOD *DH_meth_dup(const DH_METHOD *dhm);
 153 \&
 154 \& const char *DH_meth_get0_name(const DH_METHOD *dhm);
 155 \& int DH_meth_set1_name(DH_METHOD *dhm, const char *name);
 156 \&
 157 \& int DH_meth_get_flags(const DH_METHOD *dhm);
 158 \& int DH_meth_set_flags(DH_METHOD *dhm, int flags);
 159 \&
 160 \& void *DH_meth_get0_app_data(const DH_METHOD *dhm);
 161 \& int DH_meth_set0_app_data(DH_METHOD *dhm, void *app_data);
 162 \&
 163 \& int (*DH_meth_get_generate_key(const DH_METHOD *dhm))(DH *);
 164 \& int DH_meth_set_generate_key(DH_METHOD *dhm, int (*generate_key)(DH *));
 165 \&
 166 \& int (*DH_meth_get_compute_key(const DH_METHOD *dhm))
 167 \&     (unsigned char *key, const BIGNUM *pub_key, DH *dh);
 168 \& int DH_meth_set_compute_key(DH_METHOD *dhm,
 169 \&     int (*compute_key)(unsigned char *key, const BIGNUM *pub_key, DH *dh));
 170 \&
 171 \& int (*DH_meth_get_bn_mod_exp(const DH_METHOD *dhm))
 172 \&     (const DH *dh, BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
 173 \&      const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);
 174 \& int DH_meth_set_bn_mod_exp(DH_METHOD *dhm,
 175 \&     int (*bn_mod_exp)(const DH *dh, BIGNUM *r, const BIGNUM *a,
 176 \&                       const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx,
 177 \&                       BN_MONT_CTX *m_ctx));
 178 \&
 179 \& int (*DH_meth_get_init(const DH_METHOD *dhm))(DH *);
 180 \& int DH_meth_set_init(DH_METHOD *dhm, int (*init)(DH *));
 181 \&
 182 \& int (*DH_meth_get_finish(const DH_METHOD *dhm))(DH *);
 183 \& int DH_meth_set_finish(DH_METHOD *dhm, int (*finish)(DH *));
 184 \&
 185 \& int (*DH_meth_get_generate_params(const DH_METHOD *dhm))
 186 \&     (DH *, int, int, BN_GENCB *);
 187 \& int DH_meth_set_generate_params(DH_METHOD *dhm,
 188 \&     int (*generate_params)(DH *, int, int, BN_GENCB *));
 189 .Ve
 190 .SH "DESCRIPTION"
 191 .IX Header "DESCRIPTION"
 192 The \fB\s-1DH_METHOD\s0\fR type is a structure used for the provision of custom \s-1DH\s0
 193 implementations. It provides a set of functions used by OpenSSL for the
 194 implementation of the various \s-1DH\s0 capabilities.
 195 .PP
 196 \&\fBDH_meth_new()\fR creates a new \fB\s-1DH_METHOD\s0\fR structure. It should be given a
 197 unique \fBname\fR and a set of \fBflags\fR. The \fBname\fR should be a \s-1NULL\s0 terminated
 198 string, which will be duplicated and stored in the \fB\s-1DH_METHOD\s0\fR object. It is
 199 the callers responsibility to free the original string. The flags will be used
 200 during the construction of a new \fB\s-1DH\s0\fR object based on this \fB\s-1DH_METHOD\s0\fR. Any
 201 new \fB\s-1DH\s0\fR object will have those flags set by default.
 202 .PP
 203 \&\fBDH_meth_dup()\fR creates a duplicate copy of the \fB\s-1DH_METHOD\s0\fR object passed as a
 204 parameter. This might be useful for creating a new \fB\s-1DH_METHOD\s0\fR based on an
 205 existing one, but with some differences.
 206 .PP
 207 \&\fBDH_meth_free()\fR destroys a \fB\s-1DH_METHOD\s0\fR structure and frees up any memory
 208 associated with it.
 209 .PP
 210 \&\fBDH_meth_get0_name()\fR will return a pointer to the name of this \s-1DH_METHOD.\s0 This
 211 is a pointer to the internal name string and so should not be freed by the
 212 caller. \fBDH_meth_set1_name()\fR sets the name of the \s-1DH_METHOD\s0 to \fBname\fR. The
 213 string is duplicated and the copy is stored in the \s-1DH_METHOD\s0 structure, so the
 214 caller remains responsible for freeing the memory associated with the name.
 215 .PP
 216 \&\fBDH_meth_get_flags()\fR returns the current value of the flags associated with this
 217 \&\s-1DH_METHOD.\s0 \fBDH_meth_set_flags()\fR provides the ability to set these flags.
 218 .PP
 219 The functions \fBDH_meth_get0_app_data()\fR and \fBDH_meth_set0_app_data()\fR provide the
 220 ability to associate implementation specific data with the \s-1DH_METHOD.\s0 It is
 221 the application's responsibility to free this data before the \s-1DH_METHOD\s0 is
 222 freed via a call to \fBDH_meth_free()\fR.
 223 .PP
 224 \&\fBDH_meth_get_generate_key()\fR and \fBDH_meth_set_generate_key()\fR get and set the
 225 function used for generating a new \s-1DH\s0 key pair respectively. This function will
 226 be called in response to the application calling \fBDH_generate_key()\fR. The
 227 parameter for the function has the same meaning as for \fBDH_generate_key()\fR.
 228 .PP
 229 \&\fBDH_meth_get_compute_key()\fR and \fBDH_meth_set_compute_key()\fR get and set the
 230 function used for computing a new \s-1DH\s0 shared secret respectively. This function
 231 will be called in response to the application calling \fBDH_compute_key()\fR. The
 232 parameters for the function have the same meaning as for \fBDH_compute_key()\fR.
 233 .PP
 234 \&\fBDH_meth_get_bn_mod_exp()\fR and \fBDH_meth_set_bn_mod_exp()\fR get and set the function
 235 used for computing the following value:
 236 .PP
 237 .Vb 1
 238 \& r = a ^ p mod m
 239 .Ve
 240 .PP
 241 This function will be called by the default OpenSSL function for
 242 \&\fBDH_generate_key()\fR. The result is stored in the \fBr\fR parameter. This function
 243 may be \s-1NULL\s0 unless using the default generate key function, in which case it
 244 must be present.
 245 .PP
 246 \&\fBDH_meth_get_init()\fR and \fBDH_meth_set_init()\fR get and set the function used
 247 for creating a new \s-1DH\s0 instance respectively. This function will be
 248 called in response to the application calling \fBDH_new()\fR (if the current default
 249 \&\s-1DH_METHOD\s0 is this one) or \fBDH_new_method()\fR. The \fBDH_new()\fR and \fBDH_new_method()\fR
 250 functions will allocate the memory for the new \s-1DH\s0 object, and a pointer to this
 251 newly allocated structure will be passed as a parameter to the function. This
 252 function may be \s-1NULL.\s0
 253 .PP
 254 \&\fBDH_meth_get_finish()\fR and \fBDH_meth_set_finish()\fR get and set the function used
 255 for destroying an instance of a \s-1DH\s0 object respectively. This function will be
 256 called in response to the application calling \fBDH_free()\fR. A pointer to the \s-1DH\s0
 257 to be destroyed is passed as a parameter. The destroy function should be used
 258 for \s-1DH\s0 implementation specific clean up. The memory for the \s-1DH\s0 itself should
 259 not be freed by this function. This function may be \s-1NULL.\s0
 260 .PP
 261 \&\fBDH_meth_get_generate_params()\fR and \fBDH_meth_set_generate_params()\fR get and set the
 262 function used for generating \s-1DH\s0 parameters respectively. This function will be
 263 called in response to the application calling \fBDH_generate_parameters_ex()\fR (or
 264 \&\fBDH_generate_parameters()\fR). The parameters for the function have the same
 265 meaning as for \fBDH_generate_parameters_ex()\fR. This function may be \s-1NULL.\s0
 266 .SH "RETURN VALUES"
 267 .IX Header "RETURN VALUES"
 268 \&\fBDH_meth_new()\fR and \fBDH_meth_dup()\fR return the newly allocated \s-1DH_METHOD\s0 object
 269 or \s-1NULL\s0 on failure.
 270 .PP
 271 \&\fBDH_meth_get0_name()\fR and \fBDH_meth_get_flags()\fR return the name and flags
 272 associated with the \s-1DH_METHOD\s0 respectively.
 273 .PP
 274 All other DH_meth_get_*() functions return the appropriate function pointer
 275 that has been set in the \s-1DH_METHOD,\s0 or \s-1NULL\s0 if no such pointer has yet been
 276 set.
 277 .PP
 278 \&\fBDH_meth_set1_name()\fR and all DH_meth_set_*() functions return 1 on success or
 279 0 on failure.
 280 .SH "SEE ALSO"
 281 .IX Header "SEE ALSO"
 282 \&\fBDH_new\fR\|(3), \fBDH_new\fR\|(3), \fBDH_generate_parameters\fR\|(3), \fBDH_generate_key\fR\|(3),
 283 \&\fBDH_set_method\fR\|(3), \fBDH_size\fR\|(3), \fBDH_get0_pqg\fR\|(3)
 284 .SH "HISTORY"
 285 .IX Header "HISTORY"
 286 The functions described here were added in OpenSSL 1.1.0.
 287 .SH "COPYRIGHT"
 288 .IX Header "COPYRIGHT"
 289 Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved.
 290 .PP
 291 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 292 this file except in compliance with the License.  You can obtain a copy
 293 in the file \s-1LICENSE\s0 in the source distribution or at
 294 <https://www.openssl.org/source/license.html>.