113 The KEM identifier I<kem_id> is one of the following:
129 The KDF identifier I<kdf_id> is one of the following:
141 The AEAD identifier I<aead_id> is one of the following:
201 An I<OSSL_HPKE_CTX> with this role can be used with
207 An I<OSSL_HPKE_CTX> with this role can be used with OSSL_HPKE_decap(),
212 Calling a function with an incorrect role set on I<OSSL_HPKE_CTX> will result
219 implementation we apply a limit of 66 octets for the I<ikmlen>, I<psklen>, and
220 I<labellen> parameters, and for the length of the string I<pskid> for HPKE
221 functions below. The constant I<OSSL_HPKE_MAX_PARMLEN> is defined as the limit
226 I<OSSL_HPKE_MIN_PSKLEN> with a value of 32 for the minimum length of a
227 pre-shared key, passed in I<psklen>.
229 While RFC9180 also RECOMMENDS a 64 octet limit for the I<infolen> parameter,
231 enforce a limit of I<OSSL_HPKE_MAX_INFOLEN> with a value of 1024 as the limit
232 for the I<infolen> parameter.
237 subsequent HPKE operations, given a I<mode> (See L</HPKE Modes>), I<suite> (see
238 L</OSSL_HPKE_SUITE Identifiers>) and a I<role> (see L</HPKE Roles>). The
239 I<libctx> and I<propq> are used when fetching algorithms from providers and may
242 OSSL_HPKE_CTX_free() frees the I<ctx> B<OSSL_HPKE_CTX> that was created
251 (I<pub>) and to internally derive secrets. This produces the encapsulated public value
252 (I<enc>) to be sent to the recipient in whatever protocol is using HPKE. Having done the
254 OSSL_HPKE_seal() to encrypt plaintexts using the secret stored within I<ctx>.
256 OSSL_HPKE_encap() uses the HPKE context I<ctx>, the recipient public value
257 I<pub> of size I<publen>, and an optional I<info> parameter of size I<infolen>,
258 to produce the encapsulated public value I<enc>.
259 On input I<enclen> should contain the maximum size of the I<enc> buffer, and returns
260 the output size. An error will occur if the input I<enclen> is
262 I<info> may be used to bind other protocol or application artefacts such as identifiers.
263 Generally, the encapsulated public value I<enc> corresponds to a
268 OSSL_HPKE_seal() takes the B<OSSL_HPKE_CTX> context I<ctx>, the plaintext
269 buffer I<pt> of size I<ptlen> and optional additional authenticated data buffer
270 I<aad> of size I<aadlen>, and returns the ciphertext I<ct> of size I<ctlen>.
271 On input I<ctlen> should contain the maximum size of the I<ct> buffer, and returns
272 the output size. An error will occur if the input I<ctlen> is
298 on the HPKE I<suite> to be used. It returns a L<EVP_PKEY(3)> pointer
299 for the private value I<priv> and a encoded public key I<pub> of size I<publen>.
300 On input I<publen> should contain the maximum size of the I<pub> buffer, and
301 returns the output size. An error will occur if the input I<publen> is too small.
302 The I<libctx> and I<propq> are used when fetching algorithms from providers
306 OSSL_HPKE_keygen() also has an option to use that scheme, using the I<ikm>
307 parameter of size I<ikmlen>. If either I<ikm> is NULL or I<ikmlen> is zero,
308 then a randomly generated key for the relevant I<suite> will be produced.
309 If required I<ikmlen> should be greater than or equal to
313 produced by OSSL_HPKE_encap() (I<enc>) and the recipient's L<EVP_PKEY(3)>
314 pointer (I<prov>), and then re-generates the internal secret derived by the
315 sender. As before, an optional I<info> parameter allows binding that derived
319 OSSL_HPKE_open() is used by the recipient to decrypt the ciphertext I<ct> of
320 size I<ctlen> using the I<ctx> and additional authenticated data I<aad> of
321 size I<aadlen>, to produce the plaintext I<pt> of size I<ptlen>.
322 On input I<ptlen> should contain the maximum size of the I<pt> buffer, and
323 returns the output size. A I<pt> buffer that is the same size as the
324 I<ct> buffer will suffice - generally the plaintext output will be
326 An error will occur if the input I<ptlen> is too small.
339 supplied label I<label> of size I<labellen>, to produce a secret I<secret>
340 of size I<secretlen>. The sender must first call OSSL_HPKE_encap(), and the
345 I<OSSL_HPKE_AEAD_ID_EXPORTONLY> may be used as the B<OSSL_HPKE_SUITE> I<aead_id>
359 private I<priv> B<EVP_PKEY> key into the B<OSSL_HPKE_CTX> I<ctx> before calling
363 encoded pub key I<pub> of size I<publen> into the B<OSSL_HPKE_CTX> I<ctx> before
372 OSSL_HPKE_CTX_set1_psk() sets the PSK identifier I<pskid> string, and PSK buffer
373 I<psk> of size I<psklen> into the I<ctx>. If required this must be called
375 As per RFC9180, if required, both I<psk> and I<pskid> must be set to non-NULL values.
384 setting a deterministic input key material I<ikm> of size I<ikmlen> into
385 the B<OSSL_HPKE_CTX> I<ctx>.
388 I<ikmlen> should be greater than or equal to OSSL_HPKE_get_recommended_ikmelen().
401 used for such purposes with the I<seq> parameter value resetting the internal
406 open. (In other words, the first I<seq> increment defaults to zero.)
410 I<seq> output) that will be used in the next call to seal or open. That would
416 We therefore only support application control over I<seq> for decryption
419 For compatibility with other implementations these I<seq> increments are
420 represented as I<uint64_t>.
427 OSSL_HPKE_suite_check() checks if a specific B<OSSL_HPKE_SUITE> I<suite>
432 plaintext of length I<clearlen>.  (AEAD algorithms add a data integrity tag,
436 the encapsulated public value will be for a given HPKE I<suite>.
439 size (in bytes) for a given I<suite>. This is needed in cases where the same
441 I<ikmlen> should be at least this size.
444 given I<suite_in> value (or a random value if I<suite_in> is NULL) so that a
447 be supplied on input. The output I<enc> value will have an appropriate
448 length for I<suite_out> and a random value, and the I<ct> output will be
452 OSSL_HPKE_str2suite() maps input I<str> strings to an B<OSSL_HPKE_SUITE> object.
453 The input I<str> should be a comma-separated string with a KEM,

Last Index update Tue Oct 01 22:02:31 UTC 2024

Dedicated to & Maintained by Room-11