From f93707e7ba4c13728244c67c6e3c50bc7ffb1686 Mon Sep 17 00:00:00 2001 From: Krzysztof Jackiewicz Date: Thu, 6 Apr 2023 15:41:12 +0200 Subject: [PATCH] Fix documentation issues in E2EE API * Issues raised by check-header.py (see: https://github.sec.samsung.net/RPO7-TIZEN/tizen-native-api-review-script) * Other issues raised during ACR. * Own initiative cleanup. Changes done separately to simplify ACR review. Change-Id: I346b979cd16f1cda8a0fd970ae38f7db7bb093d7 --- src/include/ckmc/ckmc-manager.h | 32 ++++++++++--------- src/include/ckmc/ckmc-type.h | 68 ++++++++++++++++++++++------------------- 2 files changed, 54 insertions(+), 46 deletions(-) diff --git a/src/include/ckmc/ckmc-manager.h b/src/include/ckmc/ckmc-manager.h index 03d22f6..dcec32a 100644 --- a/src/include/ckmc/ckmc-manager.h +++ b/src/include/ckmc/ckmc-manager.h @@ -1104,7 +1104,7 @@ int ckmc_decrypt_data(ckmc_param_list_h params, /** * @brief Unwraps one key with another and stores it inside key manager. * - * @since_tizen 7.5 + * @since_tizen 6.5 * * @remarks The wrapping key must be either symmetric (#CKMC_KEY_AES) or private RSA * (#CKMC_KEY_RSA_PRIVATE). @@ -1131,6 +1131,8 @@ int ckmc_decrypt_data(ckmc_param_list_h params, * * @return @c 0 on success, otherwise a negative error value * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager, the + * wrapping key or to create the unwrapped key * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory * algorithm parameter, GCM tag authentication failed, * @a wrapping_key_alias = NULL, @a alias = NULL, @@ -1142,7 +1144,6 @@ int ckmc_decrypt_data(ckmc_param_list_h params, * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Wrapping key decryption failed because * @a wrapping_key_password is incorrect - * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager * @retval #CKMC_ERROR_SERVER_ERROR Unknown error * * @pre User is already logged in and the user key is already loaded into memory in plain text form. @@ -1163,10 +1164,11 @@ int ckmc_import_wrapped_key(const ckmc_param_list_h params, /** * @brief Wraps one key with another and returns it to the client. * - * @since_tizen 7.5 + * @since_tizen 6.5 * * @remarks The wrapping key must be either symmetric (#CKMC_KEY_AES) or public RSA * (#CKMC_KEY_RSA_PUBLIC). + * @remarks The @a ppwrapped_key should be released using ckmc_key_free(). * * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e * for details. Supported algorithms: @@ -1177,22 +1179,23 @@ int ckmc_import_wrapped_key(const ckmc_param_list_h params, * - #CKMC_ALGO_RSA_OAEP * @param[in] wrapping_key_alias The name of the wrapping key * @param[in] wrapping_key_password An optional password of the wrapping key - * @param[in] wrapped_key_alias The name of the key to be wrapped and exported - * @param[in] wrapped_key_password An optional password used to decrypt the key pointed by @a wrapped_key_alias + * @param[in] alias The name of the key to be wrapped and exported + * @param[in] password An optional password used to decrypt the key pointed by @a alias * @param[out] ppwrapped_key The wrapped key * * @return @c 0 on success, otherwise a negative error value * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_PERMISSION_DENIED Insuffucient permissions to access key manager, the + * wrapping key or the key being wrapped * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory * algorithm parameter, GCM tag authentication failed, - * @a wrapping_key_alias = NULL, @a wrapped_key_alias = NULL, + * @a wrapping_key_alias = NULL, @a alias = NULL, * @a ppwrapped_key = NULL) * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in) - * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a wrapping_key_alias or @a wrapped_key_alias does not exist + * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a wrapping_key_alias or @a alias does not exist * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Wrapping key decryption failed because * @a wrapping_key_password is incorrect - * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager * @retval #CKMC_ERROR_SERVER_ERROR Unknown error * * @pre User is already logged in and the user key is already loaded into memory in plain text form. @@ -1204,15 +1207,15 @@ int ckmc_import_wrapped_key(const ckmc_param_list_h params, int ckmc_export_wrapped_key(const ckmc_param_list_h params, const char *wrapping_key_alias, const char *wrapping_key_password, - const char *wrapped_key_alias, - const char *wrapped_key_password, + const char *alias, + const char *password, ckmc_key_s **ppwrapped_key); /** * @brief Derives a key from another key/secret and stores it inside key manager. * - * @since_tizen 7.5 + * @since_tizen 6.5 * * @remarks The derived key will be a symmetric one. It will be stored as a #CKMC_KEY_AES. * @@ -1227,6 +1230,8 @@ int ckmc_export_wrapped_key(const ckmc_param_list_h params, * * @return @c 0 on success, otherwise a negative error value * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager, the secret + * or to create the new key * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory * algorithm parameter, @a secret_alias = NULL, * @a new_key_alias = NULL) @@ -1234,15 +1239,14 @@ int ckmc_export_wrapped_key(const ckmc_param_list_h params, * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a secret_alias does not exist * @retval #CKMC_ERROR_DB_ALIAS_EXISTS @a new_key_alias already exists * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error - * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager - * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Secret decryption failed because @a secret_password is + * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Secret decryption failed because @a secret_password is * incorrect * @retval #CKMC_ERROR_SERVER_ERROR Unknown error * * @pre User is already logged in and the user key is already loaded into memory in plain text form. * * @par Example - * @snippet examples/key_derive.cpp KEY_DERIVE example + * @snippet key_derive.cpp KEY_DERIVE example * * @see #ckmc_param_list_h * @see #ckmc_policy_s diff --git a/src/include/ckmc/ckmc-type.h b/src/include/ckmc/ckmc-type.h index d1fddef..e568655 100644 --- a/src/include/ckmc/ckmc-type.h +++ b/src/include/ckmc/ckmc-type.h @@ -300,45 +300,46 @@ typedef enum __ckmc_param_name { CKMC_PARAM_ED_TAG_LEN, /**< integer - tag length in bits */ CKMC_PARAM_ED_LABEL, /**< buffer - RSA OAEP label (not supported at the moment) */ - CKMC_PARAM_KDF_PRF = 401, /**< integer - pseudo-random function number (see #ckmc_kdf_prf_e) */ + CKMC_PARAM_KDF_PRF = 401, /**< integer - pseudo-random function number (see #ckmc_kdf_prf_e) + (Since 6.5) */ CKMC_PARAM_KDF_LEN, /**< integer - length of the derived key in bytes. The value must be one of - {16, 24, 32} */ + {16, 24, 32} (Since 6.5) */ - CKMC_PARAM_KBKDF_MODE, /**< integer - KDF mode number (see #ckmc_kbkdf_mode_e) */ + CKMC_PARAM_KBKDF_MODE, /**< integer - KDF mode number (see #ckmc_kbkdf_mode_e) (Since 6.5) */ CKMC_PARAM_KBKDF_LABEL, /**< buffer - the purpose for the derived key. Conflicts with - #CKMC_PARAM_KBKDF_FIXED_INPUT */ + #CKMC_PARAM_KBKDF_FIXED_INPUT (Since 6.5) */ CKMC_PARAM_KBKDF_CONTEXT, /**< buffer - information related to the derived key. Conflicts with - #CKMC_PARAM_KBKDF_FIXED_INPUT */ + #CKMC_PARAM_KBKDF_FIXED_INPUT (Since 6.5) */ - CKMC_PARAM_KBKDF_FIXED_INPUT, /**< buffer - KBKDF fixed input replacing context and label. - Conflicts with: + CKMC_PARAM_KBKDF_FIXED_INPUT, /**< buffer - KBKDF fixed input replacing context and label + (Since 6.5). Conflicts with: - #CKMC_PARAM_KBKDF_LABEL, - #CKMC_PARAM_KBKDF_CONTEXT, - #CKMC_PARAM_KBKDF_LLEN, - #CKMC_PARAM_KBKDF_NO_SEPARATOR */ CKMC_PARAM_KBKDF_COUNTER_LOCATION, /**< integer - specifies location of the counter in KBKDF - (see #ckmc_kbkdf_counter_location_e) */ + (see #ckmc_kbkdf_counter_location_e) (Since 6.5) */ CKMC_PARAM_KBKDF_RLEN, /**< integer - specifies the length of the counter representation in bits in KBKDF. The value must be one of {8, 16, 24, 32}. If not set, the - default value = 32 will be used */ + default value = 32 will be used. (Since 6.5) */ CKMC_PARAM_KBKDF_LLEN, /**< integer - specifies the length of the length suffix representation in bits in KBKDF. The value must be one of {0, 8, 16, 24, 32}. If set to 0 the length suffix will be skipped. If not set, the default value = 32 will be used. The length suffix is skipped if #CKMC_PARAM_KBKDF_FIXED_INPUT is passed and this parameter conflicts - with it */ + with it. (Since 6.5) */ CKMC_PARAM_KBKDF_NO_SEPARATOR, /**< integer - presence of this parameter will skip the zero octet separator between label and context in KBKDF. All values are allowed. This parameter conflicts with - #CKMC_PARAM_KBKDF_FIXED_INPUT. */ + #CKMC_PARAM_KBKDF_FIXED_INPUT. (Since 6.5) */ - CKMC_PARAM_ECDH_PUBKEY, /**< buffer - EC public key in DER form (see #ckmc_key_s) */ + CKMC_PARAM_ECDH_PUBKEY, /**< buffer - EC public key in DER form (see #ckmc_key_s) (Since 6.5) */ } ckmc_param_name_e; /** - * @brief Enumeration for key derivation function pseudo-random function parameter - * @since_tizen 7.5 + * @brief Enumeration for key derivation function pseudo-random function parameter. + * @since_tizen 6.5 * * @see ckmc_key_derive() * @see #ckmc_param_name_e @@ -350,8 +351,8 @@ typedef enum __ckmc_kdf_prf { } ckmc_kdf_prf_e; /** - * @brief Enumeration for key based key derivation function mode - * @since_tizen 7.5 + * @brief Enumeration for key based key derivation function mode. + * @since_tizen 6.5 * * @see ckmc_key_derive() * @see #ckmc_param_name_e @@ -361,8 +362,8 @@ typedef enum __ckmc_kbkdf_mode { } ckmc_kbkdf_mode_e; /** - * @brief Enumeration for KBKDF counter location relative to fixed input - * @since_tizen 7.5 + * @brief Enumeration for KBKDF counter location relative to fixed input. + * @since_tizen 6.5 * * @see ckmc_key_derive() * @see #ckmc_param_name_e @@ -438,23 +439,26 @@ typedef enum __ckmc_algo_type { CKMC_ALGO_KBKDF, /**< Key based key derivation algorithm Supported parameters: - - CKMC_PARAM_ALGO_TYPE = CKMC_ALGO_KBKDF(mandatory), - - CKMC_PARAM_KDF_PRF = pseudo-random function (see #ckmc_kdf_prf_e)(mandatory), - - CKMC_PARAM_KBKDF_MODE = KDF mode (see #ckmc_kbkdf_mode_e)(mandatory), - - CKMC_PARAM_KBKDF_LABEL = the purpose for the derived key(optional), - - CKMC_PARAM_KBKDF_CONTEXT = information related to the derived key(optional), - - CKMC_PARAM_KDF_LEN = length of the derived key(mandatory) - - CKMC_PARAM_KBKDF_FIXED_INPUT = replacement for context and label(optional), - - CKMC_PARAM_KBKDF_COUNTER_LOCATION = counter location - (see #ckmc_kbkdf_counter_location_e)(mandatory), - - CKMC_PARAM_KBKDF_RLEN = length of the counter representation(optional), - - CKMC_PARAM_KBKDF_LLEN = length of the length suffix representation(optional), - - CKMC_PARAM_KBKDF_NO_SEPARATOR = existence of zero separator(optional) */ + - #CKMC_PARAM_ALGO_TYPE = #CKMC_ALGO_KBKDF (mandatory), + - #CKMC_PARAM_KDF_PRF = pseudo-random function (see #ckmc_kdf_prf_e) + (mandatory), + - #CKMC_PARAM_KBKDF_MODE = KDF mode (see #ckmc_kbkdf_mode_e) (mandatory), + - #CKMC_PARAM_KBKDF_LABEL = the purpose for the derived key (optional), + - #CKMC_PARAM_KBKDF_CONTEXT = information related to the derived key + (optional), + - #CKMC_PARAM_KDF_LEN = length of the derived key (mandatory) + - #CKMC_PARAM_KBKDF_FIXED_INPUT = replacement for context and label (optional), + - #CKMC_PARAM_KBKDF_COUNTER_LOCATION = counter location + (see #ckmc_kbkdf_counter_location_e) (mandatory), + - #CKMC_PARAM_KBKDF_RLEN = length of the counter representation (optional), + - #CKMC_PARAM_KBKDF_LLEN = length of the length suffix representation + (optional), + - #CKMC_PARAM_KBKDF_NO_SEPARATOR = existence of zero separator (optional) */ CKMC_ALGO_ECDH, /**< ECDH shared secret key agreement protocol Supported parameters (all are required): - - CKMC_PARAM_ALGO_TYPE = CKMC_ALGO_ECDH, - - CKMC_PARAM_ECDH_PUBKEY = peer's public key (see #ckmc_key_s) */ + - #CKMC_PARAM_ALGO_TYPE = #CKMC_ALGO_ECDH, + - #CKMC_PARAM_ECDH_PUBKEY = peer's public key (see #ckmc_key_s) */ } ckmc_algo_type_e; /** -- 2.7.4