secure/lib/libcrypto/man/RSA_set_method.3

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