ACR: Apply changes from API review part 2

Change-Id: I13a1a8e49eef233bf748ea0c871e872f67708ea5

diff --git a/api/yaca/yaca_error.h b/api/yaca/yaca_error.h
index edbbfe7..263f3d7 100644 (file)
--- a/api/yaca/yaca_error.h
+++ b/api/yaca/yaca_error.h
@@ -40,7 +40,7 @@ extern "C" {
  */
 
 /**
- * @brief Error enums
+ * @brief Enumeration of YACA error values.
  *
  * @since_tizen 3.0
  */

diff --git a/api/yaca/yaca_key.h b/api/yaca/yaca_key.h
index f79115f..c5aca0f 100644 (file)
--- a/api/yaca/yaca_key.h
+++ b/api/yaca/yaca_key.h
@@ -39,6 +39,11 @@ extern "C" {
  * @{
  */
 
+/**
+ * @brief  NULL value for yaca_key_h type.
+ *
+ * @since_tizen 3.0
+ */
 #define YACA_KEY_NULL ((yaca_key_h) NULL)
 
 /**
@@ -76,7 +81,7 @@ int yaca_key_get_bits(const yaca_key_h key, size_t *key_bits);
  * @since_tizen 3.0
  *
  * @remarks This function imports a key trying to match it to the key_type specified.
- *          It should autodetect both, key format and file format.
+ *          It should autodetect both the key format and the file format.
  *
  *          For symmetric, IV and DES keys RAW binary format and BASE64 encoded
  *          binary format are supported.
@@ -246,7 +251,7 @@ void yaca_key_free(yaca_key_h key);
  * @since_tizen 3.0
  *
  * @param[in]  password  User password as a NULL-terminated string
- * @param[in]  salt      Salt, should be non-zero
+ * @param[in]  salt      Salt, should be a non-empty string
  * @param[in]  salt_len  Length of the salt
  * @param[in]  iter      Number of iterations
  * @param[in]  algo      Digest algorithm that should be used in key generation

diff --git a/api/yaca/yaca_seal.h b/api/yaca/yaca_seal.h
index cd1eed3..beea34d 100644 (file)
--- a/api/yaca/yaca_seal.h
+++ b/api/yaca/yaca_seal.h
@@ -55,7 +55,9 @@ extern "C" {
  * @param[in]  sym_key_bits  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_free())
  * @param[out] iv            Generated initialization vector that will be used
+ *                           (must be freed with yaca_key_free())
  *
  * @return #YACA_ERROR_NONE on success, negative on error
  * @retval #YACA_ERROR_NONE Successful
@@ -68,6 +70,7 @@ extern "C" {
  * @see #yaca_block_cipher_mode_e
  * @see yaca_seal_update()
  * @see yaca_seal_final()
+ * @see yaca_key_free()
  */
 int yaca_seal_init(yaca_ctx_h *ctx,
                    const yaca_key_h pub_key,

diff --git a/api/yaca/yaca_types.h b/api/yaca/yaca_types.h
index 933e584..15cfe12 100644 (file)
--- a/api/yaca/yaca_types.h
+++ b/api/yaca/yaca_types.h
@@ -51,7 +51,7 @@ typedef struct yaca_ctx_s *yaca_ctx_h;
 typedef struct yaca_key_s *yaca_key_h;
 
 /**
- * @brief Key formats.
+ * @brief Enumeration of YACA key formats.
  *
  * @since_tizen 3.0
  */
@@ -63,46 +63,57 @@ typedef enum {
 } yaca_key_fmt_e;
 
 /**
- * @brief Key file formats.
+ * @brief Enumeration of YACA key file formats.
  *
  * @since_tizen 3.0
  */
 typedef enum {
-       YACA_KEY_FILE_FORMAT_RAW,      /**< key file is in raw binary format, used for symmetric keys */
-       YACA_KEY_FILE_FORMAT_BASE64,   /**< key file is encoded in ASCII-base64, used for symmetric keys */
-       YACA_KEY_FILE_FORMAT_PEM,      /**< key file is in PEM file format, used for asymmetric keys */
-       YACA_KEY_FILE_FORMAT_DER       /**< key file is in DER file format, used for asymmetric keys */
+       /** Key file is in raw binary format, used for symmetric keys */
+       YACA_KEY_FILE_FORMAT_RAW,
+       /** Key file is encoded in ASCII-base64, used for symmetric keys */
+       YACA_KEY_FILE_FORMAT_BASE64,
+       /** Key file is in PEM file format, used for asymmetric keys */
+       YACA_KEY_FILE_FORMAT_PEM,
+       /** Key file is in DER file format, used for asymmetric keys */
+       YACA_KEY_FILE_FORMAT_DER
 } yaca_key_file_fmt_e;
 
 /**
- * @brief Key types, IV is considered as key.
+ * @brief Enumeration of YACA key types, IV is considered as key.
  *
  * @since_tizen 3.0
  */
 typedef enum {
-       YACA_KEY_TYPE_SYMMETRIC,   /**< Generic symmetric cipher KEY */
-       YACA_KEY_TYPE_DES,         /**< DES* key - must be handled differently because of parity bits */
-       YACA_KEY_TYPE_IV,          /**< Initialization Vector for symmetric algorithms */
-
-       YACA_KEY_TYPE_RSA_PUB,     /**< RSA public key */
-       YACA_KEY_TYPE_RSA_PRIV,    /**< RSA private key */
-
-       YACA_KEY_TYPE_DSA_PUB,     /**< Digital Signature Algorithm public key */
-       YACA_KEY_TYPE_DSA_PRIV,    /**< Digital Signature Algorithm private key */
+       /** Generic symmetric cipher KEY */
+       YACA_KEY_TYPE_SYMMETRIC,
+       /** DES* key - must be handled differently because of parity bits */
+       YACA_KEY_TYPE_DES,
+       /** Initialization Vector for symmetric algorithms */
+       YACA_KEY_TYPE_IV,
+
+       /** RSA public key */
+       YACA_KEY_TYPE_RSA_PUB,
+       /** RSA private key */
+       YACA_KEY_TYPE_RSA_PRIV,
+
+       /** Digital Signature Algorithm public key */
+       YACA_KEY_TYPE_DSA_PUB,
+       /** Digital Signature Algorithm private key */
+       YACA_KEY_TYPE_DSA_PRIV,
 } yaca_key_type_e;
 
 /**
- * @brief Key length.
+ * @brief Enumeration of YACA key lengths.
  *        It is possible to use arbitrary integer instead,
  *        this enums are placed here to avoid magic numbers.
  *
  * @since_tizen 3.0
  */
 typedef enum {
-       YACA_KEY_IV_UNSAFE_24BIT = 24,    /**< 24-bit IV */
-       YACA_KEY_IV_64BIT = 64,           /**< 64-bit IV */
-       YACA_KEY_IV_128BIT = 128,         /**< 128-bit IV */
-       YACA_KEY_IV_256BIT = 256,         /**< 256-bit IV */
+       YACA_KEY_IV_UNSAFE_24BIT = 24,
+       YACA_KEY_IV_64BIT = 64,
+       YACA_KEY_IV_128BIT = 128,
+       YACA_KEY_IV_256BIT = 256,
        YACA_KEY_UNSAFE_8BIT = 8,
        YACA_KEY_UNSAFE_40BIT = 40,
        YACA_KEY_UNSAFE_64BIT = 64,
@@ -118,21 +129,27 @@ typedef enum {
 } yaca_key_bits_e;
 
 /**
- * @brief Message digest algorithms.
+ * @brief Enumeration of YACA message digest algorithms.
  *
  * @since_tizen 3.0
  */
 typedef enum {
-       YACA_DIGEST_MD5,      /**< Message digest algorithm MD5  */
-       YACA_DIGEST_SHA1,     /**< Message digest algorithm SHA1  */
-       YACA_DIGEST_SHA224,   /**< Message digest algorithm SHA2, 224bit  */
-       YACA_DIGEST_SHA256,   /**< Message digest algorithm SHA2, 256bit  */
-       YACA_DIGEST_SHA384,   /**< Message digest algorithm SHA2, 384bit  */
-       YACA_DIGEST_SHA512,   /**< Message digest algorithm SHA2, 512bit  */
+       /** Message digest algorithm MD5 */
+       YACA_DIGEST_MD5,
+       /** Message digest algorithm SHA1 */
+       YACA_DIGEST_SHA1,
+       /** Message digest algorithm SHA2, 224bit */
+       YACA_DIGEST_SHA224,
+       /** Message digest algorithm SHA2, 256bit */
+       YACA_DIGEST_SHA256,
+       /** Message digest algorithm SHA2, 384bit */
+       YACA_DIGEST_SHA384,
+       /** Message digest algorithm SHA2, 512bit */
+       YACA_DIGEST_SHA512,
 } yaca_digest_algo_e;
 
 /**
- * @brief Symmetric encryption algorithms.
+ * @brief Enumeration of YACA symmetric encryption algorithms.
  *
  * @since_tizen 3.0
  */
@@ -233,7 +250,7 @@ typedef enum {
 } yaca_enc_algo_e;
 
 /**
- * @brief Chaining modes for block ciphers.
+ * @brief Enumeration of YACA chaining modes for block ciphers.
  *
  * @since_tizen 3.0
  */
@@ -346,34 +363,43 @@ typedef enum {
 
 
 /**
- * @brief Non-standard parameters for algorithms.
+ * @brief Enumeration of YACA non-standard parameters for algorithms.
  *
  * @since_tizen 3.0
  */
 typedef enum {
-       YACA_PARAM_PADDING,      /**< Padding */
-
-       YACA_PARAM_GCM_AAD,      /**< GCM Additional Authentication Data */
-       YACA_PARAM_GCM_TAG,      /**< GCM Tag bits */
-       YACA_PARAM_GCM_TAG_LEN,  /**< GCM Tag length */
-
-       YACA_PARAM_CCM_AAD,      /**< CCM Additional Authentication Data */
-       YACA_PARAM_CCM_TAG,      /**< CCM Tag bits */
-       YACA_PARAM_CCM_TAG_LEN,  /**< CCM Tag length */
+       /** Padding */
+       YACA_PARAM_PADDING,
+
+       /** GCM Additional Authentication Data */
+       YACA_PARAM_GCM_AAD,
+       /** GCM Tag bits */
+       YACA_PARAM_GCM_TAG,
+       /** GCM Tag length */
+       YACA_PARAM_GCM_TAG_LEN,
+
+       /** CCM Additional Authentication Data */
+       YACA_PARAM_CCM_AAD,
+       /** CCM Tag bits */
+       YACA_PARAM_CCM_TAG,
+       /** CCM Tag length */
+       YACA_PARAM_CCM_TAG_LEN
 } yaca_ex_param_e;
 
 /**
- * @brief Paddings supported by Yet Another Crypto API.
+ * @brief Enumeration of YACA paddings.
  *
  * @since_tizen 3.0
  */
 typedef enum {
-       YACA_PADDING_NONE = 0,   /**< total number of data MUST multiple of block size, Default */
-       YACA_PADDING_X931,       /**< RSA X9.31 padding*/
-       YACA_PADDING_PKCS1,      /**< RSA signature/verify operations */
-       YACA_PADDING_PKCS1_PSS,  /**< RSA signature/verify operations */
-       YACA_PADDING_SSLV23,     /**< RSA SSLv23 */
-       YACA_PADDING_PKCS1_OAEP  /**< RSA encrypt/decrypt operations */
+       /** The total number of data bytes MUST be a multiple of block size */
+       YACA_PADDING_NONE = 0,
+       /** RSA X9.31 padding */
+       YACA_PADDING_X931,
+       /** RSA signature/verify operations */
+       YACA_PADDING_PKCS1,
+       /** RSA signature/verify operations */
+       YACA_PADDING_PKCS1_PSS,
 } yaca_padding_e;
 
 /**@}*/