Debian Codegraph @

upstream/debian-unstable/man3/OSSL_HPKE_CTX_new.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 "OSSL_HPKE_CTX_NEW 3SSL"
58 .TH OSSL_HPKE_CTX_NEW 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 OSSL_HPKE_CTX_new, OSSL_HPKE_CTX_free,
65 OSSL_HPKE_encap, OSSL_HPKE_decap,
66 OSSL_HPKE_seal, OSSL_HPKE_open, OSSL_HPKE_export,
67 OSSL_HPKE_suite_check, OSSL_HPKE_str2suite,
68 OSSL_HPKE_keygen, OSSL_HPKE_get_grease_value,
69 OSSL_HPKE_get_ciphertext_size, OSSL_HPKE_get_public_encap_size,
70 OSSL_HPKE_get_recommended_ikmelen,
71 OSSL_HPKE_CTX_set1_psk, OSSL_HPKE_CTX_set1_ikme,
72 OSSL_HPKE_CTX_set1_authpriv, OSSL_HPKE_CTX_set1_authpub,
73 OSSL_HPKE_CTX_get_seq, OSSL_HPKE_CTX_set_seq
74 \&\- Hybrid Public Key Encryption (HPKE) functions
75 .SH SYNOPSIS
76 .IX Header "SYNOPSIS"
77 .Vb 1
78 \& #include <openssl/hpke.h>
79 \&
80 \& typedef struct {
81 \& uint16_t kem_id;
82 \& uint16_t kdf_id;
83 \& uint16_t aead_id;
84 \& } OSSL_HPKE_SUITE;
85 \&
86 \& OSSL_HPKE_CTX *OSSL_HPKE_CTX_new(int mode, OSSL_HPKE_SUITE suite, int role,
87 \& OSSL_LIB_CTX *libctx, const char *propq);
88 \& void OSSL_HPKE_CTX_free(OSSL_HPKE_CTX *ctx);
89 \&
90 \& int OSSL_HPKE_encap(OSSL_HPKE_CTX *ctx,
91 \& unsigned char *enc, size_t *enclen,
92 \& const unsigned char *pub, size_t publen,
93 \& const unsigned char *info, size_t infolen);
94 \& int OSSL_HPKE_seal(OSSL_HPKE_CTX *ctx,
95 \& unsigned char *ct, size_t *ctlen,
96 \& const unsigned char *aad, size_t aadlen,
97 \& const unsigned char *pt, size_t ptlen);
98 \&
99 \& int OSSL_HPKE_keygen(OSSL_HPKE_SUITE suite,
100 \& unsigned char *pub, size_t *publen, EVP_PKEY **priv,
101 \& const unsigned char *ikm, size_t ikmlen,
102 \& OSSL_LIB_CTX *libctx, const char *propq);
103 \& int OSSL_HPKE_decap(OSSL_HPKE_CTX *ctx,
104 \& const unsigned char *enc, size_t enclen,
105 \& EVP_PKEY *recippriv,
106 \& const unsigned char *info, size_t infolen);
107 \& int OSSL_HPKE_open(OSSL_HPKE_CTX *ctx,
108 \& unsigned char *pt, size_t *ptlen,
109 \& const unsigned char *aad, size_t aadlen,
110 \& const unsigned char *ct, size_t ctlen);
111 \&
112 \& int OSSL_HPKE_export(OSSL_HPKE_CTX *ctx,
113 \& unsigned char *secret, size_t secretlen,
114 \& const unsigned char *label, size_t labellen);
115 \&
116 \& int OSSL_HPKE_CTX_set1_authpriv(OSSL_HPKE_CTX *ctx, EVP_PKEY *priv);
117 \& int OSSL_HPKE_CTX_set1_authpub(OSSL_HPKE_CTX *ctx,
118 \& unsigned char *pub, size_t publen);
119 \& int OSSL_HPKE_CTX_set1_psk(OSSL_HPKE_CTX *ctx,
120 \& const char *pskid,
121 \& const unsigned char *psk, size_t psklen);
122 \&
123 \& int OSSL_HPKE_CTX_get_seq(OSSL_HPKE_CTX *ctx, uint64_t *seq);
124 \& int OSSL_HPKE_CTX_set_seq(OSSL_HPKE_CTX *ctx, uint64_t seq);
125 \&
126 \& int OSSL_HPKE_CTX_set1_ikme(OSSL_HPKE_CTX *ctx,
127 \& const unsigned char *ikme, size_t ikmelen);
128 \&
129 \& int OSSL_HPKE_suite_check(OSSL_HPKE_SUITE suite);
130 \& int OSSL_HPKE_get_grease_value(const OSSL_HPKE_SUITE *suite_in,
131 \& OSSL_HPKE_SUITE *suite,
132 \& unsigned char *enc, size_t *enclen,
133 \& unsigned char *ct, size_t ctlen,
134 \& OSSL_LIB_CTX *libctx, const char *propq);
135 \&
136 \& int OSSL_HPKE_str2suite(const char *str, OSSL_HPKE_SUITE *suite);
137 \& size_t OSSL_HPKE_get_ciphertext_size(OSSL_HPKE_SUITE suite, size_t clearlen);
138 \& size_t OSSL_HPKE_get_public_encap_size(OSSL_HPKE_SUITE suite);
139 \& size_t OSSL_HPKE_get_recommended_ikmelen(OSSL_HPKE_SUITE suite);
140 .Ve
141 .SH DESCRIPTION
142 .IX Header "DESCRIPTION"
143 These functions provide an API for using the form of Hybrid Public Key
144 Encryption (HPKE) defined in RFC9180. Understanding the HPKE specification
145 is likely required before using these APIs. HPKE is used by various
146 other IETF specifications, including the TLS Encrypted Client
147 Hello (ECH) specification and others.
148 .PP
149 HPKE is a standardised, highly flexible construct for encrypting "to" a public
150 key that supports combinations of a key encapsulation method (KEM), a key
151 derivation function (KDF) and an authenticated encryption with additional data
152 (AEAD) algorithm, with optional sender authentication.
153 .PP
154 The sender and a receiver here will generally be using some application or
155 protocol making use of HPKE. For example, with ECH,
156 the sender will be a browser and the receiver will be a web server.
157 .SS "Data Structures"
158 .IX Subsection "Data Structures"
159 \&\fBOSSL_HPKE_SUITE\fR is a structure that holds identifiers for the algorithms
160 used for KEM, KDF and AEAD operations.
161 .PP
162 \&\fBOSSL_HPKE_CTX\fR is a context that maintains internal state as HPKE
163 operations are carried out. Separate \fBOSSL_HPKE_CTX\fR objects must be used for
164 the sender and receiver. Attempting to use a single context for both will
165 result in errors.
166 .SS "OSSL_HPKE_SUITE Identifiers"
167 .IX Subsection "OSSL_HPKE_SUITE Identifiers"
168 The identifiers used by \fBOSSL_HPKE_SUITE\fR are:
169 .PP
170 The KEM identifier \fIkem_id\fR is one of the following:
171 .IP "0x10 \fBOSSL_HPKE_KEM_ID_P256\fR" 4
172 .IX Item "0x10 OSSL_HPKE_KEM_ID_P256"
173 .PD 0
174 .IP "0x11 \fBOSSL_HPKE_KEM_ID_P384\fR" 4
175 .IX Item "0x11 OSSL_HPKE_KEM_ID_P384"
176 .IP "0x12 \fBOSSL_HPKE_KEM_ID_P521\fR" 4
177 .IX Item "0x12 OSSL_HPKE_KEM_ID_P521"
178 .IP "0x20 \fBOSSL_HPKE_KEM_ID_X25519\fR" 4
179 .IX Item "0x20 OSSL_HPKE_KEM_ID_X25519"
180 .IP "0x21 \fBOSSL_HPKE_KEM_ID_X448\fR" 4
181 .IX Item "0x21 OSSL_HPKE_KEM_ID_X448"
182 .PD
183 .PP
184 The KDF identifier \fIkdf_id\fR is one of the following:
185 .IP "0x01 \fBOSSL_HPKE_KDF_ID_HKDF_SHA256\fR" 4
186 .IX Item "0x01 OSSL_HPKE_KDF_ID_HKDF_SHA256"
187 .PD 0
188 .IP "0x02 \fBOSSL_HPKE_KDF_ID_HKDF_SHA384\fR" 4
189 .IX Item "0x02 OSSL_HPKE_KDF_ID_HKDF_SHA384"
190 .IP "0x03 \fBOSSL_HPKE_KDF_ID_HKDF_SHA512\fR" 4
191 .IX Item "0x03 OSSL_HPKE_KDF_ID_HKDF_SHA512"
192 .PD
193 .PP
194 The AEAD identifier \fIaead_id\fR is one of the following:
195 .IP "0x01 \fBOSSL_HPKE_AEAD_ID_AES_GCM_128\fR" 4
196 .IX Item "0x01 OSSL_HPKE_AEAD_ID_AES_GCM_128"
197 .PD 0
198 .IP "0x02 \fBOSSL_HPKE_AEAD_ID_AES_GCM_256\fR" 4
199 .IX Item "0x02 OSSL_HPKE_AEAD_ID_AES_GCM_256"
200 .IP "0x03 \fBOSSL_HPKE_AEAD_ID_CHACHA_POLY1305\fR" 4
201 .IX Item "0x03 OSSL_HPKE_AEAD_ID_CHACHA_POLY1305"
202 .IP "0xFFFF \fBOSSL_HPKE_AEAD_ID_EXPORTONLY\fR" 4
203 .IX Item "0xFFFF OSSL_HPKE_AEAD_ID_EXPORTONLY"
204 .PD
205 The last identifier above indicates that AEAD operations are not needed.
206 \&\fBOSSL_HPKE_export()\fR can be used, but \fBOSSL_HPKE_open()\fR and \fBOSSL_HPKE_seal()\fR will
207 return an error if called with a context using that AEAD identifier.
208 .SS "HPKE Modes"
209 .IX Subsection "HPKE Modes"
210 HPKE supports the following variants of Authentication using a mode Identifier:
211 .IP "\fBOSSL_HPKE_MODE_BASE\fR, 0x00" 4
212 .IX Item "OSSL_HPKE_MODE_BASE, 0x00"
213 Authentication is not used.
214 .IP "\fBOSSL_HPKE_MODE_PSK\fR, 0x01" 4
215 .IX Item "OSSL_HPKE_MODE_PSK, 0x01"
216 Authenticates possession of a pre-shared key (PSK).
217 .IP "\fBOSSL_HPKE_MODE_AUTH\fR, 0x02" 4
218 .IX Item "OSSL_HPKE_MODE_AUTH, 0x02"
219 Authenticates possession of a KEM-based sender private key.
220 .IP "\fBOSSL_HPKE_MODE_PSKAUTH\fR, 0x03" 4
221 .IX Item "OSSL_HPKE_MODE_PSKAUTH, 0x03"
222 A combination of \fBOSSL_HPKE_MODE_PSK\fR and \fBOSSL_HPKE_MODE_AUTH\fR.
223 Both the PSK and the senders authentication public/private must be
224 supplied before the encapsulation/decapsulation operation will work.
225 .PP
226 For further information related to authentication see "Pre-Shared Key HPKE
227 modes" and "Sender-authenticated HPKE Modes".
228 .SS "HPKE Roles"
229 .IX Subsection "HPKE Roles"
230 HPKE contexts have a role \- either sender or receiver. This is used
231 to control which functions can be called and so that senders do not
232 reuse a key and nonce with different plaintexts.
233 .PP
234 \&\fBOSSL_HPKE_CTX_free()\fR, \fBOSSL_HPKE_export()\fR, \fBOSSL_HPKE_CTX_set1_psk()\fR,
235 and \fBOSSL_HPKE_CTX_get_seq()\fR can be called regardless of role.
236 .IP "\fBOSSL_HPKE_ROLE_SENDER\fR, 0" 4
237 .IX Item "OSSL_HPKE_ROLE_SENDER, 0"
238 An \fIOSSL_HPKE_CTX\fR with this role can be used with
239 \&\fBOSSL_HPKE_encap()\fR, \fBOSSL_HPKE_seal()\fR, \fBOSSL_HPKE_CTX_set1_ikme()\fR and
240 \&\fBOSSL_HPKE_CTX_set1_authpriv()\fR.
241 .IP "\fBOSSL_HPKE_ROLE_RECEIVER\fR, 1" 4
242 .IX Item "OSSL_HPKE_ROLE_RECEIVER, 1"
243 An \fIOSSL_HPKE_CTX\fR with this role can be used with \fBOSSL_HPKE_decap()\fR,
244 \&\fBOSSL_HPKE_open()\fR, \fBOSSL_HPKE_CTX_set1_authpub()\fR and \fBOSSL_HPKE_CTX_set_seq()\fR.
245 .PP
246 Calling a function with an incorrect role set on \fIOSSL_HPKE_CTX\fR will result
247 in an error.
248 .SS "Parameter Size Limits"
249 .IX Subsection "Parameter Size Limits"
250 In order to improve interoperability, RFC9180, section 7.2.1 suggests a
251 RECOMMENDED maximum size of 64 octets for various input parameters. In this
252 implementation we apply a limit of 66 octets for the \fIikmlen\fR, \fIpsklen\fR, and
253 \&\fIlabellen\fR parameters, and for the length of the string \fIpskid\fR for HPKE
254 functions below. The constant \fIOSSL_HPKE_MAX_PARMLEN\fR is defined as the limit
255 of this value. (We chose 66 octets so that we can validate all the test
256 vectors present in RFC9180, Appendix A.)
257 .PP
258 In accordance with RFC9180, section 9.5, we define a constant
259 \&\fIOSSL_HPKE_MIN_PSKLEN\fR with a value of 32 for the minimum length of a
260 pre-shared key, passed in \fIpsklen\fR.
261 .PP
262 While RFC9180 also RECOMMENDS a 64 octet limit for the \fIinfolen\fR parameter,
263 that is not sufficient for TLS Encrypted ClientHello (ECH) processing, so we
264 enforce a limit of \fIOSSL_HPKE_MAX_INFOLEN\fR with a value of 1024 as the limit
265 for the \fIinfolen\fR parameter.
266 .SS "Context Construct/Free"
267 .IX Subsection "Context Construct/Free"
268 \&\fBOSSL_HPKE_CTX_new()\fR creates a \fBOSSL_HPKE_CTX\fR context object used for
269 subsequent HPKE operations, given a \fImode\fR (See "HPKE Modes"), \fIsuite\fR (see
270 "OSSL_HPKE_SUITE Identifiers") and a \fIrole\fR (see "HPKE Roles"). The
271 \&\fIlibctx\fR and \fIpropq\fR are used when fetching algorithms from providers and may
272 be set to NULL.
273 .PP
274 \&\fBOSSL_HPKE_CTX_free()\fR frees the \fIctx\fR \fBOSSL_HPKE_CTX\fR that was created
275 previously by a call to \fBOSSL_HPKE_CTX_new()\fR. If the argument to
276 \&\fBOSSL_HPKE_CTX_free()\fR is NULL, nothing is done.
277 .SS "Sender APIs"
278 .IX Subsection "Sender APIs"
279 A sender's goal is to use HPKE to encrypt using a public key, via use of a
280 KEM, then a KDF and finally an AEAD. The first step is to encapsulate (using
281 \&\fBOSSL_HPKE_encap()\fR) the sender's public value using the recipient's public key,
282 (\fIpub\fR) and to internally derive secrets. This produces the encapsulated public value
283 (\fIenc\fR) to be sent to the recipient in whatever protocol is using HPKE. Having done the
284 encapsulation step, the sender can then make one or more calls to
285 \&\fBOSSL_HPKE_seal()\fR to encrypt plaintexts using the secret stored within \fIctx\fR.
286 .PP
287 \&\fBOSSL_HPKE_encap()\fR uses the HPKE context \fIctx\fR, the recipient public value
288 \&\fIpub\fR of size \fIpublen\fR, and an optional \fIinfo\fR parameter of size \fIinfolen\fR,
289 to produce the encapsulated public value \fIenc\fR.
290 On input \fIenclen\fR should contain the maximum size of the \fIenc\fR buffer, and returns
291 the output size. An error will occur if the input \fIenclen\fR is
292 smaller than the value returned from \fBOSSL_HPKE_get_public_encap_size()\fR.
293 \&\fIinfo\fR may be used to bind other protocol or application artefacts such as identifiers.
294 Generally, the encapsulated public value \fIenc\fR corresponds to a
295 single-use ephemeral private value created as part of the encapsulation
296 process. Only a single call to \fBOSSL_HPKE_encap()\fR is allowed for a given
297 \&\fBOSSL_HPKE_CTX\fR.
298 .PP
299 \&\fBOSSL_HPKE_seal()\fR takes the \fBOSSL_HPKE_CTX\fR context \fIctx\fR, the plaintext
300 buffer \fIpt\fR of size \fIptlen\fR and optional additional authenticated data buffer
301 \&\fIaad\fR of size \fIaadlen\fR, and returns the ciphertext \fIct\fR of size \fIctlen\fR.
302 On input \fIctlen\fR should contain the maximum size of the \fIct\fR buffer, and returns
303 the output size. An error will occur if the input \fIctlen\fR is
304 smaller than the value returned from \fBOSSL_HPKE_get_public_encap_size()\fR.
305 .PP
306 \&\fBOSSL_HPKE_encap()\fR must be called before the \fBOSSL_HPKE_seal()\fR. \fBOSSL_HPKE_seal()\fR
307 may be called multiple times, with an internal "nonce" being incremented by one
308 after each call.
309 .SS "Recipient APIs"
310 .IX Subsection "Recipient APIs"
311 Recipients using HPKE require a typically less ephemeral private value so that
312 the public value can be distributed to potential senders via whatever protocol
313 is using HPKE. For this reason, recipients will generally first generate a key
314 pair and will need to manage their private key value using standard mechanisms
315 outside the scope of this API. Private keys use normal \fBEVP_PKEY\fR\|(3) pointers
316 so normal private key management mechanisms can be used for the relevant
317 values.
318 .PP
319 In order to enable encapsulation, the recipient needs to make it's public value
320 available to the sender. There is no generic HPKE format defined for that \- the
321 relevant formatting is intended to be defined by the application/protocols that
322 makes use of HPKE. ECH for example defines an ECHConfig data structure that
323 combines the public value with other ECH data items. Normal library functions
324 must therefore be used to extract the public value in the required format based
325 on the \fBEVP_PKEY\fR\|(3) for the private value.
326 .PP
327 \&\fBOSSL_HPKE_keygen()\fR provides a way for recipients to generate a key pair based
328 on the HPKE \fIsuite\fR to be used. It returns a \fBEVP_PKEY\fR\|(3) pointer
329 for the private value \fIpriv\fR and a encoded public key \fIpub\fR of size \fIpublen\fR.
330 On input \fIpublen\fR should contain the maximum size of the \fIpub\fR buffer, and
331 returns the output size. An error will occur if the input \fIpublen\fR is too small.
332 The \fIlibctx\fR and \fIpropq\fR are used when fetching algorithms from providers
333 and may be set to NULL.
334 The HPKE specification also defines a deterministic key generation scheme where
335 the private value is derived from initial keying material (IKM), so
336 \&\fBOSSL_HPKE_keygen()\fR also has an option to use that scheme, using the \fIikm\fR
337 parameter of size \fIikmlen\fR. If either \fIikm\fR is NULL or \fIikmlen\fR is zero,
338 then a randomly generated key for the relevant \fIsuite\fR will be produced.
339 If required \fIikmlen\fR should be greater than or equal to
340 \&\fBOSSL_HPKE_get_recommended_ikmelen()\fR.
341 .PP
342 \&\fBOSSL_HPKE_decap()\fR takes as input the sender's encapsulated public value
343 produced by \fBOSSL_HPKE_encap()\fR (\fIenc\fR) and the recipient's \fBEVP_PKEY\fR\|(3)
344 pointer (\fIprov\fR), and then re-generates the internal secret derived by the
345 sender. As before, an optional \fIinfo\fR parameter allows binding that derived
346 secret to other application/protocol artefacts. Only a single call to
347 \&\fBOSSL_HPKE_decap()\fR is allowed for a given \fBOSSL_HPKE_CTX\fR.
348 .PP
349 \&\fBOSSL_HPKE_open()\fR is used by the recipient to decrypt the ciphertext \fIct\fR of
350 size \fIctlen\fR using the \fIctx\fR and additional authenticated data \fIaad\fR of
351 size \fIaadlen\fR, to produce the plaintext \fIpt\fR of size \fIptlen\fR.
352 On input \fIptlen\fR should contain the maximum size of the \fIpt\fR buffer, and
353 returns the output size. A \fIpt\fR buffer that is the same size as the
354 \&\fIct\fR buffer will suffice \- generally the plaintext output will be
355 a little smaller than the ciphertext input.
356 An error will occur if the input \fIptlen\fR is too small.
357 \&\fBOSSL_HPKE_open()\fR may be called multiple times, but as with \fBOSSL_HPKE_seal()\fR
358 there is an internally incrementing nonce value so ciphertexts need to be
359 presented in the same order as used by the \fBOSSL_HPKE_seal()\fR.
360 See "Re-sequencing" if you need to process multiple ciphertexts in a
361 different order.
362 .SS "Exporting Secrets"
363 .IX Subsection "Exporting Secrets"
364 HPKE defines a way to produce exported secrets for use by the
365 application.
366 .PP
367 \&\fBOSSL_HPKE_export()\fR takes as input the \fBOSSL_HPKE_CTX\fR, and an application
368 supplied label \fIlabel\fR of size \fIlabellen\fR, to produce a secret \fIsecret\fR
369 of size \fIsecretlen\fR. The sender must first call \fBOSSL_HPKE_encap()\fR, and the
370 receiver must call \fBOSSL_HPKE_decap()\fR in order to derive the same shared secret.
371 .PP
372 Multiple calls to \fBOSSL_HPKE_export()\fR with the same inputs will produce the
373 same secret.
374 \&\fIOSSL_HPKE_AEAD_ID_EXPORTONLY\fR may be used as the \fBOSSL_HPKE_SUITE\fR \fIaead_id\fR
375 that is passed to \fBOSSL_HPKE_CTX_new()\fR if the user needs to produce a shared
376 secret, but does not wish to perform HPKE encryption.
377 .SS "Sender-authenticated HPKE Modes"
378 .IX Subsection "Sender-authenticated HPKE Modes"
379 HPKE defines modes that support KEM-based sender-authentication
380 \&\fBOSSL_HPKE_MODE_AUTH\fR and \fBOSSL_HPKE_MODE_PSKAUTH\fR. This works by binding
381 the sender's authentication private/public values into the encapsulation and
382 decapsulation operations. The key used for such modes must also use the same
383 KEM as used for the overall exchange. \fBOSSL_HPKE_keygen()\fR can be used to
384 generate the private value required.
385 .PP
386 \&\fBOSSL_HPKE_CTX_set1_authpriv()\fR can be used by the sender to set the senders
387 private \fIpriv\fR \fBEVP_PKEY\fR key into the \fBOSSL_HPKE_CTX\fR \fIctx\fR before calling
388 \&\fBOSSL_HPKE_encap()\fR.
389 .PP
390 \&\fBOSSL_HPKE_CTX_set1_authpub()\fR can be used by the receiver to set the senders
391 encoded pub key \fIpub\fR of size \fIpublen\fR into the \fBOSSL_HPKE_CTX\fR \fIctx\fR before
392 calling \fBOSSL_HPKE_decap()\fR.
393 .SS "Pre-Shared Key HPKE modes"
394 .IX Subsection "Pre-Shared Key HPKE modes"
395 HPKE also defines a symmetric equivalent to the authentication described above
396 using a pre-shared key (PSK) and a PSK identifier. PSKs can be used with the
397 \&\fBOSSL_HPKE_MODE_PSK\fR and \fBOSSL_HPKE_MODE_PSKAUTH\fR modes.
398 .PP
399 \&\fBOSSL_HPKE_CTX_set1_psk()\fR sets the PSK identifier \fIpskid\fR string, and PSK buffer
400 \&\fIpsk\fR of size \fIpsklen\fR into the \fIctx\fR. If required this must be called
401 before \fBOSSL_HPKE_encap()\fR or \fBOSSL_HPKE_decap()\fR.
402 As per RFC9180, if required, both \fIpsk\fR and \fIpskid\fR must be set to non-NULL values.
403 As PSKs are symmetric the same calls must happen on both sender and receiver
404 sides.
405 .SS "Deterministic key generation for senders"
406 .IX Subsection "Deterministic key generation for senders"
407 Normally the senders ephemeral private key is generated randomly inside
408 \&\fBOSSL_HPKE_encap()\fR and remains secret.
409 \&\fBOSSL_HPKE_CTX_set1_ikme()\fR allows the user to override this behaviour by
410 setting a deterministic input key material \fIikm\fR of size \fIikmlen\fR into
411 the \fBOSSL_HPKE_CTX\fR \fIctx\fR.
412 If required \fBOSSL_HPKE_CTX_set1_ikme()\fR can optionally be called before
413 \&\fBOSSL_HPKE_encap()\fR.
414 \&\fIikmlen\fR should be greater than or equal to \fBOSSL_HPKE_get_recommended_ikmelen()\fR.
415 .PP
416 It is generally undesirable to use \fBOSSL_HPKE_CTX_set1_ikme()\fR, since it
417 exposes the relevant secret to the application rather then preserving it
418 within the library, and is more likely to result in use of predictable values
419 or values that leak.
420 .SS Re-sequencing
421 .IX Subsection "Re-sequencing"
422 Some protocols may have to deal with packet loss while still being able to
423 decrypt arriving packets later. We provide a way to set the increment used for
424 the nonce to the next subsequent call to \fBOSSL_HPKE_open()\fR (but not to
425 \&\fBOSSL_HPKE_seal()\fR as explained below). The \fBOSSL_HPKE_CTX_set_seq()\fR API can be
426 used for such purposes with the \fIseq\fR parameter value resetting the internal
427 nonce increment to be used for the next call.
428 .PP
429 A baseline nonce value is established based on the encapsulation or
430 decapsulation operation and is then incremented by 1 for each call to seal or
431 open. (In other words, the first \fIseq\fR increment defaults to zero.)
432 .PP
433 If a caller needs to determine how many calls to seal or open have been made
434 the \fBOSSL_HPKE_CTX_get_seq()\fR API can be used to retrieve the increment (in the
435 \&\fIseq\fR output) that will be used in the next call to seal or open. That would
436 return 0 before the first call a sender made to \fBOSSL_HPKE_seal()\fR and 1 after
437 that first call.
438 .PP
439 Note that reuse of the same nonce and key with different plaintexts would
440 be very dangerous and could lead to loss of confidentiality and integrity.
441 We therefore only support application control over \fIseq\fR for decryption
442 (i.e. \fBOSSL_HPKE_open()\fR) operations.
443 .PP
444 For compatibility with other implementations these \fIseq\fR increments are
445 represented as \fIuint64_t\fR.
446 .SS "Protocol Convenience Functions"
447 .IX Subsection "Protocol Convenience Functions"
448 Additional convenience APIs allow the caller to access internal details of
449 local HPKE support and/or algorithms, such as parameter lengths.
450 .PP
451 \&\fBOSSL_HPKE_suite_check()\fR checks if a specific \fBOSSL_HPKE_SUITE\fR \fIsuite\fR
452 is supported locally.
453 .PP
454 To assist with memory allocation, \fBOSSL_HPKE_get_ciphertext_size()\fR provides a
455 way for the caller to know by how much ciphertext will be longer than a
456 plaintext of length \fIclearlen\fR. (AEAD algorithms add a data integrity tag,
457 so there is a small amount of ciphertext expansion.)
458 .PP
459 \&\fBOSSL_HPKE_get_public_encap_size()\fR provides a way for senders to know how big
460 the encapsulated public value will be for a given HPKE \fIsuite\fR.
461 .PP
462 \&\fBOSSL_HPKE_get_recommended_ikmelen()\fR returns the recommended Input Key Material
463 size (in bytes) for a given \fIsuite\fR. This is needed in cases where the same
464 public value needs to be regenerated by a sender before calling \fBOSSL_HPKE_seal()\fR.
465 \&\fIikmlen\fR should be at least this size.
466 .PP
467 \&\fBOSSL_HPKE_get_grease_value()\fR produces values of the appropriate length for a
468 given \fIsuite_in\fR value (or a random value if \fIsuite_in\fR is NULL) so that a
469 protocol using HPKE can send so-called GREASE (see RFC8701) values that are
470 harder to distinguish from a real use of HPKE. The buffer sizes should
471 be supplied on input. The output \fIenc\fR value will have an appropriate
472 length for \fIsuite_out\fR and a random value, and the \fIct\fR output will be
473 a random value. The relevant sizes for buffers can be found using
474 \&\fBOSSL_HPKE_get_ciphertext_size()\fR and \fBOSSL_HPKE_get_public_encap_size()\fR.
475 .PP
476 \&\fBOSSL_HPKE_str2suite()\fR maps input \fIstr\fR strings to an \fBOSSL_HPKE_SUITE\fR object.
477 The input \fIstr\fR should be a comma-separated string with a KEM,
478 KDF and AEAD name in that order, for example "x25519,hkdf\-sha256,aes\-128\-gcm".
479 This can be used by command line tools that accept string form names for HPKE
480 codepoints. Valid (case-insensitive) names are:
481 "p\-256", "p\-384", "p\-521", "x25519" and "x448" for KEM,
482 "hkdf\-sha256", "hkdf\-sha384" and "hkdf\-sha512" for KDF, and
483 "aes\-128\-gcm", "aes\-256\-gcm", "chacha20\-poly1305" and "exporter" for AEAD.
484 String variants of the numbers listed in "OSSL_HPKE_SUITE Identifiers"
485 can also be used.
486 .SH "RETURN VALUES"
487 .IX Header "RETURN VALUES"
488 \&\fBOSSL_HPKE_CTX_new()\fR returns an OSSL_HPKE_CTX pointer or NULL on error.
489 .PP
490 \&\fBOSSL_HPKE_get_ciphertext_size()\fR, \fBOSSL_HPKE_get_public_encap_size()\fR,
491 \&\fBOSSL_HPKE_get_recommended_ikmelen()\fR all return a size_t with the
492 relevant value or zero on error.
493 .PP
494 All other functions return 1 for success or zero for error.
495 .SH EXAMPLES
496 .IX Header "EXAMPLES"
497 This example demonstrates a minimal round-trip using HPKE.
498 .PP
499 .Vb 4
500 \& #include <stddef.h>
501 \& #include <string.h>
502 \& #include <openssl/hpke.h>
503 \& #include <openssl/evp.h>
504 \&
505 \& /*
506 \& * this is big enough for this example, real code would need different
507 \& * handling
508 \& */
509 \& #define LBUFSIZE 48
510 \&
511 \& /* Do a round\-trip, generating a key, encrypting and decrypting */
512 \& int main(int argc, char **argv)
513 \& {
514 \& int ok = 0;
515 \& int hpke_mode = OSSL_HPKE_MODE_BASE;
516 \& OSSL_HPKE_SUITE hpke_suite = OSSL_HPKE_SUITE_DEFAULT;
517 \& OSSL_HPKE_CTX *sctx = NULL, *rctx = NULL;
518 \& EVP_PKEY *priv = NULL;
519 \& unsigned char pub[LBUFSIZE];
520 \& size_t publen = sizeof(pub);
521 \& unsigned char enc[LBUFSIZE];
522 \& size_t enclen = sizeof(enc);
523 \& unsigned char ct[LBUFSIZE];
524 \& size_t ctlen = sizeof(ct);
525 \& unsigned char clear[LBUFSIZE];
526 \& size_t clearlen = sizeof(clear);
527 \& const unsigned char *pt = "a message not in a bottle";
528 \& size_t ptlen = strlen((char *)pt);
529 \& const unsigned char *info = "Some info";
530 \& size_t infolen = strlen((char *)info);
531 \& unsigned char aad[] = { 1, 2, 3, 4, 5, 6, 7, 8 };
532 \& size_t aadlen = sizeof(aad);
533 \&
534 \& /*
535 \& * Generate receiver\*(Aqs key pair.
536 \& * The receiver gives this public key to the sender.
537 \& */
538 \& if (OSSL_HPKE_keygen(hpke_suite, pub, &publen, &priv,
539 \& NULL, 0, NULL, NULL) != 1)
540 \& goto err;
541 \&
542 \& /* sender\*(Aqs actions \- encrypt data using the receivers public key */
543 \& if ((sctx = OSSL_HPKE_CTX_new(hpke_mode, hpke_suite,
544 \& OSSL_HPKE_ROLE_SENDER,
545 \& NULL, NULL)) == NULL)
546 \& goto err;
547 \& if (OSSL_HPKE_encap(sctx, enc, &enclen, pub, publen, info, infolen) != 1)
548 \& goto err;
549 \& if (OSSL_HPKE_seal(sctx, ct, &ctlen, aad, aadlen, pt, ptlen) != 1)
550 \& goto err;
551 \&
552 \& /* receiver\*(Aqs actions \- decrypt data using the receivers private key */
553 \& if ((rctx = OSSL_HPKE_CTX_new(hpke_mode, hpke_suite,
554 \& OSSL_HPKE_ROLE_RECEIVER,
555 \& NULL, NULL)) == NULL)
556 \& goto err;
557 \& if (OSSL_HPKE_decap(rctx, enc, enclen, priv, info, infolen) != 1)
558 \& goto err;
559 \& if (OSSL_HPKE_open(rctx, clear, &clearlen, aad, aadlen, ct, ctlen) != 1)
560 \& goto err;
561 \& ok = 1;
562 \& err:
563 \& /* clean up */
564 \& printf(ok ? "All Good!\en" : "Error!\en");
565 \& OSSL_HPKE_CTX_free(rctx);
566 \& OSSL_HPKE_CTX_free(sctx);
567 \& EVP_PKEY_free(priv);
568 \& return 0;
569 \& }
570 .Ve
571 .SH WARNINGS
572 .IX Header "WARNINGS"
573 Note that the \fBOSSL_HPKE_CTX_set_seq()\fR API could be dangerous \- if used with GCM
574 that could lead to nonce-reuse, which is a known danger. So avoid that
575 entirely, or be very very careful when using that API.
576 .PP
577 Use of an IKM value for deterministic key generation (via
578 \&\fBOSSL_HPKE_CTX_set1_ikme()\fR or \fBOSSL_HPKE_keygen()\fR) creates the potential for
579 leaking keys (or IKM values). Only use that if really needed and if you
580 understand how keys or IKM values could be abused.
581 .SH "SEE ALSO"
582 .IX Header "SEE ALSO"
583 The RFC9180 specification: https://datatracker.ietf.org/doc/rfc9180/
584 .SH HISTORY
585 .IX Header "HISTORY"
586 This functionality described here was added in OpenSSL 3.2.
587 .SH COPYRIGHT
588 .IX Header "COPYRIGHT"
589 Copyright 2022\-2026 The OpenSSL Project Authors. All Rights Reserved.
590 .PP
591 Licensed under the Apache License 2.0 (the "License"). You may not use
592 this file except in compliance with the License. You can obtain a copy
593 in the file LICENSE in the source distribution or at
594 <https://www.openssl.org/source/license.html>.