secure/lib/libcrypto/man/man3/RSA_set_method.3

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