summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/RSA_new.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/RSA_new.3')
-rw-r--r--src/lib/libcrypto/man/RSA_new.3248
1 files changed, 0 insertions, 248 deletions
diff --git a/src/lib/libcrypto/man/RSA_new.3 b/src/lib/libcrypto/man/RSA_new.3
deleted file mode 100644
index f5c7929e77..0000000000
--- a/src/lib/libcrypto/man/RSA_new.3
+++ /dev/null
@@ -1,248 +0,0 @@
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 .