xref: /openbsd-src/lib/libcrypto/man/RSA_set_method.3 (revision c90a81c56dcebd6a1b73fe4aff9b03385b8e63b3) 
1.\"	$OpenBSD: RSA_set_method.3,v 1.12 2018/04/18 01:07:38 schwarze Exp $
2.\"	OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
3.\"
4.\" This file was written by Ulf Moeller <ulf@openssl.org>
5.\" and Geoff Thorpe <geoff@openssl.org>.
6.\" Copyright (c) 2000, 2002, 2007, 2014 The OpenSSL Project.
7.\" All rights reserved.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\"
13.\" 1. Redistributions of source code must retain the above copyright
14.\"    notice, this list of conditions and the following disclaimer.
15.\"
16.\" 2. Redistributions in binary form must reproduce the above copyright
17.\"    notice, this list of conditions and the following disclaimer in
18.\"    the documentation and/or other materials provided with the
19.\"    distribution.
20.\"
21.\" 3. All advertising materials mentioning features or use of this
22.\"    software must display the following acknowledgment:
23.\"    "This product includes software developed by the OpenSSL Project
24.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
25.\"
26.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
27.\"    endorse or promote products derived from this software without
28.\"    prior written permission. For written permission, please contact
29.\"    openssl-core@openssl.org.
30.\"
31.\" 5. Products derived from this software may not be called "OpenSSL"
32.\"    nor may "OpenSSL" appear in their names without prior written
33.\"    permission of the OpenSSL Project.
34.\"
35.\" 6. Redistributions of any form whatsoever must retain the following
36.\"    acknowledgment:
37.\"    "This product includes software developed by the OpenSSL Project
38.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
39.\"
40.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
41.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
42.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
43.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
44.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
45.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
46.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
47.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
48.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
49.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
50.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
51.\" OF THE POSSIBILITY OF SUCH DAMAGE.
52.\"
53.Dd $Mdocdate: April 18 2018 $
54.Dt RSA_SET_METHOD 3
55.Os
56.Sh NAME
57.Nm RSA_set_default_method ,
58.Nm RSA_get_default_method ,
59.Nm RSA_set_method ,
60.Nm RSA_get_method ,
61.Nm RSA_PKCS1_SSLeay ,
62.Nm RSA_flags ,
63.Nm RSA_new_method
64.Nd select RSA method
65.Sh SYNOPSIS
66.In openssl/rsa.h
67.Ft void
68.Fo RSA_set_default_method
69.Fa "const RSA_METHOD *meth"
70.Fc
71.Ft const RSA_METHOD *
72.Fn RSA_get_default_method void
73.Ft int
74.Fo RSA_set_method
75.Fa "RSA *rsa"
76.Fa "const RSA_METHOD *meth"
77.Fc
78.Ft const RSA_METHOD *
79.Fo RSA_get_method
80.Fa "const RSA *rsa"
81.Fc
82.Ft const RSA_METHOD *
83.Fn RSA_PKCS1_SSLeay void
84.Ft int
85.Fo RSA_flags
86.Fa "const RSA *rsa"
87.Fc
88.Ft RSA *
89.Fo RSA_new_method
90.Fa "ENGINE *engine"
91.Fc
92.Sh DESCRIPTION
93An
94.Vt RSA_METHOD
95object contains pointers to the functions used for RSA operations.
96By default, the internal implementation returned by
97.Fn RSA_PKCS1_SSLeay
98is used.
99By selecting another method, alternative implementations
100such as hardware accelerators may be used.
101.Pp
102.Fn RSA_set_default_method
103selects
104.Fa meth
105as the default method for all
106.Vt RSA
107structures created later.
108If any
109.Vt ENGINE
110was registered with
111.Xr ENGINE_register_RSA 3
112that can be successfully initialized, it overrides the default.
113.Pp
114.Fn RSA_get_default_method
115returns a pointer to the current default method,
116even if it is actually overridded by an
117.Vt ENGINE .
118.Pp
119.Fn RSA_set_method
120selects
121.Fa meth
122to perform all operations using the key
123.Fa rsa .
124This replaces the
125.Vt RSA_METHOD
126used by the RSA key, and if the previous method was supplied by an
127.Vt ENGINE ,
128.Xr ENGINE_finish 3
129is called on it.
130It is possible to have RSA keys that only work with certain
131.Vt RSA_METHOD
132implementations (e.g. from an
133.Vt ENGINE
134module that supports embedded hardware-protected keys),
135and in such cases attempting to change the
136.Vt RSA_METHOD
137for the key can have unexpected results.
138.Pp
139.Fn RSA_get_method
140returns a pointer to the
141.Vt RSA_METHOD
142being used by
143.Fa rsa .
144This method may or may not be supplied by an
145.Vt ENGINE
146implementation but if it is, the return value can only be guaranteed
147to be valid as long as the RSA key itself is valid and does not
148have its implementation changed by
149.Fn RSA_set_method .
150.Pp
151.Fn RSA_flags
152returns the flags that are set for the current
153.Vt RSA_METHOD
154of
155.Fa rsa .
156See the
157.Sx BUGS
158section.
159.Pp
160.Fn RSA_new_method
161allocates and initializes an
162.Vt RSA
163structure so that
164.Fa engine
165is used for the RSA operations.
166If
167.Fa engine
168is
169.Dv NULL ,
170.Xr ENGINE_get_default_RSA 3
171is used.
172If that returns
173.Dv NULL ,
174the default method controlled by
175.Fn RSA_set_default_method
176is used.
177.Pp
178The
179.Dv RSA_METHOD
180structure is defined as follows:
181.Bd -literal
182typedef struct rsa_meth_st
183{
184     /* name of the implementation */
185	const char *name;
186
187     /* encrypt */
188	int (*rsa_pub_enc)(int flen, unsigned char *from,
189          unsigned char *to, RSA *rsa, int padding);
190
191     /* verify arbitrary data */
192	int (*rsa_pub_dec)(int flen, unsigned char *from,
193          unsigned char *to, RSA *rsa, int padding);
194
195     /* sign arbitrary data */
196	int (*rsa_priv_enc)(int flen, unsigned char *from,
197          unsigned char *to, RSA *rsa, int padding);
198
199     /* decrypt */
200	int (*rsa_priv_dec)(int flen, unsigned char *from,
201          unsigned char *to, RSA *rsa, int padding);
202
203     /* compute r0 = r0 ^ I mod rsa->n (May be NULL for some
204                                        implementations) */
205	int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa);
206
207     /* compute r = a ^ p mod m (May be NULL for some implementations) */
208	int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
209          const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);
210
211     /* called at RSA_new */
212	int (*init)(RSA *rsa);
213
214     /* called at RSA_free */
215	int (*finish)(RSA *rsa);
216
217     /* RSA_FLAG_EXT_PKEY        - rsa_mod_exp is called for private key
218      *                            operations, even if p,q,dmp1,dmq1,iqmp
219      *                            are NULL
220      * RSA_FLAG_SIGN_VER        - enable rsa_sign and rsa_verify
221      * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match
222      */
223	int flags;
224
225	char *app_data; /* ?? */
226
227     /* sign. For backward compatibility, this is used only
228      * if (flags & RSA_FLAG_SIGN_VER)
229      */
230	int (*rsa_sign)(int type, unsigned char *m, unsigned int m_len,
231           unsigned char *sigret, unsigned int *siglen, RSA *rsa);
232
233     /* verify. For backward compatibility, this is used only
234      * if (flags & RSA_FLAG_SIGN_VER)
235      */
236	int (*rsa_verify)(int type, unsigned char *m, unsigned int m_len,
237           unsigned char *sigbuf, unsigned int siglen, RSA *rsa);
238
239} RSA_METHOD;
240.Ed
241.Sh RETURN VALUES
242.Fn RSA_PKCS1_SSLeay ,
243.Fn RSA_get_default_method ,
244and
245.Fn RSA_get_method
246return pointers to the respective
247.Vt RSA_METHOD .
248.Pp
249.Fn RSA_set_method
250returns 1 on success or 0 on failure.
251Currently, it cannot fail.
252.Pp
253.Fn RSA_new_method
254returns
255.Dv NULL
256and sets an error code that can be obtained by
257.Xr ERR_get_error 3
258if the allocation fails.
259Otherwise it returns a pointer to the newly allocated structure.
260.Sh SEE ALSO
261.Xr ENGINE_get_default_RSA 3 ,
262.Xr ENGINE_register_RSA 3 ,
263.Xr ENGINE_set_default_RSA 3 ,
264.Xr RSA_meth_new 3 ,
265.Xr RSA_new 3
266.Sh HISTORY
267.Fn RSA_set_default_method ,
268.Fn RSA_PKCS1_SSLeay ,
269and
270.Fn RSA_new_method
271first appeared in SSLeay 0.8.0.
272.Fn RSA_flags
273first appeared in SSLeay 0.9.0.
274These functions have been available since
275.Ox 2.4 .
276.Pp
277.Fn RSA_get_default_method ,
278.Fn RSA_set_method ,
279and
280.Fn RSA_get_method
281as well as the
282.Fa rsa_sign
283and
284.Fa rsa_verify
285components of
286.Vt RSA_METHOD
287first appeared in OpenSSL 0.9.4 and have been available since
288.Ox 2.6 .
289.Sh BUGS
290The behaviour of
291.Fn RSA_flags
292is a misfeature that is left as-is for now to avoid creating
293compatibility problems.
294RSA functionality, such as the encryption functions, are controlled by
295the
296.Fa flags
297value in the
298.Vt RSA
299key itself, not by the
300.Fa flags
301value in the
302.Vt RSA_METHOD
303attached to the RSA key (which is what this function returns).
304If the flags element of an
305.Vt RSA
306key is changed, the changes will be honoured by RSA functionality
307but will not be reflected in the return value of the
308.Fn RSA_flags
309function - in effect
310.Fn RSA_flags
311behaves more like a RSA_default_flags() function, which does not
312currently exist.
313