Commit manual pages after running 'man-update' and add new manual pages.
[dragonfly.git] / secure / lib / libcrypto / man / DH_set_method.3
CommitLineData
74dab6c2
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
74dab6c2 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
74dab6c2 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
74dab6c2 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
74dab6c2 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
74dab6c2
JR
34'''
35'''
36''' Set up \*(-- to give an unbreakable dash;
37''' string Tr holds user defined translation string.
38''' Bell System Logo is used as a dummy character.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
74dab6c2
JR
42.ds -- \(*W-
43.ds PI pi
44.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46.ds L" ""
47.ds R" ""
48''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49''' \*(L" and \*(R", except that they are used on ".xx" lines,
50''' such as .IP and .SH, which do another additional levels of
51''' double-quote interpretation
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
74dab6c2
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
74dab6c2
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
74dab6c2
JR
93.nr % 0
94.rr F
984263bc 95.\}
74dab6c2
JR
96.TH DH_set_method 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
74dab6c2
JR
100.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101.de CQ \" put $1 in typewriter font
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
74dab6c2 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
74dab6c2
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
74dab6c2
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
74dab6c2 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
74dab6c2
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
74dab6c2
JR
141. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
984263bc 150.\}
74dab6c2 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
152.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
74dab6c2
JR
154.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
984263bc
MD
158.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163.ds ae a\h'-(\w'a'u*4/10)'e
164.ds Ae A\h'-(\w'A'u*4/10)'E
74dab6c2
JR
165.ds oe o\h'-(\w'o'u*4/10)'e
166.ds Oe O\h'-(\w'O'u*4/10)'E
167. \" corrections for vroff
984263bc
MD
168.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
74dab6c2 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
74dab6c2
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc
MD
190.SH "NAME"
191DH_set_default_method, DH_get_default_method,
74dab6c2 192DH_set_method, DH_new_method, DH_OpenSSL \- select DH method
984263bc 193.SH "SYNOPSIS"
74dab6c2 194.PP
984263bc
MD
195.Vb 2
196\& #include <openssl/dh.h>
197\& #include <openssl/engine.h>
198.Ve
199.Vb 1
200\& void DH_set_default_method(const DH_METHOD *meth);
201.Ve
202.Vb 1
203\& const DH_METHOD *DH_get_default_method(void);
204.Ve
205.Vb 1
206\& int DH_set_method(DH *dh, const DH_METHOD *meth);
207.Ve
208.Vb 1
209\& DH *DH_new_method(ENGINE *engine);
210.Ve
211.Vb 1
212\& const DH_METHOD *DH_OpenSSL(void);
213.Ve
214.SH "DESCRIPTION"
74dab6c2 215A \fBDH_METHOD\fR specifies the functions that OpenSSL uses for Diffie-Hellman
984263bc 216operations. By modifying the method, alternative implementations
74dab6c2
JR
217such as hardware accelerators may be used. IMPORTANT: See the NOTES section for
218important information about how these DH API functions are affected by the use
219of \fBENGINE\fR API calls.
984263bc 220.PP
74dab6c2 221Initially, the default DH_METHOD is the OpenSSL internal implementation, as
984263bc
MD
222returned by \fIDH_OpenSSL()\fR.
223.PP
74dab6c2
JR
224\fIDH_set_default_method()\fR makes \fBmeth\fR the default method for all DH
225structures created later. \fBNB\fR: This is true only whilst no ENGINE has been set
226as a default for DH, so this function is no longer recommended.
984263bc 227.PP
74dab6c2
JR
228\fIDH_get_default_method()\fR returns a pointer to the current default DH_METHOD.
229However, the meaningfulness of this result is dependant on whether the ENGINE
230API is being used, so this function is no longer recommended.
984263bc 231.PP
74dab6c2
JR
232\fIDH_set_method()\fR selects \fBmeth\fR to perform all operations using the key \fBdh\fR.
233This will replace the DH_METHOD used by the DH key and if the previous method
234was supplied by an ENGINE, the handle to that ENGINE will be released during the
235change. It is possible to have DH keys that only work with certain DH_METHOD
236implementations (eg. from an ENGINE module that supports embedded
237hardware-protected keys), and in such cases attempting to change the DH_METHOD
984263bc
MD
238for the key can have unexpected results.
239.PP
74dab6c2
JR
240\fIDH_new_method()\fR allocates and initializes a DH structure so that \fBengine\fR will
241be used for the DH operations. If \fBengine\fR is NULL, the default ENGINE for DH
242operations is used, and if no default ENGINE is set, the DH_METHOD controlled by
243\fIDH_set_default_method()\fR is used.
984263bc 244.SH "THE DH_METHOD STRUCTURE"
74dab6c2 245.PP
984263bc
MD
246.Vb 4
247\& typedef struct dh_meth_st
248\& {
249\& /* name of the implementation */
250\& const char *name;
251.Ve
252.Vb 2
253\& /* generate private and public DH values for key agreement */
254\& int (*generate_key)(DH *dh);
255.Ve
256.Vb 2
257\& /* compute shared secret */
258\& int (*compute_key)(unsigned char *key, BIGNUM *pub_key, DH *dh);
259.Ve
260.Vb 4
261\& /* compute r = a ^ p mod m (May be NULL for some implementations) */
262\& int (*bn_mod_exp)(DH *dh, BIGNUM *r, BIGNUM *a, const BIGNUM *p,
263\& const BIGNUM *m, BN_CTX *ctx,
264\& BN_MONT_CTX *m_ctx);
265.Ve
266.Vb 2
267\& /* called at DH_new */
268\& int (*init)(DH *dh);
269.Ve
270.Vb 2
271\& /* called at DH_free */
272\& int (*finish)(DH *dh);
273.Ve
274.Vb 1
275\& int flags;
276.Ve
277.Vb 1
278\& char *app_data; /* ?? */
279.Ve
280.Vb 1
281\& } DH_METHOD;
282.Ve
283.SH "RETURN VALUES"
74dab6c2
JR
284\fIDH_OpenSSL()\fR and \fIDH_get_default_method()\fR return pointers to the respective
285\fBDH_METHOD\fRs.
984263bc 286.PP
74dab6c2 287\fIDH_set_default_method()\fR returns no value.
984263bc 288.PP
74dab6c2
JR
289\fIDH_set_method()\fR returns non-zero if the provided \fBmeth\fR was successfully set as
290the method for \fBdh\fR (including unloading the ENGINE handle if the previous
291method was supplied by an ENGINE).
984263bc 292.PP
74dab6c2 293\fIDH_new_method()\fR returns NULL and sets an error code that can be obtained by
984263bc
MD
294ERR_get_error(3) if the allocation fails. Otherwise it
295returns a pointer to the newly allocated structure.
296.SH "NOTES"
74dab6c2
JR
297As of version 0.9.7, DH_METHOD implementations are grouped together with other
298algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in \fBENGINE\fR modules. If a
299default ENGINE is specified for DH functionality using an ENGINE API function,
300that will override any DH defaults set using the DH API (ie.
301\fIDH_set_default_method()\fR). For this reason, the ENGINE API is the recommended way
302to control default implementations for use in DH and other cryptographic
984263bc
MD
303algorithms.
304.SH "SEE ALSO"
984263bc
MD
305dh(3), DH_new(3)
306.SH "HISTORY"
74dab6c2
JR
307\fIDH_set_default_method()\fR, \fIDH_get_default_method()\fR, \fIDH_set_method()\fR,
308\fIDH_new_method()\fR and \fIDH_OpenSSL()\fR were added in OpenSSL 0.9.4.
984263bc 309.PP
74dab6c2
JR
310\fIDH_set_default_openssl_method()\fR and \fIDH_get_default_openssl_method()\fR replaced
311\fIDH_set_default_method()\fR and \fIDH_get_default_method()\fR respectively, and
312\fIDH_set_method()\fR and \fIDH_new_method()\fR were altered to use \fBENGINE\fRs rather than
313\fBDH_METHOD\fRs during development of the engine version of OpenSSL 0.9.6. For
3140.9.7, the handling of defaults in the ENGINE API was restructured so that this
984263bc 315change was reversed, and behaviour of the other functions resembled more closely
74dab6c2
JR
316the previous behaviour. The behaviour of defaults in the ENGINE API now
317transparently overrides the behaviour of defaults in the DH API without
984263bc 318requiring changing these function prototypes.
74dab6c2
JR
319
320.rn }` ''
321.IX Title "DH_set_method 3"
322.IX Name "DH_set_default_method, DH_get_default_method,
323DH_set_method, DH_new_method, DH_OpenSSL - select DH method"
324
325.IX Header "NAME"
326
327.IX Header "SYNOPSIS"
328
329.IX Header "DESCRIPTION"
330
331.IX Header "THE DH_METHOD STRUCTURE"
332
333.IX Header "RETURN VALUES"
334
335.IX Header "NOTES"
336
337.IX Header "SEE ALSO"
338
339.IX Header "HISTORY"
340