diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/OSSL_HPKE_CTX_new.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/OSSL_HPKE_CTX_new.3 | 63 |
1 files changed, 33 insertions, 30 deletions
diff --git a/secure/lib/libcrypto/man/man3/OSSL_HPKE_CTX_new.3 b/secure/lib/libcrypto/man/man3/OSSL_HPKE_CTX_new.3 index a40dcee5d5fb..3900a564e61c 100644 --- a/secure/lib/libcrypto/man/man3/OSSL_HPKE_CTX_new.3 +++ b/secure/lib/libcrypto/man/man3/OSSL_HPKE_CTX_new.3 @@ -1,5 +1,5 @@ .\" -*- mode: troff; coding: utf-8 -*- -.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== @@ -52,10 +52,13 @@ . \} .\} .rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l .\" ======================================================================== .\" .IX Title "OSSL_HPKE_CTX_NEW 3ossl" -.TH OSSL_HPKE_CTX_NEW 3ossl 2025-09-30 3.5.4 OpenSSL +.TH OSSL_HPKE_CTX_NEW 3ossl 2026-04-07 3.5.6 OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -213,18 +216,18 @@ HPKE supports the following variants of Authentication using a mode Identifier: Authentication is not used. .IP "\fBOSSL_HPKE_MODE_PSK\fR, 0x01" 4 .IX Item "OSSL_HPKE_MODE_PSK, 0x01" -Authenticates possession of a pre-shared key (PSK). +Authenticates possession of a pre\-shared key (PSK). .IP "\fBOSSL_HPKE_MODE_AUTH\fR, 0x02" 4 .IX Item "OSSL_HPKE_MODE_AUTH, 0x02" -Authenticates possession of a KEM-based sender private key. +Authenticates possession of a KEM\-based sender private key. .IP "\fBOSSL_HPKE_MODE_PSKAUTH\fR, 0x03" 4 .IX Item "OSSL_HPKE_MODE_PSKAUTH, 0x03" A combination of \fBOSSL_HPKE_MODE_PSK\fR and \fBOSSL_HPKE_MODE_AUTH\fR. Both the PSK and the senders authentication public/private must be supplied before the encapsulation/decapsulation operation will work. .PP -For further information related to authentication see "Pre-Shared Key HPKE -modes" and "Sender-authenticated HPKE Modes". +For further information related to authentication see "Pre\-Shared Key HPKE +modes" and "Sender\-authenticated HPKE Modes". .SS "HPKE Roles" .IX Subsection "HPKE Roles" HPKE contexts have a role \- either sender or receiver. This is used @@ -257,7 +260,7 @@ vectors present in RFC9180, Appendix A.) .PP In accordance with RFC9180, section 9.5, we define a constant \&\fIOSSL_HPKE_MIN_PSKLEN\fR with a value of 32 for the minimum length of a -pre-shared key, passed in \fIpsklen\fR. +pre\-shared key, passed in \fIpsklen\fR. .PP While RFC9180 also RECOMMENDS a 64 octet limit for the \fIinfolen\fR parameter, that is not sufficient for TLS Encrypted ClientHello (ECH) processing, so we @@ -276,9 +279,9 @@ previously by a call to \fBOSSL_HPKE_CTX_new()\fR. If the argument to \&\fBOSSL_HPKE_CTX_free()\fR is NULL, nothing is done. .SS "Sender APIs" .IX Subsection "Sender APIs" -A sender's goal is to use HPKE to encrypt using a public key, via use of a +A sender\*(Aqs goal is to use HPKE to encrypt using a public key, via use of a KEM, then a KDF and finally an AEAD. The first step is to encapsulate (using -\&\fBOSSL_HPKE_encap()\fR) the sender's public value using the recipient's public key, +\&\fBOSSL_HPKE_encap()\fR) the sender\*(Aqs public value using the recipient\*(Aqs public key, (\fIpub\fR) and to internally derive secrets. This produces the encapsulated public value (\fIenc\fR) to be sent to the recipient in whatever protocol is using HPKE. Having done the encapsulation step, the sender can then make one or more calls to @@ -292,7 +295,7 @@ the output size. An error will occur if the input \fIenclen\fR is smaller than the value returned from \fBOSSL_HPKE_get_public_encap_size()\fR. \&\fIinfo\fR may be used to bind other protocol or application artefacts such as identifiers. Generally, the encapsulated public value \fIenc\fR corresponds to a -single-use ephemeral private value created as part of the encapsulation +single\-use ephemeral private value created as part of the encapsulation process. Only a single call to \fBOSSL_HPKE_encap()\fR is allowed for a given \&\fBOSSL_HPKE_CTX\fR. .PP @@ -316,7 +319,7 @@ outside the scope of this API. Private keys use normal \fBEVP_PKEY\fR\|(3) point so normal private key management mechanisms can be used for the relevant values. .PP -In order to enable encapsulation, the recipient needs to make it's public value +In order to enable encapsulation, the recipient needs to make it\*(Aqs public value available to the sender. There is no generic HPKE format defined for that \- the relevant formatting is intended to be defined by the application/protocols that makes use of HPKE. ECH for example defines an ECHConfig data structure that @@ -339,9 +342,9 @@ then a randomly generated key for the relevant \fIsuite\fR will be produced. If required \fIikmlen\fR should be greater than or equal to \&\fBOSSL_HPKE_get_recommended_ikmelen()\fR. .PP -\&\fBOSSL_HPKE_decap()\fR takes as input the sender's encapsulated public value -produced by \fBOSSL_HPKE_encap()\fR (\fIenc\fR) and the recipient's \fBEVP_PKEY\fR\|(3) -pointer (\fIprov\fR), and then re-generates the internal secret derived by the +\&\fBOSSL_HPKE_decap()\fR takes as input the sender\*(Aqs encapsulated public value +produced by \fBOSSL_HPKE_encap()\fR (\fIenc\fR) and the recipient\*(Aqs \fBEVP_PKEY\fR\|(3) +pointer (\fIprov\fR), and then re\-generates the internal secret derived by the sender. As before, an optional \fIinfo\fR parameter allows binding that derived secret to other application/protocol artefacts. Only a single call to \&\fBOSSL_HPKE_decap()\fR is allowed for a given \fBOSSL_HPKE_CTX\fR. @@ -357,7 +360,7 @@ An error will occur if the input \fIptlen\fR is too small. \&\fBOSSL_HPKE_open()\fR may be called multiple times, but as with \fBOSSL_HPKE_seal()\fR there is an internally incrementing nonce value so ciphertexts need to be presented in the same order as used by the \fBOSSL_HPKE_seal()\fR. -See "Re-sequencing" if you need to process multiple ciphertexts in a +See "Re\-sequencing" if you need to process multiple ciphertexts in a different order. .SS "Exporting Secrets" .IX Subsection "Exporting Secrets" @@ -374,11 +377,11 @@ same secret. \&\fIOSSL_HPKE_AEAD_ID_EXPORTONLY\fR may be used as the \fBOSSL_HPKE_SUITE\fR \fIaead_id\fR that is passed to \fBOSSL_HPKE_CTX_new()\fR if the user needs to produce a shared secret, but does not wish to perform HPKE encryption. -.SS "Sender-authenticated HPKE Modes" +.SS "Sender\-authenticated HPKE Modes" .IX Subsection "Sender-authenticated HPKE Modes" -HPKE defines modes that support KEM-based sender-authentication +HPKE defines modes that support KEM\-based sender\-authentication \&\fBOSSL_HPKE_MODE_AUTH\fR and \fBOSSL_HPKE_MODE_PSKAUTH\fR. This works by binding -the sender's authentication private/public values into the encapsulation and +the sender\*(Aqs authentication private/public values into the encapsulation and decapsulation operations. The key used for such modes must also use the same KEM as used for the overall exchange. \fBOSSL_HPKE_keygen()\fR can be used to generate the private value required. @@ -390,16 +393,16 @@ private \fIpriv\fR \fBEVP_PKEY\fR key into the \fBOSSL_HPKE_CTX\fR \fIctx\fR bef \&\fBOSSL_HPKE_CTX_set1_authpub()\fR can be used by the receiver to set the senders encoded pub key \fIpub\fR of size \fIpublen\fR into the \fBOSSL_HPKE_CTX\fR \fIctx\fR before calling \fBOSSL_HPKE_decap()\fR. -.SS "Pre-Shared Key HPKE modes" +.SS "Pre\-Shared Key HPKE modes" .IX Subsection "Pre-Shared Key HPKE modes" HPKE also defines a symmetric equivalent to the authentication described above -using a pre-shared key (PSK) and a PSK identifier. PSKs can be used with the +using a pre\-shared key (PSK) and a PSK identifier. PSKs can be used with the \&\fBOSSL_HPKE_MODE_PSK\fR and \fBOSSL_HPKE_MODE_PSKAUTH\fR modes. .PP \&\fBOSSL_HPKE_CTX_set1_psk()\fR sets the PSK identifier \fIpskid\fR string, and PSK buffer \&\fIpsk\fR of size \fIpsklen\fR into the \fIctx\fR. If required this must be called before \fBOSSL_HPKE_encap()\fR or \fBOSSL_HPKE_decap()\fR. -As per RFC9180, if required, both \fIpsk\fR and \fIpskid\fR must be set to non-NULL values. +As per RFC9180, if required, both \fIpsk\fR and \fIpskid\fR must be set to non\-NULL values. As PSKs are symmetric the same calls must happen on both sender and receiver sides. .SS "Deterministic key generation for senders" @@ -417,7 +420,7 @@ It is generally undesirable to use \fBOSSL_HPKE_CTX_set1_ikme()\fR, since it exposes the relevant secret to the application rather then preserving it within the library, and is more likely to result in use of predictable values or values that leak. -.SS Re-sequencing +.SS Re\-sequencing .IX Subsection "Re-sequencing" Some protocols may have to deal with packet loss while still being able to decrypt arriving packets later. We provide a way to set the increment used for @@ -466,7 +469,7 @@ public value needs to be regenerated by a sender before calling \fBOSSL_HPKE_sea .PP \&\fBOSSL_HPKE_get_grease_value()\fR produces values of the appropriate length for a given \fIsuite_in\fR value (or a random value if \fIsuite_in\fR is NULL) so that a -protocol using HPKE can send so-called GREASE (see RFC8701) values that are +protocol using HPKE can send so\-called GREASE (see RFC8701) values that are harder to distinguish from a real use of HPKE. The buffer sizes should be supplied on input. The output \fIenc\fR value will have an appropriate length for \fIsuite_out\fR and a random value, and the \fIct\fR output will be @@ -474,13 +477,13 @@ a random value. The relevant sizes for buffers can be found using \&\fBOSSL_HPKE_get_ciphertext_size()\fR and \fBOSSL_HPKE_get_public_encap_size()\fR. .PP \&\fBOSSL_HPKE_str2suite()\fR maps input \fIstr\fR strings to an \fBOSSL_HPKE_SUITE\fR object. -The input \fIstr\fR should be a comma-separated string with a KEM, -KDF and AEAD name in that order, for example "x25519,hkdf\-sha256,aes128gcm". +The input \fIstr\fR should be a comma\-separated string with a KEM, +KDF and AEAD name in that order, for example "x25519,hkdf\-sha256,aes\-128\-gcm". This can be used by command line tools that accept string form names for HPKE -codepoints. Valid (case-insensitive) names are: +codepoints. Valid (case\-insensitive) names are: "p\-256", "p\-384", "p\-521", "x25519" and "x448" for KEM, "hkdf\-sha256", "hkdf\-sha384" and "hkdf\-sha512" for KDF, and -"aes\-gcm\-128", "aes\-gcm\-256", "chacha20\-poly1305" and "exporter" for AEAD. +"aes\-128\-gcm", "aes\-256\-gcm", "chacha20\-poly1305" and "exporter" for AEAD. String variants of the numbers listed in "OSSL_HPKE_SUITE Identifiers" can also be used. .SH "RETURN VALUES" @@ -494,7 +497,7 @@ relevant value or zero on error. All other functions return 1 for success or zero for error. .SH EXAMPLES .IX Header "EXAMPLES" -This example demonstrates a minimal round-trip using HPKE. +This example demonstrates a minimal round\-trip using HPKE. .PP .Vb 4 \& #include <stddef.h> @@ -571,7 +574,7 @@ This example demonstrates a minimal round-trip using HPKE. .SH WARNINGS .IX Header "WARNINGS" Note that the \fBOSSL_HPKE_CTX_set_seq()\fR API could be dangerous \- if used with GCM -that could lead to nonce-reuse, which is a known danger. So avoid that +that could lead to nonce\-reuse, which is a known danger. So avoid that entirely, or be very very careful when using that API. .PP Use of an IKM value for deterministic key generation (via @@ -586,7 +589,7 @@ The RFC9180 specification: https://datatracker.ietf.org/doc/rfc9180/ This functionality described here was added in OpenSSL 3.2. .SH COPYRIGHT .IX Header "COPYRIGHT" -Copyright 2022\-2025 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2022\-2026 The OpenSSL Project Authors. All Rights Reserved. .PP Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy |