Debian Codegraph @

upstream/debian-unstable/man3/EVP_PKEY_encapsulate.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_ENCAPSULATE 3SSL"
58 .TH EVP_PKEY_ENCAPSULATE 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_encapsulate_init, EVP_PKEY_auth_encapsulate_init, EVP_PKEY_encapsulate
65 \&\- Key encapsulation using a KEM algorithm with a public key
66 .SH SYNOPSIS
67 .IX Header "SYNOPSIS"
68 .Vb 1
69 \& #include <openssl/evp.h>
70 \&
71 \& int EVP_PKEY_encapsulate_init(EVP_PKEY_CTX *ctx, const OSSL_PARAM params[]);
72 \& int EVP_PKEY_auth_encapsulate_init(EVP_PKEY_CTX *ctx, EVP_PKEY *authpriv,
73 \& const OSSL_PARAM params[]);
74 \& int EVP_PKEY_encapsulate(EVP_PKEY_CTX *ctx,
75 \& unsigned char *wrappedkey, size_t *wrappedkeylen,
76 \& unsigned char *genkey, size_t *genkeylen);
77 .Ve
78 .SH DESCRIPTION
79 .IX Header "DESCRIPTION"
80 The \fBEVP_PKEY_encapsulate_init()\fR function initializes a public key algorithm
81 context \fIctx\fR for an encapsulation operation and then sets the \fIparams\fR
82 on the context in the same way as calling \fBEVP_PKEY_CTX_set_params\fR\|(3).
83 Note that \fIctx\fR is usually is produced using \fBEVP_PKEY_CTX_new_from_pkey\fR\|(3),
84 specifying the public key to use.
85 .PP
86 The \fBEVP_PKEY_auth_encapsulate_init()\fR function is similar to
87 \&\fBEVP_PKEY_encapsulate_init()\fR but also passes an \fIauthpriv\fR authentication private
88 key that is used during encapsulation.
89 .PP
90 The \fBEVP_PKEY_encapsulate()\fR function performs a public key encapsulation
91 operation using \fIctx\fR.
92 The shared secret written to \fIgenkey\fR can be used as an input for key
93 derivation, typically for various symmetric algorithms.
94 Its size is written to \fIgenkeylen\fR, which must be initialised to the
95 size of the provided buffer.
96 .PP
97 The ciphertext written to \fIwrappedkey\fR is an encapsulated form, which
98 is expected to be only usable by the holder of the private key corresponding
99 to the public key associated with \fIctx\fR.
100 This ciphertext is then communicated to the private-key holder, who can use
101 \&\fBEVP_PKEY_decapsulate\fR\|(3) to securely recover the same shared secret.
102 .PP
103 If \fIwrappedkey\fR is NULL then the maximum size of the output buffer is written
104 to the \fI*wrappedkeylen\fR parameter unless \fIwrappedkeylen\fR is NULL and the
105 maximum size of the generated key buffer is written to \fI*genkeylen\fR unless
106 \&\fIgenkeylen\fR is NULL.
107 .PP
108 If \fIwrappedkey\fR is not NULL and the call is successful then the generated
109 shared secret is written to \fIgenkey\fR and its size is written to
110 \&\fI*genkeylen\fR (which must be non-NULL).
111 The encapsulated ciphertext is written to \fIwrappedkey\fR and
112 its size is written to \fI*wrappedkeylen\fR (must also be non-NULL),
113 The value pointed to by \fIwrappedlen\fR initially hold the size of the
114 \&\fIunwrapped\fR buffer so that its size can be validated by the call, ensuring it
115 is large enough to hold the result written to \fIwrapped\fR.
116 .PP
117 Absent detailed prior knowledge of the internals of the specific KEM
118 algorithm, callers SHOULD NOT assume that the returned shared secret and
119 ciphertext are necessarily of the maximum possible length.
120 The lengths returned via \fI*wrappedkeylen\fR and \fI*genkeylen\fR SHOULD
121 be used to determine the actual lengths of the outputs.
122 .SH NOTES
123 .IX Header "NOTES"
124 After the call to \fBEVP_PKEY_encapsulate_init()\fR, algorithm-specific parameters
125 for the operation may be set or modified using \fBEVP_PKEY_CTX_set_params\fR\|(3).
126 .SH "RETURN VALUES"
127 .IX Header "RETURN VALUES"
128 \&\fBEVP_PKEY_encapsulate_init()\fR, \fBEVP_PKEY_auth_encapsulate_init()\fR and
129 \&\fBEVP_PKEY_encapsulate()\fR return 1 for success and 0 or a negative value for
130 failure. In particular a return value of \-2 indicates the operation is not
131 supported by the public key algorithm.
132 .SH EXAMPLES
133 .IX Header "EXAMPLES"
134 Encapsulate an RSASVE key (for RSA keys).
135 .PP
136 .Vb 1
137 \& #include <openssl/evp.h>
138 \&
139 \& /*
140 \& * NB: assumes rsa_pub_key is an public key of another party.
141 \& */
142 \&
143 \& EVP_PKEY_CTX *ctx = NULL;
144 \& size_t secretlen = 0, outlen = 0;
145 \& unsigned char *out = NULL, *secret = NULL;
146 \&
147 \& ctx = EVP_PKEY_CTX_new_from_pkey(libctx, rsa_pub_key, NULL);
148 \& if (ctx == NULL)
149 \& /* Error */
150 \& if (EVP_PKEY_encapsulate_init(ctx, NULL) <= 0)
151 \& /* Error */
152 \&
153 \& /* Set the mode \- only \*(AqRSASVE\*(Aq is currently supported */
154 \& if (EVP_PKEY_CTX_set_kem_op(ctx, "RSASVE") <= 0)
155 \& /* Error */
156 \& /* Determine buffer length */
157 \& if (EVP_PKEY_encapsulate(ctx, NULL, &outlen, NULL, &secretlen) <= 0)
158 \& /* Error */
159 \&
160 \& out = OPENSSL_malloc(outlen);
161 \& secret = OPENSSL_malloc(secretlen);
162 \& if (out == NULL || secret == NULL)
163 \& /* malloc failure */
164 \&
165 \& /*
166 \& * The generated \*(Aqsecret\*(Aq can be used as key material.
167 \& * The encapsulated \*(Aqout\*(Aq can be sent to another party who can
168 \& * decapsulate it using their private key to retrieve the \*(Aqsecret\*(Aq.
169 \& */
170 \& if (EVP_PKEY_encapsulate(ctx, out, &outlen, secret, &secretlen) <= 0)
171 \& /* Error */
172 .Ve
173 .SH "SEE ALSO"
174 .IX Header "SEE ALSO"
175 \&\fBEVP_PKEY_CTX_new_from_pkey\fR\|(3),
176 \&\fBEVP_PKEY_decapsulate\fR\|(3),
177 \&\fBEVP_KEM\-RSA\fR\|(7),
178 \&\fBEVP_KEM\-X25519\fR\|(7),
179 \&\fBEVP_KEM\-EC\fR\|(7),
180 \&\fBEVP_KEM\-ML\-KEM\-512\fR\|(7),
181 \&\fBEVP_KEM\-ML\-KEM\-768\fR\|(7),
182 \&\fBEVP_KEM\-ML\-KEM\-1024\fR\|(7)
183 .SH HISTORY
184 .IX Header "HISTORY"
185 The functions \fBEVP_PKEY_encapsulate_init()\fR and \fBEVP_PKEY_encapsulate()\fR were
186 added in OpenSSL 3.0.
187 The function \fBEVP_PKEY_auth_encapsulate_init()\fR was added in OpenSSL 3.2.
188 .PP
189 Support for \fBML-KEM\fR was added in OpenSSL 3.5.
190 .SH COPYRIGHT
191 .IX Header "COPYRIGHT"
192 Copyright 2020\-2025 The OpenSSL Project Authors. All Rights Reserved.
193 .PP
194 Licensed under the Apache License 2.0 (the "License"). You may not use
195 this file except in compliance with the License. You can obtain a copy
196 in the file LICENSE in the source distribution or at
197 <https://www.openssl.org/source/license.html>.