1.\" $OpenBSD: RSA_meth_new.3,v 1.6 2025/01/05 15:40:42 tb 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: January 5 2025 $ 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. 458.Pp 459.Fn RSA_meth_get_mod_exp 460and 461.Fn RSA_meth_set_mod_exp 462get and set the function 463used for Chinese Remainder Theorem (CRT) computations involving the 464.Fa p , 465.Fa q , 466.Fa dmp1 , 467.Fa dmq1 , 468and 469.Fa iqmp 470fields of an 471.Vt RSA 472object. 473It is used by the default RSA implementation during 474.Xr RSA_private_encrypt 3 475and 476.Xr RSA_private_decrypt 3 477when the required components of the private key are available 478or when the 479.Dv RSA_FLAG_EXT_PKEY 480flag is set. 481.Pp 482.Fn RSA_meth_get_bn_mod_exp 483and 484.Fn RSA_meth_set_bn_mod_exp 485get and set the function used for CRT computations, 486specifically the value r = 487.Fa a 488\(ha 489.Fa p 490mod 491.Fa m . 492It is used by the default RSA implementation during 493.Xr RSA_public_encrypt 3 494and 495.Xr RSA_public_decrypt 3 496and as a fallback during 497.Xr RSA_private_encrypt 3 498and 499.Xr RSA_private_decrypt 3 . 500.Pp 501.Fn RSA_meth_get_keygen 502and 503.Fn RSA_meth_set_keygen 504get and set the optional function used for generating a new RSA key pair. 505Unless 506.Fa keygen 507is 508.Dv NULL , 509it will be called from 510.Xr RSA_generate_key_ex 3 511and takes the same parameters. 512Otherwise, a builtin default implementation is used. 513.Sh RETURN VALUES 514.Fn RSA_meth_new 515and 516.Fn RSA_meth_dup 517return the newly allocated 518.Vt RSA_METHOD 519object or 520.Dv NULL 521on failure. 522.Pp 523.Fn RSA_meth_get0_name 524returns an internal pointer which must not be freed by the caller. 525.Pp 526.Fn RSA_meth_get_flags 527returns zero or more 528.Dv RSA_FLAG_* 529constants OR'ed together, or 0 if no flags are set in 530.Fa meth . 531.Pp 532.Fn RSA_meth_get0_app_data 533returns the pointer that was earlier passed to 534.Fn RSA_meth_set0_app_data 535or 536.Dv NULL 537otherwise. 538.Pp 539All other 540.Fn RSA_meth_get_* 541functions return the appropriate function pointer that has been set 542with the corresponding 543.Fn RSA_meth_set_* 544function, or 545.Dv NULL 546if no such pointer has been set in 547.Fa meth . 548.Pp 549All 550.Fn RSA_meth_set* 551functions return 1 on success or 0 on failure. 552In the current implementation, only 553.Fn RSA_meth_set1_name 554can actually fail. 555.Sh SEE ALSO 556.Xr RSA_generate_key_ex 3 , 557.Xr RSA_new 3 , 558.Xr RSA_private_encrypt 3 , 559.Xr RSA_public_encrypt 3 , 560.Xr RSA_set_flags 3 , 561.Xr RSA_set_method 3 , 562.Xr RSA_sign 3 563.Sh HISTORY 564These functions first appeared in OpenSSL 1.1.0. 565.Fn RSA_meth_new , 566.Fn RSA_meth_dup , 567.Fn RSA_meth_free , 568.Fn RSA_meth_set_finish , 569.Fn RSA_meth_set_priv_enc , 570and 571.Fn RSA_meth_set_priv_dec 572have been available since 573.Ox 6.3 , 574.Fn RSA_meth_set1_name 575and 576.Fn RSA_meth_get_finish 577since 578.Ox 6.4 , 579and 580.Fn RSA_meth_get0_name , 581.Fn RSA_meth_get_flags , 582.Fn RSA_meth_set_flags , 583.Fn RSA_meth_get0_app_data , 584.Fn RSA_meth_set0_app_data , 585.Fn RSA_meth_get_init , 586.Fn RSA_meth_set_init , 587.Fn RSA_meth_set_finish , 588.Fn RSA_meth_get_pub_enc , 589.Fn RSA_meth_set_pub_enc , 590.Fn RSA_meth_get_pub_dec , 591.Fn RSA_meth_set_pub_dec , 592.Fn RSA_meth_get_priv_enc , 593.Fn RSA_meth_get_priv_dec , 594.Fn RSA_meth_get_sign , 595.Fn RSA_meth_set_sign , 596.Fn RSA_meth_get_verify , 597.Fn RSA_meth_set_verify , 598.Fn RSA_meth_get_mod_exp , 599.Fn RSA_meth_set_mod_exp , 600.Fn RSA_meth_get_bn_mod_exp , 601.Fn RSA_meth_set_bn_mod_exp , 602.Fn RSA_meth_get_keygen , 603and 604.Fn RSA_meth_set_keygen 605since 606.Ox 6.6 . 607