Detailed documentation for encryption/decryption API

[Problem] The encryption/decryption API documentation in header file wasn't
detailed enough.
[Solution] Add more more details.

[Verification] Rate intelligibility of documentation

Change-Id: I2695651928ccf294e94fed2e4c2d0a4019365582

diff --git a/src/include/ckmc/ckmc-manager.h b/src/include/ckmc/ckmc-manager.h
index d7ccd59..35a3413 100644 (file)
--- a/src/include/ckmc/ckmc-manager.h
+++ b/src/include/ckmc/ckmc-manager.h
@@ -1095,12 +1095,16 @@ int ckmc_remove_alias(const char *alias);
  *
  * @remarks Key identified by @a key_alias should exist.
  *
- * @param[in] params            Algorithm parameter list handle
+ * @param[in] params            Algorithm parameter list handle. See #ckmc_param_list_h and
+ *                              #ckmc_algo_type_e for details
  * @param[in] key_alias         Alias of the key to be used for encryption
  * @param[in] password          The password used in decrypting a key value \n
  *                              If password of policy is provided in ckmc_save_key(), the same
  *                              password should be provided
- * @param[in] decrypted         Data to be encrypted
+ * @param[in] decrypted         Data to be encrypted. In case of AES algorithm there are no
+ *                              restrictions on the size of data. For RSA the size must be smaller
+ *                              or equal to <key_size_in bytes> - 42. Example: for 1024 RSA key the
+ *                              maximum data size is 1024/8 - 42 = 86.
  * @param[out] ppencrypted      Encrypted data (some algorithms may return additional information
  *                              embedded in encrypted data. AES GCM is an example) \n
  *                              The caller is responsible for freeing @a encrypted with
@@ -1109,7 +1113,9 @@ int ckmc_remove_alias(const char *alias);
  * @return @c 0 on success, otherwise a negative error value
  *
  * @retval #CKMC_ERROR_NONE                 Successful
- * @retval #CKMC_ERROR_INVALID_PARAMETER    Input parameter is invalid
+ * @retval #CKMC_ERROR_INVALID_PARAMETER    Input parameter is invalid (missing or invalid
+ *                                          mandatory algorithm parameter, decrypted = NULL,
+ *                                          ppencrypted = NULL)
  * @retval #CKMC_ERROR_DB_LOCKED            A user key is not loaded in memory (a user is not logged
  *                                          in)
  * @retval #CKMC_ERROR_DB_ERROR             Failed due to the error with unknown reason
@@ -1128,6 +1134,7 @@ int ckmc_remove_alias(const char *alias);
  * @see ckmc_generate_new_params()
  * @see #ckmc_param_list_h
  * @see #ckmc_param_name_e
