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-03-19" "1.0.1m" "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.