openssl: Adjust manual pages for 1.0.1m.
[dragonfly.git] / secure / lib / libcrypto / man / DH_set_method.3
CommitLineData
5a44c043 1.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
8b0cefbb
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
8b0cefbb 5.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
6.if t .sp .5v
7.if n .sp
8..
8b0cefbb 9.de Vb \" Begin verbatim text
984263bc
MD
10.ft CW
11.nf
12.ne \\$1
13..
8b0cefbb 14.de Ve \" End verbatim text
984263bc 15.ft R
984263bc
MD
16.fi
17..
8b0cefbb
JR
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
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-
8b0cefbb 25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 26.ie n \{\
8b0cefbb
JR
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' ""
984263bc
MD
35'br\}
36.el\{\
8b0cefbb
JR
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
5a44c043
SW
41. ds C`
42. ds C'
984263bc 43'br\}
8b0cefbb 44.\"
e257b235
PA
45.\" Escape single quotes in literal strings from groff's Unicode transform.
46.ie \n(.g .ds Aq \(aq
47.el .ds Aq '
48.\"
8b0cefbb 49.\" If the F register is turned on, we'll generate index entries on stderr for
01185282 50.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
8b0cefbb
JR
51.\" entries marked with X<> in POD. Of course, you'll have to process the
52.\" output yourself in some meaningful fashion.
5a44c043
SW
53.\"
54.\" Avoid warning from groff about undefined register 'F'.
55.de IX
984263bc 56..
5a44c043
SW
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"
e257b235 63..
5a44c043
SW
64. if !\nF==2 \{
65. nr % 0
66. nr F 2
67. \}
68. \}
e257b235 69.\}
5a44c043 70.rr rF
aac4ff6f 71.\"
8b0cefbb
JR
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
984263bc 75.if n \{\
8b0cefbb
JR
76. ds #H 0
77. ds #V .8m
78. ds #F .3m
79. ds #[ \f1
80. ds #] \fP
984263bc
MD
81.\}
82.if t \{\
8b0cefbb
JR
83. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
84. ds #V .6m
85. ds #F 0
86. ds #[ \&
87. ds #] \&
984263bc 88.\}
8b0cefbb 89. \" simple accents for nroff and troff
984263bc 90.if n \{\
8b0cefbb
JR
91. ds ' \&
92. ds ` \&
93. ds ^ \&
94. ds , \&
95. ds ~ ~
96. ds /
984263bc
MD
97.\}
98.if t \{\
8b0cefbb
JR
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'
984263bc 105.\}
8b0cefbb 106. \" troff and (daisy-wheel) nroff accents
984263bc
MD
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
8b0cefbb 116. \" corrections for vroff
984263bc
MD
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'
8b0cefbb 119. \" for low resolution devices (crt and lpr)
984263bc
MD
120.if \n(.H>23 .if \n(.V>19 \
121\{\
8b0cefbb
JR
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
984263bc
MD
131.\}
132.rm #[ #] #H #V #F C
8b0cefbb
JR
133.\" ========================================================================
134.\"
135.IX Title "DH_set_method 3"
5a44c043 136.TH DH_set_method 3 "2015-03-19" "1.0.1m" "OpenSSL"
e257b235
PA
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
984263bc
MD
141.SH "NAME"
142DH_set_default_method, DH_get_default_method,
74dab6c2 143DH_set_method, DH_new_method, DH_OpenSSL \- select DH method
984263bc 144.SH "SYNOPSIS"
8b0cefbb 145.IX Header "SYNOPSIS"
984263bc
MD
146.Vb 2
147\& #include <openssl/dh.h>
148\& #include <openssl/engine.h>
e257b235 149\&
984263bc 150\& void DH_set_default_method(const DH_METHOD *meth);
e257b235 151\&
984263bc 152\& const DH_METHOD *DH_get_default_method(void);
e257b235 153\&
984263bc 154\& int DH_set_method(DH *dh, const DH_METHOD *meth);
e257b235 155\&
984263bc 156\& DH *DH_new_method(ENGINE *engine);
e257b235 157\&
984263bc
MD
158\& const DH_METHOD *DH_OpenSSL(void);
159.Ve
160.SH "DESCRIPTION"
8b0cefbb
JR
161.IX Header "DESCRIPTION"
162A \fB\s-1DH_METHOD\s0\fR specifies the functions that OpenSSL uses for Diffie-Hellman
984263bc 163operations. By modifying the method, alternative implementations
8b0cefbb 164such as hardware accelerators may be used. \s-1IMPORTANT:\s0 See the \s-1NOTES\s0 section for
5a44c043 165important information about how these \s-1DH API\s0 functions are affected by the use
8b0cefbb 166of \fB\s-1ENGINE\s0\fR \s-1API\s0 calls.
984263bc 167.PP
8b0cefbb 168Initially, the default \s-1DH_METHOD\s0 is the OpenSSL internal implementation, as
984263bc
MD
169returned by \fIDH_OpenSSL()\fR.
170.PP
8b0cefbb
JR
171\&\fIDH_set_default_method()\fR makes \fBmeth\fR the default method for all \s-1DH\s0
172structures created later. \fB\s-1NB\s0\fR: This is true only whilst no \s-1ENGINE\s0 has been set
5a44c043 173as a default for \s-1DH,\s0 so this function is no longer recommended.
984263bc 174.PP
5a44c043
SW
175\&\fIDH_get_default_method()\fR returns a pointer to the current default \s-1DH_METHOD.\s0
176However, the meaningfulness of this result is dependent on whether the \s-1ENGINE
177API\s0 is being used, so this function is no longer recommended.
984263bc 178.PP
8b0cefbb
JR
179\&\fIDH_set_method()\fR selects \fBmeth\fR to perform all operations using the key \fBdh\fR.
180This will replace the \s-1DH_METHOD\s0 used by the \s-1DH\s0 key and if the previous method
5a44c043 181was supplied by an \s-1ENGINE,\s0 the handle to that \s-1ENGINE\s0 will be released during the
8b0cefbb
JR
182change. It is possible to have \s-1DH\s0 keys that only work with certain \s-1DH_METHOD\s0
183implementations (eg. from an \s-1ENGINE\s0 module that supports embedded
184hardware-protected keys), and in such cases attempting to change the \s-1DH_METHOD\s0
984263bc
MD
185for the key can have unexpected results.
186.PP
8b0cefbb 187\&\fIDH_new_method()\fR allocates and initializes a \s-1DH\s0 structure so that \fBengine\fR will
5a44c043 188be used for the \s-1DH\s0 operations. If \fBengine\fR is \s-1NULL,\s0 the default \s-1ENGINE\s0 for \s-1DH\s0
8b0cefbb
JR
189operations is used, and if no default \s-1ENGINE\s0 is set, the \s-1DH_METHOD\s0 controlled by
190\&\fIDH_set_default_method()\fR is used.
984263bc 191.SH "THE DH_METHOD STRUCTURE"
8b0cefbb 192.IX Header "THE DH_METHOD STRUCTURE"
984263bc
MD
193.Vb 4
194\& typedef struct dh_meth_st
195\& {
196\& /* name of the implementation */
197\& const char *name;
e257b235 198\&
984263bc
MD
199\& /* generate private and public DH values for key agreement */
200\& int (*generate_key)(DH *dh);
e257b235 201\&
984263bc
MD
202\& /* compute shared secret */
203\& int (*compute_key)(unsigned char *key, BIGNUM *pub_key, DH *dh);
e257b235 204\&
984263bc
MD
205\& /* compute r = a ^ p mod m (May be NULL for some implementations) */
206\& int (*bn_mod_exp)(DH *dh, BIGNUM *r, BIGNUM *a, const BIGNUM *p,
207\& const BIGNUM *m, BN_CTX *ctx,
208\& BN_MONT_CTX *m_ctx);
e257b235 209\&
984263bc
MD
210\& /* called at DH_new */
211\& int (*init)(DH *dh);
e257b235 212\&
984263bc
MD
213\& /* called at DH_free */
214\& int (*finish)(DH *dh);
e257b235 215\&
984263bc 216\& int flags;
e257b235 217\&
984263bc 218\& char *app_data; /* ?? */
e257b235 219\&
984263bc
MD
220\& } DH_METHOD;
221.Ve
222.SH "RETURN VALUES"
8b0cefbb
JR
223.IX Header "RETURN VALUES"
224\&\fIDH_OpenSSL()\fR and \fIDH_get_default_method()\fR return pointers to the respective
225\&\fB\s-1DH_METHOD\s0\fRs.
984263bc 226.PP
8b0cefbb 227\&\fIDH_set_default_method()\fR returns no value.
984263bc 228.PP
8b0cefbb
JR
229\&\fIDH_set_method()\fR returns non-zero if the provided \fBmeth\fR was successfully set as
230the method for \fBdh\fR (including unloading the \s-1ENGINE\s0 handle if the previous
231method was supplied by an \s-1ENGINE\s0).
984263bc 232.PP
8b0cefbb
JR
233\&\fIDH_new_method()\fR returns \s-1NULL\s0 and sets an error code that can be obtained by
234\&\fIERR_get_error\fR\|(3) if the allocation fails. Otherwise it
984263bc
MD
235returns a pointer to the newly allocated structure.
236.SH "NOTES"
8b0cefbb
JR
237.IX Header "NOTES"
238As of version 0.9.7, \s-1DH_METHOD\s0 implementations are grouped together with other
5a44c043
SW
239algorithmic APIs (eg. \s-1RSA_METHOD, EVP_CIPHER,\s0 etc) in \fB\s-1ENGINE\s0\fR modules. If a
240default \s-1ENGINE\s0 is specified for \s-1DH\s0 functionality using an \s-1ENGINE API\s0 function,
241that will override any \s-1DH\s0 defaults set using the \s-1DH API \s0(ie.
242\&\fIDH_set_default_method()\fR). For this reason, the \s-1ENGINE API\s0 is the recommended way
8b0cefbb 243to control default implementations for use in \s-1DH\s0 and other cryptographic
984263bc
MD
244algorithms.
245.SH "SEE ALSO"
8b0cefbb
JR
246.IX Header "SEE ALSO"
247\&\fIdh\fR\|(3), \fIDH_new\fR\|(3)
984263bc 248.SH "HISTORY"
8b0cefbb
JR
249.IX Header "HISTORY"
250\&\fIDH_set_default_method()\fR, \fIDH_get_default_method()\fR, \fIDH_set_method()\fR,
251\&\fIDH_new_method()\fR and \fIDH_OpenSSL()\fR were added in OpenSSL 0.9.4.
984263bc 252.PP
8b0cefbb
JR
253\&\fIDH_set_default_openssl_method()\fR and \fIDH_get_default_openssl_method()\fR replaced
254\&\fIDH_set_default_method()\fR and \fIDH_get_default_method()\fR respectively, and
255\&\fIDH_set_method()\fR and \fIDH_new_method()\fR were altered to use \fB\s-1ENGINE\s0\fRs rather than
256\&\fB\s-1DH_METHOD\s0\fRs during development of the engine version of OpenSSL 0.9.6. For
5a44c043 2570.9.7, the handling of defaults in the \s-1ENGINE API\s0 was restructured so that this
984263bc 258change was reversed, and behaviour of the other functions resembled more closely
5a44c043
SW
259the previous behaviour. The behaviour of defaults in the \s-1ENGINE API\s0 now
260transparently overrides the behaviour of defaults in the \s-1DH API\s0 without
984263bc 261requiring changing these function prototypes.