secure/lib/libcrypto/man/RSA_set_method.3

   1 .\" Automatically generated by Pod::Man 4.09 (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 "2018-11-20" "1.1.1a" "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, RSA_get_method, RSA_PKCS1_OpenSSL, RSA_flags, RSA_new_method \- select RSA method
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/rsa.h>
 143 \&
 144 \& void RSA_set_default_method(const RSA_METHOD *meth);
 145 \&
 146 \& RSA_METHOD *RSA_get_default_method(void);
 147 \&
 148 \& int RSA_set_method(RSA *rsa, const RSA_METHOD *meth);
 149 \&
 150 \& RSA_METHOD *RSA_get_method(const RSA *rsa);
 151 \&
 152 \& RSA_METHOD *RSA_PKCS1_OpenSSL(void);
 153 \&
 154 \& int RSA_flags(const RSA *rsa);
 155 \&
 156 \& RSA *RSA_new_method(ENGINE *engine);
 157 .Ve
 158 .SH "DESCRIPTION"
 159 .IX Header "DESCRIPTION"
 160 An \fB\s-1RSA_METHOD\s0\fR specifies the functions that OpenSSL uses for \s-1RSA\s0
 161 operations. By modifying the method, alternative implementations such as
 162 hardware accelerators may be used. \s-1IMPORTANT:\s0 See the \s-1NOTES\s0 section for
 163 important information about how these \s-1RSA API\s0 functions are affected by the
 164 use of \fB\s-1ENGINE\s0\fR \s-1API\s0 calls.
 165 .PP
 166 Initially, the default \s-1RSA_METHOD\s0 is the OpenSSL internal implementation,
 167 as returned by \fIRSA_PKCS1_OpenSSL()\fR.
 168 .PP
 169 \&\fIRSA_set_default_method()\fR makes \fBmeth\fR the default method for all \s-1RSA\s0
 170 structures created later.
 171 \&\fB\s-1NB\s0\fR: This is true only whilst no \s-1ENGINE\s0 has
 172 been set as a default for \s-1RSA,\s0 so this function is no longer recommended.
 173 This function is not thread-safe and should not be called at the same time
 174 as other OpenSSL functions.
 175 .PP
 176 \&\fIRSA_get_default_method()\fR returns a pointer to the current default
 177 \&\s-1RSA_METHOD.\s0 However, the meaningfulness of this result is dependent on
 178 whether the \s-1ENGINE API\s0 is being used, so this function is no longer
 179 recommended.
 180 .PP
 181 \&\fIRSA_set_method()\fR selects \fBmeth\fR to perform all operations using the key
 182 \&\fBrsa\fR. This will replace the \s-1RSA_METHOD\s0 used by the \s-1RSA\s0 key and if the
 183 previous method was supplied by an \s-1ENGINE,\s0 the handle to that \s-1ENGINE\s0 will
 184 be released during the change. It is possible to have \s-1RSA\s0 keys that only
 185 work with certain \s-1RSA_METHOD\s0 implementations (eg. from an \s-1ENGINE\s0 module
 186 that supports embedded hardware-protected keys), and in such cases
 187 attempting to change the \s-1RSA_METHOD\s0 for the key can have unexpected
 188 results.
 189 .PP
 190 \&\fIRSA_get_method()\fR returns a pointer to the \s-1RSA_METHOD\s0 being used by \fBrsa\fR.
 191 This method may or may not be supplied by an \s-1ENGINE\s0 implementation, but if
 192 it is, the return value can only be guaranteed to be valid as long as the
 193 \&\s-1RSA\s0 key itself is valid and does not have its implementation changed by
 194 \&\fIRSA_set_method()\fR.
 195 .PP
 196 \&\fIRSA_flags()\fR returns the \fBflags\fR that are set for \fBrsa\fR's current
 197 \&\s-1RSA_METHOD.\s0 See the \s-1BUGS\s0 section.
 198 .PP
 199 \&\fIRSA_new_method()\fR allocates and initializes an \s-1RSA\s0 structure so that
 200 \&\fBengine\fR will be used for the \s-1RSA\s0 operations. If \fBengine\fR is \s-1NULL,\s0 the
 201 default \s-1ENGINE\s0 for \s-1RSA\s0 operations is used, and if no default \s-1ENGINE\s0 is set,
 202 the \s-1RSA_METHOD\s0 controlled by \fIRSA_set_default_method()\fR is used.
 203 .PP
 204 \&\fIRSA_flags()\fR returns the \fBflags\fR that are set for \fBrsa\fR's current method.
 205 .PP
 206 \&\fIRSA_new_method()\fR allocates and initializes an \fB\s-1RSA\s0\fR structure so that
 207 \&\fBmethod\fR will be used for the \s-1RSA\s0 operations. If \fBmethod\fR is \fB\s-1NULL\s0\fR,
 208 the default method is used.
 209 .SH "THE RSA_METHOD STRUCTURE"
 210 .IX Header "THE RSA_METHOD STRUCTURE"
 211 .Vb 4
 212 \& typedef struct rsa_meth_st
 213 \& {
 214 \&     /* name of the implementation */
 215 \&     const char *name;
 216 \&
 217 \&     /* encrypt */
 218 \&     int (*rsa_pub_enc)(int flen, unsigned char *from,
 219 \&                        unsigned char *to, RSA *rsa, int padding);
 220 \&
 221 \&     /* verify arbitrary data */
 222 \&     int (*rsa_pub_dec)(int flen, unsigned char *from,
 223 \&                        unsigned char *to, RSA *rsa, int padding);
 224 \&
 225 \&     /* sign arbitrary data */
 226 \&     int (*rsa_priv_enc)(int flen, unsigned char *from,
 227 \&                         unsigned char *to, RSA *rsa, int padding);
 228 \&
 229 \&     /* decrypt */
 230 \&     int (*rsa_priv_dec)(int flen, unsigned char *from,
 231 \&                         unsigned char *to, RSA *rsa, int padding);
 232 \&
 233 \&     /* compute r0 = r0 ^ I mod rsa\->n (May be NULL for some implementations) */
 234 \&     int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa);
 235 \&
 236 \&     /* compute r = a ^ p mod m (May be NULL for some implementations) */
 237 \&     int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
 238 \&                       const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);
 239 \&
 240 \&     /* called at RSA_new */
 241 \&     int (*init)(RSA *rsa);
 242 \&
 243 \&     /* called at RSA_free */
 244 \&     int (*finish)(RSA *rsa);
 245 \&
 246 \&     /*
 247 \&      * RSA_FLAG_EXT_PKEY        \- rsa_mod_exp is called for private key
 248 \&      *                            operations, even if p,q,dmp1,dmq1,iqmp
 249 \&      *                            are NULL
 250 \&      * RSA_METHOD_FLAG_NO_CHECK \- don\*(Aqt check pub/private match
 251 \&      */
 252 \&     int flags;
 253 \&
 254 \&     char *app_data; /* ?? */
 255 \&
 256 \&     int (*rsa_sign)(int type,
 257 \&                     const unsigned char *m, unsigned int m_length,
 258 \&                     unsigned char *sigret, unsigned int *siglen, const RSA *rsa);
 259 \&     int (*rsa_verify)(int dtype,
 260 \&                       const unsigned char *m, unsigned int m_length,
 261 \&                       const unsigned char *sigbuf, unsigned int siglen,
 262 \&                       const RSA *rsa);
 263 \&     /* keygen. If NULL builtin RSA key generation will be used */
 264 \&     int (*rsa_keygen)(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb);
 265 \&
 266 \& } RSA_METHOD;
 267 .Ve
 268 .SH "RETURN VALUES"
 269 .IX Header "RETURN VALUES"
 270 \&\fIRSA_PKCS1_OpenSSL()\fR, \fIRSA_PKCS1_null_method()\fR, \fIRSA_get_default_method()\fR
 271 and \fIRSA_get_method()\fR return pointers to the respective RSA_METHODs.
 272 .PP
 273 \&\fIRSA_set_default_method()\fR returns no value.
 274 .PP
 275 \&\fIRSA_set_method()\fR returns a pointer to the old \s-1RSA_METHOD\s0 implementation
 276 that was replaced. However, this return value should probably be ignored
 277 because if it was supplied by an \s-1ENGINE,\s0 the pointer could be invalidated
 278 at any time if the \s-1ENGINE\s0 is unloaded (in fact it could be unloaded as a
 279 result of the \fIRSA_set_method()\fR function releasing its handle to the
 280 \&\s-1ENGINE\s0). For this reason, the return type may be replaced with a \fBvoid\fR
 281 declaration in a future release.
 282 .PP
 283 \&\fIRSA_new_method()\fR returns \s-1NULL\s0 and sets an error code that can be obtained
 284 by \fIERR_get_error\fR\|(3) if the allocation fails. Otherwise
 285 it returns a pointer to the newly allocated structure.
 286 .SH "BUGS"
 287 .IX Header "BUGS"
 288 The behaviour of \fIRSA_flags()\fR is a mis-feature that is left as-is for now
 289 to avoid creating compatibility problems. \s-1RSA\s0 functionality, such as the
 290 encryption functions, are controlled by the \fBflags\fR value in the \s-1RSA\s0 key
 291 itself, not by the \fBflags\fR value in the \s-1RSA_METHOD\s0 attached to the \s-1RSA\s0 key
 292 (which is what this function returns). If the flags element of an \s-1RSA\s0 key
 293 is changed, the changes will be honoured by \s-1RSA\s0 functionality but will not
 294 be reflected in the return value of the \fIRSA_flags()\fR function \- in effect
 295 \&\fIRSA_flags()\fR behaves more like an \fIRSA_default_flags()\fR function (which does
 296 not currently exist).
 297 .SH "SEE ALSO"
 298 .IX Header "SEE ALSO"
 299 \&\fIRSA_new\fR\|(3)
 300 .SH "HISTORY"
 301 .IX Header "HISTORY"
 302 The \fIRSA_null_method()\fR, which was a partial attempt to avoid patent issues,
 303 was replaced to always return \s-1NULL\s0 in OpenSSL 1.1.1.
 304 .SH "COPYRIGHT"
 305 .IX Header "COPYRIGHT"
 306 Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
 307 .PP
 308 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 309 this file except in compliance with the License.  You can obtain a copy
 310 in the file \s-1LICENSE\s0 in the source distribution or at
 311 <https://www.openssl.org/source/license.html>.