
@subheading gnutls_hpke_decap
@anchor{gnutls_hpke_decap}
@deftypefun {int} {gnutls_hpke_decap} (gnutls_hpke_context_t @var{ctx}, const gnutls_datum_t * @var{info}, const gnutls_datum_t * @var{enc}, const gnutls_privkey_t @var{receiver_privkey}, const gnutls_pubkey_t @var{sender_pubkey}, const gnutls_datum_t * @var{psk}, const gnutls_datum_t * @var{psk_id})
@var{ctx}: The HPKE context to use for decapsulation.

@var{info}: The application-specific information that was included in the key schedule (optional).

@var{enc}: A pointer to a gnutls_datum_t structure containing the encapsulated key received from the sender.

@var{receiver_privkey}: The receiver's private key to use for decapsulation.

@var{sender_pubkey}: The sender's public key for AuthDecap operation (optional).

@var{psk}: The pre-shared key (optional).

@var{psk_id}: The pre-shared key identifier (optional).

This function performs the decapsulation operation of HPKE. It
takes the encapsulated key ( @code{enc} ) received from the sender and uses
it along with the receiver's private key to derive the shared
secret. It then uses this shared secret along with any provided
application-specific information ( @code{info} ) to set up the necessary
keys and nonces in the HPKE context for subsequent sealing and
opening operations.

This function must be used once per HPKE context and before any
calls to @code{gnutls_hpke_open()} .

 @code{enc} should be the same encapsulated key that was generated by
@code{gnutls_hpke_encap()}  on the sender's side.

 @code{receiver_privkey} must be a valid private key that is compatible
with the KEM algorithm specified in the HPKE context and that
corresponds to the receiver's public key used during encapsulation.

For @code{GNUTLS_HPKE_MODE_AUTH}  or @code{GNUTLS_HPKE_MODE_AUTH_PSK} ,
 @code{sender_pubkey} must be a valid public key that can be used for
authentication. For @code{GNUTLS_HPKE_MODE_PSK}  or
@code{GNUTLS_HPKE_MODE_AUTH_PSK} , a pre-shared key ( @code{psk} ) and its
identifier ( @code{psk_id} ) must be supplied.

@strong{Returns:} 0 on success, or a negative error code on failure

@strong{Since:} 3.8.13
@end deftypefun

@subheading gnutls_hpke_deinit
@anchor{gnutls_hpke_deinit}
@deftypefun {int} {gnutls_hpke_deinit} (gnutls_hpke_context_t @var{ctx})
@var{ctx}: The HPKE context to deinitialize.

This function deinitializes the HPKE context and securely erases any
sensitive information contained within it, such as keys and secrets.
It is important to call this function when the HPKE context is no longer needed
to prevent sensitive data from lingering in memory.

@strong{Returns:} 0 on success, or a negative error code on failure.

@strong{Since:} 3.8.13
@end deftypefun

@subheading gnutls_hpke_derive_keypair
@anchor{gnutls_hpke_derive_keypair}
@deftypefun {int} {gnutls_hpke_derive_keypair} (gnutls_hpke_kem_t @var{kem}, const gnutls_datum_t * @var{ikm}, gnutls_privkey_t @var{privkey}, gnutls_pubkey_t @var{pubkey})
@var{kem}: The KEM algorithm to use for key pair generation.

@var{ikm}: A pointer to a gnutls_datum_t structure containing the input key material (IKM) to be used for key pair
generation.

@var{privkey}: An initialized private key.

@var{pubkey}: An initialized public key.

This function derives a key pair (private key and public key) for
the specified KEM algorithm from the provided input key material
( @code{ikm} ).

 @code{ikm} is used as a seed for the key generation process, allowing for
deterministic key pair generation if the same IKM is used. The
function checks that the provided parameters are valid and that the
KEM algorithm is supported.

 @code{ikm} should be a non-empty byte string that serves as the seed for
key pair generation.

@strong{Returns:} 0 on success, or a negative error code on failure

