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