From: Daiki Ueno Date: Mon, 20 Apr 2026 13:39:50 +0000 (+0900) Subject: hpke: fix documentation comments X-Git-Tag: 3.8.13~2^2~9 X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=099d0978dc773e9524918b1f7652dcaa62026e1b;p=thirdparty%2Fgnutls.git hpke: fix documentation comments Signed-off-by: Daiki Ueno --- diff --git a/lib/hpke/hpke.c b/lib/hpke/hpke.c index d0cd75f910..d96719e819 100644 --- a/lib/hpke/hpke.c +++ b/lib/hpke/hpke.c @@ -14,7 +14,6 @@ * 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 @@ -685,11 +684,15 @@ cleanup: * @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, @@ -732,7 +735,9 @@ int gnutls_hpke_init(gnutls_hpke_context_t *ctx, gnutls_hpke_mode_t mode, * 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) { @@ -756,25 +761,40 @@ 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, @@ -881,23 +901,28 @@ static void get_seq_nonce(const gnutls_datum_t *base_nonce, uint64_t seq, /** * 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, @@ -989,25 +1014,39 @@ cleanup: /** * 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, @@ -1097,24 +1136,34 @@ cleanup: /** * 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, @@ -1201,17 +1250,19 @@ cleanup: 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) { @@ -1254,16 +1305,24 @@ int _gnutls_hpke_set_ikme(gnutls_hpke_context_t ctx, const gnutls_datum_t *ikme) * 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) @@ -1282,17 +1341,19 @@ int gnutls_hpke_derive_keypair(gnutls_hpke_kem_t kem, const gnutls_datum_t *ikm, 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) { @@ -1306,23 +1367,30 @@ int _gnutls_hpke_get_seq(gnutls_hpke_context_t ctx, uint64_t *seq) /** * 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) { @@ -1354,7 +1422,7 @@ int gnutls_hpke_export(gnutls_hpke_context_t ctx, 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); @@ -1362,19 +1430,19 @@ int gnutls_hpke_export(gnutls_hpke_context_t ctx, 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; } diff --git a/lib/includes/gnutls/hpke.h b/lib/includes/gnutls/hpke.h index 3bf980959e..f083ea0312 100644 --- a/lib/includes/gnutls/hpke.h +++ b/lib/includes/gnutls/hpke.h @@ -135,7 +135,7 @@ int gnutls_hpke_derive_keypair(gnutls_hpke_kem_t kem, const gnutls_datum_t *ikm, gnutls_pubkey_t pubkey); 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); #ifdef __cplusplus