1.\" $OpenBSD: RSA_get0_key.3,v 1.7 2023/03/06 13:05:32 tb Exp $ 2.\" selective merge up to: OpenSSL 665d899f Aug 2 02:19:43 2017 +0800 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org> 8.\" 9.\" Permission to use, copy, modify, and distribute this software for any 10.\" purpose with or without fee is hereby granted, provided that the above 11.\" copyright notice and this permission notice appear in all copies. 12.\" 13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 20.\" 21.\" The original file was written by Richard Levitte <levitte@openssl.org> 22.\" Copyright (c) 2016 The OpenSSL Project. All rights reserved. 23.\" 24.\" Redistribution and use in source and binary forms, with or without 25.\" modification, are permitted provided that the following conditions 26.\" are met: 27.\" 28.\" 1. Redistributions of source code must retain the above copyright 29.\" notice, this list of conditions and the following disclaimer. 30.\" 31.\" 2. Redistributions in binary form must reproduce the above copyright 32.\" notice, this list of conditions and the following disclaimer in 33.\" the documentation and/or other materials provided with the 34.\" distribution. 35.\" 36.\" 3. All advertising materials mentioning features or use of this 37.\" software must display the following acknowledgment: 38.\" "This product includes software developed by the OpenSSL Project 39.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 40.\" 41.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 42.\" endorse or promote products derived from this software without 43.\" prior written permission. For written permission, please contact 44.\" openssl-core@openssl.org. 45.\" 46.\" 5. Products derived from this software may not be called "OpenSSL" 47.\" nor may "OpenSSL" appear in their names without prior written 48.\" permission of the OpenSSL Project. 49.\" 50.\" 6. Redistributions of any form whatsoever must retain the following 51.\" acknowledgment: 52.\" "This product includes software developed by the OpenSSL Project 53.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 54.\" 55.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 56.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 57.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 58.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 59.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 60.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 61.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 62.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 63.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 64.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 66.\" OF THE POSSIBILITY OF SUCH DAMAGE. 67.\" 68.Dd $Mdocdate: March 6 2023 $ 69.Dt RSA_GET0_KEY 3 70.Os 71.Sh NAME 72.Nm RSA_get0_key , 73.Nm RSA_get0_n , 74.Nm RSA_get0_e , 75.Nm RSA_get0_d , 76.Nm RSA_set0_key , 77.Nm RSA_get0_factors , 78.Nm RSA_get0_p , 79.Nm RSA_get0_q , 80.Nm RSA_set0_factors , 81.Nm RSA_get0_crt_params , 82.Nm RSA_get0_dmp1 , 83.Nm RSA_get0_dmq1 , 84.Nm RSA_get0_iqmp , 85.Nm RSA_set0_crt_params , 86.Nm RSA_clear_flags , 87.Nm RSA_test_flags , 88.Nm RSA_set_flags 89.Nd get and set data in an RSA object 90.Sh SYNOPSIS 91.In openssl/rsa.h 92.Ft void 93.Fo RSA_get0_key 94.Fa "const RSA *r" 95.Fa "const BIGNUM **n" 96.Fa "const BIGNUM **e" 97.Fa "const BIGNUM **d" 98.Fc 99.Ft "const BIGNUM *" 100.Fo RSA_get0_n 101.Fa "const RSA *r" 102.Fc 103.Ft "const BIGNUM *" 104.Fo RSA_get0_e 105.Fa "const RSA *r" 106.Fc 107.Ft "const BIGNUM *" 108.Fo RSA_get0_d 109.Fa "const RSA *r" 110.Fc 111.Ft int 112.Fo RSA_set0_key 113.Fa "RSA *r" 114.Fa "BIGNUM *n" 115.Fa "BIGNUM *e" 116.Fa "BIGNUM *d" 117.Fc 118.Ft void 119.Fo RSA_get0_factors 120.Fa "const RSA *r" 121.Fa "const BIGNUM **p" 122.Fa "const BIGNUM **q" 123.Fc 124.Ft "const BIGNUM *" 125.Fo RSA_get0_p 126.Fa "const RSA *r" 127.Fc 128.Ft "const BIGNUM *" 129.Fo RSA_get0_q 130.Fa "const RSA *r" 131.Fc 132.Ft int 133.Fo RSA_set0_factors 134.Fa "RSA *r" 135.Fa "BIGNUM *p" 136.Fa "BIGNUM *q" 137.Fc 138.Ft void 139.Fo RSA_get0_crt_params 140.Fa "const RSA *r" 141.Fa "const BIGNUM **dmp1" 142.Fa "const BIGNUM **dmq1" 143.Fa "const BIGNUM **iqmp" 144.Fc 145.Ft "const BIGNUM *" 146.Fo RSA_get0_dmp1 147.Fa "const RSA *r" 148.Fc 149.Ft "const BIGNUM *" 150.Fo RSA_get0_dmq1 151.Fa "const RSA *r" 152.Fc 153.Ft "const BIGNUM *" 154.Fo RSA_get0_iqmp 155.Fa "const RSA *r" 156.Fc 157.Ft int 158.Fo RSA_set0_crt_params 159.Fa "RSA *r" 160.Fa "BIGNUM *dmp1" 161.Fa "BIGNUM *dmq1" 162.Fa "BIGNUM *iqmp" 163.Fc 164.Ft void 165.Fo RSA_clear_flags 166.Fa "RSA *r" 167.Fa "int flags" 168.Fc 169.Ft int 170.Fo RSA_test_flags 171.Fa "const RSA *r" 172.Fa "int flags" 173.Fc 174.Ft void 175.Fo RSA_set_flags 176.Fa "RSA *r" 177.Fa "int flags" 178.Fc 179.Sh DESCRIPTION 180An 181.Vt RSA 182object contains the components for the public and private key. 183.Fa n 184is the modulus common to both public and private key, 185.Fa e 186is the public exponent and 187.Fa d 188is the private exponent. 189.Fa p , 190.Fa q , 191.Fa dmp1 , 192.Fa dmq1 , 193and 194.Fa iqmp 195are the factors for the second representation of a private key 196(see PKCS#1 section 3 Key Types), where 197.Fa p 198and 199.Fa q 200are the first and second factor of 201.Fa n . 202.Fa dmp1 , 203.Fa dmq1 , 204and 205.Fa iqmp 206are the exponents and coefficient 207for Chinese Remainder Theorem (CRT) calculations. 208.Pp 209The 210.Fa n , 211.Fa e , 212and 213.Fa d 214parameters can be obtained by calling 215.Fn RSA_get0_key . 216If they have not been set yet, then 217.Pf * Fa n , 218.Pf * Fa e , 219and 220.Pf * Fa d 221are set to 222.Dv NULL . 223Otherwise, they are set to pointers to the internal representations 224of the values that should not be freed by the caller. 225.Pp 226The 227.Fa n , 228.Fa e , 229and 230.Fa d 231parameter values can be set by calling 232.Fn RSA_set0_key . 233The values 234.Fa n 235and 236.Fa e 237must be 238.Pf non- Dv NULL 239the first time this function is called on a given 240.Vt RSA 241object. 242The value 243.Fa d 244may be 245.Dv NULL . 246On subsequent calls, any of these values may be 247.Dv NULL , 248which means that the corresponding field is left untouched. 249Calling this function transfers the memory management of the values to 250the RSA object. 251Therefore, the values that have been passed in 252should not be freed by the caller. 253.Pp 254In a similar fashion, the 255.Fa p 256and 257.Fa q 258parameters can be obtained and set with 259.Fn RSA_get0_factors 260and 261.Fn RSA_set0_factors , 262and the 263.Fa dmp1 , 264.Fa dmq1 , 265and 266.Fa iqmp 267parameters can be obtained and set with 268.Fn RSA_get0_crt_params 269and 270.Fn RSA_set0_crt_params . 271.Pp 272For 273.Fn RSA_get0_key , 274.Fn RSA_get0_factors , 275and 276.Fn RSA_get0_crt_params , 277.Dv NULL 278value 279.Vt BIGNUM ** 280output arguments are permitted. 281The functions 282ignore 283.Dv NULL 284arguments but return values for other, 285.Pf non- Dv NULL , 286arguments. 287.Pp 288Values retrieved with 289.Fn RSA_get0_key , 290.Fn RSA_get0_factors , 291and 292.Fn RSA_get0_crt_params 293are owned by the 294.Vt RSA 295object used in the call and may therefore 296.Em not 297be passed to 298.Fn RSA_set0_key , 299.Fn RSA_set0_factors , 300or 301.Fn RSA_set0_crt_params . 302If needed, duplicate the received value using 303.Xr BN_dup 3 304and pass the duplicate. 305.Pp 306Any of the values 307.Fa n , 308.Fa e , 309.Fa d , 310.Fa p , 311.Fa q , 312.Fa dmp1 , 313.Fa dmq1 , 314and 315.Fa iqmp 316can also be retrieved separately by the corresponding functions 317.Fn RSA_get0_n , 318.Fn RSA_get0_e , 319.Fn RSA_get0_d , 320.Fn RSA_get0_p , 321.Fn RSA_get0_q , 322.Fn RSA_get0_dmp1 , 323.Fn RSA_get0_dmq1 , 324and 325.Fn RSA_get0_iqmp , 326respectively. 327The pointers are owned by the 328.Vt RSA 329object. 330.Pp 331.Fn RSA_clear_flags 332clears the specified 333.Fa flags 334in 335.Fa r . 336.Fn RSA_test_flags 337tests the 338.Fa flags 339in 340.Fa r . 341.Fn RSA_set_flags 342sets the 343.Fa flags 344in 345.Fa r ; 346any flags already set remain set. 347For all three functions, multiple flags can be passed in one call, 348OR'ed together bitwise. 349.Pp 350The following flags are supported: 351.Bl -tag -width Ds 352.It Dv RSA_FLAG_CACHE_PRIVATE No and Dv RSA_FLAG_CACHE_PUBLIC 353Precompute information needed for Montgomery multiplication 354from the private and public key, respectively, and cache it in 355.Fa r 356for repeated use. 357These two flags are set by default for the default RSA implementation, 358.Xr RSA_PKCS1_SSLeay 3 . 359.It Dv RSA_FLAG_EXT_PKEY 360The function set with 361.Xr RSA_meth_set_mod_exp 3 362is used for private key operations even if 363.Fa p , 364.Fa q , 365.Fa dmp1 , 366.Fa dmq1 , 367and 368.Fa iqmp 369are all 370.Dv NULL . 371This flag may be useful with RSA implementations that do not use the 372private key components stored in the standard fields, for example 373because they store the private key in external hardware. 374If this flag is unset, the function set with 375.Xr RSA_meth_set_bn_mod_exp 3 376is used with 377.Fa n 378and 379.Fa d 380instead. 381.It Dv RSA_FLAG_NO_BLINDING 382Turn off blinding during private key encryption and decryption. 383This flag is set by 384.Xr RSA_blinding_off 3 . 385.It Dv RSA_FLAG_SIGN_VER 386Enable the use of the functions set with 387.Xr RSA_meth_set_sign 3 388and 389.Xr RSA_meth_set_verify 3 . 390If unset, the functions set with 391.Xr RSA_meth_set_priv_enc 3 392and 393.Xr RSA_meth_set_pub_dec 3 394are used instead, respectively. 395.El 396.Pp 397The flags 398.Dv RSA_FLAG_BLINDING , 399.Dv RSA_FLAG_CHECKED , 400.Dv RSA_FLAG_FIPS_METHOD , 401.Dv RSA_FLAG_NON_FIPS_ALLOW , 402and 403.Dv RSA_FLAG_THREAD_SAFE 404are defined for compatibility with existing code but have no effect. 405.Sh RETURN VALUES 406.Fn RSA_get0_n , 407.Fn RSA_get0_e , 408.Fn RSA_get0_d , 409.Fn RSA_get0_p , 410.Fn RSA_get0_q , 411.Fn RSA_get0_dmp1 , 412.Fn RSA_get0_dmq1 , 413and 414.Fn RSA_get0_iqmp 415return a pointer owned by the 416.Vt RSA 417object if the corresponding value has been set, 418otherwise they return 419.Dv NULL . 420.Pp 421.Fn RSA_set0_key , 422.Fn RSA_set0_factors , 423and 424.Fn RSA_set0_crt_params 425return 1 on success or 0 on failure. 426.Pp 427.Fn RSA_test_flags 428returns those of the given 429.Fa flags 430currently set in 431.Fa r 432or 0 if none of the given 433.Fa flags 434are set. 435.Sh SEE ALSO 436.Xr RSA_check_key 3 , 437.Xr RSA_generate_key 3 , 438.Xr RSA_new 3 , 439.Xr RSA_print 3 , 440.Xr RSA_size 3 441.Sh HISTORY 442.Fn RSA_get0_key , 443.Fn RSA_set0_key , 444.Fn RSA_get0_factors , 445.Fn RSA_set0_factors , 446.Fn RSA_get0_crt_params , 447.Fn RSA_set0_crt_params , 448.Fn RSA_clear_flags , 449.Fn RSA_test_flags , 450and 451.Fn RSA_set_flags 452first appeared in OpenSSL 1.1.0 453and have been available since 454.Ox 6.3 . 455.Pp 456.Fn RSA_get0_n , 457.Fn RSA_get0_e , 458.Fn RSA_get0_d , 459.Fn RSA_get0_p , 460.Fn RSA_get0_q , 461.Fn RSA_get0_dmp1 , 462.Fn RSA_get0_dmq1 , 463and 464.Fn RSA_get0_iqmp 465first appeared in OpenSSL 1.1.1 466and have been available since 467.Ox 7.1 . 468