openssl: Adjust manual pages for 1.0.1o.
[dragonfly.git] / secure / lib / libcrypto / man / RSA_set_method.3
1 .\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings.  \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 .    ds -- \(*W-
28 .    ds PI pi
29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
31 .    ds L" ""
32 .    ds R" ""
33 .    ds C` ""
34 .    ds C' ""
35 'br\}
36 .el\{\
37 .    ds -- \|\(em\|
38 .    ds PI \(*p
39 .    ds L" ``
40 .    ds R" ''
41 .    ds C`
42 .    ds C'
43 'br\}
44 .\"
45 .\" Escape single quotes in literal strings from groff's Unicode transform.
46 .ie \n(.g .ds Aq \(aq
47 .el       .ds Aq '
48 .\"
49 .\" If the F register is turned on, we'll generate index entries on stderr for
50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
52 .\" output yourself in some meaningful fashion.
53 .\"
54 .\" Avoid warning from groff about undefined register 'F'.
55 .de IX
56 ..
57 .nr rF 0
58 .if \n(.g .if rF .nr rF 1
59 .if (\n(rF:(\n(.g==0)) \{
60 .    if \nF \{
61 .        de IX
62 .        tm Index:\\$1\t\\n%\t"\\$2"
63 ..
64 .        if !\nF==2 \{
65 .            nr % 0
66 .            nr F 2
67 .        \}
68 .    \}
69 .\}
70 .rr rF
71 .\"
72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
74 .    \" fudge factors for nroff and troff
75 .if n \{\
76 .    ds #H 0
77 .    ds #V .8m
78 .    ds #F .3m
79 .    ds #[ \f1
80 .    ds #] \fP
81 .\}
82 .if t \{\
83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
84 .    ds #V .6m
85 .    ds #F 0
86 .    ds #[ \&
87 .    ds #] \&
88 .\}
89 .    \" simple accents for nroff and troff
90 .if n \{\
91 .    ds ' \&
92 .    ds ` \&
93 .    ds ^ \&
94 .    ds , \&
95 .    ds ~ ~
96 .    ds /
97 .\}
98 .if t \{\
99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
105 .\}
106 .    \" troff and (daisy-wheel) nroff accents
107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
114 .ds ae a\h'-(\w'a'u*4/10)'e
115 .ds Ae A\h'-(\w'A'u*4/10)'E
116 .    \" corrections for vroff
117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
119 .    \" for low resolution devices (crt and lpr)
120 .if \n(.H>23 .if \n(.V>19 \
121 \{\
122 .    ds : e
123 .    ds 8 ss
124 .    ds o a
125 .    ds d- d\h'-1'\(ga
126 .    ds D- D\h'-1'\(hy
127 .    ds th \o'bp'
128 .    ds Th \o'LP'
129 .    ds ae ae
130 .    ds Ae AE
131 .\}
132 .rm #[ #] #H #V #F C
133 .\" ========================================================================
134 .\"
135 .IX Title "RSA_set_method 3"
136 .TH RSA_set_method 3 "2015-06-12" "1.0.1o" "OpenSSL"
137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
138 .\" way too many mistakes in technical documents.
139 .if n .ad l
140 .nh
141 .SH "NAME"
142 RSA_set_default_method, RSA_get_default_method, RSA_set_method,
143 RSA_get_method, RSA_PKCS1_SSLeay, RSA_null_method, RSA_flags,
144 RSA_new_method \- select RSA method
145 .SH "SYNOPSIS"
146 .IX Header "SYNOPSIS"
147 .Vb 1
148 \& #include <openssl/rsa.h>
149 \&
150 \& void RSA_set_default_method(const RSA_METHOD *meth);
151 \&
152 \& RSA_METHOD *RSA_get_default_method(void);
153 \&
154 \& int RSA_set_method(RSA *rsa, const RSA_METHOD *meth);
155 \&
156 \& RSA_METHOD *RSA_get_method(const RSA *rsa);
157 \&
158 \& RSA_METHOD *RSA_PKCS1_SSLeay(void);
159 \&
160 \& RSA_METHOD *RSA_null_method(void);
161 \&
162 \& int RSA_flags(const RSA *rsa);
163 \&
164 \& RSA *RSA_new_method(RSA_METHOD *method);
165 .Ve
166 .SH "DESCRIPTION"
167 .IX Header "DESCRIPTION"
168 An \fB\s-1RSA_METHOD\s0\fR specifies the functions that OpenSSL uses for \s-1RSA\s0
169 operations. By modifying the method, alternative implementations such as
170 hardware accelerators may be used. \s-1IMPORTANT:\s0 See the \s-1NOTES\s0 section for
171 important information about how these \s-1RSA API\s0 functions are affected by the
172 use of \fB\s-1ENGINE\s0\fR \s-1API\s0 calls.
173 .PP
174 Initially, the default \s-1RSA_METHOD\s0 is the OpenSSL internal implementation,
175 as returned by \fIRSA_PKCS1_SSLeay()\fR.
176 .PP
177 \&\fIRSA_set_default_method()\fR makes \fBmeth\fR the default method for all \s-1RSA\s0
178 structures created later. \fB\s-1NB\s0\fR: This is true only whilst no \s-1ENGINE\s0 has
179 been set as a default for \s-1RSA,\s0 so this function is no longer recommended.
180 .PP
181 \&\fIRSA_get_default_method()\fR returns a pointer to the current default
182 \&\s-1RSA_METHOD.\s0 However, the meaningfulness of this result is dependent on
183 whether the \s-1ENGINE API\s0 is being used, so this function is no longer 
184 recommended.
185 .PP
186 \&\fIRSA_set_method()\fR selects \fBmeth\fR to perform all operations using the key
187 \&\fBrsa\fR. This will replace the \s-1RSA_METHOD\s0 used by the \s-1RSA\s0 key and if the
188 previous method was supplied by an \s-1ENGINE,\s0 the handle to that \s-1ENGINE\s0 will
189 be released during the change. It is possible to have \s-1RSA\s0 keys that only
190 work with certain \s-1RSA_METHOD\s0 implementations (eg. from an \s-1ENGINE\s0 module
191 that supports embedded hardware-protected keys), and in such cases
192 attempting to change the \s-1RSA_METHOD\s0 for the key can have unexpected
193 results.
194 .PP
195 \&\fIRSA_get_method()\fR returns a pointer to the \s-1RSA_METHOD\s0 being used by \fBrsa\fR.
196 This method may or may not be supplied by an \s-1ENGINE\s0 implementation, but if
197 it is, the return value can only be guaranteed to be valid as long as the
198 \&\s-1RSA\s0 key itself is valid and does not have its implementation changed by
199 \&\fIRSA_set_method()\fR.
200 .PP
201 \&\fIRSA_flags()\fR returns the \fBflags\fR that are set for \fBrsa\fR's current
202 \&\s-1RSA_METHOD.\s0 See the \s-1BUGS\s0 section.
203 .PP
204 \&\fIRSA_new_method()\fR allocates and initializes an \s-1RSA\s0 structure so that
205 \&\fBengine\fR will be used for the \s-1RSA\s0 operations. If \fBengine\fR is \s-1NULL,\s0 the
206 default \s-1ENGINE\s0 for \s-1RSA\s0 operations is used, and if no default \s-1ENGINE\s0 is set,
207 the \s-1RSA_METHOD\s0 controlled by \fIRSA_set_default_method()\fR is used.
208 .PP
209 \&\fIRSA_flags()\fR returns the \fBflags\fR that are set for \fBrsa\fR's current method.
210 .PP
211 \&\fIRSA_new_method()\fR allocates and initializes an \fB\s-1RSA\s0\fR structure so that
212 \&\fBmethod\fR will be used for the \s-1RSA\s0 operations. If \fBmethod\fR is \fB\s-1NULL\s0\fR,
213 the default method is used.
214 .SH "THE RSA_METHOD STRUCTURE"
215 .IX Header "THE RSA_METHOD STRUCTURE"
216 .Vb 4
217 \& typedef struct rsa_meth_st
218 \& {
219 \&     /* name of the implementation */
220 \&        const char *name;
221 \&
222 \&     /* encrypt */
223 \&        int (*rsa_pub_enc)(int flen, unsigned char *from,
224 \&          unsigned char *to, RSA *rsa, int padding);
225 \&
226 \&     /* verify arbitrary data */
227 \&        int (*rsa_pub_dec)(int flen, unsigned char *from,
228 \&          unsigned char *to, RSA *rsa, int padding);
229 \&
230 \&     /* sign arbitrary data */
231 \&        int (*rsa_priv_enc)(int flen, unsigned char *from,
232 \&          unsigned char *to, RSA *rsa, int padding);
233 \&
234 \&     /* decrypt */
235 \&        int (*rsa_priv_dec)(int flen, unsigned char *from,
236 \&          unsigned char *to, RSA *rsa, int padding);
237 \&
238 \&     /* compute r0 = r0 ^ I mod rsa\->n (May be NULL for some
239 \&                                        implementations) */
240 \&        int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa);
241 \&
242 \&     /* compute r = a ^ p mod m (May be NULL for some implementations) */
243 \&        int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
244 \&          const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);
245 \&
246 \&     /* called at RSA_new */
247 \&        int (*init)(RSA *rsa);
248 \&
249 \&     /* called at RSA_free */
250 \&        int (*finish)(RSA *rsa);
251 \&
252 \&     /* RSA_FLAG_EXT_PKEY        \- rsa_mod_exp is called for private key
253 \&      *                            operations, even if p,q,dmp1,dmq1,iqmp
254 \&      *                            are NULL
255 \&      * RSA_FLAG_SIGN_VER        \- enable rsa_sign and rsa_verify
256 \&      * RSA_METHOD_FLAG_NO_CHECK \- don\*(Aqt check pub/private match
257 \&      */
258 \&        int flags;
259 \&
260 \&        char *app_data; /* ?? */
261 \&
262 \&     /* sign. For backward compatibility, this is used only
263 \&      * if (flags & RSA_FLAG_SIGN_VER)
264 \&      */
265 \&        int (*rsa_sign)(int type,
266 \&                const unsigned char *m, unsigned int m_length,
267 \&                unsigned char *sigret, unsigned int *siglen, const RSA *rsa);
268 \&     /* verify. For backward compatibility, this is used only
269 \&      * if (flags & RSA_FLAG_SIGN_VER)
270 \&      */
271 \&        int (*rsa_verify)(int dtype,
272 \&                const unsigned char *m, unsigned int m_length,
273 \&                const unsigned char *sigbuf, unsigned int siglen,
274 \&                                                                const RSA *rsa);
275 \&     /* keygen. If NULL builtin RSA key generation will be used */
276 \&        int (*rsa_keygen)(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb);
277 \&
278 \& } RSA_METHOD;
279 .Ve
280 .SH "RETURN VALUES"
281 .IX Header "RETURN VALUES"
282 \&\fIRSA_PKCS1_SSLeay()\fR, \fIRSA_PKCS1_null_method()\fR, \fIRSA_get_default_method()\fR
283 and \fIRSA_get_method()\fR return pointers to the respective RSA_METHODs.
284 .PP
285 \&\fIRSA_set_default_method()\fR returns no value.
286 .PP
287 \&\fIRSA_set_method()\fR returns a pointer to the old \s-1RSA_METHOD\s0 implementation
288 that was replaced. However, this return value should probably be ignored
289 because if it was supplied by an \s-1ENGINE,\s0 the pointer could be invalidated
290 at any time if the \s-1ENGINE\s0 is unloaded (in fact it could be unloaded as a
291 result of the \fIRSA_set_method()\fR function releasing its handle to the
292 \&\s-1ENGINE\s0). For this reason, the return type may be replaced with a \fBvoid\fR
293 declaration in a future release.
294 .PP
295 \&\fIRSA_new_method()\fR returns \s-1NULL\s0 and sets an error code that can be obtained
296 by \fIERR_get_error\fR\|(3) if the allocation fails. Otherwise
297 it returns a pointer to the newly allocated structure.
298 .SH "NOTES"
299 .IX Header "NOTES"
300 As of version 0.9.7, \s-1RSA_METHOD\s0 implementations are grouped together with
301 other algorithmic APIs (eg. \s-1DSA_METHOD, EVP_CIPHER,\s0 etc) into \fB\s-1ENGINE\s0\fR
302 modules. If a default \s-1ENGINE\s0 is specified for \s-1RSA\s0 functionality using an
303 \&\s-1ENGINE API\s0 function, that will override any \s-1RSA\s0 defaults set using the \s-1RSA
304 API \s0(ie.  \fIRSA_set_default_method()\fR). For this reason, the \s-1ENGINE API\s0 is the
305 recommended way to control default implementations for use in \s-1RSA\s0 and other
306 cryptographic algorithms.
307 .SH "BUGS"
308 .IX Header "BUGS"
309 The behaviour of \fIRSA_flags()\fR is a mis-feature that is left as-is for now
310 to avoid creating compatibility problems. \s-1RSA\s0 functionality, such as the
311 encryption functions, are controlled by the \fBflags\fR value in the \s-1RSA\s0 key
312 itself, not by the \fBflags\fR value in the \s-1RSA_METHOD\s0 attached to the \s-1RSA\s0 key
313 (which is what this function returns). If the flags element of an \s-1RSA\s0 key
314 is changed, the changes will be honoured by \s-1RSA\s0 functionality but will not
315 be reflected in the return value of the \fIRSA_flags()\fR function \- in effect
316 \&\fIRSA_flags()\fR behaves more like an \fIRSA_default_flags()\fR function (which does
317 not currently exist).
318 .SH "SEE ALSO"
319 .IX Header "SEE ALSO"
320 \&\fIrsa\fR\|(3), \fIRSA_new\fR\|(3)
321 .SH "HISTORY"
322 .IX Header "HISTORY"
323 \&\fIRSA_new_method()\fR and \fIRSA_set_default_method()\fR appeared in SSLeay 0.8.
324 \&\fIRSA_get_default_method()\fR, \fIRSA_set_method()\fR and \fIRSA_get_method()\fR as
325 well as the rsa_sign and rsa_verify components of \s-1RSA_METHOD\s0 were
326 added in OpenSSL 0.9.4.
327 .PP
328 \&\fIRSA_set_default_openssl_method()\fR and \fIRSA_get_default_openssl_method()\fR
329 replaced \fIRSA_set_default_method()\fR and \fIRSA_get_default_method()\fR
330 respectively, and \fIRSA_set_method()\fR and \fIRSA_new_method()\fR were altered to use
331 \&\fB\s-1ENGINE\s0\fRs rather than \fB\s-1RSA_METHOD\s0\fRs during development of the engine
332 version of OpenSSL 0.9.6. For 0.9.7, the handling of defaults in the \s-1ENGINE
333 API\s0 was restructured so that this change was reversed, and behaviour of the
334 other functions resembled more closely the previous behaviour. The
335 behaviour of defaults in the \s-1ENGINE API\s0 now transparently overrides the
336 behaviour of defaults in the \s-1RSA API\s0 without requiring changing these
337 function prototypes.