From d23ceada62bc8cc1d4a3e76100f0101bff37078f Mon Sep 17 00:00:00 2001 From: Krzysztof Jackiewicz Date: Fri, 17 Jun 2016 12:48:23 +0200 Subject: [PATCH] ACR: Modify remarks related to pointer/handle cleanup Change-Id: Id2e9136a8d896ff8036a9aa5096b617454b5c609 --- api/yaca/yaca_crypto.h | 20 ++++++++++++++------ api/yaca/yaca_digest.h | 4 +++- api/yaca/yaca_encrypt.h | 8 ++++++-- api/yaca/yaca_key.h | 16 ++++++++++++---- api/yaca/yaca_seal.h | 14 ++++++++++---- api/yaca/yaca_sign.h | 16 ++++++++++++---- api/yaca/yaca_simple.h | 18 ++++++++++++------ 7 files changed, 69 insertions(+), 27 deletions(-) diff --git a/api/yaca/yaca_crypto.h b/api/yaca/yaca_crypto.h index d95a7c2..17ad90b 100644 --- a/api/yaca/yaca_crypto.h +++ b/api/yaca/yaca_crypto.h @@ -78,6 +78,8 @@ int yaca_cleanup(void); * * @since_tizen 3.0 * + * @remarks The @a memory should be freed using yaca_free() + * * @param[in] size Size of the allocation (bytes) * @param[out] memory Allocated memory * @@ -97,6 +99,8 @@ int yaca_malloc(size_t size, void **memory); * * @since_tizen 3.0 * + * @remarks The @a memory should be freed using yaca_free() + * * @param[in] size Size of the allocation (bytes) * @param[out] memory Allocated memory * @@ -116,11 +120,13 @@ int yaca_zalloc(size_t size, void **memory); * * @since_tizen 3.0 * - * @remarks In case of failure the function doesn't free the memory pointed by @b memory. + * @remarks In case of failure the function doesn't free the memory pointed by @a memory. * - * @remarks If @b *memory is NULL then the call is equivalent to yaca_malloc(). + * @remarks If @a *memory is NULL then the call is equivalent to yaca_malloc(). * - * @remarks If the function fails the contents of @b memory will be left unchanged. + * @remarks If the function fails the contents of @a memory will be left unchanged. + * + * @remarks The @a memory should be freed using yaca_free() * * @param[in] size Size of the new allocation (bytes) * @param[in,out] memory Memory to be reallocated @@ -154,7 +160,7 @@ int yaca_realloc(size_t size, void **memory); int yaca_free(void *memory); /** - * @brief Safely compares first @b len bytes of two buffers. + * @brief Safely compares first @a len bytes of two buffers. * * @since_tizen 3.0 * @@ -214,9 +220,11 @@ int yaca_context_set_property(yaca_context_h ctx, * * @since_tizen 3.0 * + * @remarks The @a value should be freed using yaca_free() + * * @param[in] ctx Previously initialized crypto context * @param[in] property Property to be read - * @param[out] value Copy of the property value (must be freed with yaca_free()) + * @param[out] value Copy of the property value * @param[out] value_len Length of the property value will be returned here * * @return #YACA_ERROR_NONE on success, negative on error @@ -259,7 +267,7 @@ int yaca_context_destroy(yaca_context_h ctx); * * @remarks This function can be used to learn the required size of the output buffer * for a single operation (eg. *_update or *_finalize). In case the operation - * has no input (eg. *_finalize), the value of @b input_len has to be set to 0. + * has no input (eg. *_finalize), the value of @a input_len has to be set to 0. * * @param[in] ctx Previously initialized crypto context * @param[in] input_len Length of the input data to be processed diff --git a/api/yaca/yaca_digest.h b/api/yaca/yaca_digest.h index 622928b..6a66a6f 100644 --- a/api/yaca/yaca_digest.h +++ b/api/yaca/yaca_digest.h @@ -43,7 +43,9 @@ extern "C" { * * @since_tizen 3.0 * - * @param[out] ctx Newly created context (must be freed with yaca_context_destroy()) + * @remarks The @a ctx should be released using yaca_context_destroy() + * + * @param[out] ctx Newly created context * @param[in] algo Digest algorithm that will be used * * @return #YACA_ERROR_NONE on success, negative on error diff --git a/api/yaca/yaca_encrypt.h b/api/yaca/yaca_encrypt.h index c87d048..d2425d4 100644 --- a/api/yaca/yaca_encrypt.h +++ b/api/yaca/yaca_encrypt.h @@ -68,7 +68,9 @@ int yaca_encrypt_get_iv_bit_length(yaca_encrypt_algorithm_e algo, * * @since_tizen 3.0 * - * @param[out] ctx Newly created context (must be freed with yaca_context_destroy()) + * @remarks The @a ctx should be released using yaca_context_destroy() + * + * @param[out] ctx Newly created context * @param[in] algo Encryption algorithm that will be used * @param[in] bcm Chaining mode that will be used * @param[in] sym_key Symmetric key that will be used @@ -152,7 +154,9 @@ int yaca_encrypt_finalize(yaca_context_h ctx, * * @since_tizen 3.0 * - * @param[out] ctx Newly created context (must be freed with yaca_context_destroy()) + * @remarks The @a ctx should be released using yaca_context_destroy() + * + * @param[out] ctx Newly created context * @param[in] algo Encryption algorithm that was used to encrypt the data * @param[in] bcm Chaining mode that was used to encrypt the data * @param[in] sym_key Symmetric key that was used to encrypt the data diff --git a/api/yaca/yaca_key.h b/api/yaca/yaca_key.h index 5f0aa1b..4ad7ff4 100644 --- a/api/yaca/yaca_key.h +++ b/api/yaca/yaca_key.h @@ -95,11 +95,13 @@ int yaca_key_get_bit_length(const yaca_key_h key, size_t *key_bit_len); * used. If it's not known if the key is encrypted one should pass NULL as * password and check for the #YACA_ERROR_INVALID_PASSWORD return code. * + * @remarks The @a key should be released using yaca_key_destroy() + * * @param[in] key_type Type of the key * @param[in] password null terminated password for the key (can be NULL) * @param[in] data Blob containing the key * @param[in] data_len Size of the blob - * @param[out] key Returned key (must be freed with yaca_key_destroy()) + * @param[out] key Returned key * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful @@ -183,9 +185,11 @@ int yaca_key_export(const yaca_key_h key, * - RSA: length >= 256bits * - DSA: length >= 512bits, multiple of 64 * + * @remarks The @a key should be released using yaca_key_destroy() + * * @param[in] key_type Type of the key to be generated * @param[in] key_bit_len Length of the key (in bits) to be generated - * @param[out] key Newly generated key (must be freed with yaca_key_destroy()) + * @param[out] key Newly generated key * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful @@ -207,8 +211,10 @@ int yaca_key_generate(yaca_key_type_e key_type, * * @since_tizen 3.0 * + * @remarks The @a pub_key should be released using yaca_key_destroy() + * * @param[in] prv_key Private key to extract the public one from - * @param[out] pub_key Extracted public key (must be freed with yaca_key_destroy()) + * @param[out] pub_key Extracted public key * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful @@ -252,13 +258,15 @@ int yaca_key_destroy(yaca_key_h key); * * @since_tizen 3.0 * + * @remarks The @a key should be released using yaca_key_destroy() + * * @param[in] password User password as a NULL-terminated string * @param[in] salt Salt, should be a non-empty string * @param[in] salt_len Length of the salt * @param[in] iterations Number of iterations * @param[in] algo Digest algorithm that should be used in key generation * @param[in] key_bit_len Length of a key (in bits) to be generated - * @param[out] key Newly generated key (must be freed with yaca_key_destroy()) + * @param[out] key Newly generated key * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful diff --git a/api/yaca/yaca_seal.h b/api/yaca/yaca_seal.h index 2171130..72d090e 100644 --- a/api/yaca/yaca_seal.h +++ b/api/yaca/yaca_seal.h @@ -49,18 +49,22 @@ extern "C" { * so can be ONLY used with yaca_open_initialize(). It can be exported, * but after import it can be ONLY used with yaca_open_initialize() as well. * + * @remarks The @a ctx should be released using yaca_context_destroy() + * + * @remarks The @a sym_key should be released using yaca_key_destroy() + * + * @remarks The @a iv should be released using yaca_key_destroy() + * * @since_tizen 3.0 * - * @param[out] ctx Newly created context (must be freed with yaca_context_destroy()) + * @param[out] ctx Newly created context * @param[in] pub_key Public key of the peer that will receive the encrypted data * @param[in] algo Symmetric algorithm that will be used * @param[in] bcm Block chaining mode for the symmetric algorithm * @param[in] sym_key_bit_len Symmetric key length (in bits) that will be generated * @param[out] sym_key Generated symmetric key that will be used, * it is encrypted with peer's public key - * (must be freed with yaca_key_destroy()) * @param[out] iv Generated initialization vector that will be used - * (must be freed with yaca_key_destroy()) * * @return #YACA_ERROR_NONE on success, negative on error * @retval #YACA_ERROR_NONE Successful @@ -145,7 +149,9 @@ int yaca_seal_finalize(yaca_context_h ctx, * * @since_tizen 3.0 * - * @param[out] ctx Newly created context (must be freed by yaca_context_destroy()) + * @remarks The @a ctx should be released using yaca_context_destroy() + * + * @param[out] ctx Newly created context * @param[in] prv_key Private key, part of the pair that was used for the encryption * @param[in] algo Symmetric algorithm that was used for the encryption * @param[in] bcm Block chaining mode for the symmetric algorithm diff --git a/api/yaca/yaca_sign.h b/api/yaca/yaca_sign.h index 2d9206f..a5267d8 100644 --- a/api/yaca/yaca_sign.h +++ b/api/yaca/yaca_sign.h @@ -46,7 +46,9 @@ extern "C" { * @remarks For verification use yaca_verify_initialize(), yaca_verify_update() and * yaca_verify_finalize() functions with matching public key. * - * @param[out] ctx Newly created context (must be freed with yaca_context_destroy()) + * @remarks The @a ctx should be released using yaca_context_destroy() + * + * @param[out] ctx Newly created context * @param[in] algo Digest algorithm that will be used * @param[in] key Private key that will be used, algorithm is deduced based * on key type, supported key types: @@ -81,7 +83,9 @@ int yaca_sign_initialize(yaca_context_h *ctx, * @remarks For verification, calculate message HMAC and compare with received MAC using * yaca_memcmp(). * - * @param[out] ctx Newly created context (must be freed with yaca_context_destroy()) + * @remarks The @a ctx should be released using yaca_context_destroy() + * + * @param[out] ctx Newly created context * @param[in] algo Digest algorithm that will be used * @param[in] key Symmetric key that will be used, supported key types: * - #YACA_KEY_TYPE_SYMMETRIC, @@ -113,7 +117,9 @@ int yaca_sign_initialize_hmac(yaca_context_h *ctx, * @remarks For verification, calculate message CMAC and compare with received MAC using * yaca_memcmp(). * - * @param[out] ctx Newly created context (must be freed with yaca_context_destroy()) + * @remarks The @a ctx should be released using yaca_context_destroy() + * + * @param[out] ctx Newly created context * @param[in] algo Encryption algorithm that will be used * @param[in] key Symmetric key that will be used, supported key types: * - #YACA_KEY_TYPE_SYMMETRIC, @@ -194,7 +200,9 @@ int yaca_sign_finalize(yaca_context_h ctx, * * @since_tizen 3.0 * - * @param[out] ctx Newly created context (must be freed with yaca_context_destroy()) + * @remarks The @a ctx should be released using yaca_context_destroy() + * + * @param[out] ctx Newly created context * @param[in] algo Digest algorithm that will be used * @param[in] key Public key that will be used, algorithm is deduced based on * key type, supported key types: diff --git a/api/yaca/yaca_simple.h b/api/yaca/yaca_simple.h index 5dd2b13..86f2f88 100644 --- a/api/yaca/yaca_simple.h +++ b/api/yaca/yaca_simple.h @@ -50,11 +50,12 @@ extern "C" { * * @since_tizen 3.0 * + * @remarks The @a digest should be freed using yaca_free() + * * @param[in] algo Digest algorithm (select #YACA_DIGEST_SHA256 if unsure) * @param[in] data Data from which the digest is to be calculated * @param[in] data_len Length of the data * @param[out] digest Message digest, will be allocated by the library - * (should be freed with yaca_free()) * @param[out] digest_len Length of message digest (depends on algorithm) * * @return #YACA_ERROR_NONE on success, negative on error @@ -78,6 +79,8 @@ int yaca_simple_calculate_digest(yaca_digest_algorithm_e algo, * * @since_tizen 3.0 * + * @remarks The @a ciphertext should be freed using yaca_free() + * * @param[in] algo Encryption algorithm (select #YACA_ENCRYPT_AES if unsure) * @param[in] bcm Chaining mode (select #YACA_BCM_CBC if unsure) * @param[in] sym_key Symmetric encryption key (see key.h for key generation functions) @@ -85,7 +88,6 @@ int yaca_simple_calculate_digest(yaca_digest_algorithm_e algo, * @param[in] plaintext Plaintext to be encrypted * @param[in] plaintext_len Length of the plaintext * @param[out] ciphertext Encrypted data, will be allocated by the library - * (should be freed with yaca_free()) * @param[out] ciphertext_len Length of the encrypted data (may be larger than decrypted) * * @return #YACA_ERROR_NONE on success, negative on error @@ -114,6 +116,8 @@ int yaca_simple_encrypt(yaca_encrypt_algorithm_e algo, * * @since_tizen 3.0 * + * @remarks The @a plaintext should be freed using yaca_free() + * * @param[in] algo Decryption algorithm that was used to encrypt the data * @param[in] bcm Chaining mode that was used to encrypt the data * @param[in] sym_key Symmetric encryption key that was used to encrypt the data @@ -121,7 +125,6 @@ int yaca_simple_encrypt(yaca_encrypt_algorithm_e algo, * @param[in] ciphertext Ciphertext to be decrypted * @param[in] ciphertext_len Length of ciphertext * @param[out] plaintext Decrypted data, will be allocated by the library - * (should be freed with yaca_free()) * @param[out] plaintext_len Length of the decrypted data * * @return #YACA_ERROR_NONE on success, negative on error @@ -150,6 +153,8 @@ int yaca_simple_decrypt(yaca_encrypt_algorithm_e algo, * * @since_tizen 3.0 * + * @remarks The @a signature should be freed using yaca_free() + * * @param[in] algo Digest algorithm that will be used * @param[in] key Private key that will be used, algorithm is * deduced based on key type, supported key types: @@ -158,7 +163,6 @@ int yaca_simple_decrypt(yaca_encrypt_algorithm_e algo, * @param[in] data Data to be signed * @param[in] data_len Length of the data * @param[out] signature Message signature, will be allocated by the - * library (should be freed with yaca_free()) * @param[out] signature_len Length of the signature * * @return #YACA_ERROR_NONE on success, negative on error @@ -222,6 +226,8 @@ int yaca_simple_verify_signature(yaca_digest_algorithm_e algo, * @remarks For verification, calculate message HMAC and compare with received MAC using * yaca_memcmp(). * + * @remarks The @a mac should be freed using yaca_free() + * * @param[in] algo Digest algorithm that will be used * @param[in] key Key that will be used, supported key types: * - #YACA_KEY_TYPE_SYMMETRIC, @@ -229,7 +235,6 @@ int yaca_simple_verify_signature(yaca_digest_algorithm_e algo, * @param[in] data Data to calculate HMAC from * @param[in] data_len Length of the data * @param[out] mac MAC, will be allocated by the library - * (should be freed with yaca_free()) * @param[out] mac_len Length of the MAC * * @return #YACA_ERROR_NONE on success, negative on error @@ -259,6 +264,8 @@ int yaca_simple_calculate_hmac(yaca_digest_algorithm_e algo, * @remarks For verification, calculate message CMAC and compare with received MAC using * yaca_memcmp(). * + * @remarks The @a mac should be freed using yaca_free() + * * @param[in] algo Encryption algorithm that will be used * @param[in] key Key that will be used, supported key types: * - #YACA_KEY_TYPE_SYMMETRIC, @@ -266,7 +273,6 @@ int yaca_simple_calculate_hmac(yaca_digest_algorithm_e algo, * @param[in] data Data to calculate CMAC from * @param[in] data_len Length of the data * @param[out] mac MAC, will be allocated by the library - * (should be freed with yaca_free()) * @param[out] mac_len Length of the MAC * * @return #YACA_ERROR_NONE on success, negative on error -- 2.7.4