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