blob: 21cfeed27b4635702ed4c67f9f1b92eca14540a2 [file] [log] [blame]
Ulf Möller2186cd82000-01-11 22:35:21 +00001=pod
2
3=head1 NAME
4
5RSA_set_default_method, RSA_get_default_method, RSA_set_method,
Rich Salz076fc552017-04-07 12:07:42 -04006RSA_get_method, RSA_PKCS1_OpenSSL, RSA_flags,
Richard Levittee2045162002-09-25 13:25:44 +00007RSA_new_method - select RSA method
Ulf Möller2186cd82000-01-11 22:35:21 +00008
9=head1 SYNOPSIS
10
11 #include <openssl/rsa.h>
12
Matt Caswell3dbf8242021-12-02 11:33:49 +000013The following functions have been deprecated since OpenSSL 3.0, and can be
14hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
15see L<openssl_user_macros(7)>:
Pauli4fd8a3e2020-02-12 15:23:01 +100016
Geoff Thorpeac120e22002-08-04 21:08:36 +000017 void RSA_set_default_method(const RSA_METHOD *meth);
Ulf Möller2186cd82000-01-11 22:35:21 +000018
PW Hu10343fa2021-10-18 16:49:14 +080019 const RSA_METHOD *RSA_get_default_method(void);
Ulf Möller2186cd82000-01-11 22:35:21 +000020
Geoff Thorpeac120e22002-08-04 21:08:36 +000021 int RSA_set_method(RSA *rsa, const RSA_METHOD *meth);
Ulf Möller2186cd82000-01-11 22:35:21 +000022
PW Hu10343fa2021-10-18 16:49:14 +080023 const RSA_METHOD *RSA_get_method(const RSA *rsa);
Ulf Möller2186cd82000-01-11 22:35:21 +000024
PW Hu10343fa2021-10-18 16:49:14 +080025 const RSA_METHOD *RSA_PKCS1_OpenSSL(void);
Ulf Möller2186cd82000-01-11 22:35:21 +000026
Geoff Thorpeac120e22002-08-04 21:08:36 +000027 int RSA_flags(const RSA *rsa);
Ulf Möller2186cd82000-01-11 22:35:21 +000028
Roumen Petrov6baa3b42016-02-13 10:41:49 +020029 RSA *RSA_new_method(ENGINE *engine);
Ulf Möller2186cd82000-01-11 22:35:21 +000030
31=head1 DESCRIPTION
32
Pauli4fd8a3e2020-02-12 15:23:01 +100033All of the functions described on this page are deprecated.
34Applications should instead use the OSSL_PROVIDER APIs.
35
Ulf Möller2186cd82000-01-11 22:35:21 +000036An B<RSA_METHOD> specifies the functions that OpenSSL uses for RSA
Geoff Thorpeac120e22002-08-04 21:08:36 +000037operations. By modifying the method, alternative implementations such as
38hardware accelerators may be used. IMPORTANT: See the NOTES section for
39important information about how these RSA API functions are affected by the
40use of B<ENGINE> API calls.
Ulf Möller2186cd82000-01-11 22:35:21 +000041
Geoff Thorpeac120e22002-08-04 21:08:36 +000042Initially, the default RSA_METHOD is the OpenSSL internal implementation,
Beat Bollia6eef4c2016-04-07 23:32:59 +020043as returned by RSA_PKCS1_OpenSSL().
Ulf Möller2186cd82000-01-11 22:35:21 +000044
Geoff Thorpe415e03a2002-08-05 02:54:57 +000045RSA_set_default_method() makes B<meth> the default method for all RSA
Rich Salz076fc552017-04-07 12:07:42 -040046structures created later.
47B<NB>: This is true only whilst no ENGINE has
Geoff Thorpeac120e22002-08-04 21:08:36 +000048been set as a default for RSA, so this function is no longer recommended.
Rich Salz076fc552017-04-07 12:07:42 -040049This function is not thread-safe and should not be called at the same time
50as other OpenSSL functions.
Ulf Möller2186cd82000-01-11 22:35:21 +000051
Geoff Thorpeac120e22002-08-04 21:08:36 +000052RSA_get_default_method() returns a pointer to the current default
Lutz Jänickeb6a338c2007-11-19 09:18:03 +000053RSA_METHOD. However, the meaningfulness of this result is dependent on
Rich Salz1bc74512016-05-20 08:11:46 -040054whether the ENGINE API is being used, so this function is no longer
Geoff Thorpeac120e22002-08-04 21:08:36 +000055recommended.
Ulf Möller2186cd82000-01-11 22:35:21 +000056
Geoff Thorpeac120e22002-08-04 21:08:36 +000057RSA_set_method() selects B<meth> to perform all operations using the key
58B<rsa>. This will replace the RSA_METHOD used by the RSA key and if the
59previous method was supplied by an ENGINE, the handle to that ENGINE will
60be released during the change. It is possible to have RSA keys that only
Gustaf Neumann8c1cbc72020-06-29 21:13:07 +020061work with certain RSA_METHOD implementations (e.g. from an ENGINE module
Geoff Thorpeac120e22002-08-04 21:08:36 +000062that supports embedded hardware-protected keys), and in such cases
63attempting to change the RSA_METHOD for the key can have unexpected
64results.
Ulf Möller2186cd82000-01-11 22:35:21 +000065
Geoff Thorpeac120e22002-08-04 21:08:36 +000066RSA_get_method() returns a pointer to the RSA_METHOD being used by B<rsa>.
67This method may or may not be supplied by an ENGINE implementation, but if
68it is, the return value can only be guaranteed to be valid as long as the
69RSA key itself is valid and does not have its implementation changed by
70RSA_set_method().
Ulf Möller2186cd82000-01-11 22:35:21 +000071
Geoff Thorpeac120e22002-08-04 21:08:36 +000072RSA_flags() returns the B<flags> that are set for B<rsa>'s current
73RSA_METHOD. See the BUGS section.
Ulf Möller2186cd82000-01-11 22:35:21 +000074
Richard Levitte5270e702000-10-26 21:07:28 +000075RSA_new_method() allocates and initializes an RSA structure so that
Geoff Thorpeac120e22002-08-04 21:08:36 +000076B<engine> will be used for the RSA operations. If B<engine> is NULL, the
77default ENGINE for RSA operations is used, and if no default ENGINE is set,
78the RSA_METHOD controlled by RSA_set_default_method() is used.
Ulf Möller2186cd82000-01-11 22:35:21 +000079
Richard Levittee2045162002-09-25 13:25:44 +000080RSA_flags() returns the B<flags> that are set for B<rsa>'s current method.
81
82RSA_new_method() allocates and initializes an B<RSA> structure so that
83B<method> will be used for the RSA operations. If B<method> is B<NULL>,
84the default method is used.
85
Ulf Möller2186cd82000-01-11 22:35:21 +000086=head1 THE RSA_METHOD STRUCTURE
87
88 typedef struct rsa_meth_st
89 {
90 /* name of the implementation */
Beat Bolli2947af32016-11-19 00:10:05 +010091 const char *name;
Ulf Möller2186cd82000-01-11 22:35:21 +000092
93 /* encrypt */
Beat Bolli2947af32016-11-19 00:10:05 +010094 int (*rsa_pub_enc)(int flen, unsigned char *from,
95 unsigned char *to, RSA *rsa, int padding);
Ulf Möller2186cd82000-01-11 22:35:21 +000096
97 /* verify arbitrary data */
Beat Bolli2947af32016-11-19 00:10:05 +010098 int (*rsa_pub_dec)(int flen, unsigned char *from,
99 unsigned char *to, RSA *rsa, int padding);
Ulf Möller2186cd82000-01-11 22:35:21 +0000100
101 /* sign arbitrary data */
Beat Bolli2947af32016-11-19 00:10:05 +0100102 int (*rsa_priv_enc)(int flen, unsigned char *from,
103 unsigned char *to, RSA *rsa, int padding);
Ulf Möller2186cd82000-01-11 22:35:21 +0000104
105 /* decrypt */
Beat Bolli2947af32016-11-19 00:10:05 +0100106 int (*rsa_priv_dec)(int flen, unsigned char *from,
107 unsigned char *to, RSA *rsa, int padding);
Ulf Möller2186cd82000-01-11 22:35:21 +0000108
Beat Bolli2947af32016-11-19 00:10:05 +0100109 /* 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öller2186cd82000-01-11 22:35:21 +0000111
Ulf Möllere4947bf2000-03-09 17:07:55 +0000112 /* compute r = a ^ p mod m (May be NULL for some implementations) */
Beat Bolli2947af32016-11-19 00:10:05 +0100113 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öller2186cd82000-01-11 22:35:21 +0000115
116 /* called at RSA_new */
Beat Bolli2947af32016-11-19 00:10:05 +0100117 int (*init)(RSA *rsa);
Ulf Möller2186cd82000-01-11 22:35:21 +0000118
119 /* called at RSA_free */
Beat Bolli2947af32016-11-19 00:10:05 +0100120 int (*finish)(RSA *rsa);
Ulf Möller2186cd82000-01-11 22:35:21 +0000121
Beat Bolli2947af32016-11-19 00:10:05 +0100122 /*
123 * RSA_FLAG_EXT_PKEY - rsa_mod_exp is called for private key
Ulf Möller2186cd82000-01-11 22:35:21 +0000124 * operations, even if p,q,dmp1,dmq1,iqmp
125 * are NULL
Ulf Möller2186cd82000-01-11 22:35:21 +0000126 * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match
127 */
Beat Bolli2947af32016-11-19 00:10:05 +0100128 int flags;
Ulf Möller2186cd82000-01-11 22:35:21 +0000129
Beat Bolli2947af32016-11-19 00:10:05 +0100130 char *app_data; /* ?? */
Ulf Möller2186cd82000-01-11 22:35:21 +0000131
Beat Bolli2947af32016-11-19 00:10:05 +0100132 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 Salz9c0586d2019-09-27 13:17:09 -0400139 /* keygen. If NULL built-in RSA key generation will be used */
Beat Bolli2947af32016-11-19 00:10:05 +0100140 int (*rsa_keygen)(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb);
Ulf Möller2186cd82000-01-11 22:35:21 +0000141
142 } RSA_METHOD;
143
144=head1 RETURN VALUES
145
Beat Bollia6eef4c2016-04-07 23:32:59 +0200146RSA_PKCS1_OpenSSL(), RSA_PKCS1_null_method(), RSA_get_default_method()
Richard Levitteccb96432000-11-08 17:51:37 +0000147and RSA_get_method() return pointers to the respective RSA_METHODs.
Ulf Möller2186cd82000-01-11 22:35:21 +0000148
Geoff Thorpeac120e22002-08-04 21:08:36 +0000149RSA_set_default_method() returns no value.
Ulf Möller2186cd82000-01-11 22:35:21 +0000150
Geoff Thorpeac120e22002-08-04 21:08:36 +0000151RSA_set_method() returns a pointer to the old RSA_METHOD implementation
152that was replaced. However, this return value should probably be ignored
153because if it was supplied by an ENGINE, the pointer could be invalidated
154at any time if the ENGINE is unloaded (in fact it could be unloaded as a
155result of the RSA_set_method() function releasing its handle to the
156ENGINE). For this reason, the return type may be replaced with a B<void>
157declaration in a future release.
Ulf Möller2186cd82000-01-11 22:35:21 +0000158
Geoff Thorpeac120e22002-08-04 21:08:36 +0000159RSA_new_method() returns NULL and sets an error code that can be obtained
Rich Salz9b869742015-08-17 15:21:33 -0400160by L<ERR_get_error(3)> if the allocation fails. Otherwise
Richard Levitte5270e702000-10-26 21:07:28 +0000161it returns a pointer to the newly allocated structure.
Ulf Möller2186cd82000-01-11 22:35:21 +0000162
Geoff Thorpeac120e22002-08-04 21:08:36 +0000163=head1 BUGS
164
165The behaviour of RSA_flags() is a mis-feature that is left as-is for now
166to avoid creating compatibility problems. RSA functionality, such as the
167encryption functions, are controlled by the B<flags> value in the RSA key
168itself, 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
170is changed, the changes will be honoured by RSA functionality but will not
171be reflected in the return value of the RSA_flags() function - in effect
172RSA_flags() behaves more like an RSA_default_flags() function (which does
173not currently exist).
174
Ulf Möller2186cd82000-01-11 22:35:21 +0000175=head1 SEE ALSO
176
Rich Salz53934822016-06-09 16:39:19 -0400177L<RSA_new(3)>
Ulf Möller2186cd82000-01-11 22:35:21 +0000178
Rich Salz076fc552017-04-07 12:07:42 -0400179=head1 HISTORY
180
Pauli4fd8a3e2020-02-12 15:23:01 +1000181All of these functions were deprecated in OpenSSL 3.0.
182
Rich Salz076fc552017-04-07 12:07:42 -0400183The RSA_null_method(), which was a partial attempt to avoid patent issues,
184was replaced to always return NULL in OpenSSL 1.1.1.
185
Rich Salze2f92612016-05-18 11:44:05 -0400186=head1 COPYRIGHT
187
Matt Caswell33388b42020-04-23 13:55:52 +0100188Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
Rich Salze2f92612016-05-18 11:44:05 -0400189
Richard Levitte4746f252018-12-06 14:04:44 +0100190Licensed under the Apache License 2.0 (the "License"). You may not use
Rich Salze2f92612016-05-18 11:44:05 -0400191this file except in compliance with the License. You can obtain a copy
192in the file LICENSE in the source distribution or at
193L<https://www.openssl.org/source/license.html>.
194
195=cut