summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/EVP_PKEY_derive.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/lib/libcrypto/man/EVP_PKEY_derive.3254
1 files changed, 0 insertions, 254 deletions
diff --git a/src/lib/libcrypto/man/EVP_PKEY_derive.3 b/src/lib/libcrypto/man/EVP_PKEY_derive.3
deleted file mode 100644
index 47f467fea1..0000000000
--- a/src/lib/libcrypto/man/EVP_PKEY_derive.3
+++ /dev/null
@@ -1,254 +0,0 @@
1.\" $OpenBSD: EVP_PKEY_derive.3,v 1.12 2024/12/06 14:27:49 schwarze Exp $
2.\" full merge up to: OpenSSL 48e5119a Jan 19 10:49:22 2018 +0100
3.\"
4.\" This file is a derived work.
5.\" The changes are covered by the following Copyright and license:
6.\"
7.\" Copyright (c) 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) 2006, 2009, 2013, 2018 The OpenSSL Project.
23.\" All rights reserved.
24.\"
25.\" Redistribution and use in source and binary forms, with or without
26.\" modification, are permitted provided that the following conditions
27.\" are met:
28.\"
29.\" 1. Redistributions of source code must retain the above copyright
30.\" notice, this list of conditions and the following disclaimer.
31.\"
32.\" 2. Redistributions in binary form must reproduce the above copyright
33.\" notice, this list of conditions and the following disclaimer in
34.\" the documentation and/or other materials provided with the
35.\" distribution.
36.\"
37.\" 3. All advertising materials mentioning features or use of this
38.\" software must display the following acknowledgment:
39.\" "This product includes software developed by the OpenSSL Project
40.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
41.\"
42.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
43.\" endorse or promote products derived from this software without
44.\" prior written permission. For written permission, please contact
45.\" openssl-core@openssl.org.
46.\"
47.\" 5. Products derived from this software may not be called "OpenSSL"
48.\" nor may "OpenSSL" appear in their names without prior written
49.\" permission of the OpenSSL Project.
50.\"
51.\" 6. Redistributions of any form whatsoever must retain the following
52.\" acknowledgment:
53.\" "This product includes software developed by the OpenSSL Project
54.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
55.\"
56.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
57.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
58.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
59.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
60.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
61.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
62.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
63.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
65.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
67.\" OF THE POSSIBILITY OF SUCH DAMAGE.
68.\"
69.Dd $Mdocdate: December 6 2024 $
70.Dt EVP_PKEY_DERIVE 3
71.Os
72.Sh NAME
73.Nm EVP_PKEY_derive_init ,
74.Nm EVP_PKEY_derive_set_peer ,
75.Nm EVP_PKEY_CTX_get0_peerkey ,
76.Nm EVP_PKEY_derive
77.Nd derive public key algorithm shared secret
78.Sh SYNOPSIS
79.In openssl/evp.h
80.Ft int
81.Fo EVP_PKEY_derive_init
82.Fa "EVP_PKEY_CTX *ctx"
83.Fc
84.Ft int
85.Fo EVP_PKEY_derive_set_peer
86.Fa "EVP_PKEY_CTX *ctx"
87.Fa "EVP_PKEY *peerkey"
88.Fc
89.Ft EVP_PKEY *
90.Fo EVP_PKEY_CTX_get0_peerkey
91.Fa "EVP_PKEY_CTX *ctx"
92.Fc
93.Ft int
94.Fo EVP_PKEY_derive
95.Fa "EVP_PKEY_CTX *ctx"
96.Fa "unsigned char *key"
97.Fa "size_t *keylen"
98.Fc
99.Sh DESCRIPTION
100.Fn EVP_PKEY_derive_init
101initializes the public key algorithm context
102.Fa ctx
103for shared secret derivation using the
104.Vt EVP_PKEY
105object already stored in
106.Fa ctx .
107The library provides built-in support for keys with an
108.Xr EVP_PKEY_base_id 3
109of
110.Dv EVP_PKEY_DH ,
111.Dv EVP_PKEY_EC ,
112.Dv EVP_PKEY_HKDF ,
113and
114.Dv EVP_PKEY_X25519 .
115.Pp
116After the call to
117.Fn EVP_PKEY_derive_init ,
118algorithm specific control operations can optionally be performed
119to set any appropriate parameters for the operation.
120.Pp
121.Fn EVP_PKEY_derive_set_peer
122configures the
123.Fa ctx ,
124which already needs to be initialized with
125.Fn EVP_PKEY_derive_init ,
126.Xr EVP_PKEY_encrypt_init 3 ,
127or
128.Xr EVP_PKEY_decrypt_init 3 ,
129to use the
130.Fa peerkey ,
131which is normally a public key.
132In case of success, the reference count of the
133.Fa peerkey
134is incremented by one.
135Consequently, the caller needs to call
136.Xr EVP_PKEY_free 3
137on the
138.Fa peerkey
139when the caller no longer needs it, even if it is still in use by
140.Fa ctx .
141.Pp
142.Fn EVP_PKEY_derive
143derives a shared secret using
144.Fa ctx .
145If
146.Fa key
147is
148.Dv NULL ,
149then the maximum size of the output buffer is written to the
150.Fa keylen
151parameter.
152If
153.Fa key
154is not
155.Dv NULL
156then before the call the
157.Fa keylen
158parameter should contain the length of the
159.Fa key
160buffer.
161If the call is successful, the shared secret is written to
162.Fa key
163and the amount of data written to
164.Fa keylen .
165.Pp
166The function
167.Fn EVP_PKEY_derive
168can be called more than once on the same context if several operations
169are performed using the same parameters.
170.Sh RETURN VALUES
171.Fn EVP_PKEY_derive_init ,
172.Fn EVP_PKEY_derive_set_peer ,
173and
174.Fn EVP_PKEY_derive
175return 1 for success and 0 or a negative value for failure.
176In particular, a return value of \-2 indicates the operation is not
177supported by the public key algorithm.
178.Pp
179For
180.Fn EVP_PKEY_derive_set_peer ,
181a return value of \-1 can for example occur if
182.Fa ctx
183is not properly initialized, does not contain an
184.Vt EVP_PKEY
185that can be retrieved with
186.Xr EVP_PKEY_CTX_get0_pkey 3 ,
187the
188.Xr EVP_PKEY_id 3
189of both keys mismatch, or
190.Xr EVP_PKEY_cmp_parameters 3
191reports mismatching key parameters.
192.Pp
193.Fn EVP_PKEY_derive
194fails with a return value of \-1 for example if
195.Fa ctx
196has not been successfully initialized with
197.Fn EVP_PKEY_derive_init .
198.Pp
199.Fn EVP_PKEY_CTX_get0_peerkey
200returns an internal pointer to the
201.Fa peerkey
202used by
203.Fa ctx
204without incrementing its reference count.
205.Sh EXAMPLES
206Derive shared secret (for example DH or EC keys):
207.Bd -literal -offset indent
208#include <openssl/evp.h>
209#include <openssl/rsa.h>
210
211EVP_PKEY_CTX *ctx;
212unsigned char *skey;
213size_t skeylen;
214EVP_PKEY *pkey, *peerkey;
215
216/* Assumes that pkey and peerkey have already been set up. */
217ctx = EVP_PKEY_CTX_new(pkey, NULL);
218if (!ctx)
219 /* Error occurred */
220if (EVP_PKEY_derive_init(ctx) <= 0)
221 /* Error */
222if (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0)
223 /* Error */
224
225/* Determine buffer length */
226if (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0)
227 /* Error */
228
229skey = malloc(skeylen);
230
231if (!skey)
232 /* malloc failure */
233
234if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0)
235 /* Error */
236
237/* Shared secret is skey bytes written to buffer skey */
238.Ed
239.Sh SEE ALSO
240.Xr EVP_PKEY_CTX_new 3 ,
241.Xr EVP_PKEY_decrypt 3 ,
242.Xr EVP_PKEY_encrypt 3 ,
243.Xr EVP_PKEY_sign 3 ,
244.Xr EVP_PKEY_verify 3 ,
245.Xr EVP_PKEY_verify_recover 3 ,
246.Xr X25519 3
247.Sh HISTORY
248.Fn EVP_PKEY_derive_init ,
249.Fn EVP_PKEY_derive_set_peer ,
250.Fn EVP_PKEY_CTX_get0_peerkey ,
251and
252.Fn EVP_PKEY_derive
253first appeared in OpenSSL 1.0.0 and have been available since
254.Ox 4.9 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-07 00:39:42 +0000