1.\" $OpenBSD: RSA_get0_key.3,v 1.6 2019/07/13 17:26:38 schwarze 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: July 13 2019 $ 69.Dt RSA_GET0_KEY 3 70.Os 71.Sh NAME 72.Nm RSA_get0_key , 73.Nm RSA_set0_key , 74.Nm RSA_get0_factors , 75.Nm RSA_set0_factors , 76.Nm RSA_get0_crt_params , 77.Nm RSA_set0_crt_params , 78.Nm RSA_clear_flags , 79.Nm RSA_test_flags , 80.Nm RSA_set_flags 81.Nd get and set data in an RSA object 82.Sh SYNOPSIS 83.In openssl/rsa.h 84.Ft void 85.Fo RSA_get0_key 86.Fa "const RSA *r" 87.Fa "const BIGNUM **n" 88.Fa "const BIGNUM **e" 89.Fa "const BIGNUM **d" 90.Fc 91.Ft int 92.Fo RSA_set0_key 93.Fa "RSA *r" 94.Fa "BIGNUM *n" 95.Fa "BIGNUM *e" 96.Fa "BIGNUM *d" 97.Fc 98.Ft void 99.Fo RSA_get0_factors 100.Fa "const RSA *r" 101.Fa "const BIGNUM **p" 102.Fa "const BIGNUM **q" 103.Fc 104.Ft int 105.Fo RSA_set0_factors 106.Fa "RSA *r" 107.Fa "BIGNUM *p" 108.Fa "BIGNUM *q" 109.Fc 110.Ft void 111.Fo RSA_get0_crt_params 112.Fa "const RSA *r" 113.Fa "const BIGNUM **dmp1" 114.Fa "const BIGNUM **dmq1" 115.Fa "const BIGNUM **iqmp" 116.Fc 117.Ft int 118.Fo RSA_set0_crt_params 119.Fa "RSA *r" 120.Fa "BIGNUM *dmp1" 121.Fa "BIGNUM *dmq1" 122.Fa "BIGNUM *iqmp" 123.Fc 124.Ft void 125.Fo RSA_clear_flags 126.Fa "RSA *r" 127.Fa "int flags" 128.Fc 129.Ft int 130.Fo RSA_test_flags 131.Fa "const RSA *r" 132.Fa "int flags" 133.Fc 134.Ft void 135.Fo RSA_set_flags 136.Fa "RSA *r" 137.Fa "int flags" 138.Fc 139.Sh DESCRIPTION 140An 141.Vt RSA 142object contains the components for the public and private key. 143.Fa n 144is the modulus common to both public and private key, 145.Fa e 146is the public exponent and 147.Fa d 148is the private exponent. 149.Fa p , 150.Fa q , 151.Fa dmp1 , 152.Fa dmq1 , 153and 154.Fa iqmp 155are the factors for the second representation of a private key 156(see PKCS#1 section 3 Key Types), where 157.Fa p 158and 159.Fa q 160are the first and second factor of 161.Fa n . 162.Fa dmp1 , 163.Fa dmq1 , 164and 165.Fa iqmp 166are the exponents and coefficient 167for Chinese Remainder Theorem (CRT) calculations. 168.Pp 169The 170.Fa n , 171.Fa e , 172and 173.Fa d 174parameters can be obtained by calling 175.Fn RSA_get0_key . 176If they have not been set yet, then 177.Pf * Fa n , 178.Pf * Fa e , 179and 180.Pf * Fa d 181are set to 182.Dv NULL . 183Otherwise, they are set to pointers to the internal representations 184of the values that should not be freed by the caller. 185.Pp 186The 187.Fa n , 188.Fa e , 189and 190.Fa d 191parameter values can be set by calling 192.Fn RSA_set0_key . 193The values 194.Fa n 195and 196.Fa e 197must be 198.Pf non- Dv NULL 199the first time this function is called on a given 200.Vt RSA 201object. 202The value 203.Fa d 204may be 205.Dv NULL . 206On subsequent calls, any of these values may be 207.Dv NULL , 208which means that the corresponding field is left untouched. 209Calling this function transfers the memory management of the values to 210the RSA object. 211Therefore, the values that have been passed in 212should not be freed by the caller. 213.Pp 214In a similar fashion, the 215.Fa p 216and 217.Fa q 218parameters can be obtained and set with 219.Fn RSA_get0_factors 220and 221.Fn RSA_set0_factors , 222and the 223.Fa dmp1 , 224.Fa dmq1 , 225and 226.Fa iqmp 227parameters can be obtained and set with 228.Fn RSA_get0_crt_params 229and 230.Fn RSA_set0_crt_params . 231.Pp 232For 233.Fn RSA_get0_key , 234.Fn RSA_get0_factors , 235and 236.Fn RSA_get0_crt_params , 237.Dv NULL 238value 239.Vt BIGNUM ** 240output arguments are permitted. 241The functions 242ignore 243.Dv NULL 244arguments but return values for other, 245.Pf non- Dv NULL , 246arguments. 247.Pp 248Values retrieved with 249.Fn RSA_get0_key , 250.Fn RSA_get0_factors , 251and 252.Fn RSA_get0_crt_params 253are owned by the 254.Vt RSA 255object used in the call and may therefore 256.Em not 257be passed to 258.Fn RSA_set0_key , 259.Fn RSA_set0_factors , 260or 261.Fn RSA_set0_crt_params . 262If needed, duplicate the received value using 263.Xr BN_dup 3 264and pass the duplicate. 265.Pp 266.Fn RSA_clear_flags 267clears the specified 268.Fa flags 269in 270.Fa r . 271.Fn RSA_test_flags 272tests the 273.Fa flags 274in 275.Fa r . 276.Fn RSA_set_flags 277sets the 278.Fa flags 279in 280.Fa r ; 281any flags already set remain set. 282For all three functions, multiple flags can be passed in one call, 283OR'ed together bitwise. 284.Pp 285The following flags are supported: 286.Bl -tag -width Ds 287.It Dv RSA_FLAG_CACHE_PRIVATE No and Dv RSA_FLAG_CACHE_PUBLIC 288Precompute information needed for Montgomery multiplication 289from the private and public key, respectively, and cache it in 290.Fa r 291for repeated use. 292These two flags are set by default for the default RSA implementation, 293.Xr RSA_PKCS1_SSLeay 3 . 294.It Dv RSA_FLAG_EXT_PKEY 295The function set with 296.Xr RSA_meth_set_mod_exp 3 297is used for private key operations even if 298.Fa p , 299.Fa q , 300.Fa dmp1 , 301.Fa dmq1 , 302and 303.Fa iqmp 304are all 305.Dv NULL . 306This flag may be useful with RSA implementations that do not use the 307private key components stored in the standard fields, for example 308because they store the private key in external hardware. 309If this flag is unset, the function set with 310.Xr RSA_meth_set_bn_mod_exp 3 311is used with 312.Fa n 313and 314.Fa d 315instead. 316.It Dv RSA_FLAG_NO_BLINDING 317Turn off blinding during private key encryption and decryption. 318This flag is set by 319.Xr RSA_blinding_off 3 . 320.It Dv RSA_FLAG_SIGN_VER 321Enable the use of the functions set with 322.Xr RSA_meth_set_sign 3 323and 324.Xr RSA_meth_set_verify 3 . 325If unset, the functions set with 326.Xr RSA_meth_set_priv_enc 3 327and 328.Xr RSA_meth_set_pub_dec 3 329are used instead, respectively. 330.El 331.Pp 332The flags 333.Dv RSA_FLAG_BLINDING , 334.Dv RSA_FLAG_CHECKED , 335.Dv RSA_FLAG_FIPS_METHOD , 336.Dv RSA_FLAG_NON_FIPS_ALLOW , 337and 338.Dv RSA_FLAG_THREAD_SAFE 339are defined for compatibility with existing code but have no effect. 340.Sh RETURN VALUES 341.Fn RSA_set0_key , 342.Fn RSA_set0_factors , 343and 344.Fn RSA_set0_crt_params 345return 1 on success or 0 on failure. 346.Pp 347.Fn RSA_test_flags 348returns those of the given 349.Fa flags 350currently set in 351.Fa r 352or 0 if none of the given 353.Fa flags 354are set. 355.Sh SEE ALSO 356.Xr RSA_check_key 3 , 357.Xr RSA_generate_key 3 , 358.Xr RSA_new 3 , 359.Xr RSA_print 3 , 360.Xr RSA_size 3 361.Sh HISTORY 362These functions first appeared in OpenSSL 1.1.0 363and have been available since 364.Ox 6.3 . 365