+ * @see #ckmc_algo_type_e
  */
 int ckmc_encrypt_data(ckmc_param_list_h params,
                       const char *key_alias,
@@ -1142,7 +1149,9 @@ int ckmc_encrypt_data(ckmc_param_list_h params,
  *
  * @remarks Key identified by @a key_alias should exist.
  *
- * @param[in] params            Algorithm parameter list handle
+ * @param[in] params            Algorithm parameter list handle. You should use the same parameters
+ *                              that were used for encryption. See #ckmc_param_list_h and
+ *                              #ckmc_algo_type_e for details
  * @param[in] key_alias         Alias of the key to be used for encryption
  * @param[in] password          The password used in decrypting a key value \n
  *                              If password of policy is provided in ckmc_save_key(), the same
@@ -1156,7 +1165,9 @@ int ckmc_encrypt_data(ckmc_param_list_h params,
  * @return @c 0 on success, otherwise a negative error value
  *
  * @retval #CKMC_ERROR_NONE                 Successful
- * @retval #CKMC_ERROR_INVALID_PARAMETER    Input parameter is invalid
+ * @retval #CKMC_ERROR_INVALID_PARAMETER    Input parameter is invalid (missing or invalid
+ *                                          mandatory algorithm parameter, encrypted = NULL,
+ *                                          ppdecrypted = NULL)
  * @retval #CKMC_ERROR_DB_LOCKED            A user key is not loaded in memory (a user is not logged
  *                                          in)
  * @retval #CKMC_ERROR_DB_ERROR             Failed due to the error with unknown reason
@@ -1175,6 +1186,7 @@ int ckmc_encrypt_data(ckmc_param_list_h params,
  * @see ckmc_generate_new_params()
  * @see #ckmc_param_list_h
  * @see #ckmc_param_name_e
+ * @see #ckmc_algo_type_e
  */
 int ckmc_decrypt_data(ckmc_param_list_h params,
                       const char *key_alias,

diff --git a/src/include/ckmc/ckmc-type.h b/src/include/ckmc/ckmc-type.h
index 507d223..997ed96 100644 (file)
--- a/src/include/ckmc/ckmc-type.h
+++ b/src/include/ckmc/ckmc-type.h
@@ -264,6 +264,19 @@ typedef enum __ckmc_param_name {
 /**
  * @brief Handle for algorithm parameter list.
  * @since_tizen 3.0
+ *
+ * Each parameter list must have at least one CKMC_PARAM_ALGO_TYPE parameter that identifies the
+ * algorithm. See #ckmc_algo_type_e for available algorithms and additional parameters they support.
+ *
+ * @see ckmc_generate_new_params()
+ * @see ckmc_param_list_new()
+ * @see ckmc_param_list_set_integer()
+ * @see ckmc_param_list_set_buffer()
+ * @see ckmc_param_list_get_integer()
+ * @see ckmc_param_list_get_buffer()
+ * @see ckmc_param_list_free()
+ * @see #ckmc_algo_type_e
+ * @see #ckmc_param_name_e
  */
 typedef struct __ckmc_param_list *ckmc_param_list_h;
 
@@ -276,31 +289,35 @@ typedef struct __ckmc_param_list *ckmc_param_list_h;
 typedef enum __ckmc_algo_type {
     CKMC_ALGO_AES_CTR = 1,   /**< AES-CTR algorithm
                                   Supported parameters:
-                                  - CKMC_PARAM_ALGO_TYPE,
-                                  - CKMC_PARAM_ED_IV
-                                  - CKMC_PARAM_ED_CTR_LEN (128 only) */
+                                  - CKMC_PARAM_ALGO_TYPE = CKMC_ALGO_AES_CTR(mandatory),
+                                  - CKMC_PARAM_ED_IV = 16-byte initialization vector(mandatory)
+                                  - CKMC_PARAM_ED_CTR_LEN = length of counter block in bits
+                                    (optional, only 128b is supported at the moment) */
 
     CKMC_ALGO_AES_CBC,       /**< AES-CBC algorithm
                                   Supported parameters:
-                                  - CKMC_PARAM_ALGO_TYPE,
-                                  - CKMC_PARAM_ED_IV */
+                                  - CKMC_PARAM_ALGO_TYPE = CKMC_ALGO_AES_CBC(mandatory),
+                                  - CKMC_PARAM_ED_IV = 16-byte initialization vector(mandatory) */
 
     CKMC_ALGO_AES_GCM,       /**< AES-GCM algorithm
                                   Supported parameters:
-                                  - CKMC_PARAM_ALGO_TYPE,
-                                  - CKMC_PARAM_ED_IV
-                                  - CKMC_PARAM_ED_TAG_LEN
-                                  - CKMC_PARAM_ED_AAD */
+                                  - CKMC_PARAM_ALGO_TYPE = CKMC_ALGO_AES_GCM(mandatory),
+                                  - CKMC_PARAM_ED_IV = initialization vector(mandatory)
+                                  - CKMC_PARAM_ED_TAG_LEN = GCM tag length in bits. One of
+                                    {32, 64, 96, 104, 112, 120, 128} (optional, if not present the
+                                    length 128 is used)
+                                  - CKMC_PARAM_ED_AAD = additional authentication data(optional) */
 
     CKMC_ALGO_AES_CFB,       /**< AES-CFB algorithm
                                   Supported parameters:
-                                  - CKMC_PARAM_ALGO_TYPE,
-                                  - CKMC_PARAM_ED_IV */
+                                  - CKMC_PARAM_ALGO_TYPE = CKMC_ALGO_AES_CFB(mandatory),
+                                  - CKMC_PARAM_ED_IV = 16-byte initialization vector(mandatory) */
 
     CKMC_ALGO_RSA_OAEP       /**< RSA-OAEP algorithm
                                   Supported parameters:
-                                  - CKMC_PARAM_ALGO_TYPE,
-                                  - CKMC_PARAM_ED_LABEL */
+                                  - CKMC_PARAM_ALGO_TYPE = CKMC_ALGO_RSA_OAEP(required),
+                                  - CKMC_PARAM_ED_LABEL = label to be associated with the message
+                                    (optional, not supported at the moment) */
 } ckmc_algo_type_e;
 
 /**
@@ -746,6 +763,7 @@ void ckmc_cert_list_all_free(ckmc_cert_list_s *first);
  * @see ckmc_generate_new_params()
  * @see #ckmc_param_list_h
  * @see #ckmc_param_name_e
+ * @see #ckmc_algo_type_e
  */
 int ckmc_param_list_new(ckmc_param_list_h *pparams);
 
@@ -778,6 +796,7 @@ int ckmc_param_list_new(ckmc_param_list_h *pparams);
  * @see ckmc_generate_new_params()
  * @see #ckmc_param_list_h
  * @see #ckmc_param_name_e
+ * @see #ckmc_algo_type_e
  */
 int ckmc_param_list_set_integer(ckmc_param_list_h params,
                                 ckmc_param_name_e name,
@@ -813,6 +832,7 @@ int ckmc_param_list_set_integer(ckmc_param_list_h params,
  * @see ckmc_generate_new_params()
  * @see #ckmc_param_list_h
  * @see #ckmc_param_name_e
+ * @see #ckmc_algo_type_e
  */
 int ckmc_param_list_set_buffer(ckmc_param_list_h params,
                                ckmc_param_name_e name,
@@ -845,6 +865,7 @@ int ckmc_param_list_set_buffer(ckmc_param_list_h params,
  * @see ckmc_generate_new_params()
  * @see #ckmc_param_list_h
  * @see #ckmc_param_name_e
+ * @see #ckmc_algo_type_e
  */
 
 int ckmc_param_list_get_integer(ckmc_param_list_h params,
@@ -880,6 +901,7 @@ int ckmc_param_list_get_integer(ckmc_param_list_h params,
  * @see ckmc_buffer_free()
  * @see #ckmc_param_list_h
  * @see #ckmc_param_name_e
+ * @see #ckmc_algo_type_e
  */
 int ckmc_param_list_get_buffer(ckmc_param_list_h params,
                                ckmc_param_name_e name,
@@ -900,6 +922,7 @@ int ckmc_param_list_get_buffer(ckmc_param_list_h params,
  * @see ckmc_generate_new_params()
  * @see #ckmc_param_list_h
  * @see #ckmc_param_name_e
+ * @see #ckmc_algo_type_e
  */
 void ckmc_param_list_free(ckmc_param_list_h params);
 
@@ -931,6 +954,7 @@ void ckmc_param_list_free(ckmc_param_list_h params);
  * @see ckmc_param_list_free()
  * @see #ckmc_param_list_h
  * @see #ckmc_param_name_e
+ * @see #ckmc_algo_type_e
  */
 int ckmc_generate_new_params(ckmc_algo_type_e type, ckmc_param_list_h *pparams);