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