ACR: Modify remarks related to pointer/handle cleanup

Change-Id: Id2e9136a8d896ff8036a9aa5096b617454b5c609

diff --git a/api/yaca/yaca_crypto.h b/api/yaca/yaca_crypto.h
index d95a7c2..17ad90b 100644 (file)
--- 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 (file)
--- 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 (file)
--- 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 (file)
--- 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 (file)
--- 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 (file)
--- 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 (file)
--- 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