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

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.40)
   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_METH_NEW 3"
 136 .TH RSA_METH_NEW 3 "2020-04-21" "1.1.1g" "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_meth_get0_app_data, RSA_meth_set0_app_data, RSA_meth_new, RSA_meth_free, RSA_meth_dup, RSA_meth_get0_name, RSA_meth_set1_name, RSA_meth_get_flags, RSA_meth_set_flags, RSA_meth_get_pub_enc, RSA_meth_set_pub_enc, RSA_meth_get_pub_dec, RSA_meth_set_pub_dec, RSA_meth_get_priv_enc, RSA_meth_set_priv_enc, RSA_meth_get_priv_dec, RSA_meth_set_priv_dec, RSA_meth_get_mod_exp, RSA_meth_set_mod_exp, RSA_meth_get_bn_mod_exp, RSA_meth_set_bn_mod_exp, RSA_meth_get_init, RSA_meth_set_init, RSA_meth_get_finish, RSA_meth_set_finish, RSA_meth_get_sign, RSA_meth_set_sign, RSA_meth_get_verify, RSA_meth_set_verify, RSA_meth_get_keygen, RSA_meth_set_keygen, RSA_meth_get_multi_prime_keygen, RSA_meth_set_multi_prime_keygen \&\- Routines to build up RSA methods
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/rsa.h>
 147 \&
 148 \& RSA_METHOD *RSA_meth_new(const char *name, int flags);
 149 \& void RSA_meth_free(RSA_METHOD *meth);
 150 \&
 151 \& RSA_METHOD *RSA_meth_dup(const RSA_METHOD *meth);
 152 \&
 153 \& const char *RSA_meth_get0_name(const RSA_METHOD *meth);
 154 \& int RSA_meth_set1_name(RSA_METHOD *meth, const char *name);
 155 \&
 156 \& int RSA_meth_get_flags(const RSA_METHOD *meth);
 157 \& int RSA_meth_set_flags(RSA_METHOD *meth, int flags);
 158 \&
 159 \& void *RSA_meth_get0_app_data(const RSA_METHOD *meth);
 160 \& int RSA_meth_set0_app_data(RSA_METHOD *meth, void *app_data);
 161 \&
 162 \& int (*RSA_meth_get_pub_enc(const RSA_METHOD *meth))(int flen, const unsigned char *from,
 163 \&                                                     unsigned char *to, RSA *rsa, int padding);
 164 \& int RSA_meth_set_pub_enc(RSA_METHOD *rsa,
 165 \&                          int (*pub_enc)(int flen, const unsigned char *from,
 166 \&                                         unsigned char *to, RSA *rsa,
 167 \&                                         int padding));
 168 \&
 169 \& int (*RSA_meth_get_pub_dec(const RSA_METHOD *meth))
 170 \&     (int flen, const unsigned char *from,
 171 \&      unsigned char *to, RSA *rsa, int padding);
 172 \& int RSA_meth_set_pub_dec(RSA_METHOD *rsa,
 173 \&                          int (*pub_dec)(int flen, const unsigned char *from,
 174 \&                                         unsigned char *to, RSA *rsa,
 175 \&                                         int padding));
 176 \&
 177 \& int (*RSA_meth_get_priv_enc(const RSA_METHOD *meth))(int flen, const unsigned char *from,
 178 \&                                                      unsigned char *to, RSA *rsa,
 179 \&                                                      int padding);
 180 \& int RSA_meth_set_priv_enc(RSA_METHOD *rsa,
 181 \&                           int (*priv_enc)(int flen, const unsigned char *from,
 182 \&                                           unsigned char *to, RSA *rsa, int padding));
 183 \&
 184 \& int (*RSA_meth_get_priv_dec(const RSA_METHOD *meth))(int flen, const unsigned char *from,
 185 \&                                                      unsigned char *to, RSA *rsa,
 186 \&                                                      int padding);
 187 \& int RSA_meth_set_priv_dec(RSA_METHOD *rsa,
 188 \&                           int (*priv_dec)(int flen, const unsigned char *from,
 189 \&                                           unsigned char *to, RSA *rsa, int padding));
 190 \&
 191 \& /* Can be null */
 192 \& int (*RSA_meth_get_mod_exp(const RSA_METHOD *meth))(BIGNUM *r0, const BIGNUM *i,
 193 \&                                                     RSA *rsa, BN_CTX *ctx);
 194 \& int RSA_meth_set_mod_exp(RSA_METHOD *rsa,
 195 \&                          int (*mod_exp)(BIGNUM *r0, const BIGNUM *i, RSA *rsa,
 196 \&                                         BN_CTX *ctx));
 197 \&
 198 \& /* Can be null */
 199 \& int (*RSA_meth_get_bn_mod_exp(const RSA_METHOD *meth))(BIGNUM *r, const BIGNUM *a,
 200 \&                                                        const BIGNUM *p, const BIGNUM *m,
 201 \&                                                        BN_CTX *ctx, BN_MONT_CTX *m_ctx);
 202 \& int RSA_meth_set_bn_mod_exp(RSA_METHOD *rsa,
 203 \&                             int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a,
 204 \&                                               const BIGNUM *p, const BIGNUM *m,
 205 \&                                               BN_CTX *ctx, BN_MONT_CTX *m_ctx));
 206 \&
 207 \& /* called at new */
 208 \& int (*RSA_meth_get_init(const RSA_METHOD *meth) (RSA *rsa);
 209 \& int RSA_meth_set_init(RSA_METHOD *rsa, int (*init (RSA *rsa));
 210 \&
 211 \& /* called at free */
 212 \& int (*RSA_meth_get_finish(const RSA_METHOD *meth))(RSA *rsa);
 213 \& int RSA_meth_set_finish(RSA_METHOD *rsa, int (*finish)(RSA *rsa));
 214 \&
 215 \& int (*RSA_meth_get_sign(const RSA_METHOD *meth))(int type, const unsigned char *m,
 216 \&                                                  unsigned int m_length,
 217 \&                                                  unsigned char *sigret,
 218 \&                                                  unsigned int *siglen, const RSA *rsa);
 219 \& int RSA_meth_set_sign(RSA_METHOD *rsa,
 220 \&                       int (*sign)(int type, const unsigned char *m,
 221 \&                                   unsigned int m_length, unsigned char *sigret,
 222 \&                                   unsigned int *siglen, const RSA *rsa));
 223 \&
 224 \& int (*RSA_meth_get_verify(const RSA_METHOD *meth))(int dtype, const unsigned char *m,
 225 \&                                                    unsigned int m_length,
 226 \&                                                    const unsigned char *sigbuf,
 227 \&                                                    unsigned int siglen, const RSA *rsa);
 228 \& int RSA_meth_set_verify(RSA_METHOD *rsa,
 229 \&                         int (*verify)(int dtype, const unsigned char *m,
 230 \&                                       unsigned int m_length,
 231 \&                                       const unsigned char *sigbuf,
 232 \&                                       unsigned int siglen, const RSA *rsa));
 233 \&
 234 \& int (*RSA_meth_get_keygen(const RSA_METHOD *meth))(RSA *rsa, int bits, BIGNUM *e,
 235 \&                                                    BN_GENCB *cb);
 236 \& int RSA_meth_set_keygen(RSA_METHOD *rsa,
 237 \&                         int (*keygen)(RSA *rsa, int bits, BIGNUM *e,
 238 \&                                       BN_GENCB *cb));
 239 \&
 240 \& int (*RSA_meth_get_multi_prime_keygen(const RSA_METHOD *meth))(RSA *rsa, int bits,
 241 \&                                                                int primes, BIGNUM *e,
 242 \&                                                                BN_GENCB *cb);
 243 \&
 244 \& int RSA_meth_set_multi_prime_keygen(RSA_METHOD *meth,
 245 \&                                     int (*keygen) (RSA *rsa, int bits,
 246 \&                                                    int primes, BIGNUM *e,
 247 \&                                                    BN_GENCB *cb));
 248 .Ve
 249 .SH "DESCRIPTION"
 250 .IX Header "DESCRIPTION"
 251 The \fB\s-1RSA_METHOD\s0\fR type is a structure used for the provision of custom
 252 \&\s-1RSA\s0 implementations. It provides a set of functions used by OpenSSL
 253 for the implementation of the various \s-1RSA\s0 capabilities. See the rsa
 254 page for more information.
 255 .PP
 256 \&\fBRSA_meth_new()\fR creates a new \fB\s-1RSA_METHOD\s0\fR structure. It should be
 257 given a unique \fBname\fR and a set of \fBflags\fR. The \fBname\fR should be a
 258 \&\s-1NULL\s0 terminated string, which will be duplicated and stored in the
 259 \&\fB\s-1RSA_METHOD\s0\fR object. It is the callers responsibility to free the
 260 original string. The flags will be used during the construction of a
 261 new \fB\s-1RSA\s0\fR object based on this \fB\s-1RSA_METHOD\s0\fR. Any new \fB\s-1RSA\s0\fR object
 262 will have those flags set by default.
 263 .PP
 264 \&\fBRSA_meth_dup()\fR creates a duplicate copy of the \fB\s-1RSA_METHOD\s0\fR object
 265 passed as a parameter. This might be useful for creating a new
 266 \&\fB\s-1RSA_METHOD\s0\fR based on an existing one, but with some differences.
 267 .PP
 268 \&\fBRSA_meth_free()\fR destroys an \fB\s-1RSA_METHOD\s0\fR structure and frees up any
 269 memory associated with it.
 270 .PP
 271 \&\fBRSA_meth_get0_name()\fR will return a pointer to the name of this
 272 \&\s-1RSA_METHOD.\s0 This is a pointer to the internal name string and so
 273 should not be freed by the caller. \fBRSA_meth_set1_name()\fR sets the name
 274 of the \s-1RSA_METHOD\s0 to \fBname\fR. The string is duplicated and the copy is
 275 stored in the \s-1RSA_METHOD\s0 structure, so the caller remains responsible
 276 for freeing the memory associated with the name.
 277 .PP
 278 \&\fBRSA_meth_get_flags()\fR returns the current value of the flags associated
 279 with this \s-1RSA_METHOD.\s0 \fBRSA_meth_set_flags()\fR provides the ability to set
 280 these flags.
 281 .PP
 282 The functions \fBRSA_meth_get0_app_data()\fR and \fBRSA_meth_set0_app_data()\fR
 283 provide the ability to associate implementation specific data with the
 284 \&\s-1RSA_METHOD.\s0 It is the application's responsibility to free this data
 285 before the \s-1RSA_METHOD\s0 is freed via a call to \fBRSA_meth_free()\fR.
 286 .PP
 287 \&\fBRSA_meth_get_sign()\fR and \fBRSA_meth_set_sign()\fR get and set the function
 288 used for creating an \s-1RSA\s0 signature respectively. This function will be
 289 called in response to the application calling \fBRSA_sign()\fR. The
 290 parameters for the function have the same meaning as for \fBRSA_sign()\fR.
 291 .PP
 292 \&\fBRSA_meth_get_verify()\fR and \fBRSA_meth_set_verify()\fR get and set the
 293 function used for verifying an \s-1RSA\s0 signature respectively. This
 294 function will be called in response to the application calling
 295 \&\fBRSA_verify()\fR. The parameters for the function have the same meaning as
 296 for \fBRSA_verify()\fR.
 297 .PP
 298 \&\fBRSA_meth_get_mod_exp()\fR and \fBRSA_meth_set_mod_exp()\fR get and set the
 299 function used for \s-1CRT\s0 computations.
 300 .PP
 301 \&\fBRSA_meth_get_bn_mod_exp()\fR and \fBRSA_meth_set_bn_mod_exp()\fR get and set
 302 the function used for \s-1CRT\s0 computations, specifically the following
 303 value:
 304 .PP
 305 .Vb 1
 306 \& r = a ^ p mod m
 307 .Ve
 308 .PP
 309 Both the \fBmod_exp()\fR and \fBbn_mod_exp()\fR functions are called by the
 310 default OpenSSL method during encryption, decryption, signing and
 311 verification.
 312 .PP
 313 \&\fBRSA_meth_get_init()\fR and \fBRSA_meth_set_init()\fR get and set the function
 314 used for creating a new \s-1RSA\s0 instance respectively. This function will
 315 be called in response to the application calling \fBRSA_new()\fR (if the
 316 current default \s-1RSA_METHOD\s0 is this one) or \fBRSA_new_method()\fR. The
 317 \&\fBRSA_new()\fR and \fBRSA_new_method()\fR functions will allocate the memory for
 318 the new \s-1RSA\s0 object, and a pointer to this newly allocated structure
 319 will be passed as a parameter to the function. This function may be
 320 \&\s-1NULL.\s0
 321 .PP
 322 \&\fBRSA_meth_get_finish()\fR and \fBRSA_meth_set_finish()\fR get and set the
 323 function used for destroying an instance of an \s-1RSA\s0 object respectively.
 324 This function will be called in response to the application calling
 325 \&\fBRSA_free()\fR. A pointer to the \s-1RSA\s0 to be destroyed is passed as a
 326 parameter. The destroy function should be used for \s-1RSA\s0 implementation
 327 specific clean up. The memory for the \s-1RSA\s0 itself should not be freed
 328 by this function. This function may be \s-1NULL.\s0
 329 .PP
 330 \&\fBRSA_meth_get_keygen()\fR and \fBRSA_meth_set_keygen()\fR get and set the
 331 function used for generating a new \s-1RSA\s0 key pair respectively. This
 332 function will be called in response to the application calling
 333 \&\fBRSA_generate_key_ex()\fR. The parameter for the function has the same
 334 meaning as for \fBRSA_generate_key_ex()\fR.
 335 .PP
 336 \&\fBRSA_meth_get_multi_prime_keygen()\fR and \fBRSA_meth_set_multi_prime_keygen()\fR get
 337 and set the function used for generating a new multi-prime \s-1RSA\s0 key pair
 338 respectively. This function will be called in response to the application calling
 339 \&\fBRSA_generate_multi_prime_key()\fR. The parameter for the function has the same
 340 meaning as for \fBRSA_generate_multi_prime_key()\fR.
 341 .PP
 342 \&\fBRSA_meth_get_pub_enc()\fR, \fBRSA_meth_set_pub_enc()\fR,
 343 \&\fBRSA_meth_get_pub_dec()\fR, \fBRSA_meth_set_pub_dec()\fR,
 344 \&\fBRSA_meth_get_priv_enc()\fR, \fBRSA_meth_set_priv_enc()\fR,
 345 \&\fBRSA_meth_get_priv_dec()\fR, \fBRSA_meth_set_priv_dec()\fR get and set the
 346 functions used for public and private key encryption and decryption.
 347 These functions will be called in response to the application calling
 348 \&\fBRSA_public_encrypt()\fR, \fBRSA_private_decrypt()\fR, \fBRSA_private_encrypt()\fR and
 349 \&\fBRSA_public_decrypt()\fR and take the same parameters as those.
 350 .SH "RETURN VALUES"
 351 .IX Header "RETURN VALUES"
 352 \&\fBRSA_meth_new()\fR and \fBRSA_meth_dup()\fR return the newly allocated
 353 \&\s-1RSA_METHOD\s0 object or \s-1NULL\s0 on failure.
 354 .PP
 355 \&\fBRSA_meth_get0_name()\fR and \fBRSA_meth_get_flags()\fR return the name and
 356 flags associated with the \s-1RSA_METHOD\s0 respectively.
 357 .PP
 358 All other RSA_meth_get_*() functions return the appropriate function
 359 pointer that has been set in the \s-1RSA_METHOD,\s0 or \s-1NULL\s0 if no such
 360 pointer has yet been set.
 361 .PP
 362 RSA_meth_set1_name and all RSA_meth_set_*() functions return 1 on
 363 success or 0 on failure.
 364 .SH "SEE ALSO"
 365 .IX Header "SEE ALSO"
 366 \&\fBRSA_new\fR\|(3), \fBRSA_generate_key_ex\fR\|(3), \fBRSA_sign\fR\|(3),
 367 \&\fBRSA_set_method\fR\|(3), \fBRSA_size\fR\|(3), \fBRSA_get0_key\fR\|(3),
 368 \&\fBRSA_generate_multi_prime_key\fR\|(3)
 369 .SH "HISTORY"
 370 .IX Header "HISTORY"
 371 \&\fBRSA_meth_get_multi_prime_keygen()\fR and \fBRSA_meth_set_multi_prime_keygen()\fR were
 372 added in OpenSSL 1.1.1.
 373 .PP
 374 Other functions described here were added in OpenSSL 1.1.0.
 375 .SH "COPYRIGHT"
 376 .IX Header "COPYRIGHT"
 377 Copyright 2016\-2018 The OpenSSL Project Authors. All Rights Reserved.
 378 .PP
 379 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 380 this file except in compliance with the License.  You can obtain a copy
 381 in the file \s-1LICENSE\s0 in the source distribution or at
 382 <https://www.openssl.org/source/license.html>.