From: Kyungwook Tak Date: Thu, 1 Oct 2015 12:36:34 +0000 (+0900) Subject: Adjust API change request review result X-Git-Tag: accepted/tizen/mobile/20151014.093603~4 X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fsecurity%2Fkey-manager.git;a=commitdiff_plain;h=01dce83f4afbaaf97c2219c2da971fa1f76490de Adjust API change request review result * remove useless const keyword in ckmc_create_key_aes * ckmc_generate_params allocates new ckmc_param_list_s inside of itself * ckmc_generate_params is renamed to ckmc_generate_new_params * ckmc_param_list_s is changed to ckmc_param_list_h (handle) * handle is structure pointer : typedef struct __ckmc_param_list *ckmc_param_list_h * ckmc_param_list_add_integer -> ckmc_param_list_set_integer * ckmc_param_list_add_buffer -> ckmc_param_list_set_buffer * new line for too long description * use dot properly in description (Should not used in params and retvals) Change-Id: I760465e1ae0d1665d596ff10d402c5f191a6f1d4 Signed-off-by: Kyungwook Tak --- diff --git a/src/include/ckmc/ckmc-manager.h b/src/include/ckmc/ckmc-manager.h index 71c46d0..91cf458 100644 --- a/src/include/ckmc/ckmc-manager.h +++ b/src/include/ckmc/ckmc-manager.h @@ -44,7 +44,8 @@ extern "C" { * @brief Stores a key inside key manager based on the provided policy. * * @since_tizen 2.3 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @remarks Currently API supports seven types of keys. These are RSA public/private key, * DSA public/private key, ECDSA public/private key and AES symmetric key. @@ -87,7 +88,8 @@ int ckmc_save_key(const char *alias, const ckmc_key_s key, const ckmc_policy_s p * @brief Removes a key from key manager. * * @since_tizen 2.3 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @remarks To remove key, client must have remove permission to the specified key. * @remarks The key owner can remove by default. @@ -117,7 +119,8 @@ int ckmc_remove_key(const char *alias); * @brief Gets a key from key manager. * * @since_tizen 2.3 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @remarks A client can access only data stored by the client. * @remarks You must destroy the newly created @a ppkey by calling ckmc_key_free() if it is no @@ -154,7 +157,8 @@ int ckmc_get_key(const char *alias, const char *password, ckmc_key_s **ppkey); * @brief Gets all the alias of keys that the client can access. * * @since_tizen 2.3 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @remarks A client can access only data stored by the client. * @remarks You must destroy the newly created @a ppalias_list by calling ckmc_alias_list_all_free() @@ -226,7 +230,8 @@ int ckmc_save_cert(const char *alias, const ckmc_cert_s cert, const ckmc_policy_ * @brief Removes a certificate from key manager. * * @since_tizen 2.3 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @remarks To remove certificate, client must have remove permission to the specified certificate. * @remarks The key owner can remove by default. @@ -256,7 +261,8 @@ int ckmc_remove_cert(const char *alias); * @brief Gets a certificate from key manager. * * @since_tizen 2.3 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @remarks A client can access only certificate stored by the client. * @remarks A DER encoded certificate will be returned as a return value. @@ -294,7 +300,8 @@ int ckmc_get_cert(const char *alias, const char *password, ckmc_cert_s **ppcert) * @brief Gets all alias of certificates which the client can access. * * @since_tizen 2.3 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @remarks A client can access only data stored by the client. * @remarks You must destroy the newly created @a ppalias_list by calling ckmc_alias_list_all_free() @@ -331,7 +338,8 @@ int ckmc_get_cert_alias_list(ckmc_alias_list_s** ppalias_list); * All items from the PKCS12 will use the same alias. * * @since_tizen 2.4 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @param[in] alias The name of a data to be stored * @param[in] pkcs Pointer to the pkcs12 structure to be saved @@ -367,7 +375,8 @@ int ckmc_save_pkcs12(const char *alias, * @brief Gets a pkcs12 from key manager. * * @since_tizen 2.4 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @remarks A client can access only data stored by the client. * @remarks You must destroy the newly created @a pkcs12 by calling ckmc_pkcs12_free() if it is no @@ -403,7 +412,8 @@ int ckmc_get_pkcs12(const char *alias, const char *key_password, const char *cer * @brief Stores a data inside key manager based on the provided policy. * * @since_tizen 2.3 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @param[in] alias The name of a data to be stored * @param[in] data The binary value to be stored @@ -435,7 +445,8 @@ int ckmc_save_data(const char *alias, ckmc_raw_buffer_s data, const ckmc_policy_ * @brief Removes a data from key manager. * * @since_tizen 2.3 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @remarks To remove data, client must have remove permission to the specified data object. * @remarks The data owner can remove by default. @@ -465,7 +476,8 @@ int ckmc_remove_data(const char *alias); * @brief Gets a data from key manager. * * @since_tizen 2.3 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @remarks A client can access only data stored by the client. * @remarks You must destroy the newly created @a ppdata by calling ckmc_buffer_free() if it is no @@ -501,7 +513,8 @@ int ckmc_get_data(const char *alias, const char *password, ckmc_raw_buffer_s **p * @brief Gets all alias of data which the client can access. * * @since_tizen 2.3 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @remarks A client can access only data stored by the client. * @remarks You must destroy the newly created @a ppalias_list by calling ckmc_alias_list_all_free() @@ -538,13 +551,14 @@ int ckmc_get_data_alias_list(ckmc_alias_list_s** ppalias_list); * policy. * * @since_tizen 2.3 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @remarks If password in policy is provided, the key is additionally encrypted with the password * in policy. * * @param[in] size The size of key strength to be created \n - * @c 1024, @c 2048, and @c 4096 are supported. + * @c 1024, @c 2048, and @c 4096 are supported * @param[in] private_key_alias The name of private key to be stored * @param[in] public_key_alias The name of public key to be stored * @param[in] policy_private_key The policy about how to store a private key securely @@ -579,13 +593,14 @@ int ckmc_create_key_pair_rsa(const size_t size, * policy. * * @since_tizen 2.3 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @remarks If password in policy is provided, the key is additionally encrypted with the password * in policy. * * @param[in] size The size of key strength to be created \n - * @c 1024, @c 2048, @c 3072 and @c 4096 are supported. + * @c 1024, @c 2048, @c 3072 and @c 4096 are supported * @param[in] private_key_alias The name of private key to be stored * @param[in] public_key_alias The name of public key to be stored * @param[in] policy_private_key The policy about how to store a private key securely @@ -620,7 +635,8 @@ int ckmc_create_key_pair_dsa(const size_t size, * policy. * * @since_tizen 2.3 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @remarks If password in policy is provided, the key is additionally encrypted with the password * in policy. @@ -664,8 +680,8 @@ int ckmc_create_key_pair_ecdsa(const ckmc_ec_type_e type, * @remarks If password in policy is provided, the key is additionally encrypted with the password * in policy. * - * @param[in] size The size of key strength to be created. \n - * @c 128, @c 192 and @c 256 are supported. + * @param[in] size The size of key strength to be created \n + * @c 128, @c 192 and @c 256 are supported * @param[in] key_alias The name of key to be stored * @param[in] key_policy The policy about how to store the key securely * @@ -685,16 +701,18 @@ int ckmc_create_key_pair_ecdsa(const ckmc_ec_type_e type, * @see ckmc_create_key_pair_rsa() * @see ckmc_create_key_pair_dsa() * @see ckmc_create_key_pair_ecdsa() + * @see #ckmc_policy_s */ -int ckmc_create_key_aes(const size_t size, +int ckmc_create_key_aes(size_t size, const char *key_alias, - const ckmc_policy_s key_policy); + ckmc_policy_s key_policy); /** * @brief Creates a signature on a given message using a private key and returns the signature. * * @since_tizen 2.3 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @remarks If password of policy is provided during storing a key, the same password should be * provided. @@ -706,9 +724,9 @@ int ckmc_create_key_aes(const size_t size, * @param[in] message The message that is signed with a private key * @param[in] hash The hash algorithm used in creating signature * @param[in] padding The RSA padding algorithm used in creating signature \n - * It is used only when the signature algorithm is RSA. + * It is used only when the signature algorithm is RSA * @param[out] ppsignature The pointer to a newly created signature \n - * If an error occurs, @a *ppsignature will be null. + * If an error occurs, @a *ppsignature will be null * * @return @c 0 on success, * otherwise a negative error value @@ -721,7 +739,7 @@ int ckmc_create_key_aes(const size_t size, * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager * @retval #CKMC_ERROR_AUTHENTICATION_FAILED - * Decryption failed because password is incorrect. + * Decryption failed because password is incorrect * * @pre User is already logged in and the user key is already loaded into memory in plain text form. * @@ -744,7 +762,8 @@ int ckmc_create_signature(const char *private_key_alias, * status. * * @since_tizen 2.3 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @remarks If password of policy is provided during storing a key, the same password should be * provided. @@ -755,7 +774,7 @@ int ckmc_create_signature(const char *private_key_alias, * @param[in] signature The signature that is verified with public key * @param[in] hash The hash algorithm used in verifying signature * @param[in] padding The RSA padding algorithm used in verifying signature \n - * It is used only when the signature algorithm is RSA. + * It is used only when the signature algorithm is RSA * * @return @c 0 on success and the signature is valid, * otherwise a negative error value @@ -769,7 +788,7 @@ int ckmc_create_signature(const char *private_key_alias, * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager * @retval #CKMC_ERROR_AUTHENTICATION_FAILED - * Decryption failed because password is incorrect. + * Decryption failed because password is incorrect * * @pre User is already logged in and the user key is already loaded into memory in plain text form. * @@ -790,7 +809,8 @@ int ckmc_verify_signature(const char *public_key_alias, * @brief Verifies a certificate chain and returns that chain. * * @since_tizen 2.3 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @remarks The trusted root certificate of the chain should exist in the system's certificate * storage. @@ -801,7 +821,7 @@ int ckmc_verify_signature(const char *public_key_alias, * @param[in] untrustedcerts The untrusted CA certificates to be used in verifying a certificate * chain * @param[out] ppcert_chain_list The pointer to a newly created certificate chain's handle \n - * If an error occurs, @a *ppcert_chain_list will be null. + * If an error occurs, @a *ppcert_chain_list will be null * * @return @c 0 on success and the signature is valid, * otherwise a negative error value @@ -815,7 +835,7 @@ int ckmc_verify_signature(const char *public_key_alias, * @retval #CKMC_ERROR_INVALID_FORMAT The format of certificate is not valid * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager * @retval #CKMC_ERROR_AUTHENTICATION_FAILED - * Decryption failed because password is incorrect. + * Decryption failed because password is incorrect * * @pre User is already logged in and the user key is already loaded into memory in plain text form. * @@ -831,7 +851,8 @@ int ckmc_get_cert_chain(const ckmc_cert_s *cert, * chain. * * @since_tizen 2.3 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @remarks The trusted root certificate of the chain should exist in the system's certificate * storage. @@ -842,7 +863,7 @@ int ckmc_get_cert_chain(const ckmc_cert_s *cert, * @param[in] untrustedcerts The alias list of untrusted CA certificates stored in key manager * to be used in verifying a certificate chain * @param[out] ppcert_chain_list The pointer to a newly created certificate chain's handle \n - * If an error occurs, @a *ppcert_chain_list will be null. + * If an error occurs, @a *ppcert_chain_list will be null * * @return @c 0 on success and the signature is valid, * otherwise a negative error value @@ -858,7 +879,7 @@ int ckmc_get_cert_chain(const ckmc_cert_s *cert, * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager * @retval #CKMC_ERROR_AUTHENTICATION_FAILED * Some certificates were encrypted with password and could not - * be used. + * be used * * @pre User is already logged in and the user key is already loaded into memory in plain text form. * @@ -871,25 +892,26 @@ int ckmc_get_cert_chain_with_alias(const ckmc_cert_s *cert, /** * @brief Verifies a certificate chain and returns that chain using user entered trusted and - * untrusted CA certificates + * untrusted CA certificates. * * @since_tizen 2.4 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @remarks If the trusted root certificates are provided as a user input, these certificates do not * need to exist in the system's certificate storage. * @remarks You must destroy the newly created @a ppcert_chain_list by calling * ckmc_cert_list_all_free() if it is no longer needed. - * * + * * @param[in] cert The certificate to be verified * @param[in] untrustedcerts The untrusted CA certificates to be used in verifying a * certificate chain * @param[in] trustedcerts The trusted CA certificates to be used in verifying a * certificate chain * @param[in] use_trustedsystemcerts The flag indicating the use of the trusted root certificates - * in the system's certificate storage. + * in the system's certificate storage * @param[out] ppcert_chain_list The pointer to a newly created certificate chain's handle \n - * If an error occurs, @a *ppcert_chain_list will be null. + * If an error occurs, @a *ppcert_chain_list will be null * * @return @c 0 on success and the signature is valid, * otherwise a negative error value @@ -916,10 +938,11 @@ int ckmc_get_cert_chain_with_trustedcert(const ckmc_cert_s *cert, /** * @brief Verifies a certificate chain and returns that chain using alias lists of untrusted and - * trusted certificates + * trusted certificates. * * @since_tizen 2.4 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @remarks If the alias list of trusted root certificates is provided as a user input, these * certificates do not need to exist in the system's certificate storage. @@ -932,9 +955,9 @@ int ckmc_get_cert_chain_with_trustedcert(const ckmc_cert_s *cert, * @param[in] trustedcerts The alias list of trusted CA certificates stored in key * manager to be used in verifying a certificate chain * @param[in] use_trustedsystemcerts The flag indicating the use of the trusted root certificates - * in the system's certificate storage. - * @param[out] ppcert_chain_list The pointer to a newly created certificate chain's handle \n - * If an error occurs, @a *ppcert_chain_list will be null. + * in the system's certificate storage + * @param[out] ppcert_chain_list The pointer to a newly created certificate chain's handle \n + * If an error occurs, @a *ppcert_chain_list will be null * * @return @c 0 on success and the signature is valid, * otherwise a negative error value @@ -950,7 +973,7 @@ int ckmc_get_cert_chain_with_trustedcert(const ckmc_cert_s *cert, * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager * @retval #CKMC_ERROR_AUTHENTICATION_FAILED * Some certificates were encrypted with password and could not - * be used. + * be used * * @pre User is already logged in and the user key is already loaded into memory in plain text form. * @@ -964,7 +987,7 @@ int ckmc_get_cert_chain_with_trustedcert_alias(const ckmc_cert_s *cert, ckmc_cert_list_s **ppcert_chain_list); /** - * @brief Perform OCSP which checks certificate is whether revoked or not + * @brief Perform OCSP which checks certificate is whether revoked or not. * * @since_tizen 2.4 * @privlevel public @@ -982,7 +1005,7 @@ int ckmc_get_cert_chain_with_trustedcert_alias(const ckmc_cert_s *cert, * * @pre User is already logged in and the user key is already loaded into memory in plain text form. * @pre @a pcert_chain_list is created with ckmc_get_certificate_chain() or - * ckmc_get_certificate_chain_with_alias() + * ckmc_get_certificate_chain_with_alias(). * * @see ckmc_get_cert_chain()) * @see ckmc_cert_list_all_free() @@ -991,12 +1014,13 @@ int ckmc_ocsp_check(const ckmc_cert_list_s *pcert_chain_list, ckmc_ocsp_status_e /** * @deprecated Deprecated since 2.4. [Use ckmc_set_permission() instead] - * @brief Allows another application to access client's application data + * @brief Allows another application to access client's application data. * * @since_tizen 2.3 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * - * @remarks Data identified by @a alias should exist + * @remarks Data identified by @a alias should exist. * * @param[in] alias Data alias for which access will be granted * @param[in] accessor Package id of the application that will gain access rights @@ -1019,12 +1043,13 @@ int ckmc_ocsp_check(const ckmc_cert_list_s *pcert_chain_list, ckmc_ocsp_status_e int ckmc_allow_access(const char *alias, const char *accessor, ckmc_access_right_e granted); /** - * @brief Allows another application to access client's application data + * @brief Allows another application to access client's application data. * * @since_tizen 2.4 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * - * @remarks Data identified by @a alias should exist + * @remarks Data identified by @a alias should exist. * * @param[in] alias Data alias for which access will be granted * @param[in] accessor Package id of the application that will gain access rights @@ -1048,12 +1073,13 @@ int ckmc_set_permission(const char *alias, const char *accessor, int permissions /** * @deprecated Deprecated since 2.4. [Use ckmc_set_permission() instead] - * @brief Revokes another application's access to client's application data + * @brief Revokes another application's access to client's application data. * * @since_tizen 2.3 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * - * @remarks Data identified by @a alias should exist + * @remarks Data identified by @a alias should exist. * @remarks Only access previously granted with ckmc_allow_access can be revoked. * * @param[in] alias Data alias for which access will be revoked @@ -1081,7 +1107,8 @@ int ckmc_deny_access(const char *alias, const char *accessor); * @brief Removes a an entry (no matter of type) from the key manager. * * @since_tizen 2.4 - * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0 + * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer + * required to use this API since 3.0. * * @remarks To remove item, client must have remove permission to the specified item. * @remarks The item owner can remove by default. @@ -1118,7 +1145,7 @@ int ckmc_remove_alias(const char *alias); * * @remarks Key identified by @a key_alias should exist. * - * @param[in] params Algorithm parameters + * @param[in] params Algorithm parameter list handle * @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 @@ -1126,7 +1153,7 @@ int ckmc_remove_alias(const char *alias); * @param[in] decrypted Data to be encrypted * @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 ppencrypted with + * The caller is responsible for freeing @a encrypted with * ckmc_buffer_free() * * @return @c 0 on success, otherwise a negative error value @@ -1146,13 +1173,13 @@ int ckmc_remove_alias(const char *alias); * @see ckmc_buffer_free() * @see ckmc_param_list_new() * @see ckmc_param_list_free() - * @see ckmc_param_list_add_integer() - * @see ckmc_param_list_add_buffer() - * @see ckmc_generate_params() - * @see #ckmc_param_list_s + * @see ckmc_param_list_set_integer() + * @see ckmc_param_list_set_buffer() + * @see ckmc_generate_new_params() + * @see #ckmc_param_list_h * @see #ckmc_param_name_e */ -int ckmc_encrypt_data(const ckmc_param_list_s *params, +int ckmc_encrypt_data(ckmc_param_list_h params, const char *key_alias, const char *password, const ckmc_raw_buffer_s decrypted, @@ -1165,7 +1192,7 @@ int ckmc_encrypt_data(const ckmc_param_list_s *params, * * @remarks Key identified by @a key_alias should exist. * - * @param[in] params Algorithm parameters + * @param[in] params Algorithm parameter list handle * @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 @@ -1173,7 +1200,7 @@ int ckmc_encrypt_data(const ckmc_param_list_s *params, * @param[in] encrypted Data to be decrypted (some algorithms may require additional * information embedded in encrypted data. AES GCM is an example) * @param[out] ppdecrypted Decrypted data \n - * The caller is responsible for freeing ppdecrypted with + * The caller is responsible for freeing @a decrypted with * ckmc_buffer_free() * * @return @c 0 on success, otherwise a negative error value @@ -1193,13 +1220,13 @@ int ckmc_encrypt_data(const ckmc_param_list_s *params, * @see ckmc_buffer_free() * @see ckmc_param_list_new() * @see ckmc_param_list_free() - * @see ckmc_param_list_add_integer() - * @see ckmc_param_list_add_buffer() - * @see ckmc_generate_params() - * @see #ckmc_param_list_s + * @see ckmc_param_list_set_integer() + * @see ckmc_param_list_set_buffer() + * @see ckmc_generate_new_params() + * @see #ckmc_param_list_h * @see #ckmc_param_name_e */ -int ckmc_decrypt_data(const ckmc_param_list_s *params, +int ckmc_decrypt_data(ckmc_param_list_h params, const char *key_alias, const char *password, const ckmc_raw_buffer_s encrypted, diff --git a/src/include/ckmc/ckmc-type.h b/src/include/ckmc/ckmc-type.h index 08a28d5..2845ea1 100644 --- a/src/include/ckmc/ckmc-type.h +++ b/src/include/ckmc/ckmc-type.h @@ -273,20 +273,14 @@ typedef enum __ckmc_param_name { CKMC_PARAM_ED_CTR_LEN, /**< integer - ctr length in bits*/ CKMC_PARAM_ED_AAD, /**< buffer */ CKMC_PARAM_ED_TAG_LEN, /**< integer - tag length in bits */ - CKMC_PARAM_ED_LABEL, /**< buffer */ - - CKMC_PARAM_GEN_KEY_LEN = 201, /**< integer - key length in bits */ - CKMC_PARAM_GEN_EC, /**< integer - elliptic curve (ckmc_ec_type_e) */ - - CKMC_PARAM_SV_HASH_ALGO = 301, /**< integer - hash algorithm (ckmc_hash_algo_e) */ - CKMC_PARAM_SV_RSA_PADDING /**< integer - RSA padding (ckmc_rsa_padding_algo_e) */ + CKMC_PARAM_ED_LABEL /**< buffer */ } ckmc_param_name_e; /** - * @brief Structure for algorithm parameter list. + * @brief Handle for algorithm parameter list. * @since_tizen 3.0 */ -typedef struct __ckmc_param_list ckmc_param_list_s; +typedef struct __ckmc_param_list *ckmc_param_list_h; /** * @brief Enumeration for crypto algorithm types. @@ -318,46 +312,10 @@ typedef enum __ckmc_algo_type { - CKMC_PARAM_ALGO_TYPE, - CKMC_PARAM_ED_IV */ - CKMC_ALGO_RSA_OAEP, /**< RSA-OAEP algorithm + CKMC_ALGO_RSA_OAEP /**< RSA-OAEP algorithm Supported parameters: - CKMC_PARAM_ALGO_TYPE, - CKMC_PARAM_ED_LABEL */ - - CKMC_ALGO_RSA_SV, /**< RSA algorithm used for signing/verification - Supported parameters: - - CKMC_PARAM_ALGO_TYPE, - - CKMC_PARAM_SV_HASH_ALGO - - CKMC_PARAM_SV_RSA_PADDING */ - - CKMC_ALGO_DSA_SV, /**< DSA algorithm used for signing/verification - Supported parameters: - - CKMC_PARAM_ALGO_TYPE, - - CKMC_PARAM_SV_HASH_ALGO */ - - CKMC_ALGO_ECDSA_SV, /**< ECDA algorithm used for signing/verification - Supported parameters: - - CKMC_PARAM_ALGO_TYPE, - - CKMC_PARAM_SV_HASH_ALGO */ - - CKMC_ALGO_RSA_GEN, /**< RSA algorithm used for key generation - Supported parameters: - - CKMC_PARAM_ALGO_TYPE, - - CKMC_PARAM_GEN_KEY_LEN */ - - CKMC_ALGO_DSA_GEN, /**< DSA algorithm used for key generation - Supported parameters: - - CKMC_PARAM_ALGO_TYPE, - - CKMC_PARAM_GEN_KEY_LEN */ - - CKMC_ALGO_ECDSA_GEN, /**< ECDSA algorithm used for key generation - Supported parameters: - - CKMC_PARAM_ALGO_TYPE, - - CKMC_PARAM_GEN_EC */ - - CKMC_ALGO_AES_GEN, /**< AES key generation - Supported parameters: - - CKMC_PARAM_ALGO_TYPE, - - CKMC_PARAM_GEN_KEY_LEN */ } ckmc_algo_type_e; /** @@ -607,8 +565,8 @@ int ckmc_load_from_pkcs12_file(const char *file_path, * @see #ckmc_pkcs12_s */ int ckmc_pkcs12_load(const char *file_path, - const char *passphrase, - ckmc_pkcs12_s **pkcs12_bundle); + const char *passphrase, + ckmc_pkcs12_s **pkcs12_bundle); /** * @brief Destroys the @a ckmc_pkcs12_s handle and releases all its resources. @@ -782,14 +740,14 @@ void ckmc_cert_list_free(ckmc_cert_list_s *first); void ckmc_cert_list_all_free(ckmc_cert_list_s *first); /** - * @brief Creates new parameter list + * @brief Creates new parameter list. * * @since_tizen 3.0 * - * @remarks Caller is responsible for freeing it with ckmc_param_list_free() + * @remarks Caller is responsible for freeing it with ckmc_param_list_free(). * - * @param[in] ppparam_list Double pointer to the list variable to which the newly created list will - * be assigned + * @param[in] pparams Double pointer to the handle of param list to which the + * newly created algorithm param list will be assigned * * @return #CKMC_ERROR_NONE on success, * otherwise a negative error value @@ -797,25 +755,26 @@ void ckmc_cert_list_all_free(ckmc_cert_list_s *first); * @retval #CKMC_ERROR_NONE Successful * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid * - * @see ckmc_param_list_add_integer() - * @see ckmc_param_list_add_buffer() + * @see ckmc_param_list_set_integer() + * @see ckmc_param_list_set_buffer() * @see ckmc_param_list_free() - * @see ckmc_generate_params() - * @see #ckmc_param_list_s + * @see ckmc_generate_new_params() + * @see #ckmc_param_list_h * @see #ckmc_param_name_e */ -int ckmc_param_list_new(ckmc_param_list_s **ppparams); +int ckmc_param_list_new(ckmc_param_list_h *pparams); /** - * @brief Adds integer parameter to the list + * @brief Set integer parameter to the list. * * @since_tizen 3.0 * - * @remarks Caller is responsible for @a ckmc_param_list_s creation. + * @remarks Caller is responsible for @a ckmc_param_list_h creation. * - * @param[in] params List of params created with ckmc_param_list_new() or - * ckmc_generate_params() - * @param[in] name Name of parameter to add \n + * @param[in] params Algorithm param list handle created with + * ckmc_param_list_new() or ckmc_generate_new_params() \n + * New param with @a name and @a value will be set` here + * @param[in] name Name of parameter to set \n * Existing parameter will be overwritten \n * Passing invalid parameter name will result in an error * @param[in] value Value of the parameter in form of a integer @@ -827,28 +786,29 @@ int ckmc_param_list_new(ckmc_param_list_s **ppparams); * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid * * @see ckmc_param_list_new() - * @see ckmc_param_list_add_buffer() + * @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_generate_params() - * @see #ckmc_param_list_s + * @see ckmc_generate_new_params() + * @see #ckmc_param_list_h * @see #ckmc_param_name_e */ -int ckmc_param_list_add_integer(ckmc_param_list_s *params, +int ckmc_param_list_set_integer(ckmc_param_list_h params, ckmc_param_name_e name, uint64_t value); /** - * @brief Adds buffer parameter to the list + * @brief Set buffer parameter to the list. * * @since_tizen 3.0 * - * @remarks Caller is responsible for @a ckmc_param_list_s creation. + * @remarks Caller is responsible for @a ckmc_param_list_h creation. * - * @param[in] params List of params created with ckmc_param_list_new() - * or ckmc_generate_params() - * @param[in] name Name of parameter to add \n + * @param[in] params Algorithm param list handle created with + * ckmc_param_list_new() or ckmc_generate_new_params() + * New param with @a name and @a buffer will be set here + * @param[in] name Name of parameter to set \n * Existing parameter will be overwritten \n * Passing invalid parameter name will result in an error * @param[in] buffer Value of the parameter in form of a buffer \n @@ -861,15 +821,15 @@ int ckmc_param_list_add_integer(ckmc_param_list_s *params, * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid * * @see ckmc_param_list_new() - * @see ckmc_param_list_add_integer() + * @see ckmc_param_list_set_integer() * @see ckmc_param_list_get_integer() * @see ckmc_param_list_get_buffer() * @see ckmc_param_list_free() - * @see ckmc_generate_params() - * @see #ckmc_param_list_s + * @see ckmc_generate_new_params() + * @see #ckmc_param_list_h * @see #ckmc_param_name_e */ -int ckmc_param_list_add_buffer(ckmc_param_list_s *params, +int ckmc_param_list_set_buffer(ckmc_param_list_h params, ckmc_param_name_e name, const ckmc_raw_buffer_s *buffer); @@ -878,12 +838,13 @@ int ckmc_param_list_add_buffer(ckmc_param_list_s *params, * * @since_tizen 3.0 * - * @remarks Caller is responsible for @a ckmc_param_list_s creation. + * @remarks Caller is responsible for @a ckmc_param_list_h creation. * - * @param[in] params List of params created with ckmc_param_list_new() - * or ckmc_generate_params() + * @param[in] params Algorithm param list handle created with + * ckmc_param_list_new() or ckmc_generate_new_params() + * which contains param with @a name * @param[in] name Name of parameter to get - * @param[out] value Value of the parameter in form of a integer + * @param[out] pvalue Value of the parameter in form of a integer * * @return #CKMC_ERROR_NONE on success, * otherwise a negative error value @@ -892,30 +853,31 @@ int ckmc_param_list_add_buffer(ckmc_param_list_s *params, * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid * * @see ckmc_param_list_new() - * @see ckmc_param_list_add_integer() - * @see ckmc_param_list_add_buffer() + * @see ckmc_param_list_set_integer() + * @see ckmc_param_list_set_buffer() * @see ckmc_param_list_get_buffer() * @see ckmc_param_list_free() - * @see ckmc_generate_params() - * @see #ckmc_param_list_s + * @see ckmc_generate_new_params() + * @see #ckmc_param_list_h * @see #ckmc_param_name_e */ -int ckmc_param_list_get_integer(const ckmc_param_list_s *params, +int ckmc_param_list_get_integer(ckmc_param_list_h params, ckmc_param_name_e name, - uint64_t* value); + uint64_t *pvalue); /** * @brief Gets buffer parameter from the list. * * @since_tizen 3.0 * - * @remarks Caller is responsible for @a ckmc_param_list_s creation. + * @remarks Caller is responsible for @a ckmc_param_list_h creation. * - * @param[in] params List of params created with ckmc_param_list_new() - * or ckmc_generate_params() + * @param[in] params Algorithm param list handle created with + * ckmc_param_list_new() or ckmc_generate_new_params() + * which contains param with @a name * @param[in] name Name of parameter to get - * @param[out] buffer Value of the parameter in form of a buffer \n + * @param[out] ppbuffer Value of the parameter in form of a buffer \n * Caller is responsible for creating and freeing the buffer * * @return #CKMC_ERROR_NONE on success, @@ -925,52 +887,50 @@ int ckmc_param_list_get_integer(const ckmc_param_list_s *params, * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid * * @see ckmc_param_list_new() - * @see ckmc_param_list_add_integer() - * @see ckmc_param_list_add_buffer() + * @see ckmc_param_list_set_integer() + * @see ckmc_param_list_set_buffer() * @see ckmc_param_list_get_integer() * @see ckmc_param_list_free() - * @see ckmc_generate_params() - * @see #ckmc_param_list_s + * @see ckmc_generate_new_params() + * @see ckmc_buffer_free() + * @see #ckmc_param_list_h * @see #ckmc_param_name_e */ -int ckmc_param_list_get_buffer(const ckmc_param_list_s *params, +int ckmc_param_list_get_buffer(ckmc_param_list_h params, ckmc_param_name_e name, - ckmc_raw_buffer_s **buffer); + ckmc_raw_buffer_s **ppbuffer); /** - * @brief Frees previously allocated list of algorithm params + * @brief Frees previously allocated list of algorithm params. * * @since_tizen 3.0 * * @param[in] first First element of the list to be freed * * @see ckmc_param_list_new() - * @see ckmc_param_list_add_integer() - * @see ckmc_param_list_add_buffer() + * @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_generate_params() - * @see #ckmc_param_list_s + * @see ckmc_generate_new_params() + * @see #ckmc_param_list_h * @see #ckmc_param_name_e */ - -void ckmc_param_list_free(ckmc_param_list_s *params); +void ckmc_param_list_free(ckmc_param_list_h params); /** - * @brief Generates algorithm parameters for a given algorithm type and adds them to the list. + * @brief Generates algorithm parameters for a given algorithm type and set them to the list. * * @since_tizen 3.0 * - * @remarks Caller is responsible for @a ckmc_param_list_s creation and destruction. + * @remarks Caller is responsible for @a ckmc_param_list_h destruction. * @remarks Algorithm parameters are set to default values. Optional fields are left empty. - * Initialization vectors are left empty (they have to be added manually). Existing params - * will be overwritten with default values. Caller is responsible for freeing the list with - * ckmc_param_list_free(). + * Initialization vectors are left empty (they have to be set manually). Caller is + * responsible for freeing the list with ckmc_param_list_free(). * @remarks If the function returns error, provided param list may contain some of default parameters. * * @param[in] type Type of the algorithm - * @param[out] params List of params to be filled \n - * List should be empty, otherwise an error will be returned + * @param[out] pparams Newly generated handle of param list which should be freed by caller after used * * @return #CKMC_ERROR_NONE on success, * otherwise a negative error value @@ -979,15 +939,15 @@ void ckmc_param_list_free(ckmc_param_list_s *params); * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid * * @see ckmc_param_list_new() - * @see ckmc_param_list_add_integer() - * @see ckmc_param_list_add_buffer() + * @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_param_list_s + * @see #ckmc_param_list_h * @see #ckmc_param_name_e */ -int ckmc_generate_params(ckmc_algo_type_e type, ckmc_param_list_s *params); +int ckmc_generate_new_params(ckmc_algo_type_e type, ckmc_param_list_h *pparams); /** * @} diff --git a/src/manager/client-capi/ckmc-manager.cpp b/src/manager/client-capi/ckmc-manager.cpp index 15908e0..dd5c644 100644 --- a/src/manager/client-capi/ckmc-manager.cpp +++ b/src/manager/client-capi/ckmc-manager.cpp @@ -124,7 +124,7 @@ typedef int (CKM::Manager::*cryptoFn)(const CKM::CryptoAlgorithm&, CKM::RawBuffer&); int _cryptoOperation(cryptoFn operation, - const ckmc_param_list_s *params, + ckmc_param_list_h params, const char *key_alias, const char *password, const ckmc_raw_buffer_s in, @@ -604,9 +604,9 @@ int ckmc_create_key_pair_ecdsa(const ckmc_ec_type_e type, } KEY_MANAGER_CAPI -int ckmc_create_key_aes(const size_t size, +int ckmc_create_key_aes(size_t size, const char *key_alias, - const ckmc_policy_s key_policy) + ckmc_policy_s key_policy) { CKM::ManagerShPtr mgr = CKM::Manager::create(); @@ -874,7 +874,7 @@ int ckmc_remove_alias(const char *alias) } KEY_MANAGER_CAPI -int ckmc_encrypt_data(const ckmc_param_list_s *params, +int ckmc_encrypt_data(ckmc_param_list_h params, const char *key_alias, const char *password, const ckmc_raw_buffer_s decrypted, @@ -889,7 +889,7 @@ int ckmc_encrypt_data(const ckmc_param_list_s *params, } KEY_MANAGER_CAPI -int ckmc_decrypt_data(const ckmc_param_list_s *params, +int ckmc_decrypt_data(ckmc_param_list_h params, const char *key_alias, const char *password, const ckmc_raw_buffer_s encrypted, diff --git a/src/manager/client-capi/ckmc-type.cpp b/src/manager/client-capi/ckmc-type.cpp index 6f1ddd2..c1db6c0 100644 --- a/src/manager/client-capi/ckmc-type.cpp +++ b/src/manager/client-capi/ckmc-type.cpp @@ -572,19 +572,19 @@ void ckmc_cert_list_all_free(ckmc_cert_list_s *first) } KEY_MANAGER_CAPI -int ckmc_param_list_new(ckmc_param_list_s **ppparams) +int ckmc_param_list_new(ckmc_param_list_h *pparams) { - if (!ppparams) + if (!pparams || *pparams) return CKMC_ERROR_INVALID_PARAMETER; - *ppparams = reinterpret_cast(new(std::nothrow)(CKM::CryptoAlgorithm)); - if (!*ppparams) + *pparams = reinterpret_cast(new(std::nothrow)(CKM::CryptoAlgorithm)); + if (!*pparams) return CKMC_ERROR_OUT_OF_MEMORY; return CKMC_ERROR_NONE; } KEY_MANAGER_CAPI -int ckmc_param_list_add_integer(ckmc_param_list_s *params, +int ckmc_param_list_set_integer(ckmc_param_list_h params, ckmc_param_name_e name, uint64_t value) { @@ -597,7 +597,7 @@ int ckmc_param_list_add_integer(ckmc_param_list_s *params, } KEY_MANAGER_CAPI -int ckmc_param_list_add_buffer(ckmc_param_list_s *params, +int ckmc_param_list_set_buffer(ckmc_param_list_h params, ckmc_param_name_e name, const ckmc_raw_buffer_s *buffer) { @@ -611,26 +611,26 @@ int ckmc_param_list_add_buffer(ckmc_param_list_s *params, } KEY_MANAGER_CAPI -int ckmc_param_list_get_integer(const ckmc_param_list_s *params, +int ckmc_param_list_get_integer(ckmc_param_list_h params, ckmc_param_name_e name, - uint64_t* value) + uint64_t *pvalue) { - if (!params || !value) + if (!params || !pvalue) return CKMC_ERROR_INVALID_PARAMETER; const CKM::CryptoAlgorithm* algo = reinterpret_cast(params); - if (!algo->getParam(static_cast(name),*value)) + if (!algo->getParam(static_cast(name), *pvalue)) return CKMC_ERROR_INVALID_PARAMETER; return CKMC_ERROR_NONE; } KEY_MANAGER_CAPI -int ckmc_param_list_get_buffer(const ckmc_param_list_s *params, +int ckmc_param_list_get_buffer(ckmc_param_list_h params, ckmc_param_name_e name, - ckmc_raw_buffer_s **buffer) + ckmc_raw_buffer_s **ppbuffer) { - if (!params || !buffer) + if (!params || !ppbuffer || *ppbuffer) return CKMC_ERROR_INVALID_PARAMETER; const CKM::CryptoAlgorithm* algo = reinterpret_cast(params); @@ -638,28 +638,30 @@ int ckmc_param_list_get_buffer(const ckmc_param_list_s *params, if (!algo->getParam(static_cast(name),value)) return CKMC_ERROR_INVALID_PARAMETER; - return ckmc_buffer_new(value.data(), value.size(), buffer); + return ckmc_buffer_new(value.data(), value.size(), ppbuffer); } KEY_MANAGER_CAPI -void ckmc_param_list_free(ckmc_param_list_s *params) +void ckmc_param_list_free(ckmc_param_list_h params) { CKM::CryptoAlgorithm* algo = reinterpret_cast(params); delete algo; } KEY_MANAGER_CAPI -int ckmc_generate_params(ckmc_algo_type_e type, ckmc_param_list_s *params) +int ckmc_generate_new_params(ckmc_algo_type_e type, ckmc_param_list_h *pparams) { - // return error if params are NULL - if(params == NULL) + if (!pparams || *pparams) return CKMC_ERROR_INVALID_PARAMETER; - int ret = CKMC_ERROR_NONE; - switch(type) - { + ckmc_param_list_h params = NULL; + int ret = ckmc_param_list_new(¶ms); + if (ret != CKMC_ERROR_NONE) + return ret; + + switch (type) { case CKMC_ALGO_AES_CTR: - ret = ckmc_param_list_add_integer(params, CKMC_PARAM_ED_CTR_LEN, DEFAULT_IV_LEN_BITS); + ret = ckmc_param_list_set_integer(params, CKMC_PARAM_ED_CTR_LEN, DEFAULT_IV_LEN_BITS); break; case CKMC_ALGO_AES_CBC: case CKMC_ALGO_AES_GCM: @@ -667,22 +669,23 @@ int ckmc_generate_params(ckmc_algo_type_e type, ckmc_param_list_s *params) case CKMC_ALGO_RSA_OAEP: // no iv by default break; - case CKMC_ALGO_RSA_SV: - case CKMC_ALGO_DSA_SV: - case CKMC_ALGO_ECDSA_SV: - // no hash, no padding by default - break; - case CKMC_ALGO_RSA_GEN: - case CKMC_ALGO_DSA_GEN: - ret = ckmc_param_list_add_integer(params, CKMC_PARAM_GEN_KEY_LEN, DEFAULT_KEY_LEN_BITS); - break; - case CKMC_ALGO_ECDSA_GEN: - ret = ckmc_param_list_add_integer(params, CKMC_PARAM_GEN_EC, CKMC_EC_PRIME192V1); - break; default: - return CKMC_ERROR_INVALID_PARAMETER; + ret = CKMC_ERROR_INVALID_PARAMETER; + break; } - if (ret == CKMC_ERROR_NONE) - return ckmc_param_list_add_integer(params, CKMC_PARAM_ALGO_TYPE, type); - return ret; + + if (ret != CKMC_ERROR_NONE) { + ckmc_param_list_free(params); + return ret; + } + + ret = ckmc_param_list_set_integer(params, CKMC_PARAM_ALGO_TYPE, type); + if (ret != CKMC_ERROR_NONE) { + ckmc_param_list_free(params); + return ret; + } + + *pparams = params; + + return CKMC_ERROR_NONE; }