Debian Codegraph @

upstream/debian-unstable/man3/EVP_PKEY_derive.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "EVP_PKEY_DERIVE 3SSL"
58 .TH EVP_PKEY_DERIVE 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 EVP_PKEY_derive_init, EVP_PKEY_derive_init_ex,
65 EVP_PKEY_derive_set_peer_ex, EVP_PKEY_derive_set_peer, EVP_PKEY_derive,
66 EVP_PKEY_derive_SKEY
67 \&\- derive public key algorithm shared secret
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& #include <openssl/evp.h>
72 \&
73 \& int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx);
74 \& int EVP_PKEY_derive_init_ex(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);
75 \& int EVP_PKEY_derive_set_peer_ex(EVP_PKEY_CTX *ctx, EVP_PKEY *peer,
76 \& int validate_peer);
77 \& int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer);
78 \& int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
79 \& EVP_SKEY *EVP_PKEY_derive_SKEY(EVP_PKEY_CTX *ctx, EVP_SKEYMGMT *mgmt,
80 \& const char *key_type, const char *propquery,
81 \& size_t keylen, const OSSL_PARAM params[]);
82 .Ve
83 .SH DESCRIPTION
84 .IX Header "DESCRIPTION"
85 \&\fBEVP_PKEY_derive_init()\fR initializes a public key algorithm context \fIctx\fR for
86 shared secret derivation using the algorithm given when the context was created
87 using \fBEVP_PKEY_CTX_new\fR\|(3) or variants thereof. The algorithm is used to
88 fetch a \fBEVP_KEYEXCH\fR method implicitly, see "Implicit fetch" in \fBprovider\fR\|(7) for
89 more information about implicit fetches.
90 .PP
91 \&\fBEVP_PKEY_derive_init_ex()\fR is the same as \fBEVP_PKEY_derive_init()\fR but additionally
92 sets the passed parameters \fIparams\fR on the context before returning.
93 .PP
94 \&\fBEVP_PKEY_derive_set_peer_ex()\fR sets the peer key: this will normally
95 be a public key. The \fIvalidate_peer\fR will validate the public key if this value
96 is non zero.
97 .PP
98 \&\fBEVP_PKEY_derive_set_peer()\fR is similar to \fBEVP_PKEY_derive_set_peer_ex()\fR with
99 \&\fIvalidate_peer\fR set to 1.
100 .PP
101 \&\fBEVP_PKEY_derive()\fR derives a shared secret using \fIctx\fR.
102 If \fIkey\fR is NULL then the maximum size of the output buffer is written to the
103 \&\fIkeylen\fR parameter. If \fIkey\fR is not NULL then before the call the \fIkeylen\fR
104 parameter should contain the length of the \fIkey\fR buffer, if the call is
105 successful the shared secret is written to \fIkey\fR and the amount of data
106 written to \fIkeylen\fR.
107 .PP
108 \&\fBEVP_PKEY_derive_SKEY()\fR is similar to \fBEVP_PKEY_derive()\fR but returns an
109 \&\fBEVP_SKEY\fR object that stores the opaque data for the derived key. If
110 \&\fBEVP_SKEYMGMT\fR argument is passed, it would be explicitly used for the
111 \&\fBEVP_SKEY\fR creation. Otherwise the \fBEVP_SKEYMGMT\fR object used for \fBEVP_SKEY\fR
112 will be fetched according to \fIskeymgmtname\fR and \fIpropquery\fR. If
113 \&\fIskeymgmtname\fR is NULL, the name matching the key exchange method name is
114 assumed.
115 .SH NOTES
116 .IX Header "NOTES"
117 After the call to \fBEVP_PKEY_derive_init()\fR, algorithm
118 specific control operations can be performed to set any appropriate parameters
119 for the operation.
120 .PP
121 The function \fBEVP_PKEY_derive()\fR can be called more than once on the same
122 context if several operations are performed using the same parameters.
123 .SH "RETURN VALUES"
124 .IX Header "RETURN VALUES"
125 \&\fBEVP_PKEY_derive_init()\fR and \fBEVP_PKEY_derive()\fR return 1
126 for success and 0 or a negative value for failure.
127 In particular a return value of \-2 indicates the operation is not supported by
128 the public key algorithm.
129 .PP
130 \&\fBEVP_PKEY_derive_SKEY()\fR returns a freshly created \fBEVP_SKEY\fR object on success
131 or NULL on failure.
132 .SH EXAMPLES
133 .IX Header "EXAMPLES"
134 Derive shared secret (for example DH or EC keys):
135 .PP
136 .Vb 2
137 \& #include <openssl/evp.h>
138 \& #include <openssl/rsa.h>
139 \&
140 \& EVP_PKEY_CTX *ctx;
141 \& ENGINE *eng;
142 \& unsigned char *skey;
143 \& size_t skeylen;
144 \& EVP_PKEY *pkey, *peerkey;
145 \& /* NB: assumes pkey, eng, peerkey have been already set up */
146 \&
147 \& ctx = EVP_PKEY_CTX_new(pkey, eng);
148 \& if (!ctx)
149 \& /* Error occurred */
150 \& if (EVP_PKEY_derive_init(ctx) <= 0)
151 \& /* Error */
152 \& if (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0)
153 \& /* Error */
154 \&
155 \& /* Determine buffer length */
156 \& if (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0)
157 \& /* Error */
158 \&
159 \& skey = OPENSSL_malloc(skeylen);
160 \&
161 \& if (!skey)
162 \& /* malloc failure */
163 \&
164 \& if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0)
165 \& /* Error */
166 \&
167 \& /* Shared secret is skey bytes written to buffer skey */
168 .Ve
169 .SH "SEE ALSO"
170 .IX Header "SEE ALSO"
171 \&\fBEVP_PKEY_CTX_new\fR\|(3),
172 \&\fBEVP_PKEY_encrypt\fR\|(3),
173 \&\fBEVP_PKEY_decrypt\fR\|(3),
174 \&\fBEVP_PKEY_sign\fR\|(3),
175 \&\fBEVP_PKEY_verify\fR\|(3),
176 \&\fBEVP_PKEY_verify_recover\fR\|(3),
177 \&\fBEVP_KEYEXCH_fetch\fR\|(3)
178 .SH HISTORY
179 .IX Header "HISTORY"
180 The \fBEVP_PKEY_derive_init()\fR, \fBEVP_PKEY_derive_set_peer()\fR and \fBEVP_PKEY_derive()\fR
181 functions were originally added in OpenSSL 1.0.0.
182 .PP
183 The \fBEVP_PKEY_derive_init_ex()\fR and \fBEVP_PKEY_derive_set_peer_ex()\fR functions were
184 added in OpenSSL 3.0.
185 .PP
186 The \fBEVP_PKEY_derive_SKEY()\fR function was added in OpenSSL 3.6.
187 .SH COPYRIGHT
188 .IX Header "COPYRIGHT"
189 Copyright 2006\-2025 The OpenSSL Project Authors. All Rights Reserved.
190 .PP
191 Licensed under the Apache License 2.0 (the "License"). You may not use
192 this file except in compliance with the License. You can obtain a copy
193 in the file LICENSE in the source distribution or at
194 <https://www.openssl.org/source/license.html>.