1.\" $OpenBSD: RSA_meth_new.3,v 1.5 2019/07/13 17:26:38 schwarze Exp $ 2.\" full merge up to: OpenSSL a970b14f Jul 31 18:58:40 2017 -0400 3.\" selective merge up to: OpenSSL 24907560 Sep 17 07:47:42 2018 +1000 4.\" 5.\" This file is a derived work. 6.\" The changes are covered by the following Copyright and license: 7.\" 8.\" Copyright (c) 2018, 2019 Ingo Schwarze <schwarze@openbsd.org> 9.\" 10.\" Permission to use, copy, modify, and distribute this software for any 11.\" purpose with or without fee is hereby granted, provided that the above 12.\" copyright notice and this permission notice appear in all copies. 13.\" 14.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 15.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 16.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 17.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 18.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 19.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 20.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 21.\" 22.\" The original file was written by Richard Levitte <levitte@openssl.org>. 23.\" Copyright (c) 2016 The OpenSSL Project. All rights reserved. 24.\" 25.\" Redistribution and use in source and binary forms, with or without 26.\" modification, are permitted provided that the following conditions 27.\" are met: 28.\" 29.\" 1. Redistributions of source code must retain the above copyright 30.\" notice, this list of conditions and the following disclaimer. 31.\" 32.\" 2. Redistributions in binary form must reproduce the above copyright 33.\" notice, this list of conditions and the following disclaimer in 34.\" the documentation and/or other materials provided with the 35.\" distribution. 36.\" 37.\" 3. All advertising materials mentioning features or use of this 38.\" software must display the following acknowledgment: 39.\" "This product includes software developed by the OpenSSL Project 40.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 41.\" 42.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 43.\" endorse or promote products derived from this software without 44.\" prior written permission. For written permission, please contact 45.\" openssl-core@openssl.org. 46.\" 47.\" 5. Products derived from this software may not be called "OpenSSL" 48.\" nor may "OpenSSL" appear in their names without prior written 49.\" permission of the OpenSSL Project. 50.\" 51.\" 6. Redistributions of any form whatsoever must retain the following 52.\" acknowledgment: 53.\" "This product includes software developed by the OpenSSL Project 54.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 55.\" 56.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 57.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 58.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 59.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 60.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 61.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 62.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 63.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 65.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 67.\" OF THE POSSIBILITY OF SUCH DAMAGE. 68.\" 69.Dd $Mdocdate: July 13 2019 $ 70.Dt RSA_METH_NEW 3 71.Os 72.Sh NAME 73.Nm RSA_meth_new , 74.Nm RSA_meth_dup , 75.Nm RSA_meth_free , 76.Nm RSA_meth_get0_name , 77.Nm RSA_meth_set1_name , 78.Nm RSA_meth_get_flags , 79.Nm RSA_meth_set_flags , 80.Nm RSA_meth_get0_app_data , 81.Nm RSA_meth_set0_app_data , 82.Nm RSA_meth_get_init , 83.Nm RSA_meth_set_init , 84.Nm RSA_meth_get_finish , 85.Nm RSA_meth_set_finish , 86.Nm RSA_meth_get_pub_enc , 87.Nm RSA_meth_set_pub_enc , 88.Nm RSA_meth_get_pub_dec , 89.Nm RSA_meth_set_pub_dec , 90.Nm RSA_meth_get_priv_enc , 91.Nm RSA_meth_set_priv_enc , 92.Nm RSA_meth_get_priv_dec , 93.Nm RSA_meth_set_priv_dec , 94.Nm RSA_meth_get_sign , 95.Nm RSA_meth_set_sign , 96.Nm RSA_meth_get_verify , 97.Nm RSA_meth_set_verify , 98.Nm RSA_meth_get_mod_exp , 99.Nm RSA_meth_set_mod_exp , 100.Nm RSA_meth_get_bn_mod_exp , 101.Nm RSA_meth_set_bn_mod_exp , 102.Nm RSA_meth_get_keygen , 103.Nm RSA_meth_set_keygen 104.Nd build up RSA methods 105.Sh SYNOPSIS 106.In openssl/rsa.h 107.Ft RSA_METHOD * 108.Fo RSA_meth_new 109.Fa "const char *name" 110.Fa "int flags" 111.Fc 112.Ft RSA_METHOD * 113.Fo RSA_meth_dup 114.Fa "const RSA_METHOD *meth" 115.Fc 116.Ft void 117.Fo RSA_meth_free 118.Fa "RSA_METHOD *meth" 119.Fc 120.Ft const char * 121.Fo RSA_meth_get0_name 122.Fa "const RSA_METHOD *meth" 123.Fc 124.Ft int 125.Fo RSA_meth_set1_name 126.Fa "RSA_METHOD *meth" 127.Fa "const char *name" 128.Fc 129.Ft int 130.Fo RSA_meth_get_flags 131.Fa "const RSA_METHOD *meth" 132.Fc 133.Ft int 134.Fo RSA_meth_set_flags 135.Fa "RSA_METHOD *meth" 136.Fa "int flags" 137.Fc 138.Ft void * 139.Fo RSA_meth_get0_app_data 140.Fa "const RSA_METHOD *meth" 141.Fc 142.Ft int 143.Fo RSA_meth_set0_app_data 144.Fa "RSA_METHOD *meth" 145.Fa "void *app_data" 146.Fc 147.Ft int 148.Fo "(*RSA_meth_get_init(const RSA_METHOD *meth))" 149.Fa "RSA *rsa" 150.Fc 151.Ft int 152.Fo "RSA_meth_set_init" 153.Fa "RSA_METHOD *meth" 154.Fa "int (*init)(RSA *rsa)" 155.Fc 156.Ft int 157.Fo "(*RSA_meth_get_finish(const RSA_METHOD *meth))" 158.Fa "RSA *rsa" 159.Fc 160.Ft int 161.Fo RSA_meth_set_finish 162.Fa "RSA_METHOD *meth" 163.Fa "int (*finish)(RSA *rsa)" 164.Fc 165.Ft int 166.Fo "(*RSA_meth_get_pub_enc(const RSA_METHOD *meth))" 167.Fa "int flen" 168.Fa "const unsigned char *from" 169.Fa "unsigned char *to" 170.Fa "RSA *rsa" 171.Fa "int padding" 172.Fc 173.Ft int 174.Fo RSA_meth_set_pub_enc 175.Fa "RSA_METHOD *meth" 176.Fa "int (*pub_enc)(int flen, const unsigned char *from,\ 177 unsigned char *to, RSA *rsa, int padding)" 178.Fc 179.Ft int 180.Fo "(*RSA_meth_get_pub_dec(const RSA_METHOD *meth))" 181.Fa "int flen" 182.Fa "const unsigned char *from" 183.Fa "unsigned char *to" 184.Fa "RSA *rsa" 185.Fa "int padding" 186.Fc 187.Ft int 188.Fo RSA_meth_set_pub_dec 189.Fa "RSA_METHOD *meth" 190.Fa "int (*pub_dec)(int flen, const unsigned char *from,\ 191 unsigned char *to, RSA *rsa, int padding)" 192.Fc 193.Ft int 194.Fo "(*RSA_meth_get_priv_enc(const RSA_METHOD *meth))" 195.Fa "int flen" 196.Fa "const unsigned char *from" 197.Fa "unsigned char *to" 198.Fa "RSA *rsa" 199.Fa "int padding" 200.Fc 201.Ft int 202.Fo RSA_meth_set_priv_enc 203.Fa "RSA_METHOD *meth" 204.Fa "int (*priv_enc)(int flen, const unsigned char *from,\ 205 unsigned char *to, RSA *rsa, int padding)" 206.Fc 207.Ft int 208.Fo "(*RSA_meth_get_priv_dec(const RSA_METHOD *meth))" 209.Fa "int flen" 210.Fa "const unsigned char *from" 211.Fa "unsigned char *to" 212.Fa "RSA *rsa" 213.Fa "int padding" 214.Fc 215.Ft int 216.Fo RSA_meth_set_priv_dec 217.Fa "RSA_METHOD *meth" 218.Fa "int (*priv_dec)(int flen, const unsigned char *from,\ 219 unsigned char *to, RSA *rsa, int padding)" 220.Fc 221.Ft int 222.Fo "(*RSA_meth_get_sign(const RSA_METHOD *meth))" 223.Fa "int type" 224.Fa "const unsigned char *m" 225.Fa "unsigned int m_length" 226.Fa "unsigned char *sigret" 227.Fa "unsigned int *siglen" 228.Fa "const RSA *rsa" 229.Fc 230.Ft int 231.Fo RSA_meth_set_sign 232.Fa "RSA_METHOD *rsa" 233.Fa "int (*sign)(int type, const unsigned char *m, unsigned int m_length,\ 234 unsigned char *sigret, unsigned int *siglen, const RSA *rsa)" 235.Fc 236.Ft int 237.Fo "(*RSA_meth_get_verify(const RSA_METHOD *meth))" 238.Fa "int dtype" 239.Fa "const unsigned char *m" 240.Fa "unsigned int m_length" 241.Fa "const unsigned char *sigbuf" 242.Fa "unsigned int siglen" 243.Fa "const RSA *rsa" 244.Fc 245.Ft int 246.Fo RSA_meth_set_verify 247.Fa "RSA_METHOD *rsa" 248.Fa "int (*verify)(int dtype, const unsigned char *m,\ 249 unsigned int m_length, const unsigned char *sigbuf,\ 250 unsigned int siglen, const RSA *rsa)" 251.Fc 252.Ft int 253.Fo "(*RSA_meth_get_mod_exp(const RSA_METHOD *meth))" 254.Fa "BIGNUM *r0" 255.Fa "const BIGNUM *i" 256.Fa "RSA *rsa" 257.Fa "BN_CTX *ctx" 258.Fc 259.Ft int 260.Fo RSA_meth_set_mod_exp 261.Fa "RSA_METHOD *meth" 262.Fa "int (*mod_exp)(BIGNUM *r0, const BIGNUM *i, RSA *rsa, BN_CTX *ctx)" 263.Fc 264.Ft int 265.Fo "(*RSA_meth_get_bn_mod_exp(const RSA_METHOD *meth))" 266.Fa "BIGNUM *r" 267.Fa "const BIGNUM *a" 268.Fa "const BIGNUM *p" 269.Fa "const BIGNUM *m" 270.Fa "BN_CTX *ctx" 271.Fa "BN_MONT_CTX *m_ctx" 272.Fc 273.Ft int 274.Fo RSA_meth_set_bn_mod_exp 275.Fa "RSA_METHOD *meth" 276.Fa "int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,\ 277 const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx)" 278.Fc 279.Ft int 280.Fo "(*RSA_meth_get_keygen(const RSA_METHOD *meth))" 281.Fa "RSA *rsa" 282.Fa "int bits" 283.Fa "BIGNUM *e" 284.Fa "BN_GENCB *cb" 285.Fc 286.Ft int 287.Fo RSA_meth_set_keygen 288.Fa "RSA_METHOD *meth" 289.Fa "int (*keygen)(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb)" 290.Fc 291.Sh DESCRIPTION 292The 293.Vt RSA_METHOD 294structure holds function pointers for custom RSA implementations. 295.Pp 296.Fn RSA_meth_new 297creates a new 298.Vt RSA_METHOD 299structure. 300A copy of the NUL-terminated 301.Fa name 302is stored in the new 303.Vt RSA_METHOD 304object. 305Any new 306.Vt RSA 307object constructed from this 308.Vt RSA_METHOD 309will have the given 310.Fa flags 311set by default, as if they were set with 312.Xr RSA_set_flags 3 . 313.Pp 314.Fn RSA_meth_dup 315creates a deep copy of 316.Fa meth , 317except that a pointer stored into it with 318.Fn RSA_meth_set0_app_data 319is copied as a pointer without creating a copy of its content. 320This might be useful for creating a new 321.Vt RSA_METHOD 322based on an existing one, but with some differences. 323.Pp 324.Fn RSA_meth_free 325destroys 326.Fa meth 327and frees any memory associated with it, 328except that memory pointed to by a pointer set with 329.Fn RSA_meth_set0_app_data 330is not freed. 331If 332.Fa meth 333is 334.Dv NULL , 335no action occurs. 336.Pp 337.Fn RSA_meth_get0_name 338returns an internal pointer to the name of 339.Fa meth . 340.Fn RSA_meth_set1_name 341stores a copy of the NUL-terminated 342.Fa name 343in the 344.Vt RSA_METHOD 345object after freeing the previously stored name. 346Method names are ignored by the default RSA implementation 347but can be used by alternative implementations 348and by the application program. 349.Pp 350.Fn RSA_meth_get_flags 351retrieves the flags from 352.Fa meth . 353Flags are documented in 354.Xr RSA_test_flags 3 . 355.Fn RSA_meth_set_flags 356overwrites all flags in 357.Fa meth . 358Unlike 359.Xr RSA_set_flags 3 , 360it does not preserve any flags that were set before the call. 361.Pp 362.Fn RSA_meth_get0_app_data 363and 364.Fn RSA_meth_set0_app_data 365get and set a pointer to implementation-specific data. 366The function 367.Fn RSA_meth_free 368does not 369.Xr free 3 370the memory pointed to by 371.Fa app_data . 372The default RSA implementation does not use 373.Fa app_data . 374.Pp 375.Fn RSA_meth_get_init 376and 377.Fn RSA_meth_set_init 378get and set an optional function used when creating a new 379.Vt RSA 380object. 381Unless 382.Fa init 383is 384.Dv NULL , 385it will be called at the end of 386.Xr RSA_new 3 , 387.Xr RSA_new_method 3 , 388and 389.Xr RSA_set_method 3 , 390passing a pointer to the newly allocated or reset 391.Vt RSA 392object as an argument. 393The default RSA implementation, 394.Xr RSA_PKCS1_SSLeay 3 , 395contains an 396.Fa init 397function equivalent to calling 398.Xr RSA_set_flags 3 399with an argument of 400.Dv RSA_FLAG_CACHE_PUBLIC | RSA_FLAG_CACHE_PRIVATE . 401.Pp 402.Fn RSA_meth_get_finish 403and 404.Fn RSA_meth_set_finish 405get and set an optional function for destroying an 406.Vt RSA 407object. 408Unless 409.Fa finish 410is 411.Dv NULL , 412it will be called from 413.Xr RSA_set_method 3 414and from 415.Xr RSA_free 3 . 416It takes the same argument as 417.Xr RSA_free 3 418and is intended to do RSA implementation specific cleanup. 419The memory used by the 420.Vt RSA 421object itself should not be freed by the 422.Fa finish 423function. 424The default RSA implementation contains a 425.Fa finish 426function freeing the memory used by the 427.Dv RSA_FLAG_CACHE_PUBLIC 428and 429.Dv RSA_FLAG_CACHE_PRIVATE 430caches. 431.Pp 432.Fn RSA_meth_get_pub_enc , 433.Fn RSA_meth_set_pub_enc , 434.Fn RSA_meth_get_pub_dec , 435.Fn RSA_meth_set_pub_dec , 436.Fn RSA_meth_get_priv_enc , 437.Fn RSA_meth_set_priv_enc , 438.Fn RSA_meth_get_priv_dec , 439and 440.Fn RSA_meth_set_priv_dec 441get and set the mandatory functions 442used for public and private key encryption and decryption. 443These functions will be called from 444.Xr RSA_public_encrypt 3 , 445.Xr RSA_public_decrypt 3 , 446.Xr RSA_private_encrypt 3 , 447and 448.Xr RSA_private_decrypt 3 , 449respectively, and take the same parameters as those. 450.Pp 451.Fn RSA_meth_get_sign , 452.Fn RSA_meth_set_sign , 453.Fn RSA_meth_get_verify , 454and 455.Fn RSA_meth_set_verify 456get and set the optional functions 457used for creating and verifying an RSA signature. 458If the flag 459.Dv RSA_FLAG_SIGN_VER 460is set on the 461.Vt RSA 462object in question and 463.Fa sign 464or 465.Fa verify 466is not 467.Dv NULL , 468it will be called from 469.Xr RSA_sign 3 470or 471.Xr RSA_verify 3 , 472respectively, and take the same parameters as those. 473Otherwise, 474.Xr RSA_private_encrypt 3 475or 476.Xr RSA_public_decrypt 3 477will be used instead. 478.Pp 479.Fn RSA_meth_get_mod_exp 480and 481.Fn RSA_meth_set_mod_exp 482get and set the function 483used for Chinese Remainder Theorem (CRT) computations involving the 484.Fa p , 485.Fa q , 486.Fa dmp1 , 487.Fa dmq1 , 488and 489.Fa iqmp 490fields of an 491.Vt RSA 492object. 493It is used by the default RSA implementation during 494.Xr RSA_private_encrypt 3 495and 496.Xr RSA_private_decrypt 3 497when the required components of the private key are available 498or when the 499.Dv RSA_FLAG_EXT_PKEY 500flag is set. 501.Pp 502.Fn RSA_meth_get_bn_mod_exp 503and 504.Fn RSA_meth_set_bn_mod_exp 505get and set the function used for CRT computations, 506specifically the value r = 507.Fa a 508\(ha 509.Fa p 510mod 511.Fa m . 512It is used by the default RSA implementation during 513.Xr RSA_public_encrypt 3 514and 515.Xr RSA_public_decrypt 3 516and as a fallback during 517.Xr RSA_private_encrypt 3 518and 519.Xr RSA_private_decrypt 3 . 520.Pp 521.Fn RSA_meth_get_keygen 522and 523.Fn RSA_meth_set_keygen 524get and set the optional function used for generating a new RSA key pair. 525Unless 526.Fa keygen 527is 528.Dv NULL , 529it will be called from 530.Xr RSA_generate_key_ex 3 531and takes the same parameters. 532Otherwise, a builtin default implementation is used. 533.Sh RETURN VALUES 534.Fn RSA_meth_new 535and 536.Fn RSA_meth_dup 537return the newly allocated 538.Vt RSA_METHOD 539object or 540.Dv NULL 541on failure. 542.Pp 543.Fn RSA_meth_get0_name 544returns an internal pointer which must not be freed by the caller. 545.Pp 546.Fn RSA_meth_get_flags 547returns zero or more 548.Dv RSA_FLAG_* 549constants OR'ed together, or 0 if no flags are set in 550.Fa meth . 551.Pp 552.Fn RSA_meth_get0_app_data 553returns the pointer that was earlier passed to 554.Fn RSA_meth_set0_app_data 555or 556.Dv NULL 557otherwise. 558.Pp 559All other 560.Fn RSA_meth_get_* 561functions return the appropriate function pointer that has been set 562with the corresponding 563.Fn RSA_meth_set_* 564function, or 565.Dv NULL 566if no such pointer has been set in 567.Fa meth . 568.Pp 569All 570.Fn RSA_meth_set* 571functions return 1 on success or 0 on failure. 572In the current implementation, only 573.Fn RSA_meth_set1_name 574can actually fail. 575.Sh SEE ALSO 576.Xr RSA_generate_key_ex 3 , 577.Xr RSA_new 3 , 578.Xr RSA_private_encrypt 3 , 579.Xr RSA_public_encrypt 3 , 580.Xr RSA_set_flags 3 , 581.Xr RSA_set_method 3 , 582.Xr RSA_sign 3 583.Sh HISTORY 584These functions first appeared in OpenSSL 1.1.0. 585.Fn RSA_meth_new , 586.Fn RSA_meth_dup , 587.Fn RSA_meth_free , 588.Fn RSA_meth_set_finish , 589.Fn RSA_meth_set_priv_enc , 590and 591.Fn RSA_meth_set_priv_dec 592have been available since 593.Ox 6.3 , 594.Fn RSA_meth_set1_name 595and 596.Fn RSA_meth_get_finish 597since 598.Ox 6.4 , 599and 600.Fn RSA_meth_get0_name , 601.Fn RSA_meth_get_flags , 602.Fn RSA_meth_set_flags , 603.Fn RSA_meth_get0_app_data , 604.Fn RSA_meth_set0_app_data , 605.Fn RSA_meth_get_init , 606.Fn RSA_meth_set_init , 607.Fn RSA_meth_set_finish , 608.Fn RSA_meth_get_pub_enc , 609.Fn RSA_meth_set_pub_enc , 610.Fn RSA_meth_get_pub_dec , 611.Fn RSA_meth_set_pub_dec , 612.Fn RSA_meth_get_priv_enc , 613.Fn RSA_meth_get_priv_dec , 614.Fn RSA_meth_get_sign , 615.Fn RSA_meth_set_sign , 616.Fn RSA_meth_get_verify , 617.Fn RSA_meth_set_verify , 618.Fn RSA_meth_get_mod_exp , 619.Fn RSA_meth_set_mod_exp , 620.Fn RSA_meth_get_bn_mod_exp , 621.Fn RSA_meth_set_bn_mod_exp , 622.Fn RSA_meth_get_keygen , 623and 624.Fn RSA_meth_set_keygen 625since 626.Ox 6.6 . 627