1.\" $OpenBSD: RSA_new.3,v 1.18 2023/11/19 21:03:22 tb Exp $ 2.\" full merge up to: 3.\" OpenSSL doc/man3/RSA_new.pod e9b77246 Jan 20 19:58:49 2017 +0100 4.\" OpenSSL doc/crypto/rsa.pod 35d2e327 Jun 3 16:19:49 2016 -0400 (final) 5.\" 6.\" This file is a derived work. 7.\" The changes are covered by the following Copyright and license: 8.\" 9.\" Copyright (c) 2018, 2019 Ingo Schwarze <schwarze@openbsd.org> 10.\" 11.\" Permission to use, copy, modify, and distribute this software for any 12.\" purpose with or without fee is hereby granted, provided that the above 13.\" copyright notice and this permission notice appear in all copies. 14.\" 15.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 16.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 17.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 18.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 19.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 20.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 21.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 22.\" 23.\" The original file was written by Ulf Moeller <ulf@openssl.org>. 24.\" Copyright (c) 2000, 2002, 2016 The OpenSSL Project. All rights reserved. 25.\" 26.\" Redistribution and use in source and binary forms, with or without 27.\" modification, are permitted provided that the following conditions 28.\" are met: 29.\" 30.\" 1. Redistributions of source code must retain the above copyright 31.\" notice, this list of conditions and the following disclaimer. 32.\" 33.\" 2. Redistributions in binary form must reproduce the above copyright 34.\" notice, this list of conditions and the following disclaimer in 35.\" the documentation and/or other materials provided with the 36.\" distribution. 37.\" 38.\" 3. All advertising materials mentioning features or use of this 39.\" software must display the following acknowledgment: 40.\" "This product includes software developed by the OpenSSL Project 41.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 42.\" 43.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 44.\" endorse or promote products derived from this software without 45.\" prior written permission. For written permission, please contact 46.\" openssl-core@openssl.org. 47.\" 48.\" 5. Products derived from this software may not be called "OpenSSL" 49.\" nor may "OpenSSL" appear in their names without prior written 50.\" permission of the OpenSSL Project. 51.\" 52.\" 6. Redistributions of any form whatsoever must retain the following 53.\" acknowledgment: 54.\" "This product includes software developed by the OpenSSL Project 55.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 56.\" 57.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 58.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 59.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 60.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 61.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 62.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 63.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 64.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 65.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 66.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 67.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 68.\" OF THE POSSIBILITY OF SUCH DAMAGE. 69.\" 70.Dd $Mdocdate: November 19 2023 $ 71.Dt RSA_NEW 3 72.Os 73.Sh NAME 74.Nm RSA_new , 75.Nm RSAPrivateKey_dup , 76.Nm RSAPublicKey_dup , 77.Nm RSA_up_ref , 78.Nm RSA_free 79.Nd allocate and free RSA objects 80.Sh SYNOPSIS 81.In openssl/rsa.h 82.Ft RSA * 83.Fn RSA_new void 84.Ft RSA * 85.Fo RSAPrivateKey_dup 86.Fa "RSA *rsa" 87.Fc 88.Ft RSA * 89.Fo RSAPublicKey_dup 90.Fa "RSA *rsa" 91.Fc 92.Ft int 93.Fo RSA_up_ref 94.Fa "RSA *rsa" 95.Fc 96.Ft void 97.Fo RSA_free 98.Fa "RSA *rsa" 99.Fc 100.Sh DESCRIPTION 101The RSA functions implement RSA public key encryption and signatures 102as defined in PKCS #1 v2.0 (RFC 2437). 103.Pp 104.Fn RSA_new 105allocates and initializes an 106.Vt RSA 107structure, setting the reference count to 1. 108It is equivalent to calling 109.Xr RSA_new_method 3 110with a 111.Dv NULL 112argument. 113.Pp 114.Fn RSAPrivateKey_dup 115calls 116.Fn RSA_new 117and copies the public and private key components from 118.Fa rsa 119into the new structure. 120.Fn RSAPublicKey_dup 121does the same except that it copies the public key components only. 122.Pp 123.Fn RSA_up_ref 124increments the reference count by 1. 125.Pp 126.Fn RSA_free 127decrements the reference count by 1. 128If it reaches 0, it calls the optional 129.Fa finish 130function set up with 131.Xr RSA_meth_set_finish 3 132and frees the 133.Vt RSA 134structure and its components. 135The key is erased before the memory is returned to the system. 136If 137.Fa rsa 138is a 139.Dv NULL 140pointer, no action occurs. 141.Pp 142The 143.Vt RSA 144structure consists of several 145.Vt BIGNUM 146components. 147It can contain public as well as private RSA keys: 148.Bd -literal 149typedef struct { 150 BIGNUM *n; // public modulus 151 BIGNUM *e; // public exponent 152 BIGNUM *d; // private exponent 153 BIGNUM *p; // secret prime factor 154 BIGNUM *q; // secret prime factor 155 BIGNUM *dmp1; // d mod (p-1) 156 BIGNUM *dmq1; // d mod (q-1) 157 BIGNUM *iqmp; // q^-1 mod p 158 // ... 159} RSA; 160.Ed 161.Pp 162In public keys, the private exponent 163.Fa d 164and the related secret values 165.Fa p , q , dmp1 , dmp2 , 166and 167.Fa iqmp 168are 169.Dv NULL . 170.Pp 171.Fa p , 172.Fa q , 173.Fa dmp1 , 174.Fa dmq1 , 175and 176.Fa iqmp 177may be 178.Dv NULL 179in private keys, but the RSA operations are much faster when these 180values are available. 181.Pp 182Note that RSA keys may use non-standard 183.Vt RSA_METHOD 184implementations. 185In some cases, these 186.Vt BIGNUM 187values will not be used by the implementation or may be used for 188alternative data storage. 189For this reason, applications should generally avoid using 190.Vt RSA 191structure elements directly and instead use API functions to query 192or modify keys. 193.Sh RETURN VALUES 194.Fn RSA_new , 195.Fn RSAPrivateKey_dup , 196and 197.Fn RSAPublicKey_dup 198return a pointer to the newly allocated structure, or 199.Dv NULL 200if an error occurs. 201An error code can be obtained by 202.Xr ERR_get_error 3 . 203.Pp 204.Fn RSA_up_ref 205returns 1 for success or 0 for failure. 206.Sh SEE ALSO 207.Xr BN_new 3 , 208.Xr crypto 3 , 209.Xr d2i_RSAPublicKey 3 , 210.Xr DH_new 3 , 211.Xr DSA_new 3 , 212.Xr EVP_PKEY_set1_RSA 3 , 213.Xr RSA_blinding_on 3 , 214.Xr RSA_check_key 3 , 215.Xr RSA_generate_key 3 , 216.Xr RSA_get0_key 3 , 217.Xr RSA_get_ex_new_index 3 , 218.Xr RSA_meth_new 3 , 219.Xr RSA_padding_add_PKCS1_type_1 3 , 220.Xr RSA_pkey_ctx_ctrl 3 , 221.Xr RSA_print 3 , 222.Xr RSA_private_encrypt 3 , 223.Xr RSA_PSS_PARAMS_new 3 , 224.Xr RSA_public_encrypt 3 , 225.Xr RSA_security_bits 3 , 226.Xr RSA_set_method 3 , 227.Xr RSA_sign 3 , 228.Xr RSA_sign_ASN1_OCTET_STRING 3 , 229.Xr RSA_size 3 230.Sh STANDARDS 231SSL, PKCS #1 v2.0 232.Pp 233RSA was covered by a US patent which expired in September 2000. 234.Sh HISTORY 235.Fn RSA_new 236and 237.Fn RSA_free 238appeared in SSLeay 0.4 or earlier. 239.Fn RSAPrivateKey_dup 240first appeared in SSLeay 0.5.1 and 241.Fn RSAPublicKey_dup 242in SSLeay 0.5.2. 243These functions have been available since 244.Ox 2.4 . 245.Pp 246.Fn RSA_up_ref 247first appeared in OpenSSL 0.9.7 and has been available since 248.Ox 3.2 . 249