* \#include <ckmc/ckmc-manager.h>
*
* @section CAPI_KEY_MANAGER_CLIENT_MODULE_OVERVIEW Overview
- * It provides APIs storing, getting, and removing APIs for keys, certificates, and sensitive data on/from Key Manager secure repository which is protected by a user’s passwords.
+ * It provides APIs for storing, getting, and removing APIs for keys, certificates, and sensitive data on/from the Key Manager secure repository which is protected by a user’s passwords.
* Additionally, it provides secure cryptographic operations for non-exportable keys without revealing key values to clients.
*/
* @internal
* @ingroup CAPI_KEY_MANAGER_MODULE
* @defgroup CAPI_KEY_MANAGER_CONTROL_MODULE Key Manager Control
- * @brief These APIs controls the key manager state(Unlocked/Locked) and reflects the user's password change.
+ * @brief These APIs control the key manager state (Unlocked/Locked) and reflects the user's password change.
*
* @section CAPI_KEY_MANAGER_CONTROL_MODULE_HEADER Required Header
* \#include <ckmc/ckmc-control.h>
*
* @section CAPI_KEY_MANAGER_CONTROL_MODULE_OVERVIEW Overview
- * It provides APIs encrypting, decrypting, and re-encrypting a DKEK(with which a user's data file is encrypted).
+ * It provides APIs encrypting, decrypting, and re-encrypting a DKEK (with which a user's data file is encrypted).
* When a user logs in for the first time, the DKEK will be generated randomly.
*/
/**
* @ingroup CAPI_KEY_MANAGER_MODULE
* @defgroup CAPI_KEY_MANAGER_TYPES_MODULE Key Manager Data Types
- * @brief It defines a data types used in this 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 <ckmc/ckmc-type.h>
*
* @section CAPI_KEY_MANAGER_TYPES_MODULE_OVERVIEW Overview
- * It defines data types for key, certificate,raw buffer, and linked list used in this APIs.
- * And it also provides new and free methods for them.
+ * 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.
*
*/
/**
* @ingroup CAPI_SECURITY_FRAMEWORK
* @defgroup CAPI_KEY_MANAGER_MODULE Key Manager
- * @brief The key manager provides a secure repository protected by a user’s passwords 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 a user’s passwords 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
* <table>
* <tr><th>API</th><th>Description</th></tr>
* <tr>
* <td> @ref CAPI_KEY_MANAGER_CLIENT_MODULE</td>
- * <td> Provides APIs accessing on the secure repository and additional secure cryptographic operations.</td>
+ * <td> Provides APIs for accessing the secure repository and additional secure cryptographic operations.</td>
* </tr>
* <tr>
* <td> @ref CAPI_KEY_MANAGER_TYPES_MODULE</td>
- * <td> Defines a data types used in this APIs and provides utility methods handling them.</td>
+ * <td> Defines data types used in these APIs and provides utility methods handling them.</td>
* </tr>
* </table>
*
*
* 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)
+ * - 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 a simple access rules when storing a data in Key Manager.
+ * A client can specify simple access rules when storing a data in Key Manager.
* - Restricted/Non-Restricted:
- * Data stored in Key Manager can be access on only by its owner if the data is tagged as restricted.
- * For data tagged as non-restricted, all clients can access on the data.
+ * Data stored in Key Manager can be accessed only by its owner if the data is tagged as restricted.
+ * For data tagged as non-restricted, all clients can access the data.
* - 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 doesn’t return its raw value. For that case, Key Manager provides secure cryptographic operations for non-exportable keys without revealing key values to clients.
+ * If data is tagged as non-exportable, Key Manager does not return its raw value.
+ * In that case, Key Manager provides secure cryptographic operations for non-exportable keys without revealing key values to clients.
* - Per Key Password:
* All data in Key Manager is protected by a user’s password.
* 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 get the data from Key Manager.
+ * If a client provides a password when storing a data, the data will be encrypted with the password.
+ * This password should be provided when get the data from Key Manager.
*
* User Login/Logout and Data Protection
* - When a user logs in, logs out or changes his/her password, Key Manager should know about it.
- * Privileged APPs such as ockScreen APP or Setting APP can notify to key manager using these control APIs.
- * - When a user logs in, the key manager decrypts the user's DKEK(with which a user's data file is encrypted) with a user password.
+ * Privileged APPs such as LockScreen APP or Setting APP can notify the key manager using these control APIs.
+ * - When a user logs in, the key manager decrypts the user's DKEK (with which a user's data file is encrypted) with a user password.
* So during the login period, any client can access its data which is protected by a user's password.
* "user key" in API means DKEK.
* - When a user logs out, the key manager removes the user's DKEK from memory.
- * Therefore, any clients cannot access to any data.
- * - When a user change his/her password, the key manager re-encrypted the user's DKEK with a new password.
+ * Therefore, clients cannot access any data.
+ * - When a user changes his/her password, the key manager re-encrypts the user's DKEK with the new password.
*
*/
*
* @file ckmc-control.h
* @version 1.0
- * @brief provides control functions for the key manager.
+ * @brief Provides control functions for the key manager.
*/
#ifndef __TIZEN_CORE_CKMC_CONTROL_H
*/
/**
- * @brief Decrypts a user key(DKEK) with password. A decrypted user key exists only on memory. If this API is called for the first time, a user key will be generated internally.
+ * @brief Decrypts a user key(DKEK) with password.
+ * A decrypted user key exists only on memory. If this API is called for the first time, a user key will be generated internally.
*
* @since_tizen 2.3
* @privlevel platform
*
* @remarks The user key is a randomly generated key used in encrypting user data. And the user key is protected by a user's password.
*
- * @param[in] user a uid of a user whose key is decrypted.
- * @param[in] password used in decrypting a user key.
+ * @param[in] user The user ID of a user whose key is decrypted
+ * @param[in] password The password used in decrypting a user key
*
- * @return 0 on success, otherwise a negative error value
- * @retval #CKMC_ERROR_NONE Successful
- * @retval #CKMC_ERROR_SERVER_ERROR failed to unlock user key
- * @retval #CKMC_ERROR_INVALID_PARAMETER invalid input parameter
- * @retval #CKMC_ERROR_AUTHENTICATION_FAILED not correct password
- * @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_SERVER_ERROR Failed to unlock user key
+ * @retval #CKMC_ERROR_INVALID_PARAMETER Invalid input parameter
+ * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Not correct password
+ * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
*
* @see ckmc_lock_user_key()
* @see ckmc_remove_user_data()
* @privlevel platform
* @privilege %http://tizen.org/privilege/keymanager.admin
*
- * @param[in] user a uid of a user whose key is removed from memory.
+ * @param[in] user The user ID of a user whose key is removed from memory
+ *
+ * @return @c 0 on success,
+ * otherwise a negative error value
*
- * @return 0 on success, otherwise a negative error value
- * @retval #CKMC_ERROR_NONE Successful
- * @retval #CKMC_ERROR_INVALID_PARAMETER invalid input parameter
- * @retval #CKMC_ERROR_PERMISSION_DENIED failed to access key manager
+ * @retval #CKMC_ERROR_NONE Successful
+ * @retval #CKMC_ERROR_INVALID_PARAMETER Invalid input parameter
+ * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
*
* @see ckmc_unlock_user_key()
* @see ckmc_remove_user_data()
int ckmc_lock_user_key(uid_t user);
/**
- * @brief Removes user data from Store and erase a user key(DKEK) used for encryption
+ * @brief Removes user data from Store and erases a user key(DKEK) used for encryption.
*
* @since_tizen 2.3
* @privlevel platform
* @privilege %http://tizen.org/privilege/keymanager.admin
*
- * @param[in] user a uid of a user whose data and key are removed
+ * @param[in] user The user ID of a user whose data and key are removed
+ *
+ * @return @c 0 on success,
+ * otherwise a negative error value
*
- * @return 0 on success, otherwise a negative error value
- * @retval #CKMC_ERROR_NONE Successful
- * @retval #CKMC_ERROR_INVALID_PARAMETER invalid input parameter
- * @retval #CKMC_ERROR_PERMISSION_DENIED failed to access key manager
+ * @retval #CKMC_ERROR_NONE Successful
+ * @retval #CKMC_ERROR_INVALID_PARAMETER Invalid input parameter
+ * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
*
* @see ckmc_unlock_user_key()
* @see ckmc_lock_user_key()
int ckmc_remove_user_data(uid_t user);
/**
- * @brief Changes a password for a user. key manager decrypts a user key(DKEK) with old password and re-encrypts a user key with new password.
+ * @brief Changes a password for a user.
+ * The key manager decrypts a user key (DKEK) with old password and re-encrypts a user key with new password.
*
* @since_tizen 2.3
* @privlevel platform
* @privilege %http://tizen.org/privilege/keymanager.admin
*
- * @param[in] user a uid of a user whose user key is re-encrypted
- * @param[in] old_password used in decrypting a user key.
- * @param[in] new_password used in re-encrypting a user key.
+ * @param[in] user The user ID of a user whose user key is re-encrypted
+ * @param[in] old_password The password used in decrypting a user key
+ * @param[in] new_password The password used in re-encrypting a user key
*
- * @return 0 on success, otherwise a negative error value
- * @retval #CKMC_ERROR_NONE Successful
- * @retval #CKMC_ERROR_INVALID_PARAMETER invalid input parameter
- * @retval #CKMC_ERROR_AUTHENTICATION_FAILED not correct password
- * @retval #CKMC_ERROR_BAD_REQUEST no information about old password
- * @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 Invalid input parameter
+ * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Not correct password
+ * @retval #CKMC_ERROR_BAD_REQUEST No information about old password
+ * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
*
* @see ckmc_unlock_user_key()
* @see ckmc_lock_user_key()
* @privlevel platform
* @privilege %http://tizen.org/privilege/keymanager.admin
*
- * @param[in] user a uid of a user whose user key is re-encrypted
- * @param[in] new_password is used in re-encrypting a user key.
+ * @param[in] user The user ID of a user whose user key is re-encrypted
+ * @param[in] new_password The password used in re-encrypting a user key
+ *
+ * @return @c 0 on success,
+ * otherwise a negative error value
*
- * @return 0 on success, otherwise a negative error value
- * @retval #CKMC_ERROR_NONE Successful
- * @retval #CKMC_ERROR_INVALID_PARAMETER invalid input parameter
- * @retval #CKMC_ERROR_BAD_REQUEST a user key is not unlocked.
- * @retval #CKMC_ERROR_PERMISSION_DENIED failed to access key manager
+ * @retval #CKMC_ERROR_NONE Successful
+ * @retval #CKMC_ERROR_INVALID_PARAMETER Invalid input parameter
+ * @retval #CKMC_ERROR_BAD_REQUEST A user key is not unlocked
+ * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
*
- * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ * @pre User is already logged in and the user key is already loaded into memory in plain text form.
*
* @see ckmc_unlock_user_key()
* @see ckmc_lock_user_key()
*
* @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_
*
* @remarks Currently only four types of keys are supported for this API. These are RSA public/private key and ECDSA /private 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.
+ * @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 a key's binary value to be stored.
- * @param[in] policy about how to store a key securely.
+ * @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 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_key is not valid.
- * @retval #CKMC_ERROR_DB_ERROR failed due to other DB transaction unexpectedly.
- * @retval #CKMC_ERROR_PERMISSION_DENIED failed to access key manager
+ * @return @c 0 on success,
+ * otherwise a negative error value
*
- * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ * @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 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_remove_key()
* @see ckmc_get_key()
int ckmc_save_key(const char *alias, const ckmc_key_s key, const ckmc_policy_s policy);
/**
- * @brief Removes a key from key manager
+ * @brief Removes a key from key manager.
*
* @since_tizen 2.3
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
- * @remarks a client can remove only keys stored by the client.
+ * @remarks A client can remove only keys stored by the client.
+ *
+ * @param[in] alias The name of a key to be removed
*
- * @param[in] alias the name of a key to be removed
+ * @return @c 0 on success,
+ * otherwise a negative error value
*
- * @return 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 doesn't exists.
- * @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 must be already logged in and his user key is already loaded into memory in plain text form.
+ * @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()
int ckmc_remove_key(const char *alias);
/**
- * @brief Gets a key from key manager
+ * @brief Gets a key from key manager.
*
* @since_tizen 2.3
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
- * @remarks a client can access only data stored by the client and non-restricted data stored by other clients.
- * @remarks A newly created ppkey should be destroyed by calling ckmc_key_free() if it is no longer needed.
+ * @remarks A client can access only data stored by the client and non-restricted data stored by other clients.
+ * @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
*
- * @param[in] alias the name of a key to retrieve
- * @param[in] password used in decrypting a key value. If password of policy is provided in ckmc_save_key(), the same password should be provided.
- * @param[out] ppkey a pointer to a newly created ckmc_key_s handle
+ * @return @c 0 on success,
+ * otherwise a negative error value
*
- * @return 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 doesn't exists.
- * @retval #CKMC_ERROR_PERMISSION_DENIED failed to access key manager
- * @retval #CKMC_ERROR_NOT_EXPORTABLE a key is not exportable and could not be returned to client
- * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ * @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_key()
* @see ckmc_remove_key()
int ckmc_get_key(const char *alias, const char *password, ckmc_key_s **ppkey);
/**
- * @brief Gets a all alias of keys to which the client can access
+ * @brief Gets all the alias of keys that the client can access.
*
* @since_tizen 2.3
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
- * @remarks a client can access only data stored by the client and non-restricted data stored by other clients.
- * @remarks A newly created ppalias_list should be destroyed by calling ckmc_alias_list_all_free() if it is no longer needed.
+ * @remarks A client can access only data stored by the client and non-restricted data stored by other clients.
+ * @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 a pointer to a newly created ckmc_alias_list_s handle containing all available alias of keys. If there is no available key alias, *ppalias_list will be null.
+ * @return @c 0 on success,
+ * otherwise a negative error value
*
- * @return 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_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_PERMISSION_DENIED Failed to access key manager
*
- * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ * @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_key()
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
- * @param[in] alias the name of a certificate to be stored
- * @param[in] cert a certificate's binary value to be stored.
- * @param[in] policy about how to store a certificate securely.
+ * @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
*
- * @return 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 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_INVALID_FORMAT The format of raw_cert is not valid
+ * @retval #CKMC_ERROR_DB_ERROR Failed due to other DB transaction unexpectedly
+ * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
*
- * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ * @pre User is already logged in and the user key is already loaded into memory in plain text form.
*
* @see ckmc_remove_cert()
* @see ckmc_get_cert()
int ckmc_save_cert(const char *alias, const ckmc_cert_s cert, const ckmc_policy_s policy);
/**
- * @brief Removes a certificate from key manager
+ * @brief Removes a certificate from key manager.
*
* @since_tizen 2.3
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
- * @remarks a client can remove only certificates stored by the client.
+ * @remarks A client can remove only certificates stored by the client.
*
- * @param[in] alias the name of a certificate to be removed
+ * @param[in] alias The name of a certificate to be removed
*
- * @return 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 doesn't exists.
- * @retval #CKMC_ERROR_PERMISSION_DENIED failed to access key manager
+ * @return @c 0 on success,
+ * otherwise a negative error value
*
- * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ * @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_cert()
* @see ckmc_get_cert()
int ckmc_remove_cert(const char *alias);
/**
- * @brief Gets a certificate from key manager
+ * @brief Gets a certificate from key manager.
*
* @since_tizen 2.3
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
- * @remarks a client can access only certificate stored by the client and non-restricted certificate stored by other clients.
- * @remarks A newly created ppcert should be destroyed by calling ckmc_cert_free() if it is no longer needed.
+ * @remarks A client can access only certificate stored by the client and non-restricted certificate stored by other clients.
+ * @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.
+ * @param[out] ppcert The pointer to a newly created ckmc_cert_s handle
*
- * @param[in] alias the name of a certificate to retrieve
- * @param[in] password used in decrypting a certificate value. If password of policy is provided in ckmc_save_cert(), the same password should be provided.
- * @param[out] ppcert a pointer to a newly created ckmc_cert_s handle
+ * @return @c 0 on success,
+ * otherwise a negative error value
*
- * @return 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 doesn't exists.
- * @retval #CKMC_ERROR_PERMISSION_DENIED failed to access key manager
- * @retval #CKMC_ERROR_NOT_EXPORTABLE a certification is not exportable and could not be returned to client
+ * @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 exists
+ * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
*
- * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ * @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_cert()
int ckmc_get_cert(const char *alias, const char *password, ckmc_cert_s **ppcert);
/**
- * @brief Gets a all alias of certificates to which the client can access
+ * @brief Gets all alias of certificates which the client can access.
*
* @since_tizen 2.3
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
- * @remarks a client can access only data stored by the client and non-restricted data stored by other clients.
- * @remarks A newly created ppalias_list should be destroyed by calling ckmc_alias_list_all_free() if it is no longer needed.
+ * @remarks A client can access only data stored by the client and non-restricted data stored by other clients.
+ * @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 a pointer to a newly created ckmc_alias_list_s handle containing all available alias of keys. If there is no available key alias, *ppalias_list will be null.
+ * @return @c 0 on success,
+ * otherwise a negative error value
*
- * @return 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_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_PERMISSION_DENIED Failed to access key manager
*
- * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ * @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_cert()
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
- * @param[in] alias the name of a data to be stored
- * @param[in] data a binary value to be stored.
- * @param[in] policy about how to store a data securely.
+ * @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 0 on success, otherwise a negative error value
- * @retval #CKMC_ERROR_NONE Successful
- * @retval #CKMC_ERROR_INVALID_PARAMETER input parameter is invalid. Extractable flag in policy should be true.
- * @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
+ * @return @c 0 on success,
+ * otherwise a negative error value
*
- * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ * @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_remove_data()
* @see ckmc_get_data()
int ckmc_save_data(const char *alias, ckmc_raw_buffer_s data, const ckmc_policy_s policy);
/**
- * @brief Removes a data from key manager
+ * @brief Removes a data from key manager.
*
* @since_tizen 2.3
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
- * @remarks a client can remove only data stored by the client.
+ * @remarks A client can remove only data stored by the client.
+ *
+ * @param[in] alias The name of a data to be removed
*
- * @param[in] alias the name of a data to be removed
+ * @return @c 0 on success,
+ * otherwise a negative error value
*
- * @return 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 doesn't exists.
- * @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 must be already logged in and his user key is already loaded into memory in plain text form.
+ * @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()
int ckmc_remove_data(const char *alias);
/**
- * @brief Gets a data from key manager
+ * @brief Gets a data from key manager.
*
* @since_tizen 2.3
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
- * @remarks a client can access only data stored by the client and non-restricted data stored by other clients.
- * @remarks A newly created ppdata should be destroyed by calling ckmc_buffer_free() if it is no longer needed.
+ * @remarks A client can access only data stored by the client and non-restricted data stored by other clients.
+ * @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 used in decrypting a data value. If password of policy is provided in ckmc_save_data(), the same password should be provided.
- * @param[out] ppdata a 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 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 doesn't exists.
- * @retval #CKMC_ERROR_PERMISSION_DENIED failed to access key manager
+ * @return @c 0 on success,
+ * otherwise a negative error value
*
- * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ * @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_data()
int ckmc_get_data(const char *alias, const char *password, ckmc_raw_buffer_s **ppdata);
/**
- * @brief Gets a all alias of data to which the client can access
+ * @brief Gets all alias of data which the client can access.
*
* @since_tizen 2.3
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
- * @remarks a client can access only data stored by the client and non-restricted data stored by other clients.
- * @remarks A newly created ppalias_list should be destroyed by calling ckmc_alias_list_all_free() if it is no longer needed.
+ * @remarks A client can access only data stored by the client and non-restricted data stored by other clients.
+ * @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 a pointer to a newly created ckmc_alias_list_s handle containing all available alias of keys. If there is no available key alias, *ppalias_list will be null.
+ * @return @c 0 on success,
+ * otherwise a negative error value
*
- * @return 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_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_PERMISSION_DENIED Failed to access key manager
*
- * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ * @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_data()
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
- * @remarks if password in policy is provided, the key is additionally encrypted with the password in policy.
+ * @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
*
- * @param[in] size the size of key strength to be created. 1024, 2048, and 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 about how to store a private key securely.
- * @param[in] policy_public_key about how to store a public key securely.
+ * @return @c 0 on success,
+ * otherwise a negative error value
*
- * @return 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 must be already logged in and his user key is already loaded into memory in plain text form.
+ * @pre User is already logged in and the user key is already loaded into memory in plain text form.
*
* @see ckmc_create_key_pair_ecdsa()
* @see ckmc_create_signature()
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
- * @remarks if password in policy is provided, the key is additionally encrypted with the password in policy.
+ * @remarks If password in policy is provided, the key is additionally encrypted with the password in policy.
*
- * @param[in] type the type of eliptic 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 about how to store a private key securely.
- * @param[in] policy_public_key about how to store a public key securely.
+ * @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 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
+ * @return @c 0 on success,
+ * otherwise a negative error value
*
- * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ * @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_signature()
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 a signature on a given message using a private key and returns the signature
+ * @brief Creates a signature on a given message using a private key and returns the signature.
*
* @since_tizen 2.3
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
* @remarks If password of policy is provided during storing a key, the same password should be provided.
- * @remarks A newly created ppsignature should be destroyed by calling ckmc_buffer_free() if it is no longer needed.
+ * @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.
*
- * @param[in] private_key_alias the name of private key.
- * @param[in] password used in decrypting a private key value.
- * @param[in] message 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. It is used only when the signature algorithm is RSA.
- * @param[out] ppsignature a pointer to a newly created signature's. If an error occurs, *ppsignature will be null.
+ * @return @c 0 on success,
+ * otherwise a negative error value
*
- * @return 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_UNKNOWN alias doesn't exists.
- * @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_UNKNOWN Alias does not exist
+ * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
*
- * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ * @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()
*
* @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 used in decrypting a public key value.
- * @param[in] message a input on which the signature is created.
- * @param[in] signature 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. It is used only when the signature algorithm is RSA.
+ * @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
*
- * @return 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_ALIAS_UNKNOWN alias doesn't exists.
- * @retval #CKMC_ERROR_PERMISSION_DENIED failed to access key manager
+ * @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_ALIAS_UNKNOWN Alias does not exist
+ * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
*
- * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ * @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()
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 return that chain.
+ * @brief Verifies a certificate chain and returns that chain.
*
* @since_tizen 2.3
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
* @remarks The trusted root certificate of the chain should exist in the system's certificate storage.
- * @remarks A newly created ppcert_chain_list should be destroyed by calling ckmc_cert_list_all_free() if it is no longer needed.
+ * @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 a pointer to a newly created certificate chain's handle. If an error occurs, *ppcert_chain_list will be null.
+ * @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 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_INVALID_FORMAT the format of certificate is not valid.
- * @retval #CKMC_ERROR_PERMISSION_DENIED failed to access key manager
+ * @return @c 0 on success and the signature is valid,
+ * otherwise a negative error value
*
- * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ * @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_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_get_cert_chain_with_alias())
* @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);
/**
- * @brief Verifies a certificate chain using a 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
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
* @remarks The trusted root certificate of the chain should exist in the system's certificate storage.
- * @remarks A newly created ppcert_chain_list should be destroyed by calling ckmc_cert_list_all_free() if it is no longer needed.
- *
- * @param[in] cert the certificate to be verified
- * @param[in] untrustedcerts an alias list of untrusted CA certificates stored in key manager to be used in verifying a certificate chain.
- * @param[out] ppcert_chain_list a pointer to a newly created certificate chain's handle. If an error occurs, *ppcert_chain_list will be null.
- *
- * @return 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_ALIAS_UNKNOWN alias doesn't exists.
- * @retval #CKMC_ERROR_INVALID_FORMAT the format of certificate is not valid.
- * @retval #CKMC_ERROR_PERMISSION_DENIED failed to access key manager
- *
- * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ * @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 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_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
+ *
+ * @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()
*
* @file ckmc-type.h
* @version 1.0
- * @brief Definitions of struct for the Key Manager's CAPI and their utility functions
+ * @brief Definitions of struct for the Key Manager's CAPI and their utility functions.
*/
#ifndef __TIZEN_CORE_CKMC_TYPE_H
*/
/**
- * @brief Enumerates for key types of key manager.
+ * @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_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_type_e;
/**
- * @brief Enumerates for data format.
+ * @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 Enumerates for eliptic curve.
+ * @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 Enumerates for hash algorithm.
+ * @brief Enumeration for hash algorithm.
* @since_tizen 2.3
*/
typedef enum __ckmc_hash_algo {
- CKMC_HASH_SHA1 = 0, /**< Hash Algorithm SHA1 */
- CKMC_HASH_SHA256, /**< Hash Algorithm SHA256 */
- CKMC_HASH_SHA384, /**< Hash Algorithm SHA384 */
- CKMC_HASH_SHA512 /**< Hash Algorithm SHA512 */
+ CKMC_HASH_SHA1 = 0, /**< 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 Enumerates for RSA padding algorithm.
+ * @brief Enumeration for RSA padding algorithm.
* @since_tizen 2.3
*/
typedef enum __ckmc_rsa_padding_algo {
- CKMC_PKCS1_PADDING = 0, /**< PKCS#1 Padding */
- CKMC_X931_PADDING /**< X9.31 padding */
+ CKMC_PKCS1_PADDING = 0, /**< PKCS#1 Padding */
+ CKMC_X931_PADDING /**< X9.31 padding */
} ckmc_rsa_padding_algo_e;
/**
- * @brief Binary buffer used in key manager CAPI
+ * @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 */
+ unsigned char* data; /**< Byte array containing binary data */
+ size_t size; /**< The size of the binary data */
} ckmc_raw_buffer_s;
/**
- * @brief A policy for storing key/certificate/binary data
+ * @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 */
- bool extractable; /**< if true key may be extracted from storage */
- bool restricted; /**< if true only key owner may see data */
+ 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 */
+ bool restricted; /**< If true only key owner may see data */
} ckmc_policy_s;
/**
- * @brief Key structure used in key manager CAPI
+ * @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 */
- ckmc_key_type_e key_type; /**< the raw_key's type */
- char* password; /**< byte array used to decrypt data raw_key inside key manager. */
+ 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 */
+ ckmc_key_type_e key_type; /**< The raw_key's type */
+ char* password; /**< Byte array used to decrypt data raw_key inside key manager. */
} ckmc_key_s;
/**
- * @brief Certificate structure used in key manager CAPI
+ * @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 */
- ckmc_data_format_e data_format; /**< raw_cert's encoding format */
+ 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 Linked list structure of alias
+ * @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 */
- struct __ckmc_alias_list *next; /**< the pointer pointing to the next ckmc_alias_list_s */
+ 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 Linked list structure of ckmc_cert_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 */
- struct __ckmc_cert_list *next; /**< the pointer pointing to the next ckmc_cert_list_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;
/**
* @internal
- * @brief Creates a new ckmc_key_s handle and returns it.
+ * @brief Creates a new @a ckmc_key_s handle and returns it.
*
* @since_tizen 2.3
* @privlevel platform
* @privilege %http://tizen.org/privilege/keymanager.admin
*
- * @remarks A newly created ckmc_key_s should be destroyed by calling ckmc_key_free() if it is no longer needed.
+ * @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.
+ * @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
+ *
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ *
+ * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
+ * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
*
- * @param[in] raw_key byte array of key. raw_key may be encrypted with password
- * @param[in] key_size the byte size of raw_key
- * @param[in] key_type the raw_key's type
- * @param[in] password byte array used to decrypt raw_key inside key manager. If raw_key is not encrypted, password can be null.
- * @param[out] ppkey a pointer to a newly created ckmc_key_s handle
- * @return 0 on success, otherwise a negative error value
- * @retval #CKMC_ERROR_INVALID_PARAMETER input parameter is invalid
- * @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);
+ ckmc_key_type_e key_type, char *password, ckmc_key_s **ppkey);
/**
- * @brief Destroys the ckmc_key_s handle and releases all its resources.
+ * @brief Destroys the @a ckmc_key_s handle and releases all its resources.
*
* @since_tizen 2.3
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
- * @param[in] key a ckmc_key_s handle to destroy
+ * @param[in] key The @a ckmc_key_s handle to destroy
+ *
* @see ckmc_key_new()
*/
void ckmc_key_free(ckmc_key_s *key);
/**
* @internal
- * @brief Creates a new ckmc_raw_buffer_s handle and returns it.
+ * @brief Creates a new @a ckmc_raw_buffer_s handle and returns it.
*
* @since_tizen 2.3
* @privlevel platform
* @privilege %http://tizen.org/privilege/keymanager.admin
*
- * @remarks A newly created ckmc_raw_buffer_s should be destroyed by calling ckmc_buffer_free() if it is no longer needed.
+ * @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
+ *
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ *
+ * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
+ * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
*
- * @param[in] data byte array of buffer.
- * @param[in] size the byte size of buffer
- * @param[out] ppbuffer a pointer to a newly created ckmc_buffer_s handle
- * @return 0 on success, otherwise a negative error value
- * @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);
/**
- * @brief Destroys the ckmc_raw_buffer_s handle and releases all its resources.
+ * @brief Destroys the @a ckmc_raw_buffer_s handle and releases all its resources.
*
* @since_tizen 2.3
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
- * @param[in] buffer a ckmc_raw_buffer_s handle to destroy
+ * @param[in] buffer The @a ckmc_raw_buffer_s handle to destroy
+ *
* @see ckmc_buffer_new()
*/
void ckmc_buffer_free(ckmc_raw_buffer_s *buffer);
/**
* @internal
- * @brief Creates a new ckmc_cert_s handle and returns it.
+ * @brief Creates a new @a ckmc_cert_s handle and returns it.
*
* @since_tizen 2.3
* @privlevel platform
* @privilege %http://tizen.org/privilege/keymanager.admin
*
- * @remarks A newly created ckmc_cert_s should be destroyed by calling ckmc_cert_free() if it is no longer needed.
+ * @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
+ *
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ *
+ * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
+ * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
*
- * @param[in] raw_cert 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 a pointer to a newly created ckmc_cert_s handle
- * @return 0 on success, otherwise a negative error value
- * @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_load_from_pkcs12_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);
+ ckmc_data_format_e data_format, ckmc_cert_s **ppcert);
/**
- * @brief Destroys the ckmc_cert handle and releases all its resources.
+ * @brief Destroys the @a ckmc_cert handle and releases all its resources.
*
* @since_tizen 2.3
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
- * @param[in] cert a ckmc_cert_s handle to destroy
+ * @param[in] cert The @a ckmc_cert_s handle to destroy
+ *
* @see ckmc_cert_new()
* @see ckmc_load_cert_from_file()
* @see ckmc_load_from_pkcs12_file
void ckmc_cert_free(ckmc_cert_s *cert);
/**
- * @brief Creates a new ckmc_cert_s handle from a given file and returns it.
+ * @brief Creates a new @a ckmc_cert_s handle from a given file and returns it.
*
* @since_tizen 2.3
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
- * @remarks A newly created ckmc_cert_s should be destroyed by calling ckmc_cert_free() if it is no longer needed.
+ * @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
+ *
+ * @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
*
- * @param[in] file_path a path of certificate file to be loaded. 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 doesn't exists or cannot be accessed
* @see ckmc_cert_free()
* @see ckmc_cert_new()
* @see ckmc_load_from_pkcs12_file()
int ckmc_load_cert_from_file(const char *file_path, ckmc_cert_s **cert);
/**
- * @brief Creates a new ckmc_key_s(private key), ckmc_cert_s(certificate), and ckmc_cert_list_s(CA certificates) handle from a given PKCS#12 file and returns them.
+ * @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.
*
* @since_tizen 2.3
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
- * @remarks A newly created ckmc_key_s, ckmc_cert_s, and ckmc_cert_list_s should be destroyed by calling ckmc_key_free(), ckmc_cert_free(), and ckmc_cert_list_all_free() if they are no longer needed.
- *
- * @param[in] file_path a path of PKCS12 file to be loaded.
- * @param[in] passphrase used to decrypt the PCKS12 file. 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. It is null if the PKCS12 file doesn't contain a certificate.
- * @param[out] ca_cert_list the pointer of newly created ckmc_cert_list_s handle for CA certificates. It is null if the PKCS12 file doesn't 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 doesn't exists or cannot be accessed
+ * @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 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
+ * 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
+ *
* @see ckmc_key_free()
* @see ckmc_cert_free()
* @see ckmc_cert_list_all_free()
* @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);
+ ckmc_key_s **private_key, ckmc_cert_s **cert,
+ ckmc_cert_list_s **ca_cert_list);
/**
* @internal
- * @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 the next is null.
+ * @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.
*
* @since_tizen 2.3
* @privlevel platform
* @privilege %http://tizen.org/privilege/keymanager.admin
*
- * @remarks A newly created ckmc_alias_list_s should be destroyed by calling ckmc_alias_list_free() or ckmc_alias_list_all_free() if it is no longer needed.
+ * @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
+ *
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ *
+ * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
+ * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
*
- * @param[in] alias the first item to be set in the newly created ckmc_alias_list_s.
- * @param[out] ppalias_list a pointer to a newly created ckmc_alias_list_s handle
- * @return 0 on success, otherwise a negative error value
- * @retval #CKMC_ERROR_INVALID_PARAMETER input parameter is invalid
- * @retval #CKMC_ERROR_OUT_OF_MEMORY not enough memory
* @see ckmc_alias_list_add()
* @see ckmc_alias_list_free()
* @see ckmc_alias_list_all_free()
/**
* @internal
- * @brief Creates a new ckmc_alias_list_s handle, add 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 the next is null.
+ * @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.
*
* @since_tizen 2.3
* @privlevel platform
* @privilege %http://tizen.org/privilege/keymanager.admin
*
- * @param[in] previous the last ckmc_alias_list_s handle to which a newly created ckmc_alias_list_s is added
- * @param[in] alias an item to be set in the newly created ckmc_alias_list_s.
- * @param[out] pplast a pointer to a newly created and added ckmc_alias_list_s handle
- * @return 0 on success, otherwise a negative error value
- * @retval #CKMC_ERROR_INVALID_PARAMETER input parameter is invalid
- * @retval #CKMC_ERROR_OUT_OF_MEMORY not enough memory
+ * @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
+ *
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ *
+ * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
+ * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
+ *
* @see ckmc_alias_list_add()
* @see ckmc_alias_list_free()
* @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);
+ char *alias, ckmc_alias_list_s **pplast);
/**
* @internal
- * @brief Destroys the ckmc_alias_list_s handle and releases resources of ckmc_alias_list_s from the provided first handle cascadingly.
+ * @brief Destroys the @a ckmc_alias_list_s handle and releases resources of @a ckmc_alias_list_s from the provided first handle cascadingly.
*
* @since_tizen 2.3
* @privlevel platform
* @privilege %http://tizen.org/privilege/keymanager.admin
*
- * @remarks It does not destroy an alias itself in ckmc_alias_list_s.
+ * @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
*
- * @param[in] first the first ckmc_alias_list_s handle to destroy
* @see ckmc_alias_list_new()
* @see ckmc_alias_list_add()
* @see ckmc_alias_list_all_free()
void ckmc_alias_list_free(ckmc_alias_list_s *first);
/**
- * @brief Destroys the ckmc_alias_list_s handle and releases all its resources from the provided first handle cascadingly.
+ * @brief Destroys the @a ckmc_alias_list_s handle and releases all its resources from the provided first handle cascadingly.
*
* @since_tizen 2.3
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
- * @remarks It also destroy an alias in ckmc_alias_list_s.
+ * @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
*
- * @param[in] first the first ckmc_alias_list_s handle to destroy
* @see ckmc_alias_list_new()
* @see ckmc_alias_list_add()
* @see ckmc_alias_list_free()
/**
* @internal
- * @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 the next is null.
+ * @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.
*
* @since_tizen 2.3
* @privlevel platform
* @privilege %http://tizen.org/privilege/keymanager.admin
*
- * @remarks A newly created ckmc_cert_list_s should be destroyed by calling ckmc_cert_list_free() or ckmc_cert_list_all_free() if it is no longer needed.
+ * @remarks You must destroy the newly created @a 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
+ *
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ *
+ * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
+ * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
*
- * @param[in] cert the first item to be set in the newly created ckmc_cert_list_s.
- * @param[out] ppalias_list a pointer to a newly created ckmc_alias_list_s handle
- * @return 0 on success, otherwise a negative error value
- * @retval #CKMC_ERROR_INVALID_PARAMETER input parameter is invalid
- * @retval #CKMC_ERROR_OUT_OF_MEMORY not enough memory
* @see ckmc_cert_list_add()
* @see ckmc_cert_list_free()
* @see ckmc_cert_list_all_free()
/**
* @internal
- * @brief Creates a new ckmc_cert_list_s handle, add 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 the next is null.
+ * @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.
*
* @since 2.3
* @privlevel platform
* @privilege %http://tizen.org/privilege/keymanager.admin
*
- * @param[in] previous the last ckmc_cert_list_s handle to which a newly created ckmc_cert_list_s is added
- * @param[in] cert an item to be set in the newly created ckmc_cert_list_s.
- * @param[out] pplast a pointer to a newly created and added ckmc_alias_list_s handle
- * @return 0 on success, otherwise a negative error value
- * @retval #CKMC_ERROR_INVALID_PARAMETER input parameter is invalid
- * @retval #CKMC_ERROR_OUT_OF_MEMORY not enough memory
+ * @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
+ *
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ *
+ * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
+ * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
+ *
* @see ckmc_cert_list_add()
* @see ckmc_cert_list_free()
* @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);
+ ckmc_cert_s *cert, ckmc_cert_list_s **pplast);
/**
* @internal
- * @brief Destroys the ckmc_cert_list_s handle and releases resources of ckmc_cert_list_s from the provided first handle cascadingly.
+ * @brief Destroys the @a ckmc_cert_list_s handle and releases resources of @a ckmc_cert_list_s from the provided first handle cascadingly.
*
* @since 2.3
* @privlevel platform
* @privilege %http://tizen.org/privilege/keymanager.admin
- * @remarks It does not destroy an ckmc_cert_s itself in ckmc_cert_list_s.
*
- * @param[in] first the first ckmc_cert_list_s handle to destroy
+ * @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
+ *
* @see ckmc_cert_list_new()
* @see ckmc_cert_list_add()
* @see ckmc_cert_list_all_free()
void ckmc_cert_list_free(ckmc_cert_list_s *first);
/**
- * @brief Destroys the ckmc_cert_list_s handle and releases all its resources from the provided first handle cascadingly.
+ * @brief Destroys the @a ckmc_cert_list_s handle and releases all its resources from the provided first handle cascadingly.
*
* @since 2.3
* @privlevel public
* @privilege %http://tizen.org/privilege/keymanager
*
- * @remarks It also destroy an ckmc_cert_s in ckmc_cert_list_s.
+ * @remarks It also destroys @a ckmc_cert_s in ckmc_cert_list_s.
+ *
+ * @param[in] first The first @a ckmc_cert_list_s handle to destroy
*
- * @param[in] first the first ckmc_cert_list_s handle to destroy
* @see ckmc_cert_list_new()
* @see ckmc_cert_list_add()
* @see ckmc_cert_list_free()
projects / platform / core / security / key-manager.git / commitdiff