* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
-
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>
* @kem: The KEM algorithm to use (e.g., DHKEM(X25519)).
* @kdf: The KDF algorithm to use (e.g., HKDF-SHA256).
* @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 gnutls_hpke_deinit() when it
* is no longer needed to free any allocated resources and securely erase sensitive information.
+ *
* Returns: 0 on success, or a negative error code on failure
+ * Since: 3.8.13
*/
int gnutls_hpke_init(gnutls_hpke_context_t *ctx, gnutls_hpke_mode_t mode,
gnutls_hpke_role_t role, gnutls_hpke_kem_t kem,
* 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.
+ *
* Returns: 0 on success, or a negative error code on failure.
+ * Since: 3.8.13
*/
int gnutls_hpke_deinit(gnutls_hpke_context_t ctx)
{
/**
* gnutls_hpke_encap:
* @ctx: The HPKE context to use for encapsulation.
- * @info: A pointer to a gnutls_datum_t structure containing the application-specific information to be included in the
- * key schedule. This parameter is optional and can be NULL if no additional information is needed.
- * @enc: A pointer to a gnutls_datum_t structure where the encapsulated key will be stored. The function will allocate
- * memory for the encapsulated key, and the caller is responsible for freeing this memory using gnutls_free() when it is
- * no longer needed.
- * @receiver_pubkey: The receiver's public key to use for encapsulation. This must be a valid public key that is
- * compatible with the KEM algorithm specified in the HPKE context.
+ * @info: The application-specific information to be included in the key schedule (optional).
+ * @enc: A pointer to a gnutls_datum_t structure where the encapsulated key will be stored.
+ * @receiver_pubkey: The receiver's public key to use for encapsulation.
* @sender_privkey: The sender's private key needed for AuthEncap operation (optional).
* @psk: The pre-shared key (optional).
* @psk_id: The pre-shared key identifier (optional).
*
- * This function performs the encapsulation operation of HPKE. It generates an encapsulated key (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
- * (Sender) for encapsulation.
+ * This function performs the encapsulation operation of HPKE. It
+ * generates an encapsulated key (@enc) that can be sent to the
+ * receiver, who can then use it to derive the shared secret.
*
- * This function must be used once per HPKE context and before any calls to gnutls_hpke_seal().
+ * 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 (%GNUTLS_HPKE_ROLE_SENDER) for
+ * encapsulation.
*
- * It returns 0 on success, or a negative error code on failure.
+ * This function must be used once per HPKE context and before any
+ * calls to gnutls_hpke_seal().
+ *
+ * The function will allocate memory for @enc, and the caller is
+ * responsible for freeing this memory using gnutls_free() when it is
+ * no longer needed.
+ *
+ * @receiver_pubkey must be a valid public key that is compatible with
+ * the KEM algorithm specified in the HPKE context.
+ *
+ * For %GNUTLS_HPKE_MODE_AUTH or %GNUTLS_HPKE_MODE_AUTH_PSK,
+ * @sender_privkey must be a valid private key that can be used for
+ * authentication. For %GNUTLS_HPKE_MODE_PSK or
+ * %GNUTLS_HPKE_MODE_AUTH_PSK, a pre-shared key (@psk) and its
+ * identifier (@psk_id) must be supplied.
+ *
+ * Returns: 0 on success, or a negative error code on failure
+ * Since: 3.8.13
*/
int gnutls_hpke_encap(gnutls_hpke_context_t ctx, const gnutls_datum_t *info,
gnutls_datum_t *enc,
/**
* gnutls_hpke_seal:
* @ctx: The HPKE context to use for sealing.
- * @aad: A pointer to a gnutls_datum_t structure containing the associated data (AAD) to be authenticated but not
- * encrypted.
- * @plaintext: A pointer to a gnutls_datum_t structure containing the plaintext data to be encrypted and authenticated.
- * @ciphertext: A pointer to a gnutls_datum_t structure where the resulting ciphertext will be stored. The function will
- * allocate memory for the ciphertext, and the caller is responsible for freeing this memory using gnutls_free() when it
- * is no longer needed.
+ * @aad: The associated data (AAD) to be authenticated but not encrypted.
+ * @plaintext: The plaintext data to be encrypted and authenticated.
+ * @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 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
- * (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.
+ * This function can be used multiple times with the same HPKE
+ * context, but the encapsulation function (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.
*
- * It returns 0 on success, or a negative error code on failure.
+ * The function will allocate memory for the @ciphertext, and the
+ * caller is responsible for freeing this memory using gnutls_free()
+ * when it is no longer needed.
+ *
+ * Returns: 0 on success, or a negative error code on failure
+ * Since: 3.8.13
*/
int gnutls_hpke_seal(gnutls_hpke_context_t ctx, const gnutls_datum_t *aad,
const gnutls_datum_t *plaintext,
/**
* gnutls_hpke_decap:
* @ctx: The HPKE context to use for decapsulation.
- * @info: A pointer to a gnutls_datum_t structure containing the application-specific information that was included in the
- * key schedule during encapsulation. This parameter is optional and can be NULL if no additional information was used.
- * @enc: A pointer to a gnutls_datum_t structure containing the encapsulated key received from the sender. This should be
- * the same encapsulated key that was generated by gnutls_hpke_encap() on the sender's side.
- * @receiver_privkey: The receiver's private key to use for decapsulation. This 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.
+ * @info: The application-specific information that was included in the key schedule (optional).
+ * @enc: A pointer to a gnutls_datum_t structure containing the encapsulated key received from the sender.
+ * @receiver_privkey: The receiver's private key to use for decapsulation.
* @sender_pubkey: The sender's public key for AuthDecap operation (optional).
* @psk: The pre-shared key (optional).
* @psk_id: The pre-shared key identifier (optional).
*
- * This function performs the decapsulation operation of HPKE. It takes the encapsulated key (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 (info) to set up the necessary keys and nonces in the HPKE
- * context for subsequent sealing and opening operations.
+ * This function performs the decapsulation operation of HPKE. It
+ * takes the encapsulated key (@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 (@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 gnutls_hpke_open().
+ * This function must be used once per HPKE context and before any
+ * calls to gnutls_hpke_open().
*
- * It returns 0 on success, or a negative error code on failure.
+ * @enc should be the same encapsulated key that was generated by
+ * gnutls_hpke_encap() on the sender's side.
+ *
+ * @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 %GNUTLS_HPKE_MODE_AUTH or %GNUTLS_HPKE_MODE_AUTH_PSK,
+ * @sender_pubkey must be a valid public key that can be used for
+ * authentication. For %GNUTLS_HPKE_MODE_PSK or
+ * %GNUTLS_HPKE_MODE_AUTH_PSK, a pre-shared key (@psk) and its
+ * identifier (@psk_id) must be supplied.
+ *
+ * Returns: 0 on success, or a negative error code on failure
+ * Since: 3.8.13
*/
int gnutls_hpke_decap(gnutls_hpke_context_t ctx, const gnutls_datum_t *info,
const gnutls_datum_t *enc,
/**
* gnutls_hpke_open:
* @ctx: The HPKE context to use for opening.
- * @aad: A pointer to a gnutls_datum_t structure containing the associated data (AAD) that was authenticated during
- * sealing. This should be the same AAD that was provided to gnutls_hpke_seal() on the sender's side.
- * @ciphertext: A pointer to a gnutls_datum_t structure containing the ciphertext received from the sender. This should
- * be the same ciphertext that was generated by gnutls_hpke_seal() on the sender's side.
- * @plaintext: A pointer to a gnutls_datum_t structure where the resulting plaintext will be stored. The function will
- * allocate memory for the plaintext, and the caller is responsible for freeing this memory using gnutls_free() when it
- * is no longer needed.
+ * @aad: The associated data (AAD) that was authenticated during sealing.
+ * @ciphertext: The ciphertext received from the sender.
+ * @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 the
- * provided gnutls_datum_t structure. If the decryption or authentication fails, the function securely erases any
- * allocated plaintext and returns an error code.
+ * 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
+ * @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
- * (gnutls_hpke_decap) must be called once before the first call to this function.
+ * This function can be used multiple times with the same HPKE
+ * context, but the decapsulation function (gnutls_hpke_decap()) must
+ * be called once before the first call to this function.
*
- * It returns 0 on success, or a negative error code on failure.
+ * @aad should be the same AAD that was provided to gnutls_hpke_seal()
+ * on the sender's side.
+ *
+ * @ciphertext should be the same ciphertext that was generated by
+ * gnutls_hpke_seal() on the sender's side.
+ *
+ * The function will allocate memory for the @plaintext, and the
+ * caller is responsible for freeing this memory using gnutls_free()
+ * when it is no longer needed.
+ *
+ * Returns: 0 on success, or a negative error code on failure
+ * Since: 3.8.13
*/
int gnutls_hpke_open(gnutls_hpke_context_t ctx, const gnutls_datum_t *aad,
const gnutls_datum_t *ciphertext,
return ret;
}
-/**
+/*-
* _gnutls_hpke_set_ikme:
- * @ctx: The HPKE context to set the IKME for.
- * @ikme: A pointer to a gnutls_datum_t structure containing the IKME value and its size.
+ * @ctx: The HPKE context to set the ikmE for.
+ * @ikme: A pointer to a gnutls_datum_t structure containing the ikmE value and its size.
*
- * This function sets the IKME in the HPKE context. It securely erases any existing IKME in the context before setting
- * the new value. The function checks that the provided IKME is valid and that the context is in a mode that supports
- * IKME and that the role of the context is Sender.
+ * This function sets the ikmE in the HPKE context. It securely erases
+ * any existing ikmE in the context before setting the new value. The
+ * function checks that the provided ikmE is valid and that the
+ * context is in a mode that supports ikmE and that the role of the
+ * context is Sender.
*
* It returns 0 on success, or a negative error code on failure.
- */
+ -*/
int _gnutls_hpke_set_ikme(gnutls_hpke_context_t ctx, const gnutls_datum_t *ikme)
{
if (ctx == NULL || ikme == NULL || ikme->data == NULL) {
* gnutls_hpke_derive_keypair:
* @kem: The KEM algorithm to use for key pair generation.
* @ikm: A pointer to a gnutls_datum_t structure containing the input key material (IKM) to be used for key pair
- * generation. This should be a non-empty byte string that serves as the seed for key pair generation.
+ * generation.
* @privkey: An initialized private key.
* @pubkey: An initialized public key.
*
- * This function generates a key pair (private key and public key) for the specified KEM algorithm using the provided
- * input key material (IKM). The 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.
+ * This function derives a key pair (private key and public key) for
+ * the specified KEM algorithm from the provided input key material
+ * (@ikm).
*
- * It returns 0 on success, or a negative error code on failure.
+ * @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.
+ *
+ * @ikm should be a non-empty byte string that serves as the seed for
+ * key pair generation.
+ *
+ * Returns: 0 on success, or a negative error code on failure
+ * Since: 3.8.13
*/
int gnutls_hpke_derive_keypair(gnutls_hpke_kem_t kem, const gnutls_datum_t *ikm,
gnutls_privkey_t privkey, gnutls_pubkey_t pubkey)
return 0;
}
-/**
+/*-
* _gnutls_hpke_get_seq:
* @ctx: The HPKE context to get the sequence number from.
* @seq: A pointer to a uint64_t variable where the current sequence number will be stored.
*
- * This function retrieves the current sequence number from the HPKE context. The sequence number is used to derive
- * unique nonces for encryption and decryption operations in HPKE. The function checks that the provided parameters are
- * valid and that the context is properly initialized.
+ * This function retrieves the current sequence number from the HPKE
+ * context. The sequence number is used to derive unique nonces for
+ * encryption and decryption operations in HPKE. The function checks
+ * that the provided parameters are valid and that the context is
+ * properly initialized.
*
* It returns 0 on success, or a negative error code on failure.
- */
+ -*/
int _gnutls_hpke_get_seq(gnutls_hpke_context_t ctx, uint64_t *seq)
{
if (ctx == NULL || seq == NULL) {
/**
* gnutls_hpke_export:
* @ctx: The HPKE context to use for exporting the secret.
- * @exporter_context: A pointer to a gnutls_datum_t structure containing the application-specific context to be included
- * in the export.
- * @L: The length in bytes of the secret to be exported. This should be a positive integer that does not exceed the
+ * @exporter_context: The application-specific context to be included in the export.
+ * @length: The requested length in bytes of the secret to be exported.
+ * @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 @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
+ * @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.
+ *
+ * @length should be a positive integer that does not exceed the
* maximum allowed size for HPKE exports.
- * @secret: A pointer to a gnutls_datum_t structure where the exported secret will be stored. The function will allocate
- * memory for the secret, and the caller is responsible for freeing this memory using gnutls_free() when it is no longer
- * needed.
*
- * This function performs the export operation of HPKE. It derives a secret of length L 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 the provided gnutls_datum_t structure. 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.
+ * The function will allocate memory for @secret, and the caller is
+ * responsible for freeing this memory using gnutls_free() when it is
+ * no longer needed.
*
- * It returns 0 on success, or a negative error code on failure.
+ * Returns: 0 on success, or a negative error code on failure
+ * Since: 3.8.13
*/
int gnutls_hpke_export(gnutls_hpke_context_t ctx,
- const gnutls_datum_t *exporter_context, const size_t L,
+ const gnutls_datum_t *exporter_context, size_t length,
gnutls_datum_t *secret)
{
sizeof("sec") - 1 };
_gnutls_hpke_build_expand_info(&suite_id, &export_secret_label,
- exporter_context, L,
+ exporter_context, length,
&labeled_export_info);
const gnutls_mac_algorithm_t mac = _gnutls_hpke_kdf_to_mac(ctx->kdf);
return gnutls_assert_val(GNUTLS_E_INVALID_REQUEST);
}
- secret->data = gnutls_malloc(L);
+ secret->data = gnutls_malloc(length);
if (secret->data == NULL) {
return gnutls_assert_val(GNUTLS_E_MEMORY_ERROR);
}
ret = gnutls_hkdf_expand(mac, &ctx->exporter_secret,
- &labeled_export_info, secret->data, L);
+ &labeled_export_info, secret->data, length);
if (ret < 0) {
_gnutls_free_key_datum(secret);
return gnutls_assert_val(ret);
}
- secret->size = L;
+ secret->size = length;
return 0;
}
projects / thirdparty / gnutls.git / commitdiff
