From 984a58ab8ca99964d8be0ba36549d518988c9f34 Mon Sep 17 00:00:00 2001 From: Krzysztof Jackiewicz Date: Wed, 25 Nov 2015 10:19:17 +0100 Subject: 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 --- src/include/ckmc/ckmc-manager.h | 22 +++++++++++++----- src/include/ckmc/ckmc-type.h | 50 ++++++++++++++++++++++++++++++----------- 2 files changed, 54 insertions(+), 18 deletions(-) (limited to 'src/include') diff --git a/src/include/ckmc/ckmc-manager.h b/src/include/ckmc/ckmc-manager.h index d7ccd594..35a3413c 100644 --- 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 - 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 507d223e..997ed96f 100644 --- 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); -- cgit v1.2.3