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