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