1.\" $OpenBSD: RSA_new.3,v 1.16 2019/11/01 12:02:58 schwarze 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 1 2019 $ 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 , 132calls 133.Xr ENGINE_finish 3 134if 135.Fa rsa 136uses an engine, and frees the 137.Vt RSA 138structure and its components. 139The key is erased before the memory is returned to the system. 140If 141.Fa rsa 142is a 143.Dv NULL 144pointer, no action occurs. 145.Pp 146The 147.Vt RSA 148structure consists of several 149.Vt BIGNUM 150components. 151It can contain public as well as private RSA keys: 152.Bd -literal 153typedef struct { 154 BIGNUM *n; // public modulus 155 BIGNUM *e; // public exponent 156 BIGNUM *d; // private exponent 157 BIGNUM *p; // secret prime factor 158 BIGNUM *q; // secret prime factor 159 BIGNUM *dmp1; // d mod (p-1) 160 BIGNUM *dmq1; // d mod (q-1) 161 BIGNUM *iqmp; // q^-1 mod p 162 // ... 163} RSA; 164.Ed 165.Pp 166In public keys, the private exponent 167.Fa d 168and the related secret values 169.Fa p , q , dmp1 , dmp2 , 170and 171.Fa iqmp 172are 173.Dv NULL . 174.Pp 175.Fa p , 176.Fa q , 177.Fa dmp1 , 178.Fa dmq1 , 179and 180.Fa iqmp 181may be 182.Dv NULL 183in private keys, but the RSA operations are much faster when these 184values are available. 185.Pp 186Note that RSA keys may use non-standard 187.Vt RSA_METHOD 188implementations, either directly or by the use of 189.Vt ENGINE 190modules. 191In some cases (e.g. an 192.Vt ENGINE 193providing support for hardware-embedded keys), these 194.Vt BIGNUM 195values will not be used by the implementation or may be used for 196alternative data storage. 197For this reason, applications should generally avoid using 198.Vt RSA 199structure elements directly and instead use API functions to query 200or modify keys. 201.Sh RETURN VALUES 202.Fn RSA_new , 203.Fn RSAPrivateKey_dup , 204and 205.Fn RSAPublicKey_dup 206return a pointer to the newly allocated structure, or 207.Dv NULL 208if an error occurs. 209An error code can be obtained by 210.Xr ERR_get_error 3 . 211.Pp 212.Fn RSA_up_ref 213returns 1 for success or 0 for failure. 214.Sh SEE ALSO 215.Xr BN_new 3 , 216.Xr crypto 3 , 217.Xr d2i_RSAPublicKey 3 , 218.Xr DH_new 3 , 219.Xr DSA_new 3 , 220.Xr EVP_PKEY_set1_RSA 3 , 221.Xr RSA_blinding_on 3 , 222.Xr RSA_check_key 3 , 223.Xr RSA_generate_key 3 , 224.Xr RSA_get0_key 3 , 225.Xr RSA_get_ex_new_index 3 , 226.Xr RSA_meth_new 3 , 227.Xr RSA_padding_add_PKCS1_type_1 3 , 228.Xr RSA_pkey_ctx_ctrl 3 , 229.Xr RSA_print 3 , 230.Xr RSA_private_encrypt 3 , 231.Xr RSA_PSS_PARAMS_new 3 , 232.Xr RSA_public_encrypt 3 , 233.Xr RSA_set_method 3 , 234.Xr RSA_sign 3 , 235.Xr RSA_sign_ASN1_OCTET_STRING 3 , 236.Xr RSA_size 3 237.Sh STANDARDS 238SSL, PKCS #1 v2.0 239.Pp 240RSA was covered by a US patent which expired in September 2000. 241.Sh HISTORY 242.Fn RSA_new 243and 244.Fn RSA_free 245appeared in SSLeay 0.4 or earlier. 246.Fn RSAPrivateKey_dup 247first appeared in SSLeay 0.5.1 and 248.Fn RSAPublicKey_dup 249in SSLeay 0.5.2. 250These functions have been available since 251.Ox 2.4 . 252.Pp 253.Fn RSA_up_ref 254first appeared in OpenSSL 0.9.7 and has been available since 255.Ox 3.2 . 256