Switch from OpenSSL 0.9.7d to 0.9.7e.
[dragonfly.git] / secure / lib / libcrypto / man / DSA_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 DSA_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"
191DSA_set_default_method, DSA_get_default_method,
74dab6c2 192DSA_set_method, DSA_new_method, DSA_OpenSSL \- select DSA method
984263bc 193.SH "SYNOPSIS"
74dab6c2 194.PP
984263bc
MD
195.Vb 2
196\& #include <openssl/dsa.h>
197\& #include <openssl/engine.h>
198.Ve
199.Vb 1
200\& void DSA_set_default_method(const DSA_METHOD *meth);
201.Ve
202.Vb 1
203\& const DSA_METHOD *DSA_get_default_method(void);
204.Ve
205.Vb 1
206\& int DSA_set_method(DSA *dsa, const DSA_METHOD *meth);
207.Ve
208.Vb 1
209\& DSA *DSA_new_method(ENGINE *engine);
210.Ve
211.Vb 1
212\& DSA_METHOD *DSA_OpenSSL(void);
213.Ve
214.SH "DESCRIPTION"
74dab6c2 215A \fBDSA_METHOD\fR specifies the functions that OpenSSL uses for DSA
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 DSA API functions are affected by the use
219of \fBENGINE\fR API calls.
984263bc 220.PP
74dab6c2 221Initially, the default DSA_METHOD is the OpenSSL internal implementation,
984263bc
MD
222as returned by \fIDSA_OpenSSL()\fR.
223.PP
74dab6c2
JR
224\fIDSA_set_default_method()\fR makes \fBmeth\fR the default method for all DSA
225structures created later. \fBNB\fR: This is true only whilst no ENGINE has
226been set as a default for DSA, so this function is no longer recommended.
984263bc 227.PP
74dab6c2
JR
228\fIDSA_get_default_method()\fR returns a pointer to the current default
229DSA_METHOD. However, the meaningfulness of this result is dependant on
230whether the ENGINE API is being used, so this function is no longer
984263bc
MD
231recommended.
232.PP
74dab6c2
JR
233\fIDSA_set_method()\fR selects \fBmeth\fR to perform all operations using the key
234\fBrsa\fR. This will replace the DSA_METHOD used by the DSA key and if the
235previous method was supplied by an ENGINE, the handle to that ENGINE will
236be released during the change. It is possible to have DSA keys that only
237work with certain DSA_METHOD implementations (eg. from an ENGINE module
984263bc 238that supports embedded hardware-protected keys), and in such cases
74dab6c2 239attempting to change the DSA_METHOD for the key can have unexpected
984263bc
MD
240results.
241.PP
74dab6c2
JR
242\fIDSA_new_method()\fR allocates and initializes a DSA structure so that \fBengine\fR
243will be used for the DSA operations. If \fBengine\fR is NULL, the default engine
244for DSA operations is used, and if no default ENGINE is set, the DSA_METHOD
984263bc
MD
245controlled by \fIDSA_set_default_method()\fR is used.
246.SH "THE DSA_METHOD STRUCTURE"
984263bc
MD
247struct
248 {
249 /* name of the implementation */
250 const char *name;
251.PP
252.Vb 3
253\& /* sign */
254\& DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen,
255\& DSA *dsa);
256.Ve
257.Vb 3
258\& /* pre-compute k^-1 and r */
259\& int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp,
260\& BIGNUM **rp);
261.Ve
262.Vb 3
263\& /* verify */
264\& int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len,
265\& DSA_SIG *sig, DSA *dsa);
266.Ve
267.Vb 5
268\& /* compute rr = a1^p1 * a2^p2 mod m (May be NULL for some
269\& implementations) */
270\& int (*dsa_mod_exp)(DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1,
271\& BIGNUM *a2, BIGNUM *p2, BIGNUM *m,
272\& BN_CTX *ctx, BN_MONT_CTX *in_mont);
273.Ve
274.Vb 4
275\& /* compute r = a ^ p mod m (May be NULL for some implementations) */
276\& int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a,
277\& const BIGNUM *p, const BIGNUM *m,
278\& BN_CTX *ctx, BN_MONT_CTX *m_ctx);
279.Ve
280.Vb 2
281\& /* called at DSA_new */
282\& int (*init)(DSA *DSA);
283.Ve
284.Vb 2
285\& /* called at DSA_free */
286\& int (*finish)(DSA *DSA);
287.Ve
288.Vb 1
289\& int flags;
290.Ve
291.Vb 1
292\& char *app_data; /* ?? */
293.Ve
294.Vb 1
295\& } DSA_METHOD;
296.Ve
297.SH "RETURN VALUES"
74dab6c2
JR
298\fIDSA_OpenSSL()\fR and \fIDSA_get_default_method()\fR return pointers to the respective
299\fBDSA_METHOD\fRs.
984263bc 300.PP
74dab6c2 301\fIDSA_set_default_method()\fR returns no value.
984263bc 302.PP
74dab6c2
JR
303\fIDSA_set_method()\fR returns non-zero if the provided \fBmeth\fR was successfully set as
304the method for \fBdsa\fR (including unloading the ENGINE handle if the previous
305method was supplied by an ENGINE).
984263bc 306.PP
74dab6c2 307\fIDSA_new_method()\fR returns NULL and sets an error code that can be
984263bc
MD
308obtained by ERR_get_error(3) if the allocation
309fails. Otherwise it returns a pointer to the newly allocated structure.
310.SH "NOTES"
74dab6c2
JR
311As of version 0.9.7, DSA_METHOD implementations are grouped together with other
312algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in \fBENGINE\fR modules. If a
313default ENGINE is specified for DSA functionality using an ENGINE API function,
314that will override any DSA defaults set using the DSA API (ie.
315\fIDSA_set_default_method()\fR). For this reason, the ENGINE API is the recommended way
316to control default implementations for use in DSA and other cryptographic
984263bc
MD
317algorithms.
318.SH "SEE ALSO"
984263bc
MD
319dsa(3), DSA_new(3)
320.SH "HISTORY"
74dab6c2
JR
321\fIDSA_set_default_method()\fR, \fIDSA_get_default_method()\fR, \fIDSA_set_method()\fR,
322\fIDSA_new_method()\fR and \fIDSA_OpenSSL()\fR were added in OpenSSL 0.9.4.
984263bc 323.PP
74dab6c2
JR
324\fIDSA_set_default_openssl_method()\fR and \fIDSA_get_default_openssl_method()\fR replaced
325\fIDSA_set_default_method()\fR and \fIDSA_get_default_method()\fR respectively, and
326\fIDSA_set_method()\fR and \fIDSA_new_method()\fR were altered to use \fBENGINE\fRs rather than
327\fBDSA_METHOD\fRs during development of the engine version of OpenSSL 0.9.6. For
3280.9.7, the handling of defaults in the ENGINE API was restructured so that this
984263bc 329change was reversed, and behaviour of the other functions resembled more closely
74dab6c2
JR
330the previous behaviour. The behaviour of defaults in the ENGINE API now
331transparently overrides the behaviour of defaults in the DSA API without
984263bc 332requiring changing these function prototypes.
74dab6c2
JR
333
334.rn }` ''
335.IX Title "DSA_set_method 3"
336.IX Name "DSA_set_default_method, DSA_get_default_method,
337DSA_set_method, DSA_new_method, DSA_OpenSSL - select DSA method"
338
339.IX Header "NAME"
340
341.IX Header "SYNOPSIS"
342
343.IX Header "DESCRIPTION"
344
345.IX Header "THE DSA_METHOD STRUCTURE"
346
347.IX Header "RETURN VALUES"
348
349.IX Header "NOTES"
350
351.IX Header "SEE ALSO"
352
353.IX Header "HISTORY"
354