Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 1 | =pod |
| 2 | |
| 3 | =head1 NAME |
| 4 | |
| 5 | RSA_set_default_method, RSA_get_default_method, RSA_set_method, |
Rich Salz | 076fc55 | 2017-04-07 12:07:42 -0400 | [diff] [blame] | 6 | RSA_get_method, RSA_PKCS1_OpenSSL, RSA_flags, |
Richard Levitte | e204516 | 2002-09-25 13:25:44 +0000 | [diff] [blame] | 7 | RSA_new_method - select RSA method |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 8 | |
| 9 | =head1 SYNOPSIS |
| 10 | |
| 11 | #include <openssl/rsa.h> |
| 12 | |
Matt Caswell | 3dbf824 | 2021-12-02 11:33:49 +0000 | [diff] [blame] | 13 | The following functions have been deprecated since OpenSSL 3.0, and can be |
| 14 | hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, |
| 15 | see L<openssl_user_macros(7)>: |
Pauli | 4fd8a3e | 2020-02-12 15:23:01 +1000 | [diff] [blame] | 16 | |
Geoff Thorpe | ac120e2 | 2002-08-04 21:08:36 +0000 | [diff] [blame] | 17 | void RSA_set_default_method(const RSA_METHOD *meth); |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 18 | |
PW Hu | 10343fa | 2021-10-18 16:49:14 +0800 | [diff] [blame] | 19 | const RSA_METHOD *RSA_get_default_method(void); |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 20 | |
Geoff Thorpe | ac120e2 | 2002-08-04 21:08:36 +0000 | [diff] [blame] | 21 | int RSA_set_method(RSA *rsa, const RSA_METHOD *meth); |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 22 | |
PW Hu | 10343fa | 2021-10-18 16:49:14 +0800 | [diff] [blame] | 23 | const RSA_METHOD *RSA_get_method(const RSA *rsa); |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 24 | |
PW Hu | 10343fa | 2021-10-18 16:49:14 +0800 | [diff] [blame] | 25 | const RSA_METHOD *RSA_PKCS1_OpenSSL(void); |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 26 | |
Geoff Thorpe | ac120e2 | 2002-08-04 21:08:36 +0000 | [diff] [blame] | 27 | int RSA_flags(const RSA *rsa); |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 28 | |
Roumen Petrov | 6baa3b4 | 2016-02-13 10:41:49 +0200 | [diff] [blame] | 29 | RSA *RSA_new_method(ENGINE *engine); |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 30 | |
| 31 | =head1 DESCRIPTION |
| 32 | |
Pauli | 4fd8a3e | 2020-02-12 15:23:01 +1000 | [diff] [blame] | 33 | All of the functions described on this page are deprecated. |
| 34 | Applications should instead use the OSSL_PROVIDER APIs. |
| 35 | |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 36 | An B<RSA_METHOD> specifies the functions that OpenSSL uses for RSA |
Geoff Thorpe | ac120e2 | 2002-08-04 21:08:36 +0000 | [diff] [blame] | 37 | operations. By modifying the method, alternative implementations such as |
| 38 | hardware accelerators may be used. IMPORTANT: See the NOTES section for |
| 39 | important information about how these RSA API functions are affected by the |
| 40 | use of B<ENGINE> API calls. |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 41 | |
Geoff Thorpe | ac120e2 | 2002-08-04 21:08:36 +0000 | [diff] [blame] | 42 | Initially, the default RSA_METHOD is the OpenSSL internal implementation, |
Beat Bolli | a6eef4c | 2016-04-07 23:32:59 +0200 | [diff] [blame] | 43 | as returned by RSA_PKCS1_OpenSSL(). |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 44 | |
Geoff Thorpe | 415e03a | 2002-08-05 02:54:57 +0000 | [diff] [blame] | 45 | RSA_set_default_method() makes B<meth> the default method for all RSA |
Rich Salz | 076fc55 | 2017-04-07 12:07:42 -0400 | [diff] [blame] | 46 | structures created later. |
| 47 | B<NB>: This is true only whilst no ENGINE has |
Geoff Thorpe | ac120e2 | 2002-08-04 21:08:36 +0000 | [diff] [blame] | 48 | been set as a default for RSA, so this function is no longer recommended. |
Rich Salz | 076fc55 | 2017-04-07 12:07:42 -0400 | [diff] [blame] | 49 | This function is not thread-safe and should not be called at the same time |
| 50 | as other OpenSSL functions. |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 51 | |
Geoff Thorpe | ac120e2 | 2002-08-04 21:08:36 +0000 | [diff] [blame] | 52 | RSA_get_default_method() returns a pointer to the current default |
Lutz Jänicke | b6a338c | 2007-11-19 09:18:03 +0000 | [diff] [blame] | 53 | RSA_METHOD. However, the meaningfulness of this result is dependent on |
Rich Salz | 1bc7451 | 2016-05-20 08:11:46 -0400 | [diff] [blame] | 54 | whether the ENGINE API is being used, so this function is no longer |
Geoff Thorpe | ac120e2 | 2002-08-04 21:08:36 +0000 | [diff] [blame] | 55 | recommended. |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 56 | |
Geoff Thorpe | ac120e2 | 2002-08-04 21:08:36 +0000 | [diff] [blame] | 57 | RSA_set_method() selects B<meth> to perform all operations using the key |
| 58 | B<rsa>. This will replace the RSA_METHOD used by the RSA key and if the |
| 59 | previous method was supplied by an ENGINE, the handle to that ENGINE will |
| 60 | be released during the change. It is possible to have RSA keys that only |
Gustaf Neumann | 8c1cbc7 | 2020-06-29 21:13:07 +0200 | [diff] [blame] | 61 | work with certain RSA_METHOD implementations (e.g. from an ENGINE module |
Geoff Thorpe | ac120e2 | 2002-08-04 21:08:36 +0000 | [diff] [blame] | 62 | that supports embedded hardware-protected keys), and in such cases |
| 63 | attempting to change the RSA_METHOD for the key can have unexpected |
| 64 | results. |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 65 | |
Geoff Thorpe | ac120e2 | 2002-08-04 21:08:36 +0000 | [diff] [blame] | 66 | RSA_get_method() returns a pointer to the RSA_METHOD being used by B<rsa>. |
| 67 | This method may or may not be supplied by an ENGINE implementation, but if |
| 68 | it is, the return value can only be guaranteed to be valid as long as the |
| 69 | RSA key itself is valid and does not have its implementation changed by |
| 70 | RSA_set_method(). |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 71 | |
Geoff Thorpe | ac120e2 | 2002-08-04 21:08:36 +0000 | [diff] [blame] | 72 | RSA_flags() returns the B<flags> that are set for B<rsa>'s current |
| 73 | RSA_METHOD. See the BUGS section. |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 74 | |
Richard Levitte | 5270e70 | 2000-10-26 21:07:28 +0000 | [diff] [blame] | 75 | RSA_new_method() allocates and initializes an RSA structure so that |
Geoff Thorpe | ac120e2 | 2002-08-04 21:08:36 +0000 | [diff] [blame] | 76 | B<engine> will be used for the RSA operations. If B<engine> is NULL, the |
| 77 | default ENGINE for RSA operations is used, and if no default ENGINE is set, |
| 78 | the RSA_METHOD controlled by RSA_set_default_method() is used. |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 79 | |
Richard Levitte | e204516 | 2002-09-25 13:25:44 +0000 | [diff] [blame] | 80 | RSA_flags() returns the B<flags> that are set for B<rsa>'s current method. |
| 81 | |
| 82 | RSA_new_method() allocates and initializes an B<RSA> structure so that |
| 83 | B<method> will be used for the RSA operations. If B<method> is B<NULL>, |
| 84 | the default method is used. |
| 85 | |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 86 | =head1 THE RSA_METHOD STRUCTURE |
| 87 | |
| 88 | typedef struct rsa_meth_st |
| 89 | { |
| 90 | /* name of the implementation */ |
Beat Bolli | 2947af3 | 2016-11-19 00:10:05 +0100 | [diff] [blame] | 91 | const char *name; |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 92 | |
| 93 | /* encrypt */ |
Beat Bolli | 2947af3 | 2016-11-19 00:10:05 +0100 | [diff] [blame] | 94 | int (*rsa_pub_enc)(int flen, unsigned char *from, |
| 95 | unsigned char *to, RSA *rsa, int padding); |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 96 | |
| 97 | /* verify arbitrary data */ |
Beat Bolli | 2947af3 | 2016-11-19 00:10:05 +0100 | [diff] [blame] | 98 | int (*rsa_pub_dec)(int flen, unsigned char *from, |
| 99 | unsigned char *to, RSA *rsa, int padding); |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 100 | |
| 101 | /* sign arbitrary data */ |
Beat Bolli | 2947af3 | 2016-11-19 00:10:05 +0100 | [diff] [blame] | 102 | int (*rsa_priv_enc)(int flen, unsigned char *from, |
| 103 | unsigned char *to, RSA *rsa, int padding); |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 104 | |
| 105 | /* decrypt */ |
Beat Bolli | 2947af3 | 2016-11-19 00:10:05 +0100 | [diff] [blame] | 106 | int (*rsa_priv_dec)(int flen, unsigned char *from, |
| 107 | unsigned char *to, RSA *rsa, int padding); |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 108 | |
Beat Bolli | 2947af3 | 2016-11-19 00:10:05 +0100 | [diff] [blame] | 109 | /* compute r0 = r0 ^ I mod rsa->n (May be NULL for some implementations) */ |
| 110 | int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa); |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 111 | |
Ulf Möller | e4947bf | 2000-03-09 17:07:55 +0000 | [diff] [blame] | 112 | /* compute r = a ^ p mod m (May be NULL for some implementations) */ |
Beat Bolli | 2947af3 | 2016-11-19 00:10:05 +0100 | [diff] [blame] | 113 | int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p, |
| 114 | const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx); |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 115 | |
| 116 | /* called at RSA_new */ |
Beat Bolli | 2947af3 | 2016-11-19 00:10:05 +0100 | [diff] [blame] | 117 | int (*init)(RSA *rsa); |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 118 | |
| 119 | /* called at RSA_free */ |
Beat Bolli | 2947af3 | 2016-11-19 00:10:05 +0100 | [diff] [blame] | 120 | int (*finish)(RSA *rsa); |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 121 | |
Beat Bolli | 2947af3 | 2016-11-19 00:10:05 +0100 | [diff] [blame] | 122 | /* |
| 123 | * RSA_FLAG_EXT_PKEY - rsa_mod_exp is called for private key |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 124 | * operations, even if p,q,dmp1,dmq1,iqmp |
| 125 | * are NULL |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 126 | * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match |
| 127 | */ |
Beat Bolli | 2947af3 | 2016-11-19 00:10:05 +0100 | [diff] [blame] | 128 | int flags; |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 129 | |
Beat Bolli | 2947af3 | 2016-11-19 00:10:05 +0100 | [diff] [blame] | 130 | char *app_data; /* ?? */ |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 131 | |
Beat Bolli | 2947af3 | 2016-11-19 00:10:05 +0100 | [diff] [blame] | 132 | int (*rsa_sign)(int type, |
| 133 | const unsigned char *m, unsigned int m_length, |
| 134 | unsigned char *sigret, unsigned int *siglen, const RSA *rsa); |
| 135 | int (*rsa_verify)(int dtype, |
| 136 | const unsigned char *m, unsigned int m_length, |
| 137 | const unsigned char *sigbuf, unsigned int siglen, |
| 138 | const RSA *rsa); |
Rich Salz | 9c0586d | 2019-09-27 13:17:09 -0400 | [diff] [blame] | 139 | /* keygen. If NULL built-in RSA key generation will be used */ |
Beat Bolli | 2947af3 | 2016-11-19 00:10:05 +0100 | [diff] [blame] | 140 | int (*rsa_keygen)(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb); |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 141 | |
| 142 | } RSA_METHOD; |
| 143 | |
| 144 | =head1 RETURN VALUES |
| 145 | |
Beat Bolli | a6eef4c | 2016-04-07 23:32:59 +0200 | [diff] [blame] | 146 | RSA_PKCS1_OpenSSL(), RSA_PKCS1_null_method(), RSA_get_default_method() |
Richard Levitte | ccb9643 | 2000-11-08 17:51:37 +0000 | [diff] [blame] | 147 | and RSA_get_method() return pointers to the respective RSA_METHODs. |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 148 | |
Geoff Thorpe | ac120e2 | 2002-08-04 21:08:36 +0000 | [diff] [blame] | 149 | RSA_set_default_method() returns no value. |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 150 | |
Geoff Thorpe | ac120e2 | 2002-08-04 21:08:36 +0000 | [diff] [blame] | 151 | RSA_set_method() returns a pointer to the old RSA_METHOD implementation |
| 152 | that was replaced. However, this return value should probably be ignored |
| 153 | because if it was supplied by an ENGINE, the pointer could be invalidated |
| 154 | at any time if the ENGINE is unloaded (in fact it could be unloaded as a |
| 155 | result of the RSA_set_method() function releasing its handle to the |
| 156 | ENGINE). For this reason, the return type may be replaced with a B<void> |
| 157 | declaration in a future release. |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 158 | |
Geoff Thorpe | ac120e2 | 2002-08-04 21:08:36 +0000 | [diff] [blame] | 159 | RSA_new_method() returns NULL and sets an error code that can be obtained |
Rich Salz | 9b86974 | 2015-08-17 15:21:33 -0400 | [diff] [blame] | 160 | by L<ERR_get_error(3)> if the allocation fails. Otherwise |
Richard Levitte | 5270e70 | 2000-10-26 21:07:28 +0000 | [diff] [blame] | 161 | it returns a pointer to the newly allocated structure. |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 162 | |
Geoff Thorpe | ac120e2 | 2002-08-04 21:08:36 +0000 | [diff] [blame] | 163 | =head1 BUGS |
| 164 | |
| 165 | The behaviour of RSA_flags() is a mis-feature that is left as-is for now |
| 166 | to avoid creating compatibility problems. RSA functionality, such as the |
| 167 | encryption functions, are controlled by the B<flags> value in the RSA key |
| 168 | itself, not by the B<flags> value in the RSA_METHOD attached to the RSA key |
| 169 | (which is what this function returns). If the flags element of an RSA key |
| 170 | is changed, the changes will be honoured by RSA functionality but will not |
| 171 | be reflected in the return value of the RSA_flags() function - in effect |
| 172 | RSA_flags() behaves more like an RSA_default_flags() function (which does |
| 173 | not currently exist). |
| 174 | |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 175 | =head1 SEE ALSO |
| 176 | |
Rich Salz | 5393482 | 2016-06-09 16:39:19 -0400 | [diff] [blame] | 177 | L<RSA_new(3)> |
Ulf Möller | 2186cd8 | 2000-01-11 22:35:21 +0000 | [diff] [blame] | 178 | |
Rich Salz | 076fc55 | 2017-04-07 12:07:42 -0400 | [diff] [blame] | 179 | =head1 HISTORY |
| 180 | |
Pauli | 4fd8a3e | 2020-02-12 15:23:01 +1000 | [diff] [blame] | 181 | All of these functions were deprecated in OpenSSL 3.0. |
| 182 | |
Rich Salz | 076fc55 | 2017-04-07 12:07:42 -0400 | [diff] [blame] | 183 | The RSA_null_method(), which was a partial attempt to avoid patent issues, |
| 184 | was replaced to always return NULL in OpenSSL 1.1.1. |
| 185 | |
Rich Salz | e2f9261 | 2016-05-18 11:44:05 -0400 | [diff] [blame] | 186 | =head1 COPYRIGHT |
| 187 | |
Matt Caswell | 33388b4 | 2020-04-23 13:55:52 +0100 | [diff] [blame] | 188 | Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. |
Rich Salz | e2f9261 | 2016-05-18 11:44:05 -0400 | [diff] [blame] | 189 | |
Richard Levitte | 4746f25 | 2018-12-06 14:04:44 +0100 | [diff] [blame] | 190 | Licensed under the Apache License 2.0 (the "License"). You may not use |
Rich Salz | e2f9261 | 2016-05-18 11:44:05 -0400 | [diff] [blame] | 191 | this file except in compliance with the License. You can obtain a copy |
| 192 | in the file LICENSE in the source distribution or at |
| 193 | L<https://www.openssl.org/source/license.html>. |
| 194 | |
| 195 | =cut |