summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/EVP_PKEY_set1_RSA.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/EVP_PKEY_set1_RSA.3')
-rw-r--r--src/lib/libcrypto/man/EVP_PKEY_set1_RSA.3498
1 files changed, 0 insertions, 498 deletions
diff --git a/src/lib/libcrypto/man/EVP_PKEY_set1_RSA.3 b/src/lib/libcrypto/man/EVP_PKEY_set1_RSA.3
deleted file mode 100644
index 39404f5286..0000000000
--- a/src/lib/libcrypto/man/EVP_PKEY_set1_RSA.3
+++ /dev/null
@@ -1,498 +0,0 @@
1.\" $OpenBSD: EVP_PKEY_set1_RSA.3,v 1.24 2024/12/09 11:25:25 schwarze Exp $
2.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
3.\"
4.\" This file is a derived work.
5.\" The changes are covered by the following Copyright and license:
6.\"
7.\" Copyright (c) 2019, 2020, 2023 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 Dr. Stephen Henson <steve@openssl.org>.
22.\" Copyright (c) 2002, 2015, 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: December 9 2024 $
69.Dt EVP_PKEY_SET1_RSA 3
70.Os
71.Sh NAME
72.Nm EVP_PKEY_set1_RSA ,
73.Nm EVP_PKEY_set1_DSA ,
74.Nm EVP_PKEY_set1_DH ,
75.Nm EVP_PKEY_set1_EC_KEY ,
76.Nm EVP_PKEY_get1_RSA ,
77.Nm EVP_PKEY_get1_DSA ,
78.Nm EVP_PKEY_get1_DH ,
79.Nm EVP_PKEY_get1_EC_KEY ,
80.Nm EVP_PKEY_get0_RSA ,
81.Nm EVP_PKEY_get0_DSA ,
82.Nm EVP_PKEY_get0_DH ,
83.Nm EVP_PKEY_get0_EC_KEY ,
84.Nm EVP_PKEY_get0_hmac ,
85.Nm EVP_PKEY_get0 ,
86.Nm EVP_PKEY_assign_RSA ,
87.Nm EVP_PKEY_assign_DSA ,
88.Nm EVP_PKEY_assign_DH ,
89.Nm EVP_PKEY_assign_EC_KEY ,
90.Nm EVP_PKEY_assign ,
91.Nm EVP_PKEY_base_id ,
92.Nm EVP_PKEY_id ,
93.Nm EVP_PKEY_type ,
94.Nm EVP_PKEY_set_type ,
95.Nm EVP_PKEY_set_type_str
96.\" The function X509_certificate_type(3) is intentionally undocumented
97.\" and scheduled for deletion from the library. BoringSSL already
98.\" deleted it and OpenSSL deprecates it in version 3.0.
99.\" The following constants are also intentionally undocumented
100.\" because they are only used by that function:
101.\" EVP_PK_DH EVP_PK_DSA EVP_PK_EC EVP_PK_RSA
102.\" EVP_PKS_DSA EVP_PKS_EC EVP_PKS_RSA
103.\" EVP_PKT_ENC EVP_PKT_EXCH EVP_PKT_EXP EVP_PKT_SIGN
104.Nd EVP_PKEY assignment functions
105.Sh SYNOPSIS
106.In openssl/evp.h
107.Ft int
108.Fo EVP_PKEY_set1_RSA
109.Fa "EVP_PKEY *pkey"
110.Fa "RSA *key"
111.Fc
112.Ft int
113.Fo EVP_PKEY_set1_DSA
114.Fa "EVP_PKEY *pkey"
115.Fa "DSA *key"
116.Fc
117.Ft int
118.Fo EVP_PKEY_set1_DH
119.Fa "EVP_PKEY *pkey"
120.Fa "DH *key"
121.Fc
122.Ft int
123.Fo EVP_PKEY_set1_EC_KEY
124.Fa "EVP_PKEY *pkey"
125.Fa "EC_KEY *key"
126.Fc
127.Ft RSA *
128.Fo EVP_PKEY_get1_RSA
129.Fa "EVP_PKEY *pkey"
130.Fc
131.Ft DSA *
132.Fo EVP_PKEY_get1_DSA
133.Fa "EVP_PKEY *pkey"
134.Fc
135.Ft DH *
136.Fo EVP_PKEY_get1_DH
137.Fa "EVP_PKEY *pkey"
138.Fc
139.Ft EC_KEY *
140.Fo EVP_PKEY_get1_EC_KEY
141.Fa "EVP_PKEY *pkey"
142.Fc
143.Ft RSA *
144.Fo EVP_PKEY_get0_RSA
145.Fa "EVP_PKEY *pkey"
146.Fc
147.Ft DSA *
148.Fo EVP_PKEY_get0_DSA
149.Fa "EVP_PKEY *pkey"
150.Fc
151.Ft DH *
152.Fo EVP_PKEY_get0_DH
153.Fa "EVP_PKEY *pkey"
154.Fc
155.Ft EC_KEY *
156.Fo EVP_PKEY_get0_EC_KEY
157.Fa "EVP_PKEY *pkey"
158.Fc
159.Ft const unsigned char *
160.Fo EVP_PKEY_get0_hmac
161.Fa "const EVP_PKEY *pkey"
162.Fa "size_t *len"
163.Fc
164.Ft void *
165.Fo EVP_PKEY_get0
166.Fa "const EVP_PKEY *pkey"
167.Fc
168.Ft int
169.Fo EVP_PKEY_assign_RSA
170.Fa "EVP_PKEY *pkey"
171.Fa "RSA *key"
172.Fc
173.Ft int
174.Fo EVP_PKEY_assign_DSA
175.Fa "EVP_PKEY *pkey"
176.Fa "DSA *key"
177.Fc
178.Ft int
179.Fo EVP_PKEY_assign_DH
180.Fa "EVP_PKEY *pkey"
181.Fa "DH *key"
182.Fc
183.Ft int
184.Fo EVP_PKEY_assign_EC_KEY
185.Fa "EVP_PKEY *pkey"
186.Fa "EC_KEY *key"
187.Fc
188.Ft int
189.Fo EVP_PKEY_assign
190.Fa "EVP_PKEY *pkey"
191.Fa "int type"
192.Fa "void *key"
193.Fc
194.Ft int
195.Fo EVP_PKEY_base_id
196.Fa "EVP_PKEY *pkey"
197.Fc
198.Ft int
199.Fo EVP_PKEY_id
200.Fa "EVP_PKEY *pkey"
201.Fc
202.Ft int
203.Fo EVP_PKEY_type
204.Fa "int type"
205.Fc
206.Ft int
207.Fo EVP_PKEY_set_type
208.Fa "EVP_PKEY *pkey"
209.Fa "int type"
210.Fc
211.Ft int
212.Fo EVP_PKEY_set_type_str
213.Fa "EVP_PKEY *pkey"
214.Fa "const char *str"
215.Fa "int len"
216.Fc
217.Sh DESCRIPTION
218.Fn EVP_PKEY_set1_RSA ,
219.Fn EVP_PKEY_set1_DSA ,
220.Fn EVP_PKEY_set1_DH ,
221and
222.Fn EVP_PKEY_set1_EC_KEY
223set the key referenced by
224.Fa pkey
225to
226.Fa key
227and increment the reference count of
228.Fa key
229by 1 in case of success.
230.Pp
231.Fn EVP_PKEY_get1_RSA ,
232.Fn EVP_PKEY_get1_DSA ,
233.Fn EVP_PKEY_get1_DH ,
234and
235.Fn EVP_PKEY_get1_EC_KEY
236return the key referenced in
237.Fa pkey ,
238incrementing its reference count by 1, or
239.Dv NULL
240if the key is not of the correct type.
241.Pp
242.Fn EVP_PKEY_get0_RSA ,
243.Fn EVP_PKEY_get0_DSA ,
244.Fn EVP_PKEY_get0_DH ,
245.Fn EVP_PKEY_get0_EC_KEY ,
246and
247.Fn EVP_PKEY_get0
248are identical except that they do not increment the reference count.
249Consequently, the returned key must not be freed by the caller.
250.Pp
251.Fn EVP_PKEY_get0_hmac
252returns an internal pointer to the key referenced in
253.Fa pkey
254and sets
255.Pf * Fa len
256to its length in bytes.
257The returned pointer must not be freed by the caller.
258If
259.Fa pkey
260is not of the correct type,
261.Dv NULL
262is returned and the content of
263.Pf * Fa len
264becomes unspecified.
265.Pp
266.Fn EVP_PKEY_assign_RSA ,
267.Fn EVP_PKEY_assign_DSA ,
268.Fn EVP_PKEY_assign_DH ,
269.Fn EVP_PKEY_assign_EC_KEY ,
270and
271.Fn EVP_PKEY_assign
272also set the referenced key to
273.Fa key ;
274however these use the supplied
275.Fa key
276internally without incrementing its reference count, such that
277.Fa key
278will be freed when the parent
279.Fa pkey
280is freed.
281If the
282.Fa key
283is of the wrong type, these functions report success even though
284.Fa pkey
285ends up in a corrupted state.
286Even the functions explicitly containing the type in their name are
287.Em not
288type safe because they are implemented as macros.
289The following types are supported:
290.Dv EVP_PKEY_RSA ,
291.Dv EVP_PKEY_DSA ,
292.Dv EVP_PKEY_DH ,
293and
294.Dv EVP_PKEY_EC .
295.Pp
296.Fn EVP_PKEY_base_id
297returns the type of
298.Fa pkey
299according to the following table:
300.Pp
301.Bl -column -compact -offset 2n EVP_PKEY_RSA_PSS NID_X9_62_id_ecPublicKey
302.It Sy return value Ta Ta Sy PEM type string
303.It Dv EVP_PKEY_CMAC Ta = Dv NID_cmac Ta CMAC
304.It Dv EVP_PKEY_DH Ta = Dv NID_dhKeyAgreement Ta DH
305.It Dv EVP_PKEY_DSA Ta = Dv NID_dsa Ta DSA
306.It Dv EVP_PKEY_EC Ta = Dv NID_X9_62_id_ecPublicKey Ta EC
307.It Dv EVP_PKEY_HMAC Ta = Dv NID_hmac Ta HMAC
308.It Dv EVP_PKEY_RSA Ta = Dv NID_rsaEncryption Ta RSA
309.It Dv EVP_PKEY_RSA_PSS Ta = Dv NID_rsassaPss Ta RSA-PSS
310.El
311.Pp
312.Fn EVP_PKEY_id
313returns the actual OID associated with
314.Fa pkey .
315Historically keys using the same algorithm could use different OIDs.
316The following deprecated aliases are still supported:
317.Pp
318.Bl -column -compact -offset 2n EVP_PKEY_DSA4 NID_dsaWithSHA1_2
319.It Sy return value Ta Ta Sy alias for
320.It Dv EVP_PKEY_DSA1 Ta = Dv NID_dsa_2 Ta DSA
321.It Dv EVP_PKEY_DSA2 Ta = Dv NID_dsaWithSHA Ta DSA
322.It Dv EVP_PKEY_DSA3 Ta = Dv NID_dsaWithSHA1 Ta DSA
323.It Dv EVP_PKEY_DSA4 Ta = Dv NID_dsaWithSHA1_2 Ta DSA
324.It Dv EVP_PKEY_RSA2 Ta = Dv NID_rsa Ta RSA
325.El
326.Pp
327Most applications wishing to know a key type will simply call
328.Fn EVP_PKEY_base_id
329and will not care about the actual type,
330which will be identical in almost all cases.
331.Pp
332.Fn EVP_PKEY_type
333returns the underlying type of the NID
334.Fa type .
335For example,
336.Fn EVP_PKEY_type EVP_PKEY_RSA2
337will return
338.Dv EVP_PKEY_RSA .
339.Pp
340.Fn EVP_PKEY_set_type
341frees the key referenced in
342.Fa pkey ,
343if any, and sets the key type of
344.Fa pkey
345to
346.Fa type
347without referencing a new key from
348.Fa pkey
349yet.
350For
351.Fa type ,
352any of the possible return values of
353.Fn EVP_PKEY_base_id
354and
355.Fn EVP_PKEY_id
356can be passed.
357.Pp
358.Fn EVP_PKEY_set_type_str
359frees the key referenced in
360.Fa pkey ,
361if any, and sets the key type of
362.Fa pkey
363according to the PEM type string given by the first
364.Fa len
365bytes of
366.Fa str .
367If
368.Fa len
369is \-1, the
370.Xr strlen 3
371of
372.Fa str
373is used instead.
374The PEM type strings supported by default are listed in the table above.
375This function does not reference a new key from
376.Fa pkey .
377.Pp
378If
379.Fa pkey
380is a
381.Dv NULL
382pointer,
383.Fn EVP_PKEY_set_type
384and
385.Fn EVP_PKEY_set_type_str
386check that a matching key type exists but do not change any object.
387.Pp
388In accordance with the OpenSSL naming convention, the key obtained from
389or assigned to
390.Fa pkey
391using the
392.Sy 1
393functions must be freed as well as
394.Fa pkey .
395.Sh RETURN VALUES
396.Fn EVP_PKEY_set1_RSA ,
397.Fn EVP_PKEY_set1_DSA ,
398.Fn EVP_PKEY_set1_DH ,
399.Fn EVP_PKEY_set1_EC_KEY ,
400.Fn EVP_PKEY_assign_RSA ,
401.Fn EVP_PKEY_assign_DSA ,
402.Fn EVP_PKEY_assign_DH ,
403.Fn EVP_PKEY_assign_EC_KEY ,
404.Fn EVP_PKEY_assign ,
405.Fn EVP_PKEY_set_type ,
406and
407.Fn EVP_PKEY_set_type_str
408return 1 for success or 0 for failure.
409.Pp
410.Fn EVP_PKEY_get1_RSA ,
411.Fn EVP_PKEY_get1_DSA ,
412.Fn EVP_PKEY_get1_DH ,
413.Fn EVP_PKEY_get1_EC_KEY ,
414.Fn EVP_PKEY_get0_RSA ,
415.Fn EVP_PKEY_get0_DSA ,
416.Fn EVP_PKEY_get0_DH ,
417.Fn EVP_PKEY_get0_EC_KEY ,
418.Fn EVP_PKEY_get0_hmac ,
419and
420.Fn EVP_PKEY_get0
421return the referenced key or
422.Dv NULL
423if an error occurred.
424For
425.Fn EVP_PKEY_get0 ,
426the return value points to an
427.Vt RSA ,
428.Vt DSA ,
429.Vt DH ,
430.Vt EC_KEY ,
431or
432.Vt ASN1_OCTET_STRING
433object depending on the type of
434.Fa pkey .
435.Pp
436.Fn EVP_PKEY_base_id ,
437.Fn EVP_PKEY_id ,
438and
439.Fn EVP_PKEY_type
440return a key type or
441.Dv NID_undef
442(equivalently
443.Dv EVP_PKEY_NONE )
444on error.
445.Sh SEE ALSO
446.Xr DH_new 3 ,
447.Xr DSA_new 3 ,
448.Xr EC_KEY_new 3 ,
449.Xr EVP_PKEY_get0_asn1 3 ,
450.Xr EVP_PKEY_new 3 ,
451.Xr RSA_new 3
452.Sh HISTORY
453.Fn EVP_PKEY_assign_RSA ,
454.Fn EVP_PKEY_assign_DSA ,
455.Fn EVP_PKEY_assign_DH ,
456.Fn EVP_PKEY_assign ,
457and
458.Fn EVP_PKEY_type
459first appeared in SSLeay 0.8.0 and have been available since
460.Ox 2.4 .
461.Pp
462.Fn EVP_PKEY_set1_RSA ,
463.Fn EVP_PKEY_set1_DSA ,
464.Fn EVP_PKEY_set1_DH ,
465.Fn EVP_PKEY_get1_RSA ,
466.Fn EVP_PKEY_get1_DSA ,
467and
468.Fn EVP_PKEY_get1_DH
469first appeared in OpenSSL 0.9.5 and have been available since
470.Ox 2.7 .
471.Pp
472.Fn EVP_PKEY_set1_EC_KEY ,
473.Fn EVP_PKEY_get1_EC_KEY ,
474and
475.Fn EVP_PKEY_assign_EC_KEY
476first appeared in OpenSSL 0.9.8 and have been available since
477.Ox 4.5 .
478.Pp
479.Fn EVP_PKEY_get0 ,
480.Fn EVP_PKEY_base_id ,
481.Fn EVP_PKEY_id ,
482.Fn EVP_PKEY_set_type ,
483and
484.Fn EVP_PKEY_set_type_str
485first appeared in OpenSSL 1.0.0 and have been available since
486.Ox 4.9 .
487.Pp
488.Fn EVP_PKEY_get0_RSA ,
489.Fn EVP_PKEY_get0_DSA ,
490.Fn EVP_PKEY_get0_DH ,
491and
492.Fn EVP_PKEY_get0_EC_KEY
493first appeared in OpenSSL 1.1.0 and have been available since
494.Ox 6.3 .
495.Pp
496.Fn EVP_PKEY_get0_hmac
497first appeared in OpenSSL 1.1.0 and has been available since
498.Ox 6.5 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-01-16 18:38:17 +0000