jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: RSA_set_method.3,v 1.19 2025/06/08 22:40:30 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: June 8 2025 $
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.Lb libcrypto
67.In openssl/rsa.h
68.Ft void
69.Fo RSA_set_default_method
70.Fa "const RSA_METHOD *meth"
71.Fc
72.Ft const 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 const RSA_METHOD *
80.Fo RSA_get_method
81.Fa "const RSA *rsa"
82.Fc
83.Ft const RSA_METHOD *
84.Fn RSA_PKCS1_SSLeay void
85.Ft int
86.Fo RSA_flags
87.Fa "const RSA *rsa"
88.Fc
89.Ft RSA *
90.Fo RSA_new_method
91.Fa "ENGINE *engine"
92.Fc
93.Sh DESCRIPTION
94An
95.Vt RSA_METHOD
96object contains pointers to the functions used for RSA operations.
97By default, the internal implementation returned by
98.Fn RSA_PKCS1_SSLeay
99is used.
100By selecting another method, alternative implementations
101such as hardware accelerators may be used.
102.Pp
103.Fn RSA_set_default_method
104selects
105.Fa meth
106as the default method for all
107.Vt RSA
108structures created later.
109.Pp
110.Fn RSA_get_default_method
111returns a pointer to the current default method.
112.Pp
113.Fn RSA_set_method
114selects
115.Fa meth
116to perform all operations using the key
117.Fa rsa .
118This replaces the previous
119.Vt RSA_METHOD
120used by the RSA key, calling the
121.Fa finish
122function set up with
123.Xr RSA_meth_set_finish 3
124if any.
125If
126.Fa meth
127contains an
128.Fa init
129function set up with
130.Xr RSA_meth_set_init 3 ,
131that function is called just before returning from
132.Fn RSA_set_method .
133.Pp
134It is possible to have RSA keys that only work with certain
135.Vt RSA_METHOD
136implementations,
137and in such cases attempting to change the
138.Vt RSA_METHOD
139for the key can have unexpected results.
140.Pp
141.Fn RSA_get_method
142returns a pointer to the
143.Vt RSA_METHOD
144being used by
145.Fa rsa .
146.Pp
147The misleadingly named function
148.Fn RSA_flags
149returns the flags that are set for the current
150.Vt RSA_METHOD
151of
152.Fa rsa .
153The flags used by
154.Fa rsa
155itself can instead be tested with
156.Xr RSA_test_flags 3 .
157See the
158.Sx BUGS
159section for more details.
160.Pp
161.Fn RSA_new_method
162allocates and initializes an
163.Vt RSA
164structure.
165The
166.Fa engine
167argument is ignored and
168the default method controlled by
169.Fn RSA_set_default_method
170is used.
171.Pp
172The initial
173.Fa flags
174are copied from the
175.Vt RSA_METHOD
176object used and will not be affected by later changes to that object,
177but may be modified by the optional
178.Fa init
179function which may have been set up with
180.Xr RSA_meth_set_init 3
181and which is called just before returning from
182.Fn RSA_new_method .
183.Sh RETURN VALUES
184.Fn RSA_PKCS1_SSLeay ,
185.Fn RSA_get_default_method ,
186and
187.Fn RSA_get_method
188return pointers to the respective
189.Vt RSA_METHOD .
190.Pp
191.Fn RSA_set_method
192returns 1 on success or 0 on failure.
193Currently, it cannot fail.
194.Pp
195.Fn RSA_new_method
196returns
197.Dv NULL
198and sets an error code that can be obtained by
199.Xr ERR_get_error 3
200if the allocation fails.
201Otherwise it returns a pointer to the newly allocated structure.
202.Sh SEE ALSO
203.Xr RSA_meth_new 3 ,
204.Xr RSA_new 3
205.Sh HISTORY
206.Fn RSA_set_default_method ,
207.Fn RSA_PKCS1_SSLeay ,
208and
209.Fn RSA_new_method
210first appeared in SSLeay 0.8.0.
211.Fn RSA_flags
212first appeared in SSLeay 0.9.0.
213These functions have been available since
214.Ox 2.4 .
215.Pp
216.Fn RSA_get_default_method ,
217.Fn RSA_set_method ,
218and
219.Fn RSA_get_method
220as well as the
221.Fa rsa_sign
222and
223.Fa rsa_verify
224components of
225.Vt RSA_METHOD
226first appeared in OpenSSL 0.9.4 and have been available since
227.Ox 2.6 .
228.Sh BUGS
229The behaviour of
230.Fn RSA_flags
231is a misfeature that is left as-is for now to avoid creating
232compatibility problems.
233RSA functionality, such as the encryption functions, are controlled by
234the
235.Fa flags
236value in the
237.Vt RSA
238key itself, not by the
239.Fa flags
240value in the
241.Vt RSA_METHOD
242attached to the RSA key (which is what this function returns).
243If the flags element of an
244.Vt RSA
245key is changed, the changes will be honoured by RSA functionality
246but will not be reflected in the return value of the
247.Fn RSA_flags
248function - in effect
249.Fn RSA_flags
250behaves more like an
251.Fn RSA_default_flags
252function, which does not
253currently exist.