@strong{Since:} 3.8.13
@end deftypefun

@subheading gnutls_hpke_encap
@anchor{gnutls_hpke_encap}
@deftypefun {int} {gnutls_hpke_encap} (gnutls_hpke_context_t @var{ctx}, const gnutls_datum_t * @var{info}, gnutls_datum_t * @var{enc}, const gnutls_pubkey_t @var{receiver_pubkey}, const gnutls_privkey_t @var{sender_privkey}, const gnutls_datum_t * @var{psk}, const gnutls_datum_t * @var{psk_id})
@var{ctx}: The HPKE context to use for encapsulation.

@var{info}: The application-specific information to be included in the key schedule (optional).

@var{enc}: A pointer to a gnutls_datum_t structure where the encapsulated key will be stored.

@var{receiver_pubkey}: The receiver's public key to use for encapsulation.

@var{sender_privkey}: The sender's private key needed for AuthEncap operation (optional).

@var{psk}: The pre-shared key (optional).

@var{psk_id}: The pre-shared key identifier (optional).

This function performs the encapsulation operation of HPKE. It
generates an encapsulated key ( @code{enc} ) that can be sent to the
receiver, who can then use it to derive the shared secret.

The function checks that the context is properly initialized and
that the provided parameters are valid. It also checks that the
context is in the correct role (@code{GNUTLS_HPKE_ROLE_SENDER} ) for
encapsulation.

This function must be used once per HPKE context and before any
calls to @code{gnutls_hpke_seal()} .

The function will allocate memory for  @code{enc} , and the caller is
responsible for freeing this memory using @code{gnutls_free()}  when it is
no longer needed.

 @code{receiver_pubkey} must be a valid public key that is compatible with
the KEM algorithm specified in the HPKE context.

For @code{GNUTLS_HPKE_MODE_AUTH}  or @code{GNUTLS_HPKE_MODE_AUTH_PSK} ,
 @code{sender_privkey} must be a valid private key that can be used for
authentication. For @code{GNUTLS_HPKE_MODE_PSK}  or
@code{GNUTLS_HPKE_MODE_AUTH_PSK} , a pre-shared key ( @code{psk} ) and its
identifier ( @code{psk_id} ) must be supplied.

@strong{Returns:} 0 on success, or a negative error code on failure

@strong{Since:} 3.8.13
@end deftypefun

@subheading gnutls_hpke_export
@anchor{gnutls_hpke_export}
@deftypefun {int} {gnutls_hpke_export} (gnutls_hpke_context_t @var{ctx}, const gnutls_datum_t * @var{exporter_context}, size_t @var{length}, gnutls_datum_t * @var{secret})
@var{ctx}: The HPKE context to use for exporting the secret.

@var{exporter_context}: The application-specific context to be included in the export.

@var{length}: The requested length in bytes of the secret to be exported.

@var{secret}: A pointer to a gnutls_datum_t structure where the exported secret will be stored.

This function performs the export operation of HPKE. It derives a
secret of  @code{length} bytes from the exporter secret in the HPKE
context, using the provided application-specific context and the
KDF specified in the context. The resulting secret is stored in
 @code{secret} . The function checks that the provided parameters are valid
and that the context is properly initialized and that there is an
exporter secret available in the context.

 @code{length} should be a positive integer that does not exceed the
maximum allowed size for HPKE exports.

The function will allocate memory for  @code{secret} , and the caller is
responsible for freeing this memory using @code{gnutls_free()}  when it is
no longer needed.

@strong{Returns:} 0 on success, or a negative error code on failure

@strong{Since:} 3.8.13
@end deftypefun

@subheading gnutls_hpke_init
@anchor{gnutls_hpke_init}
@deftypefun {int} {gnutls_hpke_init} (gnutls_hpke_context_t * @var{ctx}, gnutls_hpke_mode_t @var{mode}, gnutls_hpke_role_t @var{role}, gnutls_hpke_kem_t @var{kem}, gnutls_hpke_kdf_t @var{kdf}, gnutls_hpke_aead_t @var{aead})
@var{ctx}: A pointer to the HPKE context to initialize.

