1*1dcdf01fSchristos=pod 2*1dcdf01fSchristos 3*1dcdf01fSchristos=head1 NAME 4*1dcdf01fSchristos 5*1dcdf01fSchristosRSA_set_default_method, RSA_get_default_method, RSA_set_method, 6*1dcdf01fSchristosRSA_get_method, RSA_PKCS1_OpenSSL, RSA_flags, 7*1dcdf01fSchristosRSA_new_method - select RSA method 8*1dcdf01fSchristos 9*1dcdf01fSchristos=head1 SYNOPSIS 10*1dcdf01fSchristos 11*1dcdf01fSchristos #include <openssl/rsa.h> 12*1dcdf01fSchristos 13*1dcdf01fSchristos void RSA_set_default_method(const RSA_METHOD *meth); 14*1dcdf01fSchristos 15*1dcdf01fSchristos RSA_METHOD *RSA_get_default_method(void); 16*1dcdf01fSchristos 17*1dcdf01fSchristos int RSA_set_method(RSA *rsa, const RSA_METHOD *meth); 18*1dcdf01fSchristos 19*1dcdf01fSchristos RSA_METHOD *RSA_get_method(const RSA *rsa); 20*1dcdf01fSchristos 21*1dcdf01fSchristos RSA_METHOD *RSA_PKCS1_OpenSSL(void); 22*1dcdf01fSchristos 23*1dcdf01fSchristos int RSA_flags(const RSA *rsa); 24*1dcdf01fSchristos 25*1dcdf01fSchristos RSA *RSA_new_method(ENGINE *engine); 26*1dcdf01fSchristos 27*1dcdf01fSchristos=head1 DESCRIPTION 28*1dcdf01fSchristos 29*1dcdf01fSchristosAn B<RSA_METHOD> specifies the functions that OpenSSL uses for RSA 30*1dcdf01fSchristosoperations. By modifying the method, alternative implementations such as 31*1dcdf01fSchristoshardware accelerators may be used. IMPORTANT: See the NOTES section for 32*1dcdf01fSchristosimportant information about how these RSA API functions are affected by the 33*1dcdf01fSchristosuse of B<ENGINE> API calls. 34*1dcdf01fSchristos 35*1dcdf01fSchristosInitially, the default RSA_METHOD is the OpenSSL internal implementation, 36*1dcdf01fSchristosas returned by RSA_PKCS1_OpenSSL(). 37*1dcdf01fSchristos 38*1dcdf01fSchristosRSA_set_default_method() makes B<meth> the default method for all RSA 39*1dcdf01fSchristosstructures created later. 40*1dcdf01fSchristosB<NB>: This is true only whilst no ENGINE has 41*1dcdf01fSchristosbeen set as a default for RSA, so this function is no longer recommended. 42*1dcdf01fSchristosThis function is not thread-safe and should not be called at the same time 43*1dcdf01fSchristosas other OpenSSL functions. 44*1dcdf01fSchristos 45*1dcdf01fSchristosRSA_get_default_method() returns a pointer to the current default 46*1dcdf01fSchristosRSA_METHOD. However, the meaningfulness of this result is dependent on 47*1dcdf01fSchristoswhether the ENGINE API is being used, so this function is no longer 48*1dcdf01fSchristosrecommended. 49*1dcdf01fSchristos 50*1dcdf01fSchristosRSA_set_method() selects B<meth> to perform all operations using the key 51*1dcdf01fSchristosB<rsa>. This will replace the RSA_METHOD used by the RSA key and if the 52*1dcdf01fSchristosprevious method was supplied by an ENGINE, the handle to that ENGINE will 53*1dcdf01fSchristosbe released during the change. It is possible to have RSA keys that only 54*1dcdf01fSchristoswork with certain RSA_METHOD implementations (e.g. from an ENGINE module 55*1dcdf01fSchristosthat supports embedded hardware-protected keys), and in such cases 56*1dcdf01fSchristosattempting to change the RSA_METHOD for the key can have unexpected 57*1dcdf01fSchristosresults. 58*1dcdf01fSchristos 59*1dcdf01fSchristosRSA_get_method() returns a pointer to the RSA_METHOD being used by B<rsa>. 60*1dcdf01fSchristosThis method may or may not be supplied by an ENGINE implementation, but if 61*1dcdf01fSchristosit is, the return value can only be guaranteed to be valid as long as the 62*1dcdf01fSchristosRSA key itself is valid and does not have its implementation changed by 63*1dcdf01fSchristosRSA_set_method(). 64*1dcdf01fSchristos 65*1dcdf01fSchristosRSA_flags() returns the B<flags> that are set for B<rsa>'s current 66*1dcdf01fSchristosRSA_METHOD. See the BUGS section. 67*1dcdf01fSchristos 68*1dcdf01fSchristosRSA_new_method() allocates and initializes an RSA structure so that 69*1dcdf01fSchristosB<engine> will be used for the RSA operations. If B<engine> is NULL, the 70*1dcdf01fSchristosdefault ENGINE for RSA operations is used, and if no default ENGINE is set, 71*1dcdf01fSchristosthe RSA_METHOD controlled by RSA_set_default_method() is used. 72*1dcdf01fSchristos 73*1dcdf01fSchristosRSA_flags() returns the B<flags> that are set for B<rsa>'s current method. 74*1dcdf01fSchristos 75*1dcdf01fSchristosRSA_new_method() allocates and initializes an B<RSA> structure so that 76*1dcdf01fSchristosB<method> will be used for the RSA operations. If B<method> is B<NULL>, 77*1dcdf01fSchristosthe default method is used. 78*1dcdf01fSchristos 79*1dcdf01fSchristos=head1 THE RSA_METHOD STRUCTURE 80*1dcdf01fSchristos 81*1dcdf01fSchristos typedef struct rsa_meth_st 82*1dcdf01fSchristos { 83*1dcdf01fSchristos /* name of the implementation */ 84*1dcdf01fSchristos const char *name; 85*1dcdf01fSchristos 86*1dcdf01fSchristos /* encrypt */ 87*1dcdf01fSchristos int (*rsa_pub_enc)(int flen, unsigned char *from, 88*1dcdf01fSchristos unsigned char *to, RSA *rsa, int padding); 89*1dcdf01fSchristos 90*1dcdf01fSchristos /* verify arbitrary data */ 91*1dcdf01fSchristos int (*rsa_pub_dec)(int flen, unsigned char *from, 92*1dcdf01fSchristos unsigned char *to, RSA *rsa, int padding); 93*1dcdf01fSchristos 94*1dcdf01fSchristos /* sign arbitrary data */ 95*1dcdf01fSchristos int (*rsa_priv_enc)(int flen, unsigned char *from, 96*1dcdf01fSchristos unsigned char *to, RSA *rsa, int padding); 97*1dcdf01fSchristos 98*1dcdf01fSchristos /* decrypt */ 99*1dcdf01fSchristos int (*rsa_priv_dec)(int flen, unsigned char *from, 100*1dcdf01fSchristos unsigned char *to, RSA *rsa, int padding); 101*1dcdf01fSchristos 102*1dcdf01fSchristos /* compute r0 = r0 ^ I mod rsa->n (May be NULL for some implementations) */ 103*1dcdf01fSchristos int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa); 104*1dcdf01fSchristos 105*1dcdf01fSchristos /* compute r = a ^ p mod m (May be NULL for some implementations) */ 106*1dcdf01fSchristos int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p, 107*1dcdf01fSchristos const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx); 108*1dcdf01fSchristos 109*1dcdf01fSchristos /* called at RSA_new */ 110*1dcdf01fSchristos int (*init)(RSA *rsa); 111*1dcdf01fSchristos 112*1dcdf01fSchristos /* called at RSA_free */ 113*1dcdf01fSchristos int (*finish)(RSA *rsa); 114*1dcdf01fSchristos 115*1dcdf01fSchristos /* 116*1dcdf01fSchristos * RSA_FLAG_EXT_PKEY - rsa_mod_exp is called for private key 117*1dcdf01fSchristos * operations, even if p,q,dmp1,dmq1,iqmp 118*1dcdf01fSchristos * are NULL 119*1dcdf01fSchristos * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match 120*1dcdf01fSchristos */ 121*1dcdf01fSchristos int flags; 122*1dcdf01fSchristos 123*1dcdf01fSchristos char *app_data; /* ?? */ 124*1dcdf01fSchristos 125*1dcdf01fSchristos int (*rsa_sign)(int type, 126*1dcdf01fSchristos const unsigned char *m, unsigned int m_length, 127*1dcdf01fSchristos unsigned char *sigret, unsigned int *siglen, const RSA *rsa); 128*1dcdf01fSchristos int (*rsa_verify)(int dtype, 129*1dcdf01fSchristos const unsigned char *m, unsigned int m_length, 130*1dcdf01fSchristos const unsigned char *sigbuf, unsigned int siglen, 131*1dcdf01fSchristos const RSA *rsa); 132*1dcdf01fSchristos /* keygen. If NULL builtin RSA key generation will be used */ 133*1dcdf01fSchristos int (*rsa_keygen)(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb); 134*1dcdf01fSchristos 135*1dcdf01fSchristos } RSA_METHOD; 136*1dcdf01fSchristos 137*1dcdf01fSchristos=head1 RETURN VALUES 138*1dcdf01fSchristos 139*1dcdf01fSchristosRSA_PKCS1_OpenSSL(), RSA_PKCS1_null_method(), RSA_get_default_method() 140*1dcdf01fSchristosand RSA_get_method() return pointers to the respective RSA_METHODs. 141*1dcdf01fSchristos 142*1dcdf01fSchristosRSA_set_default_method() returns no value. 143*1dcdf01fSchristos 144*1dcdf01fSchristosRSA_set_method() returns a pointer to the old RSA_METHOD implementation 145*1dcdf01fSchristosthat was replaced. However, this return value should probably be ignored 146*1dcdf01fSchristosbecause if it was supplied by an ENGINE, the pointer could be invalidated 147*1dcdf01fSchristosat any time if the ENGINE is unloaded (in fact it could be unloaded as a 148*1dcdf01fSchristosresult of the RSA_set_method() function releasing its handle to the 149*1dcdf01fSchristosENGINE). For this reason, the return type may be replaced with a B<void> 150*1dcdf01fSchristosdeclaration in a future release. 151*1dcdf01fSchristos 152*1dcdf01fSchristosRSA_new_method() returns NULL and sets an error code that can be obtained 153*1dcdf01fSchristosby L<ERR_get_error(3)> if the allocation fails. Otherwise 154*1dcdf01fSchristosit returns a pointer to the newly allocated structure. 155*1dcdf01fSchristos 156*1dcdf01fSchristos=head1 BUGS 157*1dcdf01fSchristos 158*1dcdf01fSchristosThe behaviour of RSA_flags() is a mis-feature that is left as-is for now 159*1dcdf01fSchristosto avoid creating compatibility problems. RSA functionality, such as the 160*1dcdf01fSchristosencryption functions, are controlled by the B<flags> value in the RSA key 161*1dcdf01fSchristositself, not by the B<flags> value in the RSA_METHOD attached to the RSA key 162*1dcdf01fSchristos(which is what this function returns). If the flags element of an RSA key 163*1dcdf01fSchristosis changed, the changes will be honoured by RSA functionality but will not 164*1dcdf01fSchristosbe reflected in the return value of the RSA_flags() function - in effect 165*1dcdf01fSchristosRSA_flags() behaves more like an RSA_default_flags() function (which does 166*1dcdf01fSchristosnot currently exist). 167*1dcdf01fSchristos 168*1dcdf01fSchristos=head1 SEE ALSO 169*1dcdf01fSchristos 170*1dcdf01fSchristosL<RSA_new(3)> 171*1dcdf01fSchristos 172*1dcdf01fSchristos=head1 HISTORY 173*1dcdf01fSchristos 174*1dcdf01fSchristosThe RSA_null_method(), which was a partial attempt to avoid patent issues, 175*1dcdf01fSchristoswas replaced to always return NULL in OpenSSL 1.1.1. 176*1dcdf01fSchristos 177*1dcdf01fSchristos=head1 COPYRIGHT 178*1dcdf01fSchristos 179*1dcdf01fSchristosCopyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. 180*1dcdf01fSchristos 181*1dcdf01fSchristosLicensed under the OpenSSL license (the "License"). You may not use 182*1dcdf01fSchristosthis file except in compliance with the License. You can obtain a copy 183*1dcdf01fSchristosin the file LICENSE in the source distribution or at 184*1dcdf01fSchristosL<https://www.openssl.org/source/license.html>. 185*1dcdf01fSchristos 186*1dcdf01fSchristos=cut 187