xref: /openbsd-src/lib/libcrypto/man/RSA_set_method.3 (revision aa997e528a848ca5596493c2a801bdd6fb26ae61) 
1.\"	$OpenBSD: RSA_set_method.3,v 1.11 2018/03/27 17:35:50 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: March 27 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_null_method ,
63.Nm RSA_flags ,
64.Nm RSA_new_method
65.Nd select RSA method
66.Sh SYNOPSIS
67.In openssl/rsa.h
68.Ft void
69.Fo RSA_set_default_method
70.Fa "const RSA_METHOD *meth"
71.Fc
72.Ft RSA_METHOD *
73.Fn RSA_get_default_method void
74.Ft int
75.Fo RSA_set_method
76.Fa "RSA *rsa"
77.Fa "const RSA_METHOD *meth"
78.Fc
79.Ft RSA_METHOD *
80.Fo RSA_get_method
81.Fa "const RSA *rsa"
82.Fc
83.Ft RSA_METHOD *
84.Fn RSA_PKCS1_SSLeay void
85.Ft RSA_METHOD *
86.Fn RSA_null_method void
87.Ft int
88.Fo RSA_flags
89.Fa "const RSA *rsa"
90.Fc
91.Ft RSA *
92.Fo RSA_new_method
93.Fa "RSA_METHOD *meth"
94.Fc
95.Sh DESCRIPTION
96An
97.Vt RSA_METHOD
98specifies the functions that OpenSSL uses for RSA operations.
99By modifying the method, alternative implementations such as hardware
100accelerators may be used.
101See the
102.Sx CAVEATS
103section for how these RSA API functions are affected by the use of
104.Xr engine 3
105API calls.
106.Pp
107Initially, the default
108.Vt RSA_METHOD
109is the OpenSSL internal implementation, as returned by
110.Fn RSA_PKCS1_SSLeay .
111.Pp
112.Fn RSA_set_default_method
113makes
114.Fa meth
115the default method for all
116.Vt RSA
117structures created later.
118.Sy NB :
119This is true only whilst no
120.Vt ENGINE
121has been set as a default for RSA, so this function is no longer
122recommended.
123.Pp
124.Fn RSA_get_default_method
125returns a pointer to the current default
126.Vt RSA_METHOD .
127However, the meaningfulness of this result is dependent on whether
128the
129.Xr engine 3
130API is being used, so this function is no longer recommended.
131.Pp
132.Fn RSA_set_method
133selects
134.Fa meth
135to perform all operations using the key
136.Fa rsa .
137This will replace the
138.Vt RSA_METHOD
139used by the RSA key, and if the previous method was supplied by an
140.Vt ENGINE ,
141the handle to that
142.Vt ENGINE
143will be released during the change.
144It is possible to have RSA keys that only work with certain
145.Vt RSA_METHOD
146implementations (e.g. from an
147.Vt ENGINE
148module that supports embedded hardware-protected keys),
149and in such cases attempting to change the
150.Vt RSA_METHOD
151for the key can have unexpected results.
152.Pp
153.Fn RSA_get_method
154returns a pointer to the
155.Vt RSA_METHOD
156being used by
157.Fa rsa .
158This method may or may not be supplied by an
159.Vt ENGINE
160implementation but if it is, the return value can only be guaranteed
161to be valid as long as the RSA key itself is valid and does not
162have its implementation changed by
163.Fn RSA_set_method .
164.Pp
165.Fn RSA_flags
166returns the flags that are set for the current
167.Vt RSA_METHOD
168of
169.Fa rsa .
170See the
171.Sx BUGS
172section.
173.Pp
174.Fn RSA_new_method
175allocates and initializes an
176.Vt RSA
177structure so that
178.Fa meth
179will be used for the RSA operations.
180If
181.Sy engine
182is NULL, the default ENGINE for RSA operations is used and, if no
183default ENGINE is set, the RSA_METHOD controlled by
184.Fn RSA_set_default_method
185is used.
186.Pp
187.Fn RSA_flags
188returns the
189.Sy flags
190that are set for
191.Fa rsa Ns 's
192current method.
193.Pp
194.Fn RSA_new_method
195allocates and initializes an
196.Vt RSA
197structure so that
198.Fa meth
199will be used for the RSA operations.
200If
201.Fa meth
202is
203.Dv NULL ,
204the default method is used.
205.Sh THE RSA_METHOD STRUCTURE
206.Bd -literal
207typedef struct rsa_meth_st
208{
209     /* name of the implementation */
210	const char *name;
211
212     /* encrypt */
213	int (*rsa_pub_enc)(int flen, unsigned char *from,
214          unsigned char *to, RSA *rsa, int padding);
215
216     /* verify arbitrary data */
217	int (*rsa_pub_dec)(int flen, unsigned char *from,
218          unsigned char *to, RSA *rsa, int padding);
219
220     /* sign arbitrary data */
221	int (*rsa_priv_enc)(int flen, unsigned char *from,
222          unsigned char *to, RSA *rsa, int padding);
223
224     /* decrypt */
225	int (*rsa_priv_dec)(int flen, unsigned char *from,
226          unsigned char *to, RSA *rsa, int padding);
227
228     /* compute r0 = r0 ^ I mod rsa->n (May be NULL for some
229                                        implementations) */
230	int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa);
231
232     /* compute r = a ^ p mod m (May be NULL for some implementations) */
233	int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
234          const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);
235
236     /* called at RSA_new */
237	int (*init)(RSA *rsa);
238
239     /* called at RSA_free */
240	int (*finish)(RSA *rsa);
241
242     /* RSA_FLAG_EXT_PKEY        - rsa_mod_exp is called for private key
243      *                            operations, even if p,q,dmp1,dmq1,iqmp
244      *                            are NULL
245      * RSA_FLAG_SIGN_VER        - enable rsa_sign and rsa_verify
246      * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match
247      */
248	int flags;
249
250	char *app_data; /* ?? */
251
252     /* sign. For backward compatibility, this is used only
253      * if (flags & RSA_FLAG_SIGN_VER)
254      */
255	int (*rsa_sign)(int type, unsigned char *m, unsigned int m_len,
256           unsigned char *sigret, unsigned int *siglen, RSA *rsa);
257
258     /* verify. For backward compatibility, this is used only
259      * if (flags & RSA_FLAG_SIGN_VER)
260      */
261	int (*rsa_verify)(int type, unsigned char *m, unsigned int m_len,
262           unsigned char *sigbuf, unsigned int siglen, RSA *rsa);
263
264} RSA_METHOD;
265.Ed
266.Sh RETURN VALUES
267.Fn RSA_PKCS1_SSLeay ,
268.Fn RSA_null_method ,
269.Fn RSA_get_default_method
270and
271.Fn RSA_get_method
272return pointers to the respective
273.Vt RSA_METHOD .
274.Pp
275.Fn RSA_set_method
276returns a pointer to the old
277.Vt RSA_METHOD
278implementation that was replaced.
279However, this return value should probably be ignored because if it was
280supplied by an
281.Vt ENGINE ,
282the pointer could be invalidated at any time if the
283.Vt ENGINE
284is unloaded.
285In fact, it could be unloaded as a result of the
286.Fn RSA_set_method
287function releasing its handle to the
288.Vt ENGINE .
289For this reason, the return type may be replaced with a
290.Vt void
291declaration in a future release.
292.Pp
293.Fn RSA_new_method
294returns
295.Dv NULL
296and sets an error code that can be obtained by
297.Xr ERR_get_error 3
298if the allocation fails.
299Otherwise it returns a pointer to the newly allocated structure.
300.Sh SEE ALSO
301.Xr RSA_meth_new 3 ,
302.Xr RSA_new 3
303.Sh HISTORY
304.Fn RSA_set_default_method ,
305.Fn RSA_PKCS1_SSLeay ,
306and
307.Fn RSA_new_method
308first appeared in SSLeay 0.8.0.
309.Fn RSA_flags
310first appeared in SSLeay 0.9.0.
311These functions have been available since
312.Ox 2.4 .
313.Pp
314.Fn RSA_get_default_method ,
315.Fn RSA_set_method ,
316and
317.Fn RSA_get_method
318as well as the
319.Fa rsa_sign
320and
321.Fa rsa_verify
322components of
323.Vt RSA_METHOD
324first appeared in OpenSSL 0.9.4 and have been available since
325.Ox 2.6 .
326.Pp
327.Fn RSA_null_method
328first appeared in OpenSSL 0.9.5 and has been available since
329.Ox 2.7 .
330.Sh CAVEATS
331As of version 0.9.7,
332.Vt RSA_METHOD
333implementations are grouped together with other algorithmic APIs (e.g.\&
334.Vt DSA_METHOD
335or
336.Vt EVP_CIPHER )
337into
338.Vt ENGINE
339modules.
340If a default
341.Vt ENGINE
342is specified for RSA functionality using an
343.Xr engine 3
344API function, that will override any RSA defaults set using the RSA
345API, i.e.\&
346.Fn RSA_set_default_method .
347For this reason, the
348.Xr engine 3
349API is the recommended way to control default implementations for
350use in RSA and other cryptographic algorithms.
351.Sh BUGS
352The behaviour of
353.Fn RSA_flags
354is a misfeature that is left as-is for now to avoid creating
355compatibility problems.
356RSA functionality, such as the encryption functions, are controlled by
357the
358.Fa flags
359value in the
360.Vt RSA
361key itself, not by the
362.Fa flags
363value in the
364.Vt RSA_METHOD
365attached to the RSA key (which is what this function returns).
366If the flags element of an
367.Vt RSA
368key is changed, the changes will be honoured by RSA functionality
369but will not be reflected in the return value of the
370.Fn RSA_flags
371function - in effect
372.Fn RSA_flags
373behaves more like a RSA_default_flags() function, which does not
374currently exist.
375