.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "OSSL_HPKE_CTX_NEW 3ossl"
.TH OSSL_HPKE_CTX_NEW 3ossl "2024-06-04" "3.3.1" "OpenSSL"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
OSSL_HPKE_CTX_new, OSSL_HPKE_CTX_free,
OSSL_HPKE_encap, OSSL_HPKE_decap,
OSSL_HPKE_seal, OSSL_HPKE_open, OSSL_HPKE_export,
OSSL_HPKE_suite_check, OSSL_HPKE_str2suite,
OSSL_HPKE_keygen, OSSL_HPKE_get_grease_value,
OSSL_HPKE_get_ciphertext_size, OSSL_HPKE_get_public_encap_size,
OSSL_HPKE_get_recommended_ikmelen,
OSSL_HPKE_CTX_set1_psk, OSSL_HPKE_CTX_set1_ikme,
OSSL_HPKE_CTX_set1_authpriv, OSSL_HPKE_CTX_set1_authpub,
OSSL_HPKE_CTX_get_seq, OSSL_HPKE_CTX_set_seq
\&\- Hybrid Public Key Encryption (HPKE) functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/hpke.h>
\&
\& typedef struct {
\&     uint16_t    kem_id;
\&     uint16_t    kdf_id;
\&     uint16_t    aead_id;
\& } OSSL_HPKE_SUITE;
\&
\& OSSL_HPKE_CTX *OSSL_HPKE_CTX_new(int mode, OSSL_HPKE_SUITE suite, int role,
\&                                  OSSL_LIB_CTX *libctx, const char *propq);
\& void OSSL_HPKE_CTX_free(OSSL_HPKE_CTX *ctx);
\&
\& int OSSL_HPKE_encap(OSSL_HPKE_CTX *ctx,
\&                     unsigned char *enc, size_t *enclen,
\&                     const unsigned char *pub, size_t publen,
\&                     const unsigned char *info, size_t infolen);
\& int OSSL_HPKE_seal(OSSL_HPKE_CTX *ctx,
\&                    unsigned char *ct, size_t *ctlen,
\&                    const unsigned char *aad, size_t aadlen,
\&                    const unsigned char *pt, size_t ptlen);
\&
\& int OSSL_HPKE_keygen(OSSL_HPKE_SUITE suite,
\&                      unsigned char *pub, size_t *publen, EVP_PKEY **priv,
\&                      const unsigned char *ikm, size_t ikmlen,
\&                      OSSL_LIB_CTX *libctx, const char *propq);
\& int OSSL_HPKE_decap(OSSL_HPKE_CTX *ctx,
\&                     const unsigned char *enc, size_t enclen,
\&                     EVP_PKEY *recippriv,
\&                     const unsigned char *info, size_t infolen);
\& int OSSL_HPKE_open(OSSL_HPKE_CTX *ctx,
\&                    unsigned char *pt, size_t *ptlen,
\&                    const unsigned char *aad, size_t aadlen,
\&                    const unsigned char *ct, size_t ctlen);
\&
\& int OSSL_HPKE_export(OSSL_HPKE_CTX *ctx,
\&                      unsigned char *secret, size_t secretlen,
\&                      const unsigned char *label, size_t labellen);
\&
\& int OSSL_HPKE_CTX_set1_authpriv(OSSL_HPKE_CTX *ctx, EVP_PKEY *priv);
\& int OSSL_HPKE_CTX_set1_authpub(OSSL_HPKE_CTX *ctx,
\&                                unsigned char *pub, size_t publen);
\& int OSSL_HPKE_CTX_set1_psk(OSSL_HPKE_CTX *ctx,
\&                            const char *pskid,
\&                            const unsigned char *psk, size_t psklen);
\&
\& int OSSL_HPKE_CTX_get_seq(OSSL_HPKE_CTX *ctx, uint64_t *seq);
\& int OSSL_HPKE_CTX_set_seq(OSSL_HPKE_CTX *ctx, uint64_t seq);
\&
\& int OSSL_HPKE_CTX_set1_ikme(OSSL_HPKE_CTX *ctx,
\&                             const unsigned char *ikme, size_t ikmelen);
\&
\& int OSSL_HPKE_suite_check(OSSL_HPKE_SUITE suite);
\& int OSSL_HPKE_get_grease_value(const OSSL_HPKE_SUITE *suite_in,
\&                                OSSL_HPKE_SUITE *suite,
\&                                unsigned char *enc, size_t *enclen,
\&                                unsigned char *ct, size_t ctlen,
\&                                OSSL_LIB_CTX *libctx, const char *propq);
\&
\& int OSSL_HPKE_str2suite(const char *str, OSSL_HPKE_SUITE *suite);
\& size_t OSSL_HPKE_get_ciphertext_size(OSSL_HPKE_SUITE suite, size_t clearlen);
\& size_t OSSL_HPKE_get_public_encap_size(OSSL_HPKE_SUITE suite);
\& size_t OSSL_HPKE_get_recommended_ikmelen(OSSL_HPKE_SUITE suite);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
These functions provide an \s-1API\s0 for using the form of Hybrid Public Key
Encryption (\s-1HPKE\s0) defined in \s-1RFC9180.\s0 Understanding the \s-1HPKE\s0 specification
is likely required before using these APIs.  \s-1HPKE\s0 is used by various
other \s-1IETF\s0 specifications, including the \s-1TLS\s0 Encrypted Client
Hello (\s-1ECH\s0) specification and others.
.PP
\&\s-1HPKE\s0 is a standardised, highly flexible construct for encrypting \*(L"to\*(R" a public
key that supports combinations of a key encapsulation method (\s-1KEM\s0), a key
derivation function (\s-1KDF\s0) and an authenticated encryption with additional data
(\s-1AEAD\s0) algorithm, with optional sender authentication.
.PP
The sender and a receiver here will generally be using some application or
protocol making use of \s-1HPKE.\s0 For example, with \s-1ECH,\s0
the sender will be a browser and the receiver will be a web server.
.SS "Data Structures"
.IX Subsection "Data Structures"
\&\fB\s-1OSSL_HPKE_SUITE\s0\fR is a structure that holds identifiers for the algorithms
used for \s-1KEM, KDF\s0 and \s-1AEAD\s0 operations.
.PP
\&\fB\s-1OSSL_HPKE_CTX\s0\fR is a context that maintains internal state as \s-1HPKE\s0
operations are carried out. Separate \fB\s-1OSSL_HPKE_CTX\s0\fR objects must be used for
the sender and receiver. Attempting to use a single context for both will
result in errors.
.SS "\s-1OSSL_HPKE_SUITE\s0 Identifiers"
.IX Subsection "OSSL_HPKE_SUITE Identifiers"
The identifiers used by \fB\s-1OSSL_HPKE_SUITE\s0\fR are:
.PP
The \s-1KEM\s0 identifier \fIkem_id\fR is one of the following:
.IP "0x10 \fB\s-1OSSL_HPKE_KEM_ID_P256\s0\fR" 4
.IX Item "0x10 OSSL_HPKE_KEM_ID_P256"
.PD 0
.IP "0x11 \fB\s-1OSSL_HPKE_KEM_ID_P384\s0\fR" 4
.IX Item "0x11 OSSL_HPKE_KEM_ID_P384"
.IP "0x12 \fB\s-1OSSL_HPKE_KEM_ID_P521\s0\fR" 4
.IX Item "0x12 OSSL_HPKE_KEM_ID_P521"
.IP "0x20 \fB\s-1OSSL_HPKE_KEM_ID_X25519\s0\fR" 4
.IX Item "0x20 OSSL_HPKE_KEM_ID_X25519"
.IP "0x21 \fB\s-1OSSL_HPKE_KEM_ID_X448\s0\fR" 4
.IX Item "0x21 OSSL_HPKE_KEM_ID_X448"
.PD
.PP
The \s-1KDF\s0 identifier \fIkdf_id\fR is one of the following:
.IP "0x01 \fB\s-1OSSL_HPKE_KDF_ID_HKDF_SHA256\s0\fR" 4
.IX Item "0x01 OSSL_HPKE_KDF_ID_HKDF_SHA256"
.PD 0
.IP "0x02 \fB\s-1OSSL_HPKE_KDF_ID_HKDF_SHA384\s0\fR" 4
.IX Item "0x02 OSSL_HPKE_KDF_ID_HKDF_SHA384"
.IP "0x03 \fB\s-1OSSL_HPKE_KDF_ID_HKDF_SHA512\s0\fR" 4
.IX Item "0x03 OSSL_HPKE_KDF_ID_HKDF_SHA512"
.PD
.PP
The \s-1AEAD\s0 identifier \fIaead_id\fR is one of the following:
.IP "0x01 \fB\s-1OSSL_HPKE_AEAD_ID_AES_GCM_128\s0\fR" 4
.IX Item "0x01 OSSL_HPKE_AEAD_ID_AES_GCM_128"
.PD 0
.IP "0x02 \fB\s-1OSSL_HPKE_AEAD_ID_AES_GCM_256\s0\fR" 4
.IX Item "0x02 OSSL_HPKE_AEAD_ID_AES_GCM_256"
.IP "0x03 \fB\s-1OSSL_HPKE_AEAD_ID_CHACHA_POLY1305\s0\fR" 4
.IX Item "0x03 OSSL_HPKE_AEAD_ID_CHACHA_POLY1305"
.IP "0xFFFF \fB\s-1OSSL_HPKE_AEAD_ID_EXPORTONLY\s0\fR" 4
.IX Item "0xFFFF OSSL_HPKE_AEAD_ID_EXPORTONLY"
.PD
The last identifier above indicates that \s-1AEAD\s0 operations are not needed.
\&\fIOSSL_HPKE_export()\fR can be used, but \fIOSSL_HPKE_open()\fR and \fIOSSL_HPKE_seal()\fR will
return an error if called with a context using that \s-1AEAD\s0 identifier.
.SS "\s-1HPKE\s0 Modes"
.IX Subsection "HPKE Modes"
\&\s-1HPKE\s0 supports the following variants of Authentication using a mode Identifier:
.IP "\fB\s-1OSSL_HPKE_MODE_BASE\s0\fR, 0x00" 4
.IX Item "OSSL_HPKE_MODE_BASE, 0x00"
Authentication is not used.
.IP "\fB\s-1OSSL_HPKE_MODE_PSK\s0\fR, 0x01" 4
.IX Item "OSSL_HPKE_MODE_PSK, 0x01"
Authenticates possession of a pre-shared key (\s-1PSK\s0).
.IP "\fB\s-1OSSL_HPKE_MODE_AUTH\s0\fR, 0x02" 4
.IX Item "OSSL_HPKE_MODE_AUTH, 0x02"
Authenticates possession of a KEM-based sender private key.
.IP "\fB\s-1OSSL_HPKE_MODE_PSKAUTH\s0\fR, 0x03" 4
.IX Item "OSSL_HPKE_MODE_PSKAUTH, 0x03"
A combination of \fB\s-1OSSL_HPKE_MODE_PSK\s0\fR and \fB\s-1OSSL_HPKE_MODE_AUTH\s0\fR.
Both the \s-1PSK\s0 and the senders authentication public/private must be
supplied before the encapsulation/decapsulation operation will work.
.PP
For further information related to authentication see \*(L"Pre-Shared Key \s-1HPKE\s0
modes\*(R" and \*(L"Sender-authenticated \s-1HPKE\s0 Modes\*(R".
.SS "\s-1HPKE\s0 Roles"
.IX Subsection "HPKE Roles"
\&\s-1HPKE\s0 contexts have a role \- either sender or receiver. This is used
to control which functions can be called and so that senders do not
reuse a key and nonce with different plaintexts.
.PP
\&\fIOSSL_HPKE_CTX_free()\fR, \fIOSSL_HPKE_export()\fR, \fIOSSL_HPKE_CTX_set1_psk()\fR,
and \fIOSSL_HPKE_CTX_get_seq()\fR can be called regardless of role.
.IP "\fB\s-1OSSL_HPKE_ROLE_SENDER\s0\fR, 0" 4
.IX Item "OSSL_HPKE_ROLE_SENDER, 0"
An \fI\s-1OSSL_HPKE_CTX\s0\fR with this role can be used with
\&\fIOSSL_HPKE_encap()\fR, \fIOSSL_HPKE_seal()\fR, \fIOSSL_HPKE_CTX_set1_ikme()\fR and
\&\fIOSSL_HPKE_CTX_set1_authpriv()\fR.
.IP "\fB\s-1OSSL_HPKE_ROLE_RECEIVER\s0\fR, 1" 4
.IX Item "OSSL_HPKE_ROLE_RECEIVER, 1"
An \fI\s-1OSSL_HPKE_CTX\s0\fR with this role can be used with \fIOSSL_HPKE_decap()\fR,
\&\fIOSSL_HPKE_open()\fR, \fIOSSL_HPKE_CTX_set1_authpub()\fR and \fIOSSL_HPKE_CTX_set_seq()\fR.
.PP
Calling a function with an incorrect role set on \fI\s-1OSSL_HPKE_CTX\s0\fR will result
in an error.
.SS "Parameter Size Limits"
.IX Subsection "Parameter Size Limits"
In order to improve interoperability, \s-1RFC9180,\s0 section 7.2.1 suggests a
\&\s-1RECOMMENDED\s0 maximum size of 64 octets for various input parameters.  In this
implementation we apply a limit of 66 octets for the \fIikmlen\fR, \fIpsklen\fR, and
\&\fIlabellen\fR parameters, and for the length of the string \fIpskid\fR for \s-1HPKE\s0
functions below. The constant \fI\s-1OSSL_HPKE_MAX_PARMLEN\s0\fR is defined as the limit
of this value.  (We chose 66 octets so that we can validate all the test
vectors present in \s-1RFC9180,\s0 Appendix A.)
.PP
In accordance with \s-1RFC9180,\s0 section 9.5, we define a constant
\&\fI\s-1OSSL_HPKE_MIN_PSKLEN\s0\fR with a value of 32 for the minimum length of a
pre-shared key, passed in \fIpsklen\fR.
.PP
While \s-1RFC9180\s0 also \s-1RECOMMENDS\s0 a 64 octet limit for the \fIinfolen\fR parameter,
that is not sufficient for \s-1TLS\s0 Encrypted ClientHello (\s-1ECH\s0) processing, so we
enforce a limit of \fI\s-1OSSL_HPKE_MAX_INFOLEN\s0\fR with a value of 1024 as the limit
for the \fIinfolen\fR parameter.
.SS "Context Construct/Free"
.IX Subsection "Context Construct/Free"
\&\fIOSSL_HPKE_CTX_new()\fR creates a \fB\s-1OSSL_HPKE_CTX\s0\fR context object used for
subsequent \s-1HPKE\s0 operations, given a \fImode\fR (See \*(L"\s-1HPKE\s0 Modes\*(R"), \fIsuite\fR (see
\&\*(L"\s-1OSSL_HPKE_SUITE\s0 Identifiers\*(R") and a \fIrole\fR (see \*(L"\s-1HPKE\s0 Roles\*(R"). The
\&\fIlibctx\fR and \fIpropq\fR are used when fetching algorithms from providers and may
be set to \s-1NULL.\s0
.PP
\&\fIOSSL_HPKE_CTX_free()\fR frees the \fIctx\fR \fB\s-1OSSL_HPKE_CTX\s0\fR that was created
previously by a call to \fIOSSL_HPKE_CTX_new()\fR.
.SS "Sender APIs"
.IX Subsection "Sender APIs"
A sender's goal is to use \s-1HPKE\s0 to encrypt using a public key, via use of a
\&\s-1KEM,\s0 then a \s-1KDF\s0 and finally an \s-1AEAD. \s0 The first step is to encapsulate (using
\&\fIOSSL_HPKE_encap()\fR) the sender's public value using the recipient's 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 \s-1HPKE.\s0 Having done the
encapsulation step, the sender can then make one or more calls to
\&\fIOSSL_HPKE_seal()\fR to encrypt plaintexts using the secret stored within \fIctx\fR.
.PP
\&\fIOSSL_HPKE_encap()\fR uses the \s-1HPKE\s0 context \fIctx\fR, the recipient public value
\&\fIpub\fR of size \fIpublen\fR, and an optional \fIinfo\fR parameter of size \fIinfolen\fR,
to produce the encapsulated public value \fIenc\fR.
On input \fIenclen\fR should contain the maximum size of the \fIenc\fR buffer, and returns
the output size. An error will occur if the input \fIenclen\fR is
smaller than the value returned from \fIOSSL_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
process. Only a single call to \fIOSSL_HPKE_encap()\fR is allowed for a given
\&\fB\s-1OSSL_HPKE_CTX\s0\fR.
.PP
\&\fIOSSL_HPKE_seal()\fR takes the \fB\s-1OSSL_HPKE_CTX\s0\fR context \fIctx\fR, the plaintext
buffer \fIpt\fR of size \fIptlen\fR and optional additional authenticated data buffer
\&\fIaad\fR of size \fIaadlen\fR, and returns the ciphertext \fIct\fR of size \fIctlen\fR.
On input \fIctlen\fR should contain the maximum size of the \fIct\fR buffer, and returns
the output size. An error will occur if the input \fIctlen\fR is
smaller than the value returned from \fIOSSL_HPKE_get_public_encap_size()\fR.
.PP
\&\fIOSSL_HPKE_encap()\fR must be called before the \fIOSSL_HPKE_seal()\fR.  \fIOSSL_HPKE_seal()\fR
may be called multiple times, with an internal \*(L"nonce\*(R" being incremented by one
after each call.
.SS "Recipient APIs"
.IX Subsection "Recipient APIs"
Recipients using \s-1HPKE\s0 require a typically less ephemeral private value so that
the public value can be distributed to potential senders via whatever protocol
is using \s-1HPKE.\s0 For this reason, recipients will generally first generate a key
pair and will need to manage their private key value using standard mechanisms
outside the scope of this \s-1API.\s0 Private keys use normal \s-1\fIEVP_PKEY\s0\fR\|(3) pointers
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
available to the sender. There is no generic \s-1HPKE\s0 format defined for that \- the
relevant formatting is intended to be defined by the application/protocols that
makes use of \s-1HPKE. ECH\s0 for example defines an ECHConfig data structure that
combines the public value with other \s-1ECH\s0 data items. Normal library functions
must therefore be used to extract the public value in the required format based
on the \s-1\fIEVP_PKEY\s0\fR\|(3) for the private value.
.PP
\&\fIOSSL_HPKE_keygen()\fR provides a way for recipients to generate a key pair based
on the \s-1HPKE \s0\fIsuite\fR to be used. It returns a \s-1\fIEVP_PKEY\s0\fR\|(3) pointer
for the private value \fIpriv\fR and a encoded public key \fIpub\fR of size \fIpublen\fR.
On input \fIpublen\fR should contain the maximum size of the \fIpub\fR buffer, and
returns the output size. An error will occur if the input \fIpublen\fR is too small.
The \fIlibctx\fR and \fIpropq\fR are used when fetching algorithms from providers
and may be set to \s-1NULL.\s0
The \s-1HPKE\s0 specification also defines a deterministic key generation scheme where
the private value is derived from initial keying material (\s-1IKM\s0), so
\&\fIOSSL_HPKE_keygen()\fR also has an option to use that scheme, using the \fIikm\fR
parameter of size \fIikmlen\fR. If either \fIikm\fR is \s-1NULL\s0 or \fIikmlen\fR is zero,
then a randomly generated key for the relevant \fIsuite\fR will be produced.
If required \fIikmlen\fR should be greater than or equal to
\&\fIOSSL_HPKE_get_recommended_ikmelen()\fR.
.PP
\&\fIOSSL_HPKE_decap()\fR takes as input the sender's encapsulated public value
produced by \fIOSSL_HPKE_encap()\fR (\fIenc\fR) and the recipient's \s-1\fIEVP_PKEY\s0\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
\&\fIOSSL_HPKE_decap()\fR is allowed for a given \fB\s-1OSSL_HPKE_CTX\s0\fR.
.PP
\&\fIOSSL_HPKE_open()\fR is used by the recipient to decrypt the ciphertext \fIct\fR of
size \fIctlen\fR using the \fIctx\fR and additional authenticated data \fIaad\fR of
size \fIaadlen\fR, to produce the plaintext \fIpt\fR of size \fIptlen\fR.
On input \fIptlen\fR should contain the maximum size of the \fIpt\fR buffer, and
returns the output size. A \fIpt\fR buffer that is the same size as the
\&\fIct\fR buffer will suffice \- generally the plaintext output will be
a little smaller than the ciphertext input.
An error will occur if the input \fIptlen\fR is too small.
\&\fIOSSL_HPKE_open()\fR may be called multiple times, but as with \fIOSSL_HPKE_seal()\fR
there is an internally incrementing nonce value so ciphertexts need to be
presented in the same order as used by the \fIOSSL_HPKE_seal()\fR.
See \*(L"Re-sequencing\*(R" if you need to process multiple ciphertexts in a
different order.
.SS "Exporting Secrets"
.IX Subsection "Exporting Secrets"
\&\s-1HPKE\s0 defines a way to produce exported secrets for use by the
application.
.PP
\&\fIOSSL_HPKE_export()\fR takes as input the \fB\s-1OSSL_HPKE_CTX\s0\fR, and an application
supplied label \fIlabel\fR of size \fIlabellen\fR, to produce a secret \fIsecret\fR
of size \fIsecretlen\fR. The sender must first call \fIOSSL_HPKE_encap()\fR, and the
receiver must call \fIOSSL_HPKE_decap()\fR in order to derive the same shared secret.
.PP
Multiple calls to \fIOSSL_HPKE_export()\fR with the same inputs will produce the
same secret.
\&\fI\s-1OSSL_HPKE_AEAD_ID_EXPORTONLY\s0\fR may be used as the \fB\s-1OSSL_HPKE_SUITE\s0\fR \fIaead_id\fR
that is passed to \fIOSSL_HPKE_CTX_new()\fR if the user needs to produce a shared
secret, but does not wish to perform \s-1HPKE\s0 encryption.
.SS "Sender-authenticated \s-1HPKE\s0 Modes"
.IX Subsection "Sender-authenticated HPKE Modes"
\&\s-1HPKE\s0 defines modes that support KEM-based sender-authentication
\&\fB\s-1OSSL_HPKE_MODE_AUTH\s0\fR and \fB\s-1OSSL_HPKE_MODE_PSKAUTH\s0\fR. This works by binding
the sender's authentication private/public values into the encapsulation and
decapsulation operations. The key used for such modes must also use the same
\&\s-1KEM\s0 as used for the overall exchange. \fIOSSL_HPKE_keygen()\fR can be used to
generate the private value required.
.PP
\&\fIOSSL_HPKE_CTX_set1_authpriv()\fR can be used by the sender to set the senders
private \fIpriv\fR \fB\s-1EVP_PKEY\s0\fR key into the \fB\s-1OSSL_HPKE_CTX\s0\fR \fIctx\fR before calling
\&\fIOSSL_HPKE_encap()\fR.
.PP
\&\fIOSSL_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 \fB\s-1OSSL_HPKE_CTX\s0\fR \fIctx\fR before
calling \fIOSSL_HPKE_decap()\fR.
.SS "Pre-Shared Key \s-1HPKE\s0 modes"
.IX Subsection "Pre-Shared Key HPKE modes"
\&\s-1HPKE\s0 also defines a symmetric equivalent to the authentication described above
using a pre-shared key (\s-1PSK\s0) and a \s-1PSK\s0 identifier. PSKs can be used with the
\&\fB\s-1OSSL_HPKE_MODE_PSK\s0\fR and \fB\s-1OSSL_HPKE_MODE_PSKAUTH\s0\fR modes.
.PP
\&\fIOSSL_HPKE_CTX_set1_psk()\fR sets the \s-1PSK\s0 identifier \fIpskid\fR string, and \s-1PSK\s0 buffer
\&\fIpsk\fR of size \fIpsklen\fR into the \fIctx\fR. If required this must be called
before \fIOSSL_HPKE_encap()\fR or \fIOSSL_HPKE_decap()\fR.
As per \s-1RFC9180,\s0 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"
.IX Subsection "Deterministic key generation for senders"
Normally the senders ephemeral private key is generated randomly inside
\&\fIOSSL_HPKE_encap()\fR and remains secret.
\&\fIOSSL_HPKE_CTX_set1_ikme()\fR allows the user to override this behaviour by
setting a deterministic input key material \fIikm\fR of size \fIikmlen\fR into
the \fB\s-1OSSL_HPKE_CTX\s0\fR \fIctx\fR.
If required \fIOSSL_HPKE_CTX_set1_ikme()\fR can optionally be called before
\&\fIOSSL_HPKE_encap()\fR.
\&\fIikmlen\fR should be greater than or equal to \fIOSSL_HPKE_get_recommended_ikmelen()\fR.
.PP
It is generally undesirable to use \fIOSSL_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"
.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
the nonce to the next subsequent call to \fIOSSL_HPKE_open()\fR (but not to
\&\fIOSSL_HPKE_seal()\fR as explained below).  The \fIOSSL_HPKE_CTX_set_seq()\fR \s-1API\s0 can be
used for such purposes with the \fIseq\fR parameter value resetting the internal
nonce increment to be used for the next call.
.PP
A baseline nonce value is established based on the encapsulation or
decapsulation operation and is then incremented by 1 for each call to seal or
open. (In other words, the first \fIseq\fR increment defaults to zero.)
.PP
If a caller needs to determine how many calls to seal or open have been made
the \fIOSSL_HPKE_CTX_get_seq()\fR \s-1API\s0 can be used to retrieve the increment (in the
\&\fIseq\fR output) that will be used in the next call to seal or open. That would
return 0 before the first call a sender made to \fIOSSL_HPKE_seal()\fR and 1 after
that first call.
.PP
Note that reuse of the same nonce and key with different plaintexts would
be very dangerous and could lead to loss of confidentiality and integrity.
We therefore only support application control over \fIseq\fR for decryption
(i.e. \fIOSSL_HPKE_open()\fR) operations.
.PP
For compatibility with other implementations these \fIseq\fR increments are
represented as \fIuint64_t\fR.
.SS "Protocol Convenience Functions"
.IX Subsection "Protocol Convenience Functions"
Additional convenience APIs allow the caller to access internal details of
local \s-1HPKE\s0 support and/or algorithms, such as parameter lengths.
.PP
\&\fIOSSL_HPKE_suite_check()\fR checks if a specific \fB\s-1OSSL_HPKE_SUITE\s0\fR \fIsuite\fR
is supported locally.
.PP
To assist with memory allocation, \fIOSSL_HPKE_get_ciphertext_size()\fR provides a
way for the caller to know by how much ciphertext will be longer than a
plaintext of length \fIclearlen\fR.  (\s-1AEAD\s0 algorithms add a data integrity tag,
so there is a small amount of ciphertext expansion.)
.PP
\&\fIOSSL_HPKE_get_public_encap_size()\fR provides a way for senders to know how big
the encapsulated public value will be for a given \s-1HPKE \s0\fIsuite\fR.
.PP
\&\fIOSSL_HPKE_get_recommended_ikmelen()\fR returns the recommended Input Key Material
size (in bytes) for a given \fIsuite\fR. This is needed in cases where the same
public value needs to be regenerated by a sender before calling \fIOSSL_HPKE_seal()\fR.
\&\fIikmlen\fR should be at least this size.
.PP
\&\fIOSSL_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 \s-1NULL\s0) so that a
protocol using \s-1HPKE\s0 can send so-called \s-1GREASE \s0(see \s-1RFC8701\s0) values that are
harder to distinguish from a real use of \s-1HPKE.\s0 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
a random value. The relevant sizes for buffers can be found using
\&\fIOSSL_HPKE_get_ciphertext_size()\fR and \fIOSSL_HPKE_get_public_encap_size()\fR.
.PP
\&\fIOSSL_HPKE_str2suite()\fR maps input \fIstr\fR strings to an \fB\s-1OSSL_HPKE_SUITE\s0\fR object.
The input \fIstr\fR should be a comma-separated string with a \s-1KEM,
KDF\s0 and \s-1AEAD\s0 name in that order, for example \*(L"x25519,hkdf\-sha256,aes128gcm\*(R".
This can be used by command line tools that accept string form names for \s-1HPKE\s0
codepoints. Valid (case-insensitive) names are:
\&\*(L"p256\*(R", \*(L"p384\*(R", \*(L"p521\*(R", \*(L"x25519\*(R" and \*(L"x448\*(R" for \s-1KEM,
\&\s0\*(L"hkdf\-SHA256\*(R", \*(L"hkdf\-SHA384\*(R" and \*(L"hkdf\-SHA512\*(R" for \s-1KDF,\s0 and
\&\*(L"aes\-gcm\-128\*(R", \*(L"aes\-gcm\-256\*(R" and \*(L"chacha20\-poly1305\*(R" for \s-1AEAD.\s0
String variants of the numbers listed in \*(L"\s-1OSSL_HPKE_SUITE\s0 Identifiers\*(R"
can also be used.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fIOSSL_HPKE_CTX_new()\fR returns an \s-1OSSL_HPKE_CTX\s0 pointer or \s-1NULL\s0 on error.
.PP
\&\fIOSSL_HPKE_get_ciphertext_size()\fR, \fIOSSL_HPKE_get_public_encap_size()\fR,
\&\fIOSSL_HPKE_get_recommended_ikmelen()\fR all return a size_t with the
relevant value or zero on error.
.PP
All other functions return 1 for success or zero for error.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
This example demonstrates a minimal round-trip using \s-1HPKE.\s0
.PP
.Vb 4
\&    #include <stddef.h>
\&    #include <string.h>
\&    #include <openssl/hpke.h>
\&    #include <openssl/evp.h>
\&
\&    /*
\&     * this is big enough for this example, real code would need different
\&     * handling
\&     */
\&    #define LBUFSIZE 48
\&
\&    /* Do a round\-trip, generating a key, encrypting and decrypting */
\&    int main(int argc, char **argv)
\&    {
\&        int ok = 0;
\&        int hpke_mode = OSSL_HPKE_MODE_BASE;
\&        OSSL_HPKE_SUITE hpke_suite = OSSL_HPKE_SUITE_DEFAULT;
\&        OSSL_HPKE_CTX *sctx = NULL, *rctx = NULL;
\&        EVP_PKEY *priv = NULL;
\&        unsigned char pub[LBUFSIZE];
\&        size_t publen = sizeof(pub);
\&        unsigned char enc[LBUFSIZE];
\&        size_t enclen = sizeof(enc);
\&        unsigned char ct[LBUFSIZE];
\&        size_t ctlen = sizeof(ct);
\&        unsigned char clear[LBUFSIZE];
\&        size_t clearlen = sizeof(clear);
\&        const unsigned char *pt = "a message not in a bottle";
\&        size_t ptlen = strlen((char *)pt);
\&        const unsigned char *info = "Some info";
\&        size_t infolen = strlen((char *)info);
\&        unsigned char aad[] = { 1, 2, 3, 4, 5, 6, 7, 8 };
\&        size_t aadlen = sizeof(aad);
\&
\&        /*
\&         * Generate receiver\*(Aqs key pair.
\&         * The receiver gives this public key to the sender.
\&         */
\&        if (OSSL_HPKE_keygen(hpke_suite, pub, &publen, &priv,
\&                             NULL, 0, NULL, NULL) != 1)
\&            goto err;
\&
\&        /* sender\*(Aqs actions \- encrypt data using the receivers public key */
\&        if ((sctx = OSSL_HPKE_CTX_new(hpke_mode, hpke_suite,
\&                                      OSSL_HPKE_ROLE_SENDER,
\&                                      NULL, NULL)) == NULL)
\&            goto err;
\&        if (OSSL_HPKE_encap(sctx, enc, &enclen, pub, publen, info, infolen) != 1)
\&            goto err;
\&        if (OSSL_HPKE_seal(sctx, ct, &ctlen, aad, aadlen, pt, ptlen) != 1)
\&            goto err;
\&
\&        /* receiver\*(Aqs actions \- decrypt data using the receivers private key */
\&        if ((rctx = OSSL_HPKE_CTX_new(hpke_mode, hpke_suite,
\&                                      OSSL_HPKE_ROLE_RECEIVER,
\&                                      NULL, NULL)) == NULL)
\&            goto err;
\&        if (OSSL_HPKE_decap(rctx, enc, enclen, priv, info, infolen) != 1)
\&            goto err;
\&        if (OSSL_HPKE_open(rctx, clear, &clearlen, aad, aadlen, ct, ctlen) != 1)
\&            goto err;
\&        ok = 1;
\&    err:
\&        /* clean up */
\&        printf(ok ? "All Good!\en" : "Error!\en");
\&        OSSL_HPKE_CTX_free(rctx);
\&        OSSL_HPKE_CTX_free(sctx);
\&        EVP_PKEY_free(priv);
\&        return 0;
\&    }
.Ve
.SH "WARNINGS"
.IX Header "WARNINGS"
Note that the \fIOSSL_HPKE_CTX_set_seq()\fR \s-1API\s0 could be dangerous \- if used with \s-1GCM\s0
that could lead to nonce-reuse, which is a known danger. So avoid that
entirely, or be very very careful when using that \s-1API.\s0
.PP
Use of an \s-1IKM\s0 value for deterministic key generation (via
\&\fIOSSL_HPKE_CTX_set1_ikme()\fR or \fIOSSL_HPKE_keygen()\fR) creates the potential for
leaking keys (or \s-1IKM\s0 values). Only use that if really needed and if you
understand how keys or \s-1IKM\s0 values could be abused.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The \s-1RFC9180\s0 specification: https://datatracker.ietf.org/doc/rfc9180/
.SH "HISTORY"
.IX Header "HISTORY"
This functionality described here was added in OpenSSL 3.2.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2022\-2023 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (the \*(L"License\*(R").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.