xref: /openbsd/lib/libcrypto/man/DSA_set_method.3 (revision 73471bf0) 
1.\"	$OpenBSD: DSA_set_method.3,v 1.9 2018/04/18 01:09:01 schwarze Exp $
2.\"	OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
3.\"
4.\" This file was written by Ulf Moeller <ulf@openssl.org>.
5.\" Copyright (c) 2000, 2002, 2007 The OpenSSL Project.  All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\"
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\"
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in
16.\"    the documentation and/or other materials provided with the
17.\"    distribution.
18.\"
19.\" 3. All advertising materials mentioning features or use of this
20.\"    software must display the following acknowledgment:
21.\"    "This product includes software developed by the OpenSSL Project
22.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
23.\"
24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
25.\"    endorse or promote products derived from this software without
26.\"    prior written permission. For written permission, please contact
27.\"    openssl-core@openssl.org.
28.\"
29.\" 5. Products derived from this software may not be called "OpenSSL"
30.\"    nor may "OpenSSL" appear in their names without prior written
31.\"    permission of the OpenSSL Project.
32.\"
33.\" 6. Redistributions of any form whatsoever must retain the following
34.\"    acknowledgment:
35.\"    "This product includes software developed by the OpenSSL Project
36.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
37.\"
38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
41.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49.\" OF THE POSSIBILITY OF SUCH DAMAGE.
50.\"
51.Dd $Mdocdate: April 18 2018 $
52.Dt DSA_SET_METHOD 3
53.Os
54.Sh NAME
55.Nm DSA_set_default_method ,
56.Nm DSA_get_default_method ,
57.Nm DSA_set_method ,
58.Nm DSA_new_method ,
59.Nm DSA_OpenSSL
60.Nd select DSA method
61.Sh SYNOPSIS
62.In openssl/dsa.h
63.Ft void
64.Fo DSA_set_default_method
65.Fa "const DSA_METHOD *meth"
66.Fc
67.Ft const DSA_METHOD *
68.Fn DSA_get_default_method void
69.Ft int
70.Fo DSA_set_method
71.Fa "DSA *dsa"
72.Fa "const DSA_METHOD *meth"
73.Fc
74.Ft DSA *
75.Fo DSA_new_method
76.Fa "ENGINE *engine"
77.Fc
78.Ft DSA_METHOD *
79.Fn DSA_OpenSSL void
80.Sh DESCRIPTION
81A
82.Vt DSA_METHOD
83object contains pointers to the functions used for DSA operations.
84By default, the internal implementation returned by
85.Fn DSA_OpenSSL
86is used.
87By selecting another method, alternative implementations
88such as hardware accelerators may be used.
89.Pp
90.Fn DSA_set_default_method
91selects
92.Fa meth
93as the default method for all
94.Vt DSA
95structures created later.
96If any
97.Vt ENGINE
98was registered with
99.Xr ENGINE_register_DSA 3
100that can be successfully initialized, it overrides the default.
101.Pp
102.Fn DSA_get_default_method
103returns a pointer to the current default method,
104even if it is actually overridded by an
105.Vt ENGINE .
106.Pp
107.Fn DSA_set_method
108selects
109.Fa meth
110to perform all operations using the key
111.Fa dsa .
112This replaces the
113.Vt DSA_METHOD
114used by the DSA key and if the previous method was supplied by an
115.Vt ENGINE ,
116.Xr ENGINE_finish 3
117is called on it.
118It is possible to have DSA keys that only work with certain
119.Vt DSA_METHOD
120implementations (e.g. from an
121.Vt ENGINE
122module that supports embedded hardware-protected keys),
123and in such cases attempting to change the
124.Vt DSA_METHOD
125for the key can have unexpected results.
126.Pp
127.Fn DSA_new_method
128allocates and initializes a
129.Vt DSA
130structure so that
131.Fa engine
132is used for the DSA operations.
133If
134.Fa engine
135is
136.Dv NULL ,
137.Xr ENGINE_get_default_DSA 3
138is used.
139If that returns
140.Dv NULL ,
141the default method controlled by
142.Fn DSA_set_default_method
143is used.
144.Pp
145The
146.Vt DSA_METHOD
147structure is defined as follows:
148.Bd -literal
149struct
150{
151     /* name of the implementation */
152	const char *name;
153
154     /* sign */
155	DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen,
156                                 DSA *dsa);
157
158     /* pre-compute k^-1 and r */
159	int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp,
160                                 BIGNUM **rp);
161
162     /* verify */
163	int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len,
164                                 DSA_SIG *sig, DSA *dsa);
165
166     /* compute rr = a1^p1 * a2^p2 mod m (May be NULL for some
167                                          implementations) */
168	int (*dsa_mod_exp)(DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1,
169                                 BIGNUM *a2, BIGNUM *p2, BIGNUM *m,
170                                 BN_CTX *ctx, BN_MONT_CTX *in_mont);
171
172     /* compute r = a ^ p mod m (May be NULL for some implementations) */
173        int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a,
174                                 const BIGNUM *p, const BIGNUM *m,
175                                 BN_CTX *ctx, BN_MONT_CTX *m_ctx);
176
177     /* called at DSA_new */
178        int (*init)(DSA *DSA);
179
180     /* called at DSA_free */
181        int (*finish)(DSA *DSA);
182
183        int flags;
184
185        char *app_data; /* ?? */
186
187} DSA_METHOD;
188.Ed
189.Sh RETURN VALUES
190.Fn DSA_OpenSSL
191and
192.Fn DSA_get_default_method
193return pointers to the respective
194.Vt DSA_METHOD .
195.Pp
196.Fn DSA_set_method
197returns 1 on success or 0 on failure.
198Currently, it cannot fail.
199.Pp
200.Fn DSA_new_method
201returns
202.Dv NULL
203and sets an error code that can be obtained by
204.Xr ERR_get_error 3
205if the allocation fails.
206Otherwise it returns a pointer to the newly allocated structure.
207.Sh SEE ALSO
208.Xr DSA_meth_new 3 ,
209.Xr DSA_new 3 ,
210.Xr ENGINE_get_default_DSA 3 ,
211.Xr ENGINE_register_DSA 3 ,
212.Xr ENGINE_set_default_DSA 3
213.Sh HISTORY
214.Fn DSA_set_default_method ,
215.Fn DSA_get_default_method ,
216.Fn DSA_set_method ,
217.Fn DSA_new_method ,
218and
219.Fn DSA_OpenSSL
220first appeared in OpenSSL 0.9.5 and have been available since
221.Ox 2.7 .
222