From 6851efcb3bdf1d1519f3651e3f60ac304ad9e168 Mon Sep 17 00:00:00 2001 From: Dong Sun Lee Date: Mon, 19 Dec 2016 15:27:52 -0800 Subject: [PATCH] Revert "Apply the result of English documentation reivew" This reverts commit 891379568381b38df849b98c466eeed809069bac. Change-Id: Iec0ad8337b3bf150010bdf0948f64e5a9b6728fa --- doc/key-manager-client_doc.h | 8 +- doc/key-manager-types_doc.h | 11 +- doc/key-manager_doc.h | 20 +- src/include/ckmc/ckmc-error.h | 54 +- src/include/ckmc/ckmc-manager.h | 1175 +++++++++++++++++++++++++-------------- src/include/ckmc/ckmc-type.h | 827 ++++++++++++++++----------- 6 files changed, 1300 insertions(+), 795 deletions(-) diff --git a/doc/key-manager-client_doc.h b/doc/key-manager-client_doc.h index b17a65c..25720cc 100644 --- a/doc/key-manager-client_doc.h +++ b/doc/key-manager-client_doc.h @@ -13,16 +13,13 @@ * See the License for the specific language governing permissions and * limitations under the License. */ - - #ifndef __TIZEN_CORE_KEY_MANAGER_CLIENT_DOC_H__ #define __TIZEN_CORE_KEY_MANAGER_CLIENT_DOC_H__ - - /** * @ingroup CAPI_KEY_MANAGER_MODULE * @defgroup CAPI_KEY_MANAGER_CLIENT_MODULE Key Manager Client - * @brief It provides APIs accessing on the secure repository and additional secure cryptographic operations. + * @brief It provides APIs accessing on the secure repository and additional secure cryptographic operations. + * * @section CAPI_KEY_MANAGER_CLIENT_MODULE_HEADER Required Header * \#include * @@ -31,5 +28,4 @@ * Additionally, it provides secure cryptographic operations for non-exportable keys without revealing key values to clients. */ - #endif /* __TIZEN_CORE_KEY_MANAGER_CLIENT_DOC_H__ */ diff --git a/doc/key-manager-types_doc.h b/doc/key-manager-types_doc.h index e274dbd..c13d822 100644 --- a/doc/key-manager-types_doc.h +++ b/doc/key-manager-types_doc.h @@ -13,23 +13,20 @@ * See the License for the specific language governing permissions and * limitations under the License. */ - - #ifndef __TIZEN_CORE_KEY_MANAGER_TYPES_DOC_H__ #define __TIZEN_CORE_KEY_MANAGER_TYPES_DOC_H__ - - /** * @ingroup CAPI_KEY_MANAGER_MODULE * @defgroup CAPI_KEY_MANAGER_TYPES_MODULE Key Manager Data Types - * @brief It defines data types used in these APIs and provides utility methods handling them. + * @brief It defines data types used in these APIs and provides utility methods handling them. + * * @section CAPI_KEY_MANAGER_TYPES_MODULE_HEADER Required Header * \#include * * @section CAPI_KEY_MANAGER_TYPES_MODULE_OVERVIEW Overview - * It defines data types for key, certificate, raw buffer, and linked list used in these APIs. + * It defines data types for key, certificate,raw buffer, and linked list used in these APIs. * It also provides new and free methods for them. + * */ - #endif /* __TIZEN_CORE_KEY_MANAGER_TYPES_DOC_H__ */ diff --git a/doc/key-manager_doc.h b/doc/key-manager_doc.h index d9eb510..d34293f 100644 --- a/doc/key-manager_doc.h +++ b/doc/key-manager_doc.h @@ -13,17 +13,14 @@ * See the License for the specific language governing permissions and * limitations under the License. */ - - #ifndef __TIZEN_CORE_KEY_MANAGER_DOC_H__ #define __TIZEN_CORE_KEY_MANAGER_DOC_H__ - - /** * @ingroup CAPI_SECURITY_FRAMEWORK * @defgroup CAPI_KEY_MANAGER_MODULE Key Manager - * @brief The key manager provides a secure repository protected by Tizen platform for keys, certificates, and sensitive data of users and/or their APPs. - * Additionally, the key manager provides secure cryptographic operations for non-exportable keys without revealing key values to clients. + * @brief The key manager provides a secure repository protected by Tizen platform for keys, certificates, and sensitive data of users and/or their APPs. + * Additionally, the key manager provides secure cryptographic operations for non-exportable keys without revealing key values to clients. + * * @section CAPI_KEY_MANAGER_MODULE_OVERVIEW Overview * * @@ -36,15 +33,18 @@ * * *
APIDescription
Defines data types used in these APIs and provides utility methods handling them.
+ * * It provides a secure repository for keys, certificates, and sensitive data of users and/or their APPs which are protected by Tizen platform. * Additionally, it provides secure cryptographic operations for non-exportable keys without revealing key values to clients. * * @image html capi_key_manager_overview_diagram.png + * * The key manager provides 2 types of API. * - secure repository APIs : These APIs provides storing, retrieving, and removing functions for keys, certificates, and data. * - secure crypto APIs : These APIs provides additional cryptographic operations (create asymmetric key pair, sign/verify signature, verify certificate). + * * Data Store Policy: - * A client can specify simple access rules when storing data in Key Manager. + * A client can specify simple access rules when storing a data in Key Manager. * - Exportable/Non-Exportable: * Only for data tagged as exportable, Key Manager returns the raw value of the data. * If data is tagged as non-exportable, Key Manager does not return its raw value. @@ -53,18 +53,20 @@ * All data in Key Manager is protected by Tizen platform. * Besides, a client can encrypt its data using its own password additionally. * If a client provides a password when storing a data, the data will be encrypted with the password. - * This password should be provided when getting the data from Key Manager. + * This password should be provided when get the data from Key Manager. + * * Data Access Control * - By default, only the owner of a data can access to the data. * - If the owner grants the access to other applications, those applications can read or delete the data from key-manager DB. * - When an application is deleted, the data and access control information granted by the application are also removed. + * * Alias Format * - The format of alias is "package_id name". * - If package_id is not provided by a client, the key-manager will add the package_id of the client to the name internally. * - The client can specify only its own package id in the alias when storing a key, certificate, or data. * - A client should specify the package id of the owner in the alias to retrieve a a key, certificate, or data shared by other applications. * - Aliases are returned as the format of "package_id name" from the key-manager. + * */ - #endif /* __TIZEN_CORE_KEY_MANAGER_DOC_H__ */ diff --git a/src/include/ckmc/ckmc-error.h b/src/include/ckmc/ckmc-error.h index 9153841..082c887 100644 --- a/src/include/ckmc/ckmc-error.h +++ b/src/include/ckmc/ckmc-error.h @@ -5,7 +5,7 @@ * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * - * http://www.apache.org/licenses/LICENSE-2.0 + * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, @@ -13,9 +13,9 @@ * See the License for the specific language governing permissions and * limitations under the License * - * @file ckmc-error.h + * @file ckmc-error.h * @version 1.0 - * @brief This file contains error codes of the Key Manager. + * @brief This file contains error codes of the Key Manager. */ #ifndef __TIZEN_CORE_CKMC_ERROR_H_ #define __TIZEN_CORE_CKMC_ERROR_H_ @@ -31,39 +31,37 @@ extern "C" { * @{ */ - /** * @brief Enumeration for Key Manager Errors. * @since_tizen 2.3 */ typedef enum { - CKMC_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ - CKMC_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid function parameter */ - CKMC_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */ - CKMC_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */ - CKMC_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Device needed to run API is not supported*/ + CKMC_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ + CKMC_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid function parameter */ + CKMC_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */ + CKMC_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */ + CKMC_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Device needed to run API is not supported*/ - CKMC_ERROR_SOCKET = TIZEN_ERROR_KEY_MANAGER | 0x01, /**< Socket error between client and Central Key Manager */ - CKMC_ERROR_BAD_REQUEST = TIZEN_ERROR_KEY_MANAGER | 0x02, /**< Invalid request from client */ - CKMC_ERROR_BAD_RESPONSE = TIZEN_ERROR_KEY_MANAGER | 0x03, /**< Invalid response from Central Key Manager */ - CKMC_ERROR_SEND_FAILED = TIZEN_ERROR_KEY_MANAGER | 0x04, /**< Transmitting request failed */ - CKMC_ERROR_RECV_FAILED = TIZEN_ERROR_KEY_MANAGER | 0x05, /**< Receiving response failed */ - CKMC_ERROR_AUTHENTICATION_FAILED = TIZEN_ERROR_KEY_MANAGER | 0x06, /**< Optional password which used when saving is incorrect */ - CKMC_ERROR_BUFFER_TOO_SMALL = TIZEN_ERROR_KEY_MANAGER | 0x07, /**< The output buffer size which is passed as parameter is too small */ - CKMC_ERROR_SERVER_ERROR = TIZEN_ERROR_KEY_MANAGER | 0x08, /**< Central Key Manager has been failed for some reason */ - CKMC_ERROR_DB_LOCKED = TIZEN_ERROR_KEY_MANAGER | 0x09, /**< The database was not unlocked - user did not login */ - CKMC_ERROR_DB_ERROR = TIZEN_ERROR_KEY_MANAGER | 0x0A, /**< An internal error inside the database */ - CKMC_ERROR_DB_ALIAS_EXISTS = TIZEN_ERROR_KEY_MANAGER | 0x0B, /**< Provided alias already exists in the database */ - CKMC_ERROR_DB_ALIAS_UNKNOWN = TIZEN_ERROR_KEY_MANAGER | 0x0C, /**< No data for given alias */ - CKMC_ERROR_VERIFICATION_FAILED = TIZEN_ERROR_KEY_MANAGER | 0x0D, /**< CA certificate(s) were unknown and chain could not be created */ - CKMC_ERROR_INVALID_FORMAT = TIZEN_ERROR_KEY_MANAGER | 0x0E, /**< A provided file or binary has not a valid format */ - CKMC_ERROR_FILE_ACCESS_DENIED = TIZEN_ERROR_KEY_MANAGER | 0x0F, /**< A provided file doesn't exist or cannot be accessed in the file system */ - CKMC_ERROR_NOT_EXPORTABLE = TIZEN_ERROR_KEY_MANAGER | 0x10, /**< The data is saved as unexportable so it cannot be leaked */ - CKMC_ERROR_FILE_SYSTEM = TIZEN_ERROR_KEY_MANAGER | 0x11, /**< Save key/certificate/pkcs12 failed because of file system error */ - CKMC_ERROR_UNKNOWN = TIZEN_ERROR_KEY_MANAGER | 0xFF, /**< The error with unknown reason */ + CKMC_ERROR_SOCKET = TIZEN_ERROR_KEY_MANAGER | 0x01, /**< Socket error between client and Central Key Manager */ + CKMC_ERROR_BAD_REQUEST = TIZEN_ERROR_KEY_MANAGER | 0x02, /**< Invalid request from client */ + CKMC_ERROR_BAD_RESPONSE = TIZEN_ERROR_KEY_MANAGER | 0x03, /**< Invalid response from Central Key Manager */ + CKMC_ERROR_SEND_FAILED = TIZEN_ERROR_KEY_MANAGER | 0x04, /**< Transmitting request failed */ + CKMC_ERROR_RECV_FAILED = TIZEN_ERROR_KEY_MANAGER | 0x05, /**< Receiving response failed */ + CKMC_ERROR_AUTHENTICATION_FAILED = TIZEN_ERROR_KEY_MANAGER | 0x06, /**< Optional password which used when saving is incorrect */ + CKMC_ERROR_BUFFER_TOO_SMALL = TIZEN_ERROR_KEY_MANAGER | 0x07, /**< The output buffer size which is passed as parameter is too small */ + CKMC_ERROR_SERVER_ERROR = TIZEN_ERROR_KEY_MANAGER | 0x08, /**< Central Key Manager has been failed for some reason */ + CKMC_ERROR_DB_LOCKED = TIZEN_ERROR_KEY_MANAGER | 0x09, /**< The database was not unlocked - user did not login */ + CKMC_ERROR_DB_ERROR = TIZEN_ERROR_KEY_MANAGER | 0x0A, /**< An internal error inside the database */ + CKMC_ERROR_DB_ALIAS_EXISTS = TIZEN_ERROR_KEY_MANAGER | 0x0B, /**< Provided alias already exists in the database */ + CKMC_ERROR_DB_ALIAS_UNKNOWN = TIZEN_ERROR_KEY_MANAGER | 0x0C, /**< No data for given alias */ + CKMC_ERROR_VERIFICATION_FAILED = TIZEN_ERROR_KEY_MANAGER | 0x0D, /**< CA certificate(s) were unknown and chain could not be created */ + CKMC_ERROR_INVALID_FORMAT = TIZEN_ERROR_KEY_MANAGER | 0x0E, /**< A provided file or binary has not a valid format */ + CKMC_ERROR_FILE_ACCESS_DENIED = TIZEN_ERROR_KEY_MANAGER | 0x0F, /**< A provided file doesn't exist or cannot be accessed in the file system */ + CKMC_ERROR_NOT_EXPORTABLE = TIZEN_ERROR_KEY_MANAGER | 0x10, /**< The data is saved as unexportable so it cannot be leaked */ + CKMC_ERROR_FILE_SYSTEM = TIZEN_ERROR_KEY_MANAGER | 0x11, /**< Save key/certificate/pkcs12 failed because of file system error */ + CKMC_ERROR_UNKNOWN = TIZEN_ERROR_KEY_MANAGER | 0xFF, /**< The error with unknown reason */ } key_manager_error_e; - /** * @} */ diff --git a/src/include/ckmc/ckmc-manager.h b/src/include/ckmc/ckmc-manager.h index 33ca5b0..1898129 100644 --- a/src/include/ckmc/ckmc-manager.h +++ b/src/include/ckmc/ckmc-manager.h @@ -5,7 +5,7 @@ * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * - * http://www.apache.org/licenses/LICENSE-2.0 + * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, @@ -14,10 +14,10 @@ * limitations under the License * * - * @file ckmc-manager.h - * @version 1.0 - * @brief Provides management functions(storing, retrieving, and removing) for keys, - * certificates and data of a user and additional crypto functions. + * @file ckmc-manager.h + * @version 1.0 + * @brief Provides management functions(storing, retrieving, and removing) for keys, + * certificates and data of a user and additional crypto functions. */ @@ -42,52 +42,74 @@ 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 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. - * @remarks key_type in key may be set to #CKMC_KEY_NONE as an input. key_type is determined inside key manager during storing keys. - * @remarks Some private key files are protected by a password. If raw_key in key read from those encrypted files is encrypted with a password, the password should be provided in the - #ckmc_key_s structure. - * @remarks If password in the policy is provided, the key is additionally encrypted with the password in the policy. - * @param[in] alias The name of a key to be stored - * @param[in] key The key's binary value to be stored - * @param[in] policy The policy about how to store a key securely + * @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. + * @remarks key_type in key may be set to #CKMC_KEY_NONE as an input. key_type is determined inside + * key manager during storing keys. + * @remarks Some private key files are protected by a password. If raw_key in key read from those + * encrypted files is encrypted with a password, the password should be provided in the + * #ckmc_key_s structure. + * @remarks If password in policy is provided, the key is additionally encrypted with the password + * in policy. + * + * @param[in] alias The name of a key to be stored + * @param[in] key The key's binary value to be stored + * @param[in] policy The policy about how to store a key securely + * * @return @c 0 on success, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful + * + * @retval #CKMC_ERROR_NONE Successful * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid - * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in) - * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists - * @retval #CKMC_ERROR_INVALID_FORMAT The format of raw_key is not valid - * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error + * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged + * in) + * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists + * @retval #CKMC_ERROR_INVALID_FORMAT The format of raw_key is not valid + * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_remove_alias() * @see ckmc_get_key() * @see ckmc_get_key_alias_list() * @see #ckmc_key_s * @see #ckmc_policy_s */ -int ckmc_save_key(const char *alias, const ckmc_key_s key, const ckmc_policy_s policy); - +int ckmc_save_key(const char *alias, const ckmc_key_s key, + const ckmc_policy_s policy); /** * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif [Use ckmc_remove_alias() instead] * @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. + * * @param[in] alias The name of a key to be removed + * * @return @c 0 on success, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful + * + * @retval #CKMC_ERROR_NONE Successful * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid - * @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 a database error - * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist + * @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 a database error + * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_save_key() * @see ckmc_get_key() * @see ckmc_get_key_alias_list() @@ -95,53 +117,72 @@ int ckmc_save_key(const char *alias, const ckmc_key_s key, const ckmc_policy_s p int ckmc_remove_key(const char *alias) TIZEN_DEPRECATED_API; - /** * @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 longer needed. - * @param[in] alias The name of a key to retrieve - * @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[out] ppkey The pointer to a newly created ckmc_key_s handle + * @remarks You must destroy the newly created @a ppkey by calling ckmc_key_free() if it is no + * longer needed. + * + * @param[in] alias The name of a key to retrieve + * @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[out] ppkey The pointer to a newly created ckmc_key_s handle + * * @return @c 0 on success, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful + * + * @retval #CKMC_ERROR_NONE Successful * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid - * @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 a database error + * @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 a database error * @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 + * @retval #CKMC_ERROR_AUTHENTICATION_FAILED + * 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. + * * @see ckmc_save_key() * @see ckmc_remove_alias() * @see ckmc_get_key_alias_list() */ 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() * if it is no longer needed. - * @param[out] ppalias_list The pointer to a newly created ckmc_alias_list_s handle containing all - * available alias of keys \n - * If there is no available key alias, *ppalias_list will be null + * + * @param[out] ppalias_list The pointer to a newly created ckmc_alias_list_s handle containing all + * available alias of keys \n + * If there is no available key alias, *ppalias_list will be null. + * * @return @c 0 on success, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful + * + * @retval #CKMC_ERROR_NONE Successful * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid - * @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 a database error - * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist + * @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 a database error + * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_save_key() * @see ckmc_remove_alias() * @see ckmc_get_key() @@ -149,50 +190,70 @@ int ckmc_get_key(const char *alias, const char *password, ckmc_key_s **ppkey); int ckmc_get_key_alias_list(ckmc_alias_list_s **ppalias_list); + + /** * @brief Stores a certificate 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 The certificate's binary value will be converted and saved as binary DER encoded certificates. - * @param[in] alias The name of a certificate to be stored - * @param[in] cert The certificate's binary value to be stored + * + * @remarks the certificate's binary value will be converted and saved as binary DER encoded + * certificates. + * + * @param[in] alias The name of a certificate to be stored + * @param[in] cert The certificate's binary value to be stored * @param[in] policy The policy about how to store a certificate securely + * * @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_DB_LOCKED A user key is not loaded in memory (a user is not logged in) - * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists - * @retval #CKMC_ERROR_INVALID_FORMAT The format of raw_cert is not valid - * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error - * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged + * in) + * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists + * @retval #CKMC_ERROR_INVALID_FORMAT The format of raw_cert is not valid + * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error + * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_remove_alias() * @see ckmc_get_cert() * @see ckmc_get_cert_alias_list() * @see #ckmc_cert_s * @see #ckmc_policy_s */ -int ckmc_save_cert(const char *alias, const ckmc_cert_s cert, const ckmc_policy_s policy); - +int ckmc_save_cert(const char *alias, const ckmc_cert_s cert, + const ckmc_policy_s policy); /** * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif [Use ckmc_remove_alias() instead] * @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. + * * @param[in] alias The name of a certificate to be removed + * * @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_DB_LOCKED A user key is not loaded in memory (a user is not logged in) - * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error - * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist - * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @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 a database error + * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist + * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_save_cert() * @see ckmc_get_cert() * @see ckmc_get_cert_alias_list() @@ -200,54 +261,74 @@ int ckmc_save_cert(const char *alias, const ckmc_cert_s cert, const ckmc_policy_ int ckmc_remove_cert(const char *alias) TIZEN_DEPRECATED_API; - /** * @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. - * @remarks You must destroy the newly created @a ppcert by calling ckmc_cert_free() if it is no longer needed. - * @param[in] alias The name of a certificate to retrieve + * @remarks You must destroy the newly created @a ppcert by calling ckmc_cert_free() if it is no + * longer needed. + * + * @param[in] alias The name of a certificate to retrieve * @param[in] password The password used in decrypting a certificate value \n * If password of policy is provided in ckmc_save_cert(), the same password - * should be provided + * should be provided. * @param[out] ppcert The pointer to a newly created ckmc_cert_s handle + * * @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_DB_LOCKED A user key is not loaded in memory (a user is not logged in) - * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error - * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exists - * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager - * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Decryption failed because password is incorrect + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @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 a database error + * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exists + * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * @retval #CKMC_ERROR_AUTHENTICATION_FAILED + * 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. + * * @see ckmc_save_cert() * @see ckmc_remove_alias() * @see ckmc_get_cert_alias_list() */ -int ckmc_get_cert(const char *alias, const char *password, ckmc_cert_s **ppcert); - +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() if it is no longer needed. - * @param[out] ppalias_list The pointer to a newly created ckmc_alias_list_s handle containing all available alias of keys \n + * @remarks You must destroy the newly created @a ppalias_list by calling ckmc_alias_list_all_free() + * if it is no longer needed. + * + * @param[out] ppalias_list The pointer to a newly created ckmc_alias_list_s handle containing all + * available alias of keys \n * If there is no available key alias, *ppalias_list will be null. + * * @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_DB_LOCKED A user key is not loaded in memory (a user is not logged in) - * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error - * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist - * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @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 a database error + * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist + * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_save_cert() * @see ckmc_remove_alias() * @see ckmc_get_cert() @@ -255,23 +336,34 @@ int ckmc_get_cert(const char *alias, const char *password, ckmc_cert_s **ppcert) int ckmc_get_cert_alias_list(ckmc_alias_list_s **ppalias_list); + + /** - * @brief Stores PKCS12's contents inside key manager based on the provided policies. All items from the PKCS12 will use the same alias. + * @brief Stores PKCS12's contents inside key manager based on the provided policies. + * All items from the PKCS12 will use the same alias. + * * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * @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 - * @param[in] key_policy The policy about how to store pkcs's private key - * @param[in] cert_policy The policy about how to store pkcs's certificate + * @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 + * @param[in] key_policy The policy about how to store pkcs's private key + * @param[in] cert_policy The policy about how to store pkcs's certificate + * * @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_DB_LOCKED A user key is not loaded in memory (a user is not logged in) - * @retval #CKMC_ERROR_DB_ALIAS_EXISTS 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_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged + * in) + * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists + * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error + * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_remove_alias() * @see ckmc_get_pkcs12() * @see ckmc_get_data_alias_list() @@ -279,77 +371,108 @@ int ckmc_get_cert_alias_list(ckmc_alias_list_s **ppalias_list); * @see #ckmc_pkcs12_s * @see #ckmc_policy_s */ -int ckmc_save_pkcs12(const char *alias, const ckmc_pkcs12_s *pkcs, const ckmc_policy_s key_policy, const ckmc_policy_s cert_policy); - +int ckmc_save_pkcs12(const char *alias, + const ckmc_pkcs12_s *pkcs, + const ckmc_policy_s key_policy, + const ckmc_policy_s cert_policy); /** * @brief Gets a pkcs12 from key manager. + * * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * @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 longer needed. - * @param[in] alias The name of a data to retrieve - * @param[in] key_password Password that was used to encrypt privateKey (may be NULL) - * @param[in] cert_password Password used to encrypt certificates (may be NULL) - * @param[out] pkcs12 The pointer to a newly created ckmc_pkcs12_s handle + * @remarks You must destroy the newly created @a pkcs12 by calling ckmc_pkcs12_free() if it is no + * longer needed. + * + * @param[in] alias The name of a data to retrieve + * @param[in] key_password Password that was used to encrypt privateKey (may be NULL) + * @param[in] cert_password Password used to encrypt certificates (may be NULL) + * @param[out] pkcs12 The pointer to a newly created ckmc_pkcs12_s handle + * * @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_DB_LOCKED A user key is not loaded in memory (a user is not logged in) - * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error - * @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 key_password or cert_password does not match with password used to encrypt data + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @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 a database error + * @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 + * key_password or cert_password does not match with password + * used to encrypt data + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_save_pkcs12() * @see ckmc_remove_alias() */ -int ckmc_get_pkcs12(const char *alias, const char *key_password, const char *cert_password, ckmc_pkcs12_s **pkcs12); - +int ckmc_get_pkcs12(const char *alias, const char *key_password, + const char *cert_password, ckmc_pkcs12_s **pkcs12); /** * @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. - * @param[in] alias The name of a data to be stored - * @param[in] data The binary value to be stored + * @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 * @param[in] policy The policy about how to store a data securely + * * @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_DB_LOCKED A user key is not loaded in memory (a user is not logged in) - * @retval #CKMC_ERROR_DB_ALIAS_EXISTS 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_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged + * in) + * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists + * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error + * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_remove_alias() * @see ckmc_get_data() * @see ckmc_get_data_alias_list() * @see #ckmc_raw_buffer_s * @see #ckmc_policy_s */ -int ckmc_save_data(const char *alias, ckmc_raw_buffer_s data, const ckmc_policy_s policy); - +int ckmc_save_data(const char *alias, ckmc_raw_buffer_s data, + const ckmc_policy_s policy); /** * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif [Use ckmc_remove_alias() instead] * @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. + * * @param[in] alias The name of a data to be removed + * * @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_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 - * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist - * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @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 + * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist + * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_save_data() * @see ckmc_get_data() * @see ckmc_get_data_alias_list() @@ -357,52 +480,72 @@ int ckmc_save_data(const char *alias, ckmc_raw_buffer_s data, const ckmc_policy_ int ckmc_remove_data(const char *alias) TIZEN_DEPRECATED_API; - /** * @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 * longer needed. - * @param[in] alias The name of a data to retrieve - * @param[in] password The password used in decrypting a data value \n - * If password of policy is provided in ckmc_save_data(), the same password should be provided. - * @param[out] ppdata The pointer to a newly created ckmc_raw_buffer_s handle + * + * @param[in] alias The name of a data to retrieve + * @param[in] password The password used in decrypting a data value \n + * If password of policy is provided in ckmc_save_data(), the same password + * should be provided. + * @param[out] ppdata The pointer to a newly created ckmc_raw_buffer_s handle + * * @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_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 - * @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. + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @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 + * @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. * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_save_data() * @see ckmc_remove_alias() * @see ckmc_get_data_alias_list() */ -int ckmc_get_data(const char *alias, const char *password, ckmc_raw_buffer_s **ppdata); - +int ckmc_get_data(const char *alias, const char *password, + ckmc_raw_buffer_s **ppdata); /** * @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() if it is no longer needed. - * @param[out] ppalias_list The pointer to a newly created ckmc_alias_list_s handle containing all available alias of keys \n + * @remarks You must destroy the newly created @a ppalias_list by calling ckmc_alias_list_all_free() + * if it is no longer needed. + * + * @param[out] ppalias_list The pointer to a newly created ckmc_alias_list_s handle containing all + * available alias of keys \n * If there is no available key alias, *ppalias_list will be null. + * * @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_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 - * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist - * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @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 + * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist + * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_save_data() * @see ckmc_remove_alias() * @see ckmc_get_data() @@ -410,139 +553,205 @@ int ckmc_get_data(const char *alias, const char *password, ckmc_raw_buffer_s **p int ckmc_get_data_alias_list(ckmc_alias_list_s **ppalias_list); + + /** - * @brief Creates RSA private/public key pair and stores them inside key manager based on each policy. + * @brief Creates RSA private/public key pair and stores them inside key manager based on each + * 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 If password in the policy is provided, the key is additionally encrypted with the password in the policy. - * @param[in] size The size of key strength to be created \n - * @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 - * @param[in] policy_public_key The policy about how to store a public key securely + * @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 + * @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 + * @param[in] policy_public_key The policy about how to store a public key securely + * * @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_DB_LOCKED A user key is not loaded in memory (a user is not logged in) - * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists - * @retval #CKMC_ERROR_DB_ERROR Failed due to other DB transaction unexpectedly - * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged + * in) + * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists + * @retval #CKMC_ERROR_DB_ERROR Failed due to other DB transaction unexpectedly + * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_create_key_pair_dsa() * @see ckmc_create_key_pair_ecdsa() * @see ckmc_create_signature() * @see ckmc_verify_signature() */ -int ckmc_create_key_pair_rsa(const size_t size, const char *private_key_alias, const char *public_key_alias, const ckmc_policy_s policy_private_key, const ckmc_policy_s policy_public_key); - +int ckmc_create_key_pair_rsa(const size_t size, + const char *private_key_alias, + const char *public_key_alias, + const ckmc_policy_s policy_private_key, + const ckmc_policy_s policy_public_key); /** - * @brief Creates DSA private/public key pair and stores them inside key manager based on each policy. + * @brief Creates DSA private/public key pair and stores them inside key manager based on each + * 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 If password in the policy is provided, the key is additionally encrypted with the password in the policy. - * @param[in] size The size of key strength to be created \n - * @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 - * @param[in] policy_public_key The policy about how to store a public key securely + * @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 + * @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 + * @param[in] policy_public_key The policy about how to store a public key securely + * * @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_DB_LOCKED A user key is not loaded in memory (a user is not logged in) - * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists - * @retval #CKMC_ERROR_DB_ERROR Failed due to other DB transaction unexpectedly - * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged + * in) + * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists + * @retval #CKMC_ERROR_DB_ERROR Failed due to other DB transaction unexpectedly + * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_create_key_pair_rsa() * @see ckmc_create_key_pair_ecdsa() * @see ckmc_create_signature() * @see ckmc_verify_signature() */ -int ckmc_create_key_pair_dsa(const size_t size, const char *private_key_alias, const char *public_key_alias, const ckmc_policy_s policy_private_key, const ckmc_policy_s policy_public_key); - +int ckmc_create_key_pair_dsa(const size_t size, + const char *private_key_alias, + const char *public_key_alias, + const ckmc_policy_s policy_private_key, + const ckmc_policy_s policy_public_key); /** - * @brief Creates ECDSA private/public key pair and stores them inside key manager based on each policy. + * @brief Creates ECDSA private/public key pair and stores them inside key manager based on each + * 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 If password in the policy is provided, the key is additionally encrypted with the password in the policy. - * @param[in] type The type of elliptic curve of ECDSA - * @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 - * @param[in] policy_public_key The policy about how to store a public key securely + * @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] type The type of elliptic curve of ECDSA + * @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 + * @param[in] policy_public_key The policy about how to store a public key securely + * * @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_DB_LOCKED A user key is not loaded in memory (a user is not logged in) - * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists - * @retval #CKMC_ERROR_DB_ERROR Failed due to other DB transaction unexpectedly - * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged + * in) + * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists + * @retval #CKMC_ERROR_DB_ERROR Failed due to other DB transaction unexpectedly + * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_create_key_pair_rsa() * @see ckmc_create_key_pair_dsa() * @see ckmc_create_signature() * @see ckmc_verify_signature() * @see #ckmc_ec_type_e */ -int ckmc_create_key_pair_ecdsa(const ckmc_ec_type_e type, const char *private_key_alias, const char *public_key_alias, const ckmc_policy_s policy_private_key, const ckmc_policy_s policy_public_key); - +int ckmc_create_key_pair_ecdsa(const ckmc_ec_type_e type, + const char *private_key_alias, + const char *public_key_alias, + const ckmc_policy_s policy_private_key, + const ckmc_policy_s policy_public_key); /** * @brief Creates AES key and stores it inside key manager based on the policy. + * * @since_tizen 3.0 - * @remarks If password in the policy is provided, the key is additionally encrypted with the password in the policy. - * @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 + * + * @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] key_alias The name of key to be stored + * @param[in] key_policy The policy about how to store the key securely + * * @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_DB_LOCKED A user key is not loaded in memory (a user is not logged in) - * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists - * @retval #CKMC_ERROR_DB_ERROR Failed due to other DB transaction unexpectedly - * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged + * in) + * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists + * @retval #CKMC_ERROR_DB_ERROR Failed due to other DB transaction unexpectedly + * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @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(size_t size, const char *key_alias, ckmc_policy_s key_policy); - +int ckmc_create_key_aes(size_t size, + const char *key_alias, + 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 If password of policy is provided during storing a key, the same password should be provided. - * @remarks You must destroy the newly created @a ppsignature by calling ckmc_buffer_free() if it is no longer needed. - * @param[in] private_key_alias The name of private key - * @param[in] password The password used in decrypting a private key value - * @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 - * @param[out] ppsignature The pointer to a newly created signature \n - * If an error occurs, @a *ppsignature will be null + * @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. + * @remarks You must destroy the newly created @a ppsignature by calling ckmc_buffer_free() if it is + * no longer needed. + * + * @param[in] private_key_alias The name of private key + * @param[in] password The password used in decrypting a private key value + * @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 + * @param[out] ppsignature The pointer to a newly created signature \n + * If an error occurs, @a *ppsignature will be null + * * @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_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 - * @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 + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @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 + * @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 + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_create_key_pair_rsa() * @see ckmc_create_key_pair_ecdsa() * @see ckmc_verify_signature() @@ -550,238 +759,344 @@ int ckmc_create_key_aes(size_t size, const char *key_alias, ckmc_policy_s key_po * @see #ckmc_hash_algo_e * @see #ckmc_rsa_padding_algo_e */ -int ckmc_create_signature(const char *private_key_alias, const char *password, const ckmc_raw_buffer_s message, const ckmc_hash_algo_e hash, const ckmc_rsa_padding_algo_e padding, ckmc_raw_buffer_s **ppsignature); - +int ckmc_create_signature(const char *private_key_alias, + const char *password, + const ckmc_raw_buffer_s message, + const ckmc_hash_algo_e hash, + const ckmc_rsa_padding_algo_e padding, + ckmc_raw_buffer_s **ppsignature); /** - * @brief Verifies a given signature on a given message using a public key and returns the signature status. + * @brief Verifies a given signature on a given message using a public key and returns the signature + * 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 If password of policy is provided during storing a key, the same password should be provided. - * @param[in] public_key_alias The name of public key - * @param[in] password The password used in decrypting a public key value - * @param[in] message The input on which the signature is created - * @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 + * @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. + * + * @param[in] public_key_alias The name of public key + * @param[in] password The password used in decrypting a public key value + * @param[in] message The input on which the signature is created + * @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 + * * @return @c 0 on success and the signature is valid, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful - * @retval #CKMC_ERROR_VERIFICATION_FAILED The signature is invalid - * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid - * @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 - * @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 + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_VERIFICATION_FAILED The signature is invalid + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @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 + * @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 + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_create_key_pair_rsa() * @see ckmc_create_key_pair_ecdsa() * @see ckmc_verify_signature() * @see #ckmc_hash_algo_e * @see #ckmc_rsa_padding_algo_e */ -int ckmc_verify_signature(const char *public_key_alias, const char *password, const ckmc_raw_buffer_s message, const ckmc_raw_buffer_s signature, const ckmc_hash_algo_e hash, const ckmc_rsa_padding_algo_e padding); - +int ckmc_verify_signature(const char *public_key_alias, + const char *password, + const ckmc_raw_buffer_s message, + const ckmc_raw_buffer_s signature, + const ckmc_hash_algo_e hash, + const ckmc_rsa_padding_algo_e padding); /** * @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 The trusted root certificate of the chain should 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 + * @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. + * @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[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 - * @retval #CKMC_ERROR_NONE Successful - * @retval #CKMC_ERROR_VERIFICATION_FAILED The certificate chain is not valid - * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid - * @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 - * @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 + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_VERIFICATION_FAILED The certificate chain is not valid + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @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 + * @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 + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_cert_list_all_free() */ -int ckmc_get_cert_chain(const ckmc_cert_s *cert, const ckmc_cert_list_s *untrustedcerts, ckmc_cert_list_s **ppcert_chain_list); - +int ckmc_get_cert_chain(const ckmc_cert_s *cert, + const ckmc_cert_list_s *untrustedcerts, + ckmc_cert_list_s **ppcert_chain_list); /** * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif [Use ckmc_get_cert_chain() instead] - * @brief Verifies a certificate chain using an alias list of untrusted certificates and return that chain. + * @brief Verifies a certificate chain using an alias list of untrusted certificates and return 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 The trusted root certificate of the chain should 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. + * @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. + * @remarks You must destroy the newly created @a ppcert_chain_list by calling + * ckmc_cert_list_all_free() if it is no longer needed. * @remarks @a untrustedcerts shouldn't be protected with optional password. - * @param[in] cert The certificate to be verified - * @param[in] untrustedcerts The alias list of untrusted CA certificates stored in key manager to be used in verifying a certificate chain + * + * @param[in] cert The certificate to be verified + * @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 + * * @return @c 0 on success and the signature is valid, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful - * @retval #CKMC_ERROR_VERIFICATION_FAILED The certificate chain is not valid - * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid - * @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 - * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist - * @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 Some certificates were encrypted with password and could not be used + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_VERIFICATION_FAILED The certificate chain is not valid + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @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 + * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist + * @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 + * Some certificates were encrypted with password and could not + * be used + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_get_cert_chain() * @see ckmc_cert_list_all_free() */ -int ckmc_get_cert_chain_with_alias(const ckmc_cert_s *cert, const ckmc_alias_list_s *untrustedcerts, ckmc_cert_list_s **ppcert_chain_list) +int ckmc_get_cert_chain_with_alias(const ckmc_cert_s *cert, + const ckmc_alias_list_s *untrustedcerts, + ckmc_cert_list_s **ppcert_chain_list) TIZEN_DEPRECATED_API; - /** - * @brief Verifies a certificate chain and returns that chain using user-entered, trusted, and untrusted CA certificates. + * @brief Verifies a certificate chain and returns that chain using user entered trusted and + * untrusted CA certificates. + * * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * @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 + * + * @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 * @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 - * @retval #CKMC_ERROR_NONE Successful - * @retval #CKMC_ERROR_VERIFICATION_FAILED The certificate chain is not valid - * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid - * @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 - * @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_NONE Successful + * @retval #CKMC_ERROR_VERIFICATION_FAILED The certificate chain is not valid + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @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 + * @retval #CKMC_ERROR_INVALID_FORMAT The format of certificate is not valid + * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_cert_list_all_free() */ -int ckmc_get_cert_chain_with_trustedcert(const ckmc_cert_s *cert, const ckmc_cert_list_s *untrustedcerts, const ckmc_cert_list_s *trustedcerts, const bool use_trustedsystemcerts, ckmc_cert_list_s **ppcert_chain_list); - +int ckmc_get_cert_chain_with_trustedcert(const ckmc_cert_s *cert, + const ckmc_cert_list_s *untrustedcerts, + const ckmc_cert_list_s *trustedcerts, + const bool use_trustedsystemcerts, + ckmc_cert_list_s **ppcert_chain_list); /** - * @brief Perform OCSP that checks certificate is whether revoked or not. + * @brief Perform OCSP which checks certificate is whether revoked or not. + * * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif * @privlevel public * @privilege %http://tizen.org/privilege/internet - * @remarks %http://tizen.org/privilege/internet (public level privilege) is required to use this API instead of %http://tizen.org/privilege/keymanager (public - level privilege) since 3.0. - * @param[in] pcert_chain_list Valid certificate chain to perform OCSP check - * @param[out] ocsp_status The pointer to status result of OCSP check - * @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_PERMISSION_DENIED Failed to access key manager - * @retval #CKMC_ERROR_NOT_SUPPORTED Device needed to run API is not supported + * + * @remarks %http://tizen.org/privilege/internet (public level privilege) is required + * to use this API instead of %http://tizen.org/privilege/keymanager (public + * level privilege) since 3.0. + * + * @param[in] pcert_chain_list Valid certificate chain to perform OCSP check + * @param[out] ocsp_status The pointer to status result of OCSP check + * + * @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_PERMISSION_DENIED Failed to access key manager + * @retval #CKMC_ERROR_NOT_SUPPORTED Device needed to run API is not supported + * * @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(). + * @pre @a pcert_chain_list is created with ckmc_get_certificate_chain() or + * ckmc_get_certificate_chain_with_alias(). + * * @see ckmc_get_cert_chain()) * @see ckmc_cert_list_all_free() */ -int ckmc_ocsp_check(const ckmc_cert_list_s *pcert_chain_list, ckmc_ocsp_status_e *ocsp_status); - +int ckmc_ocsp_check(const ckmc_cert_list_s *pcert_chain_list, + ckmc_ocsp_status_e *ocsp_status); /** * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif [Use ckmc_set_permission() instead] * @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. - * @param[in] alias Data alias for which access will be granted - * @param[in] accessor Package id of the application that will gain access rights - * @param[in] granted Rights granted for @a accessor application - * @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_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 - * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist - * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * + * @param[in] alias Data alias for which access will be granted + * @param[in] accessor Package id of the application that will gain access rights + * @param[in] granted Rights granted for @a accessor application + * + * @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_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 + * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist + * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_deny_access() */ -int ckmc_allow_access(const char *alias, const char *accessor, ckmc_access_right_e granted) +int ckmc_allow_access(const char *alias, const char *accessor, + ckmc_access_right_e granted) TIZEN_DEPRECATED_API; - /** * @brief Allows another application to access client's application data. + * * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * @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. - * @param[in] alias Data alias for which access will be granted - * @param[in] accessor Package id of the application that will gain access rights + * + * @param[in] alias Data alias for which access will be granted + * @param[in] accessor Package id of the application that will gain access rights * @param[in] permissions Mask of permissions granted for @a accessor application - * (@a ckmc_permission_e) + * (#ckmc_permission_e) * (previous permission mask will be replaced with the new mask value) - * @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_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 - * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist - * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * + * @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_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 + * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist + * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. */ -int ckmc_set_permission(const char *alias, const char *accessor, int permissions); - +int ckmc_set_permission(const char *alias, const char *accessor, + int permissions); /** * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif [Use ckmc_set_permission() instead] * @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 Only access previously granted with ckmc_allow_access can be revoked. - * @param[in] alias Data alias for which access will be revoked - * @param[in] accessor Package id of the application that will lose access rights - * @return @c 0 on success, - * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful - * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid or the @a accessor doesn't have access to @a alias - * @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 - * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist - * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * + * @param[in] alias Data alias for which access will be revoked + * @param[in] accessor Package id of the application that will lose access rights + * + * @return @c 0 on success, otherwise a negative error value + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid or the @a accessor doesn't + * have access to @a alias + * @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 + * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist + * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_allow_access() * @see ckmc_set_permission() */ int ckmc_deny_access(const char *alias, const char *accessor) TIZEN_DEPRECATED_API; - /** - * @brief Removes an entry (no matter of type) from the key manager. + * @brief Removes a an entry (no matter of type) from the key manager. + * * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * @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. + * * @param[in] alias Item alias to be removed + * * @return @c 0 on success, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful + * + * @retval #CKMC_ERROR_NONE Successful * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid - * @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 a database error - * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist + * @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 a database error + * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * * @see ckmc_save_key() * @see ckmc_save_cert() * @see ckmc_save_data() @@ -792,35 +1107,44 @@ TIZEN_DEPRECATED_API; */ int ckmc_remove_alias(const char *alias); - /** * @brief Encrypts data using selected key and algorithm. + * * @since_tizen 3.0 + * * @remarks Key identified by @a key_alias should exist. - * @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 the policy is provided in ckmc_save_key(), the same - * password should be provided - * @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 ckmc_buffer_free() - * @return @c 0 on success, - * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful - * @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 - * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Key with given alias does not exist - * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager - * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Key decryption failed because password is incorrect + * + * @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. 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 + * ckmc_buffer_free() + * + * @return @c 0 on success, otherwise a negative error value + * + * @retval #CKMC_ERROR_NONE Successful + * @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 + * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Key with given alias does not exist + * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * @retval #CKMC_ERROR_AUTHENTICATION_FAILED + * Key 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. + * * @see ckmc_buffer_free() * @see ckmc_param_list_new() * @see ckmc_param_list_free() @@ -831,33 +1155,48 @@ int ckmc_remove_alias(const char *alias); * @see #ckmc_param_name_e * @see #ckmc_algo_type_e */ -int ckmc_encrypt_data(ckmc_param_list_h params, const char *key_alias, const char *password, const ckmc_raw_buffer_s decrypted, ckmc_raw_buffer_s **ppencrypted); - +int ckmc_encrypt_data(ckmc_param_list_h params, + const char *key_alias, + const char *password, + const ckmc_raw_buffer_s decrypted, + ckmc_raw_buffer_s **ppencrypted); /** * @brief Decrypts data using selected key and algorithm. + * * @since_tizen 3.0 + * * @remarks Key identified by @a key_alias should exist. - * @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 the policy is provided in ckmc_save_key(), the same password should be provided - * @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 @a decrypted with ckmc_buffer_free() - * @return @c 0 on success, - * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful - * @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 - * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Key with given alias does not exist - * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager - * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Key decryption failed because password is incorrect + * + * @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 + * password should be provided + * @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 @a decrypted with + * ckmc_buffer_free() + * + * @return @c 0 on success, otherwise a negative error value + * + * @retval #CKMC_ERROR_NONE Successful + * @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 + * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Key with given alias does not exist + * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager + * @retval #CKMC_ERROR_AUTHENTICATION_FAILED + * Key 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. + * * @see ckmc_buffer_free() * @see ckmc_param_list_new() * @see ckmc_param_list_free() @@ -868,8 +1207,11 @@ int ckmc_encrypt_data(ckmc_param_list_h params, const char *key_alias, const cha * @see #ckmc_param_name_e * @see #ckmc_algo_type_e */ -int ckmc_decrypt_data(ckmc_param_list_h params, const char *key_alias, const char *password, const ckmc_raw_buffer_s encrypted, ckmc_raw_buffer_s **ppdecrypted); - +int ckmc_decrypt_data(ckmc_param_list_h params, + const char *key_alias, + const char *password, + const ckmc_raw_buffer_s encrypted, + ckmc_raw_buffer_s **ppdecrypted); #ifdef __cplusplus } @@ -879,4 +1221,5 @@ int ckmc_decrypt_data(ckmc_param_list_h params, const char *key_alias, const cha * @} */ + #endif /* __TIZEN_CORE_CKMC_MANAGER_H */ diff --git a/src/include/ckmc/ckmc-type.h b/src/include/ckmc/ckmc-type.h index 9f41ad9..86e99fe 100644 --- a/src/include/ckmc/ckmc-type.h +++ b/src/include/ckmc/ckmc-type.h @@ -5,7 +5,7 @@ * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * - * http://www.apache.org/licenses/LICENSE-2.0 + * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, @@ -14,12 +14,11 @@ * limitations under the License * * - * @file ckmc-type.h - * @version 1.0 - * @brief Definitions of struct for the Key Manager's CAPI and their utility functions. + * @file ckmc-type.h + * @version 1.0 + * @brief Definitions of struct for the Key Manager's CAPI and their utility functions. */ - #ifndef __TIZEN_CORE_CKMC_TYPE_H #define __TIZEN_CORE_CKMC_TYPE_H @@ -29,6 +28,7 @@ #define KEY_MANAGER_CAPI __attribute__((visibility("default"))) + #ifdef __cplusplus extern "C" { #endif @@ -41,229 +41,219 @@ extern "C" { /* * Note: on tizen 3.0 owner id is equal to pkgId. * Preinstalled system(uid < 5000) and user (uid >= 5000) applications - * does not have any pkgId. That's why ckm uses special "virtual" + * does not have any pkgId. Thats why ckm uses special "virtual" * pkgid for them. The virtual strings are defined under: - * ckmc_ownerid_system - * ckmc_ownerid_user - * + * ckmc_owner_id_system */ - /** * @deprecated Deprecated since 3.0. [Use ckmc_owner_id_separator instead] * @brief Separator between alias and label. + * * @since_tizen 2.3 + * * @remarks Alias can be provided as an alias alone, or together with label - in this * case, separator " " (space bar) is used to separate label and alias. + * * @see #ckmc_owner_id_separator - * @see key-manager_doc.h */ KEY_MANAGER_CAPI extern char const *const ckmc_label_name_separator; - /** * @brief Separator between alias and owner id. + * * @since_tizen 3.0 + * * @remarks Alias can be provided as an alias alone, or together with owner id. * In this case, separator " " (space bar) is used to separate id and alias. - * @see key-manager_doc.h + * + * @see ckmc_alias_new() */ KEY_MANAGER_CAPI extern char const *const ckmc_owner_id_separator; - /** * @brief The owner of system database. + * * @since_tizen 3.0 - * @remarks ckmc_owner_id_system constrains id connected with all SYSTEM applications that run with uid less than 5000. - * Client should use ckmc_owner_id_system to access data owned by system application and stored in system database. - * Note: Client must have permission to access proper row. + * + * @remarks #ckmc_owner_id_system constains id connected with all system applications + * that run with uid less than 5000. + * @remarks Client should use #ckmc_owner_id_system to access data owned by system + * application and stored in system database. + * @remarks Client must have permission to access proper row. + * + * @see ckmc_alias_new() */ KEY_MANAGER_CAPI extern char const *const ckmc_owner_id_system; - /** * @brief Enumeration for key types of key manager. * @since_tizen 2.3 */ typedef enum __ckmc_key_type { - CKMC_KEY_NONE = 0, /**< Key type not specified */ - CKMC_KEY_RSA_PUBLIC, /**< RSA public key */ - CKMC_KEY_RSA_PRIVATE, /**< RSA private key */ - CKMC_KEY_ECDSA_PUBLIC, /**< ECDSA public key */ - CKMC_KEY_ECDSA_PRIVATE, /**< ECDSA private key */ - CKMC_KEY_DSA_PUBLIC, /**< DSA public key */ - CKMC_KEY_DSA_PRIVATE, /**< DSA private key */ - CKMC_KEY_AES, /**< AES key */ + CKMC_KEY_NONE = 0, /**< Key type not specified */ + CKMC_KEY_RSA_PUBLIC, /**< RSA public key */ + CKMC_KEY_RSA_PRIVATE, /**< RSA private key */ + CKMC_KEY_ECDSA_PUBLIC, /**< ECDSA public key */ + CKMC_KEY_ECDSA_PRIVATE, /**< ECDSA private key */ + CKMC_KEY_DSA_PUBLIC, /**< DSA public key */ + CKMC_KEY_DSA_PRIVATE, /**< DSA private key */ + CKMC_KEY_AES, /**< AES key */ } ckmc_key_type_e; - /** * @brief Enumeration for data format. * @since_tizen 2.3 */ typedef enum __ckmc_data_format { - CKMC_FORM_DER_BASE64 = 0, /**< DER format base64 encoded data */ - CKMC_FORM_DER, /**< DER encoded data */ - CKMC_FORM_PEM /**< PEM encoded data. It consists of the DER format base64 encoded - with additional header and footer lines. */ + CKMC_FORM_DER_BASE64 = 0, /**< DER format base64 encoded data */ + CKMC_FORM_DER, /**< DER encoded data */ + CKMC_FORM_PEM /**< PEM encoded data. It consists of the DER format base64 encoded + with additional header and footer lines. */ } ckmc_data_format_e; - /** * @brief Enumeration for elliptic curve. * @since_tizen 2.3 */ typedef enum __ckmc_ec_type { - CKMC_EC_PRIME192V1 = 0, /**< Elliptic curve domain "secp192r1" listed in "SEC 2" recommended - elliptic curve domain */ - CKMC_EC_PRIME256V1, /**< "SEC 2" recommended elliptic curve domain - secp256r1 */ - CKMC_EC_SECP384R1 /**< NIST curve P-384(covers "secp384r1", the elliptic curve domain - listed in See SEC 2 */ + CKMC_EC_PRIME192V1 = 0, /**< Elliptic curve domain "secp192r1" listed in "SEC 2" recommended + elliptic curve domain */ + CKMC_EC_PRIME256V1, /**< "SEC 2" recommended elliptic curve domain - secp256r1 */ + CKMC_EC_SECP384R1 /**< NIST curve P-384(covers "secp384r1", the elliptic curve domain + listed in See SEC 2 */ } ckmc_ec_type_e; - /** * @brief Enumeration for hash algorithm. * @since_tizen 2.3 */ typedef enum __ckmc_hash_algo { CKMC_HASH_NONE = 0, /**< No Hash Algorithm */ - CKMC_HASH_SHA1, /**< Hash Algorithm SHA1 */ - CKMC_HASH_SHA256, /**< Hash Algorithm SHA256 */ - CKMC_HASH_SHA384, /**< Hash Algorithm SHA384 */ - CKMC_HASH_SHA512 /**< Hash Algorithm SHA512 */ + CKMC_HASH_SHA1, /**< Hash Algorithm SHA1 */ + CKMC_HASH_SHA256, /**< Hash Algorithm SHA256 */ + CKMC_HASH_SHA384, /**< Hash Algorithm SHA384 */ + CKMC_HASH_SHA512 /**< Hash Algorithm SHA512 */ } ckmc_hash_algo_e; - /** * @brief Enumeration for RSA padding algorithm. * @since_tizen 2.3 */ typedef enum __ckmc_rsa_padding_algo { - CKMC_NONE_PADDING = 0, /**< No Padding */ - CKMC_PKCS1_PADDING, /**< PKCS#1 Padding */ - CKMC_X931_PADDING /**< X9.31 padding */ + CKMC_NONE_PADDING = 0, /**< No Padding */ + CKMC_PKCS1_PADDING, /**< PKCS#1 Padding */ + CKMC_X931_PADDING /**< X9.31 padding */ } ckmc_rsa_padding_algo_e; - /** * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif [Use ckmc_permission_e() instead] * @brief Enumeration for database access rights. * @since_tizen 2.3 */ typedef enum __ckmc_access_right { - CKMC_AR_READ = 0, /**< Access right for read*/ - CKMC_AR_READ_REMOVE /**< Access right for read and remove*/ + CKMC_AR_READ = 0, /**< Access right for read*/ + CKMC_AR_READ_REMOVE /**< Access right for read and remove*/ } ckmc_access_right_e; - /** * @brief Enumeration for permissions to access/modify alias. * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif */ typedef enum __ckmc_permission { - CKMC_PERMISSION_NONE = 0x00, /**< Clear permissions */ - CKMC_PERMISSION_READ = 0x01, /**< Eead allowed */ - CKMC_PERMISSION_REMOVE = 0x02 /**< Remove allowed */ + CKMC_PERMISSION_NONE = 0x00, /**< Clear permissions */ + CKMC_PERMISSION_READ = 0x01, /**< Eead allowed */ + CKMC_PERMISSION_REMOVE = 0x02 /**< Remove allowed */ } ckmc_permission_e; - /** * @brief The structure for binary buffer used in key manager CAPI. * @since_tizen 2.3 */ typedef struct __ckmc_raw_buff { unsigned char *data; /**< Byte array containing binary data */ - size_t size; /**< The size of the binary data */ + size_t size; /**< The size of the binary data */ } ckmc_raw_buffer_s; - /** * @brief The structure for a policy for storing key/certificate/binary data. * @since_tizen 2.3 */ typedef struct __ckmc_policy { - char *password; /**< Byte array used to encrypt data inside CKM. If it is not null, the data - (or key, or certificate) is stored encrypted with this password inside - key manager */ + char *password; /**< Byte array used to encrypt data inside CKM. If it is not null, the data + (or key, or certificate) is stored encrypted with this password inside + key manager */ bool extractable; /**< If true key may be extracted from storage */ } ckmc_policy_s; - /** * @brief The structure for key used in key manager CAPI. * @since_tizen 2.3 */ typedef struct __ckmc_key { unsigned char - *raw_key; /**< Byte array of key. raw_key may be encrypted with password */ - size_t key_size; /**< The byte size of raw_key */ + *raw_key; /**< Byte array of key. raw_key may be encrypted with password */ + size_t key_size; /**< The byte size of raw_key */ ckmc_key_type_e key_type; /**< The raw_key's type */ - char *password; /**< Byte array used to decrypt data raw_key inside key manager. */ + char *password; /**< Byte array used to decrypt data raw_key inside key manager. */ } ckmc_key_s; - /** * @brief The structure for certificate used in key manager CAPI. * @since_tizen 2.3 */ typedef struct __ckmc_cert { - unsigned char *raw_cert; /**< Byte array of certificate */ - size_t cert_size; /**< Byte size of raw_cert */ + unsigned char *raw_cert; /**< Byte array of certificate */ + size_t cert_size; /**< Byte size of raw_cert */ ckmc_data_format_e data_format; /**< Raw_cert's encoding format */ } ckmc_cert_s; - /** * @brief The structure for linked list of alias. * @since_tizen 2.3 */ typedef struct __ckmc_alias_list { - char *alias; /**< The name of key, certificate or data stored in key manager */ + char *alias; /**< The name of key, certificate or data stored in key manager */ struct __ckmc_alias_list *next; /**< The pointer pointing to the next ckmc_alias_list_s */ } ckmc_alias_list_s; - /** * @brief The structure for linked list of ckmc_cert_s * @since_tizen 2.3 */ typedef struct __ckmc_cert_list { - ckmc_cert_s *cert; /**< The pointer of ckmc_cert_s */ + ckmc_cert_s *cert; /**< The pointer of ckmc_cert_s */ struct __ckmc_cert_list *next; /**< The pointer pointing to the next ckmc_cert_list_s */ } ckmc_cert_list_s; - /** * @brief Enumeration for OCSP status. * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif */ typedef enum __ckmc_ocsp_status { - CKMC_OCSP_STATUS_GOOD = 0, /**< OCSP status is good */ - CKMC_OCSP_STATUS_REVOKED, /**< The certificate is revoked */ - CKMC_OCSP_STATUS_UNKNOWN, /**< Unknown error */ - CKMC_OCSP_ERROR_UNSUPPORTED, /**< The certificate does not provide OCSP extension */ - CKMC_OCSP_ERROR_INVALID_URL, /**< The invalid URL in certificate OCSP extension */ - CKMC_OCSP_ERROR_INVALID_RESPONSE, /**< The invalid response from OCSP server */ - CKMC_OCSP_ERROR_REMOTE, /**< OCSP remote server error */ - CKMC_OCSP_ERROR_NET, /**< Network connection error */ - CKMC_OCSP_ERROR_INTERNAL /**< OpenSSL API error */ + CKMC_OCSP_STATUS_GOOD = 0, /**< OCSP status is good */ + CKMC_OCSP_STATUS_REVOKED, /**< The certificate is revoked */ + CKMC_OCSP_STATUS_UNKNOWN, /**< Unknown error */ + CKMC_OCSP_ERROR_UNSUPPORTED, /**< The certificate does not provide OCSP extension */ + CKMC_OCSP_ERROR_INVALID_URL, /**< The invalid URL in certificate OCSP extension */ + CKMC_OCSP_ERROR_INVALID_RESPONSE, /**< The invalid response from OCSP server */ + CKMC_OCSP_ERROR_REMOTE, /**< OCSP remote server error */ + CKMC_OCSP_ERROR_NET, /**< Network connection error */ + CKMC_OCSP_ERROR_INTERNAL /**< OpenSSL API error */ } ckmc_ocsp_status_e; - /** * @brief The structure for PKCS12 used in key manager CAPI. * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif */ typedef struct __ckmc_pkcs12 { - ckmc_key_s *priv_key; /**< The private key, may be null */ - ckmc_cert_s *cert; /**< The certificate, may be null */ + ckmc_key_s *priv_key; /**< The private key, may be null */ + ckmc_cert_s *cert; /**< The certificate, may be null */ ckmc_cert_list_s *ca_chain; /**< The chain certificate list, may be null */ } ckmc_pkcs12_s; - /** * @brief Enumeration for crypto algorithm parameters. * @since_tizen 3.0 @@ -273,19 +263,21 @@ typedef struct __ckmc_pkcs12 { typedef enum __ckmc_param_name { CKMC_PARAM_ALGO_TYPE = 1, - CKMC_PARAM_ED_IV = 101, /**< 16B buffer (up to 2^64-1 bytes long in case of AES GCM) */ - 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_ED_IV = 101, /**< 16B buffer (up to 2^64-1 bytes long in case of AES GCM) */ + 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_name_e; - /** - * @brief Algorithm parameter list handle. + * @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. + * + * @remarks Each parameter list must have at least one CKMC_PARAM_ALGO_TYPE parameter that identifies the + * algorithm. + * @remarks 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() @@ -298,7 +290,6 @@ typedef enum __ckmc_param_name { */ typedef struct __ckmc_param_list *ckmc_param_list_h; - /** * @brief Enumeration for crypto algorithm types. * @since_tizen 3.0 @@ -306,196 +297,272 @@ typedef struct __ckmc_param_list *ckmc_param_list_h; * @see #ckmc_param_name_e */ typedef enum __ckmc_algo_type { - CKMC_ALGO_AES_CTR = 1, /**< AES-CTR algorithm - Supported parameters: - - 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_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_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_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_ALGO_RSA_OAEP(required), - - CKMC_PARAM_ED_LABEL = label to be associated with the message - (optional, not supported at the moment) */ + CKMC_ALGO_AES_CTR = 1, /**< AES-CTR algorithm + Supported parameters: + - 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_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_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_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_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; +/** + * @brief Creates a new full alias which is a concatenation of @a owner_id and @a alias. + * + * @since_tizen 3.0 + * + * @remarks @a full_alias should be freed with free() after use. + * @remarks Returns #CKMC_ERROR_INVALID_PARAMETER if any of parameter is NULL. + * @remarks Returns #CKMC_ERROR_INVALID_PARAMETER if @a owner_id is empty. + * + * @param[in] owner_id Data owner's id. This should be package id if data owner is + * application. If you want to access data stored by system + * services, it should be #ckmc_owner_id_system + * @param[in] alias Data alias + * @param[out] full_alias The newly created alias which is a concatenation of + * @a owner_id, #ckmc_owner_id_separator and @a alias. + * Destroy by free() after use + * + * @return #CKMC_ERROR_NONE on success, otherwise a negative error value + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory + * + * @see #ckmc_owner_id_separator + * @see #ckmc_owner_id_system + */ +int ckmc_alias_new(const char *owner_id, const char *alias, char **full_alias); /** - * @brief Creates a new @a ckmc_key_s handle and returns it. + * @brief Creates a new #ckmc_key_s handle and returns it. + * * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * @remarks You must destroy the newly created @a ckmc_key_s by calling ckmc_key_free() if it is no longer needed. - * @param[in] raw_key The byte array of key \n - * @a raw_key may be encrypted with password + * + * @remarks You must destroy the newly created #ckmc_key_s by calling ckmc_key_free() if it is no + * longer needed. + * + * @param[in] raw_key The byte array of key \n + * @a raw_key may be encrypted with password * @param[in] key_size The byte size of @a raw_key * @param[in] key_type The @a raw_key's type * @param[in] password The byte array used to decrypt @a raw_key inside key manager \n * If @a raw_key is not encrypted, @a password can be null - * @param[out] ppkey The pointer to a newly created @a ckmc_key_s handle + * @param[out] ppkey The pointer to a newly created #ckmc_key_s handle + * * @return #CKMC_ERROR_NONE on success, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful + * + * @retval #CKMC_ERROR_NONE Successful * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid - * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory\ + * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory + * * @see ckmc_key_free() * @see #ckmc_key_s */ -int ckmc_key_new(unsigned char *raw_key, size_t key_size, ckmc_key_type_e key_type, char *password, ckmc_key_s **ppkey); - +int ckmc_key_new(unsigned char *raw_key, + size_t key_size, + ckmc_key_type_e key_type, + char *password, ckmc_key_s **ppkey); /** - * @brief Destroys the @a ckmc_key_s handle and releases all its resources. + * @brief Destroys the #ckmc_key_s handle and releases all its resources. + * * @since_tizen 2.3 - * @param[in] key The @a ckmc_key_s handle to destroy + * + * @param[in] key The #ckmc_key_s handle to destroy * */ void ckmc_key_free(ckmc_key_s *key); - /** - * @brief Creates a new @a ckmc_raw_buffer_s handle and returns it. + * @brief Creates a new #ckmc_raw_buffer_s handle and returns it. + * * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * @remarks You must destroy the newly created @a ckmc_raw_buffer_s by calling ckmc_buffer_free() if it is no longer needed. - * @param[in] data The byte array of buffer - * @param[in] size The byte size of buffer - * @param[out] ppbuffer The pointer to a newly created @a ckmc_buffer_s handle + * + * @remarks You must destroy the newly created #ckmc_raw_buffer_s by calling ckmc_buffer_free() if + * it is no longer needed. + * + * @param[in] data The byte array of buffer + * @param[in] size The byte size of buffer + * @param[out] ppbuffer The pointer to a newly created #ckmc_raw_buffer_s handle + * * @return #CKMC_ERROR_NONE on success, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful - * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid - * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory * * @see ckmc_buffer_free() * @see #ckmc_raw_buffer_s */ -int ckmc_buffer_new(unsigned char *data, size_t size, ckmc_raw_buffer_s **ppbuffer); - +int ckmc_buffer_new(unsigned char *data, size_t size, + ckmc_raw_buffer_s **ppbuffer); /** - * @brief Destroys the @a ckmc_raw_buffer_s handle and releases all its resources. + * @brief Destroys the #ckmc_raw_buffer_s handle and releases all its resources. + * * @since_tizen 2.3 - * @param[in] buffer The @a ckmc_raw_buffer_s structure to destroy + * + * @param[in] buffer The #ckmc_raw_buffer_s structure to destroy * */ void ckmc_buffer_free(ckmc_raw_buffer_s *buffer); - /** - * @brief Creates a new @a ckmc_cert_s handle and returns it. + * @brief Creates a new #ckmc_cert_s handle and returns it. + * * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * @remarks You must destroy the newly created @a ckmc_cert_s by calling ckmc_cert_free() if it is no longer needed. - * @param[in] raw_cert The byte array of certificate - * @param[in] cert_size The byte size of raw_cert - * @param[in] data_format The encoding format of raw_cert - * @param[out] ppcert The pointer to a newly created @a ckmc_cert_s handle + * + * @remarks You must destroy the newly created #ckmc_cert_s by calling ckmc_cert_free() if it is + * no longer needed. + * + * @param[in] raw_cert The byte array of certificate + * @param[in] cert_size The byte size of raw_cert + * @param[in] data_format The encoding format of raw_cert + * @param[out] ppcert The pointer to a newly created #ckmc_cert_s handle + * * @return #CKMC_ERROR_NONE on success, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful - * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid - * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory * * @see ckmc_cert_free() * @see ckmc_load_cert_from_file() * @see #ckmc_cert_s */ -int ckmc_cert_new(unsigned char *raw_cert, size_t cert_size, ckmc_data_format_e data_format, ckmc_cert_s **ppcert); - +int ckmc_cert_new(unsigned char *raw_cert, + size_t cert_size, + ckmc_data_format_e data_format, + ckmc_cert_s **ppcert); /** - * @brief Destroys the @a ckmc_cert handle and releases all its resources. + * @brief Destroys the #ckmc_cert_s handle and releases all its resources. + * * @since_tizen 2.3 - * @param[in] cert The @a ckmc_cert_s handle to destroy + * + * @param[in] cert The #ckmc_cert_s handle to destroy + * * @see ckmc_load_cert_from_file() - * @see ckmc_load_from_pkcs12_file */ void ckmc_cert_free(ckmc_cert_s *cert); - /** - * @brief Creates a new @a ckmc_cert_s handle from a given file and returns it. + * @brief Creates a new #ckmc_cert_s handle from a given file and returns it. + * * @since_tizen 2.3 - * @remarks You must destroy the newly created @a ckmc_cert_s by calling ckmc_cert_free() if it is no longer needed. - * @param[in] file_path The path of certificate file to be loaded \n - * The only DER or PEM encoded certificate file is supported - * @param[out] cert The pointer of newly created @a ckmc_cert_s handle + * + * @remarks You must destroy the newly created #ckmc_cert_s by calling ckmc_cert_free() if it is + * no longer needed. + * + * @param[in] file_path The path of certificate file to be loaded \n + * The only DER or PEM encoded certificate file is supported + * @param[out] cert The pointer of newly created #ckmc_cert_s handle + * * @return #CKMC_ERROR_NONE on success, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful - * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory space - * @retval #CKMC_ERROR_INVALID_FORMAT Invalid certificate file format - * @retval #CKMC_ERROR_FILE_ACCESS_DENIED Provided file does not exist or cannot be accessed + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory space + * @retval #CKMC_ERROR_INVALID_FORMAT Invalid certificate file format + * @retval #CKMC_ERROR_FILE_ACCESS_DENIED Provided file does not exist or cannot be accessed + * * @see ckmc_cert_free() * @see #ckmc_cert_s */ int ckmc_load_cert_from_file(const char *file_path, ckmc_cert_s **cert); - /** - * @brief Creates a new @a ckmc_pkcs12_s handle and returns it. + * @brief Creates a new #ckmc_pkcs12_s handle and returns it. + * * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * @remarks You must destroy the newly created @a ckmc_pkcs12_s by calling ckmc_pkcs12_free() if it is no longer needed. - * @remarks On success, private_key, cert && ca_cert_list ownership is transferred into newly returned ckmc_pkcs12_s. - * @param[in] private_key @a ckmc_key_s handle to the private key (optional) - * @param[in] cert @a ckmc_cert_s handle to the certificate (optional) - * @param[in] ca_cert_list @a ckmc_cert_list_s list of chain certificate handles (optional) - * @param[out] pkcs12_bundle The pointer to a newly created @a ckmc_pkcs12_s handle + * + * @remarks You must destroy the newly created #ckmc_pkcs12_s by calling ckmc_pkcs12_free() if it + * is no longer needed. + * @remarks On success, private_key, cert && ca_cert_list ownership is transferred into newly + * returned ckmc_pkcs12_s. + * + * @param[in] private_key #ckmc_key_s handle to the private key (optional) + * @param[in] cert #ckmc_cert_s handle to the certificate (optional) + * @param[in] ca_cert_list #ckmc_cert_list_s list of chain certificate handles (optional) + * @param[out] pkcs12_bundle The pointer to a newly created #ckmc_pkcs12_s handle + * * @return #CKMC_ERROR_NONE on success, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful - * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid or private_key, cert and ca_cert_list all are null - * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid or private_key, cert and + * ca_cert_list all are null + * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory + * * @see ckmc_pkcs12_free() - * @see ckmc_load_from_pkcs12_file() * @see ckmc_pkcs12_load() * @see #ckmc_key_s * @see #ckmc_cert_s * @see #ckmc_cert_list_s * @see #ckmc_pkcs12_s */ -int ckmc_pkcs12_new(ckmc_key_s *private_key, ckmc_cert_s *cert, ckmc_cert_list_s *ca_cert_list, ckmc_pkcs12_s **pkcs12_bundle); - +int ckmc_pkcs12_new(ckmc_key_s *private_key, + ckmc_cert_s *cert, + ckmc_cert_list_s *ca_cert_list, + ckmc_pkcs12_s **pkcs12_bundle); /** * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif [Use ckmc_pkcs12_load() instead] - * @brief Creates a new @a ckmc_key_s(private key), @a ckmc_cert_s(certificate), and - * @a ckmc_cert_list_s(CA certificates) handle from a given PKCS#12 file and returns them. + * @brief Creates a new #ckmc_key_s (@a private_key), #ckmc_cert_s (@a cert), and + * #ckmc_cert_list_s (@a ca_cert_list) handle from a given PKCS#12 file and returns them. + * * @since_tizen 2.3 - * @remarks You must destroy the newly created @a ckmc_key_s, @a ckmc_cert_s and - * @a ckmc_cert_list_s by calling ckmc_key_free(), ckmc_cert_free(), and + * + * @remarks You must destroy the newly created #ckmc_key_s, #ckmc_cert_s, and + * #ckmc_cert_list_s by calling ckmc_key_free(), ckmc_cert_free(), and * ckmc_cert_list_all_free() if they are no longer needed. - * @param[in] file_path The path of PKCS12 file to be loaded - * @param[in] passphrase The passphrase used to decrypt the PCKS12 file \n - * If PKCS12 file is not encrypted, passphrase can be null - * @param[out] private_key The pointer of newly created @a ckmc_key_s handle for a private key - * @param[out] cert The pointer of newly created @a ckmc_cert_s handle for a certificate \n - * It is null if the PKCS12 file does not contain a certificate - * @param[out] ca_cert_list The pointer of newly created @a ckmc_cert_list_s handle for CA certificates \n + * + * @param[in] file_path The path of PKCS12 file to be loaded + * @param[in] passphrase The passphrase used to decrypt the PCKS12 file \n + * If PKCS12 file is not encrypted, passphrase can be null + * @param[out] private_key The pointer of newly created #ckmc_key_s handle for a private key + * @param[out] cert The pointer of newly created #ckmc_cert_s handle for a certificate \n + * It is null if the PKCS12 file does not contain a certificate + * @param[out] ca_cert_list The pointer of newly created #ckmc_cert_list_s handle for CA + * certificates \n * It is null if the PKCS12 file does not contain CA certificates + * * @return #CKMC_ERROR_NONE on success, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful - * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory space - * @retval #CKMC_ERROR_INVALID_FORMAT Invalid PKCS12 file format - * @retval #CKMC_ERROR_FILE_ACCESS_DENIED Provided file does not exist or cannot be accessed + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory space + * @retval #CKMC_ERROR_INVALID_FORMAT Invalid PKCS12 file format + * @retval #CKMC_ERROR_FILE_ACCESS_DENIED Provided file does not exist or cannot be accessed + * * @see ckmc_pkcs12_new() * @see ckmc_pkcs12_load() * @see ckmc_key_free() @@ -505,166 +572,230 @@ int ckmc_pkcs12_new(ckmc_key_s *private_key, ckmc_cert_s *cert, ckmc_cert_list_s * @see #ckmc_cert_s * @see #ckmc_cert_list_s */ -int ckmc_load_from_pkcs12_file(const char *file_path, const char *passphrase, ckmc_key_s **private_key, ckmc_cert_s **cert, ckmc_cert_list_s **ca_cert_list) +int ckmc_load_from_pkcs12_file(const char *file_path, + const char *passphrase, + ckmc_key_s **private_key, ckmc_cert_s **cert, + ckmc_cert_list_s **ca_cert_list) TIZEN_DEPRECATED_API; - /** - * @brief Creates a new @a ckmc_pkcs12_s handle from a given PKCS#12 file and returns it. + * @brief Creates a new #ckmc_pkcs12_s handle from a given PKCS#12 file and returns it. + * * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * @remarks You must destroy the newly created @a ckmc_pkcs12_s by calling ckmc_pkcs12_free() if they are no longer needed. - * @param[in] file_path The path of PKCS12 file to be loaded - * @param[in] passphrase The passphrase used to decrypt the PCKS12 file \n - * If PKCS12 file is not encrypted, passphrase can be null - * @param[out] ca_cert_list The pointer of newly created @a ckmc_cert_list_s handle for CA certificates \n - * It is null if the PKCS12 file does not contain CA certificates + * + * @remarks You must destroy the newly created #ckmc_pkcs12_s by calling ckmc_pkcs12_free() if + * they are no longer needed. + * + * @param[in] file_path The path of PKCS12 file to be loaded + * @param[in] passphrase The passphrase used to decrypt the PCKS12 file \n + * If PKCS12 file is not encrypted, passphrase can be null + * @param[out] pkcs12_bundle The pointer of newly created #ckmc_cert_list_s handle for CA + * certificates \n + * It is null if the PKCS12 file does not contain CA certificates + * * @return #CKMC_ERROR_NONE on success, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful - * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory space - * @retval #CKMC_ERROR_INVALID_FORMAT Invalid PKCS12 file format - * @retval #CKMC_ERROR_FILE_ACCESS_DENIED Provided file does not exist or cannot be accessed + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory space + * @retval #CKMC_ERROR_INVALID_FORMAT Invalid PKCS12 file format + * @retval #CKMC_ERROR_FILE_ACCESS_DENIED Provided file does not exist or cannot be accessed + * * @see ckmc_pkcs12_free() * @see #ckmc_pkcs12_s */ -int ckmc_pkcs12_load(const char *file_path, const char *passphrase, ckmc_pkcs12_s **pkcs12_bundle); - +int ckmc_pkcs12_load(const char *file_path, + const char *passphrase, + ckmc_pkcs12_s **pkcs12_bundle); /** - * @brief Destroys the @a ckmc_pkcs12_s handle and releases all its resources. + * @brief Destroys the #ckmc_pkcs12_s handle and releases all its resources. + * * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * @param[in] pkcs12 The @a ckmc_pkcs12_s handle to destroy + * + * @param[in] pkcs12 The #ckmc_pkcs12_s handle to destroy + * * @see ckmc_pkcs12_new() * @see ckmc_pkcs12_load() */ void ckmc_pkcs12_free(ckmc_pkcs12_s *pkcs12); - /** - * @brief Creates a new @a ckmc_alias_list_s handle and returns it. - * The alias pointer in the returned @a ckmc_alias_list_s handle points to the provided characters and next is null. + * @brief Creates a new #ckmc_alias_list_s handle and returns it. + * The alias pointer in the returned #ckmc_alias_list_s handle points to the provided + * characters and next is null. + * * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * @remarks You must destroy the newly created @a ckmc_alias_list_s - * by calling ckmc_alias_list_free() or ckmc_alias_list_all_free() if it is no longer needed. - * @param[in] alias The first item to be set in the newly created @a ckmc_alias_list_s - * @param[out] ppalias_list The pointer to a newly created @a ckmc_alias_list_s handle + * + * @remarks You must destroy the newly created #ckmc_alias_list_s + * by calling ckmc_alias_list_free() or ckmc_alias_list_all_free() if it is no longer + * needed. + * + * @param[in] alias The first item to be set in the newly created #ckmc_alias_list_s + * @param[out] ppalias_list The pointer to a newly created #ckmc_alias_list_s handle + * * @return #CKMC_ERROR_NONE on success, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful + * + * @retval #CKMC_ERROR_NONE Successful * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid - * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory + * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory + * * @see ckmc_alias_list_all_free() * @see #ckmc_alias_list_s */ int ckmc_alias_list_new(char *alias, ckmc_alias_list_s **ppalias_list); - /** - * @brief Creates a new @a ckmc_alias_list_s handle, adds it to a previous @a ckmc_alias_list_s and returns it. - * The alias pointer in the returned @a ckmc_alias_list_s handle points to the provided characters and next is null. + * @brief Creates a new #ckmc_alias_list_s handle, adds it to a previous #ckmc_alias_list_s and + * returns it. The alias pointer in the returned #ckmc_alias_list_s handle points to the + * provided characters and next is null. + * * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * @param[in] previous The last @a ckmc_alias_list_s handle to which a newly created @a ckmc_alias_list_s is added - * @param[in] alias The item to be set in the newly created @a ckmc_alias_list_s - * @param[out] pplast The pointer to a newly created and added @a ckmc_alias_list_s handle + * + * @param[in] previous The last #ckmc_alias_list_s handle to which a newly created + * #ckmc_alias_list_s is added + * @param[in] alias The item to be set in the newly created #ckmc_alias_list_s + * @param[out] pplast The pointer to a newly created and added #ckmc_alias_list_s handle + * * @return #CKMC_ERROR_NONE on success, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful - * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid - * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory + * * @see ckmc_alias_list_all_free() * @see #ckmc_alias_list_s */ -int ckmc_alias_list_add(ckmc_alias_list_s *previous, char *alias, ckmc_alias_list_s **pplast); - +int ckmc_alias_list_add(ckmc_alias_list_s *previous, + char *alias, + ckmc_alias_list_s **pplast); /** - * @brief Destroys the @a ckmc_alias_list_s handle and releases resources of @a ckmc_alias_list_s from the provided first handle cascadingly. + * @brief Destroys the #ckmc_alias_list_s handle and releases resources of #ckmc_alias_list_s + * from the provided first handle cascadingly. + * * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * @remarks It does not destroy an alias itself in @a ckmc_alias_list_s. - * @param[in] first The first @a ckmc_alias_list_s handle to destroy + * + * @remarks It does not destroy an alias itself in #ckmc_alias_list_s. + * + * @param[in] first The first #ckmc_alias_list_s handle to destroy + * * @see ckmc_alias_list_all_free() * @see #ckmc_alias_list_s */ void ckmc_alias_list_free(ckmc_alias_list_s *first); - /** - * @brief Destroys the @a ckmc_alias_list_s handle and releases all its resources from the provided first handle cascadingly. + * @brief Destroys the #ckmc_alias_list_s handle and releases all its resources from the provided + * first handle cascadingly. + * * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * @remarks It also destroys the alias in @a ckmc_alias_list_s. - * @param[in] first The first @a ckmc_alias_list_s handle to destroy + * + * @remarks It also destroys the alias in #ckmc_alias_list_s. + * + * @param[in] first The first #ckmc_alias_list_s handle to destroy + * * @see #ckmc_alias_list_s */ void ckmc_alias_list_all_free(ckmc_alias_list_s *first); - /** - * @brief Creates a new @a ckmc_cert_list_s handle and returns it. - * The cert pointer in the returned @a ckmc_cert_list_s handle points to the provided @a ckmc_cert_s and next is null. + * @brief Creates a new #ckmc_cert_list_s handle and returns it. + * The cert pointer in the returned #ckmc_cert_list_s handle points to the provided + * #ckmc_cert_s and next is null. + * * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * @remarks You must destroy the newly created @a ckmc_cert_list_s by calling ckmc_cert_list_free() + * + * @remarks You must destroy the newly created #ckmc_cert_list_s by calling ckmc_cert_list_free() * or ckmc_cert_list_all_free() if it is no longer needed. - * @param[in] cert The first item to be set in the newly created @a ckmc_cert_list_s - * @param[out] ppalias_list The pointer to a newly created @a ckmc_alias_list_s handle + * + * @param[in] cert The first item to be set in the newly created #ckmc_cert_list_s + * @param[out] ppalias_list The pointer to a newly created #ckmc_alias_list_s handle + * * @return #CKMC_ERROR_NONE on success, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful - * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid - * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory + * * @see ckmc_cert_list_all_free() * @see #ckmc_cert_list_s */ int ckmc_cert_list_new(ckmc_cert_s *cert, ckmc_cert_list_s **ppalias_list); - /** - * @brief Creates a new @a ckmc_cert_list_s handle, adds it to a previous @a ckmc_cert_list_s and returns it. - * The cert pointer in the returned @a ckmc_alias_list_s handle points to the provided @a ckmc_cert_s and next is null. + * @brief Creates a new #ckmc_cert_list_s handle, adds it to a previous #ckmc_cert_list_s and + * returns it. The cert pointer in the returned #ckmc_alias_list_s handle points to the + * provided #ckmc_cert_s and next is null. + * * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * @param[in] previous The last @a ckmc_cert_list_s handle to which a newly created @a ckmc_cert_list_s is added - * @param[in] cert The item to be set in the newly created @a ckmc_cert_list_s - * @param[out] pplast The pointer to a newly created and added @a ckmc_alias_list_s handle + * + * @param[in] previous The last #ckmc_cert_list_s handle to which a newly created + * #ckmc_cert_list_s is added + * @param[in] cert The item to be set in the newly created #ckmc_cert_list_s + * @param[out] pplast The pointer to a newly created and added #ckmc_alias_list_s handle + * * @return #CKMC_ERROR_NONE on success, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful - * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid - * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory + * * @see ckmc_cert_list_all_free() * @see #ckmc_cert_list_s */ -int ckmc_cert_list_add(ckmc_cert_list_s *previous, ckmc_cert_s *cert, ckmc_cert_list_s **pplast); - +int ckmc_cert_list_add(ckmc_cert_list_s *previous, ckmc_cert_s *cert, + ckmc_cert_list_s **pplast); /** - * @brief Destroys the @a ckmc_cert_list_s handle and releases resources of @a ckmc_cert_list_s from the provided first handle cascadingly. + * @brief Destroys the #ckmc_cert_list_s handle and releases resources of #ckmc_cert_list_s + * from the provided first handle cascadingly. + * * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif - * @remarks It does not destroy @a ckmc_cert_s itself in @a ckmc_cert_list_s. - * @param[in] first The first @a ckmc_cert_list_s handle to destroy + * + * @remarks It does not destroy #ckmc_cert_s itself in #ckmc_cert_list_s. + * + * @param[in] first The first #ckmc_cert_list_s handle to destroy + * * @see ckmc_cert_list_all_free() * @see #ckmc_cert_list_s */ void ckmc_cert_list_free(ckmc_cert_list_s *first); - /** - * @brief Destroys the @a ckmc_cert_list_s handle and releases all its resources from the provided first handle cascadingly. + * @brief Destroys the #ckmc_cert_list_s handle and releases all its resources from the provided + * first handle cascadingly. + * * @since_tizen 2.3 - * @remarks It also destroys @a ckmc_cert_s in @a ckmc_cert_list_s. - * @param[in] first The first @a ckmc_cert_list_s handle to destroy + * + * @remarks It also destroys #ckmc_cert_s in #ckmc_cert_list_s. + * + * @param[in] first The first #ckmc_cert_list_s handle to destroy + * * @see #ckmc_cert_list_s */ void ckmc_cert_list_all_free(ckmc_cert_list_s *first); - /** * @brief Creates new parameter list. + * * @since_tizen 3.0 + * * @remarks Caller is responsible for freeing it with ckmc_param_list_free(). - * @param[in] pparams Double pointer to the handle of param list to which the newly created algorithm param 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 - * @retval #CKMC_ERROR_NONE Successful - * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * * @see ckmc_param_list_set_integer() * @see ckmc_param_list_set_buffer() * @see ckmc_param_list_free() @@ -675,21 +806,27 @@ void ckmc_cert_list_all_free(ckmc_cert_list_s *first); */ int ckmc_param_list_new(ckmc_param_list_h *pparams); - /** * @brief Sets integer parameter to the list. + * * @since_tizen 3.0 - * @remarks Caller is responsible for @a ckmc_param_list_h creation. - * @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 an integer + * + * @remarks Caller is responsible for #ckmc_param_list_h creation. + * + * @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 + * * @return #CKMC_ERROR_NONE on success, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful - * @retval #CKMC_ERROR_INVALID_PARAMETER nput parameter is invalid + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * * @see ckmc_param_list_new() * @see ckmc_param_list_set_buffer() * @see ckmc_param_list_get_integer() @@ -700,24 +837,32 @@ int ckmc_param_list_new(ckmc_param_list_h *pparams); * @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, uint64_t value); - +int ckmc_param_list_set_integer(ckmc_param_list_h params, + ckmc_param_name_e name, + uint64_t value); /** * @brief Sets buffer parameter to the list. + * * @since_tizen 3.0 - * @remarks Caller is responsible for @a ckmc_param_list_h creation. - * @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 the form of a buffer \n - * Caller is responsible for creating and freeing the buffer + * + * @remarks Caller is responsible for #ckmc_param_list_h creation. + * + * @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 + * Caller is responsible for creating and freeing the buffer + * * @return #CKMC_ERROR_NONE on success, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful - * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * * @see ckmc_param_list_new() * @see ckmc_param_list_set_integer() * @see ckmc_param_list_get_integer() @@ -728,21 +873,29 @@ int ckmc_param_list_set_integer(ckmc_param_list_h params, ckmc_param_name_e name * @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, const ckmc_raw_buffer_s *buffer); - +int ckmc_param_list_set_buffer(ckmc_param_list_h params, + ckmc_param_name_e name, + const ckmc_raw_buffer_s *buffer); /** * @brief Gets integer parameter from the list. + * * @since_tizen 3.0 - * @remarks Caller is responsible for @a ckmc_param_list_h creation. - * @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] pvalue Value of the parameter in the form of an integer + * + * @remarks Caller is responsible for #ckmc_param_list_h creation. + * + * @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] pvalue Value of the parameter in form of a integer + * * @return #CKMC_ERROR_NONE on success, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful - * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * * @see ckmc_param_list_new() * @see ckmc_param_list_set_integer() * @see ckmc_param_list_set_buffer() @@ -754,22 +907,30 @@ int ckmc_param_list_set_buffer(ckmc_param_list_h params, ckmc_param_name_e name, * @see #ckmc_algo_type_e */ -int ckmc_param_list_get_integer(ckmc_param_list_h params, ckmc_param_name_e name, uint64_t *pvalue); - +int ckmc_param_list_get_integer(ckmc_param_list_h params, + ckmc_param_name_e name, + uint64_t *pvalue); /** * @brief Gets buffer parameter from the list. + * * @since_tizen 3.0 - * @remarks Caller is responsible for @a ckmc_param_list_h creation. - * @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 + * + * @remarks Caller is responsible for #ckmc_param_list_h creation. + * + * @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] 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, * otherwise a negative error value - * @retval #CKMC_ERROR_NONE Successful - * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * * @see ckmc_param_list_new() * @see ckmc_param_list_set_integer() * @see ckmc_param_list_set_buffer() @@ -781,13 +942,17 @@ int ckmc_param_list_get_integer(ckmc_param_list_h params, ckmc_param_name_e name * @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, ckmc_raw_buffer_s **ppbuffer); - +int ckmc_param_list_get_buffer(ckmc_param_list_h params, + ckmc_param_name_e name, + ckmc_raw_buffer_s **ppbuffer); /** * @brief Frees previously allocated list of algorithm params. + * * @since_tizen 3.0 - * @param[in] first First element of the list to be freed + * + * @param[in] params First element of the list to be freed + * * @see ckmc_param_list_new() * @see ckmc_param_list_set_integer() * @see ckmc_param_list_set_buffer() @@ -800,21 +965,26 @@ int ckmc_param_list_get_buffer(ckmc_param_list_h params, ckmc_param_name_e name, */ void ckmc_param_list_free(ckmc_param_list_h params); - /** * @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_h destruction. + * + * @remarks Caller is responsible for #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 set manually). - * 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] pparams Newly generated handle of param list which should be freed by caller after use + * + * @param[in] type Type of the algorithm + * @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 - * @retval #CKMC_ERROR_NONE Successful - * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * * @see ckmc_param_list_new() * @see ckmc_param_list_set_integer() * @see ckmc_param_list_set_buffer() @@ -827,7 +997,6 @@ void ckmc_param_list_free(ckmc_param_list_h params); */ int ckmc_generate_new_params(ckmc_algo_type_e type, ckmc_param_list_h *pparams); - /** * @} */ -- 2.7.4