@var{mode}: The HPKE mode to use (Base, PSK, Auth, or AuthPSK).

@var{role}: The role of the context (Sender or Receiver).

@var{kem}: The KEM algorithm to use (e.g., DHKEM(X25519)).

@var{kdf}: The KDF algorithm to use (e.g., HKDF-SHA256).

@var{aead}: The AEAD algorithm to use (e.g., AES-128-GCM).

This function initializes the HPKE context with the specified parameters.
It allocates memory for the context and sets the initial values for the fields based on the provided parameters.

The context must be deinitialized using @code{gnutls_hpke_deinit()}  when it
is no longer needed to free any allocated resources and securely erase sensitive information.

@strong{Returns:} 0 on success, or a negative error code on failure

@strong{Since:} 3.8.13
@end deftypefun

@subheading gnutls_hpke_open
@anchor{gnutls_hpke_open}
@deftypefun {int} {gnutls_hpke_open} (gnutls_hpke_context_t @var{ctx}, const gnutls_datum_t * @var{aad}, const gnutls_datum_t * @var{ciphertext}, gnutls_datum_t * @var{plaintext})
@var{ctx}: The HPKE context to use for opening.

@var{aad}: The associated data (AAD) that was authenticated during sealing.

@var{ciphertext}: The ciphertext received from the sender.

@var{plaintext}: A pointer to a gnutls_datum_t structure where the resulting plaintext will be stored.

This function performs the opening operation of HPKE. It takes the
ciphertext received from the sender and uses the keys and nonces
set up in the HPKE context (after decapsulation) to decrypt the
ciphertext and verify the authentication tag. If the decryption and
authentication are successful, the resulting plaintext is stored in
 @code{plaintext} . If the decryption or authentication fails, the function
securely erases any allocated plaintext and returns an error code.

This function can be used multiple times with the same HPKE
context, but the decapsulation function (@code{gnutls_hpke_decap()} ) must
be called once before the first call to this function.

 @code{aad} should be the same AAD that was provided to @code{gnutls_hpke_seal()} 
on the sender's side.

 @code{ciphertext} should be the same ciphertext that was generated by
@code{gnutls_hpke_seal()}  on the sender's side.

The function will allocate memory for the  @code{plaintext} , and the
caller is responsible for freeing this memory using @code{gnutls_free()} 
when it is no longer needed.

@strong{Returns:} 0 on success, or a negative error code on failure

@strong{Since:} 3.8.13
@end deftypefun

@subheading gnutls_hpke_seal
@anchor{gnutls_hpke_seal}
@deftypefun {int} {gnutls_hpke_seal} (gnutls_hpke_context_t @var{ctx}, const gnutls_datum_t * @var{aad}, const gnutls_datum_t * @var{plaintext}, gnutls_datum_t * @var{ciphertext})
@var{ctx}: The HPKE context to use for sealing.

@var{aad}: The associated data (AAD) to be authenticated but not encrypted.

@var{plaintext}: The plaintext data to be encrypted and authenticated.

@var{ciphertext}: A pointer to a gnutls_datum_t structure where the resulting ciphertext will be stored.

This function performs the sealing operation of HPKE. It encrypts
the plaintext and computes an authentication tag using the AEAD
algorithm specified in the HPKE context. The resulting ciphertext
includes both the encrypted plaintext and the authentication tag.

This function can be used multiple times with the same HPKE
context, but the encapsulation function (@code{gnutls_hpke_encap()} ) must
be called once before the first call to this function to set up the
necessary keys and nonces in the context. Each call to this
function will increment the sequence number in the context, which
is used to derive unique nonces for each encryption operation.

The function will allocate memory for the  @code{ciphertext} , and the
caller is responsible for freeing this memory using @code{gnutls_free()} 
when it is no longer needed.

@strong{Returns:} 0 on success, or a negative error code on failure

@strong{Since:} 3.8.13
@end deftypefun

