*
*
* @file ckmc-control.h
- * @author Yuseok Jeon(yuseok.jeon@samsung.com)
* @version 1.0
- * @brief provides functions which are able to control key-manager daemon.
+ * @brief provides control functions for the key manager.
*/
-#ifndef CKMC_CONTROL_H
-#define CKMC_CONTROL_H
+#ifndef __TIZEN_CORE_CKMC_CONTROL_H
+#define __TIZEN_CORE_CKMC_CONTROL_H
#include <sys/types.h>
extern "C" {
#endif
+/**
+ * @addtogroup CAPI_KEY_MANAGER_MODULE
+ * @{
+ */
-// decrypt user key with password
+/**
+ * @brief Decrypts a user key 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.
+ *
+ * @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 is a uid of a user whose key is decrypted.
+ * @param[in] password is used in decrypting a user key.
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_SERVER_ERROR failed to unlock user key
+ * @retval #CKM_API_ERROR_INPUT_PARAM invalid input parameter
+ * @retval #CKM_API_ERROR_AUTHENTICATION_FAILED not correct password
+ *
+ * @see ckm_lock_user_key()
+ * @see ckm_remove_user_data()
+ * @see ckm_change_user_password()
+ * @see ckm_reset_user_password()
+ */
int ckm_unlock_user_key(uid_t user, const char *password);
-// remove user key from memory
+/**
+ * @brief remove a decrypted user key from memory
+ *
+ * @param[in] user is a uid of a user whose key is removed from memory.
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_INPUT_PARAM invalid input parameter
+ *
+ * @see ckm_unlock_user_key()
+ * @see ckm_remove_user_data()
+ * @see ckm_change_user_password()
+ * @see ckm_reset_user_password()
+ */
int ckm_lock_user_key(uid_t user);
-// remove user data from Store and erase key used for encryption
+/**
+ * @brief remove user data from Store and erase a user key used for encryption
+ *
+ * @param[in] user is a uid of a user whose data and key are removed
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_INPUT_PARAM invalid input parameter
+ *
+ * @see ckm_unlock_user_key()
+ * @see ckm_lock_user_key()
+ * @see ckm_change_user_password()
+ * @see ckm_reset_user_password()
+ */
int ckm_remove_user_data(uid_t user);
-// change password for user
+/**
+ * @brief change a password for a user. key manager decrypts a user key with old password and re-encrypts a user key with new password.
+ *
+ * @param[in] user is a uid of a user whose user key is re-encrypted
+ * @param[in] old_password is used in decrypting a user key.
+ * @param[in] new_password is used in re-encrypting a user key.
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_INPUT_PARAM invalid input parameter
+ * @retval #CKM_API_ERROR_AUTHENTICATION_FAILED not correct password
+ * @retval #CKM_API_ERROR_BAD_REQUEST no information about old password
+ *
+ * @see ckm_unlock_user_key()
+ * @see ckm_lock_user_key()
+ * @see ckm_remove_user_data()
+ * @see ckm_reset_user_password()
+ */
int ckm_change_user_password(uid_t user, const char *old_password, const char *new_password);
-// This is work around for security-server api - resetPassword that may be called without passing oldPassword.
-// This api should not be supported on tizen 3.0
-// User must be already logged in and his DKEK is already loaded into memory in plain text form.
-// The service will use DKEK in plain text and encrypt it in encrypted form (using new password).
-int ckm_reset_user_password(uid_t user, const char *new_password);
+/**
+ * @brief change a password for a user without old password.
+ *
+ * @param[in] user is a uid of a user whose user key is re-encrypted
+ * @param[in] new_password is used in re-encrypting a user key.
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_INPUT_PARAM invalid input parameter
+ * @retval #CKM_API_ERROR_BAD_REQUEST a user key is not unlocked.
+ *
+ * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ *
+ * @see ckm_unlock_user_key()
+ * @see ckm_lock_user_key()
+ * @see ckm_remove_user_data()
+ * @see ckm_change_user_password()
+ */
+int ckm_reset_user_password(uid_t user, const char *newPassword);
+/**
+ * @}
+ */
#ifdef __cplusplus
}
#endif
-#endif /* CKMC_CONTROL_H */
+#endif /* __TIZEN_CORE_CKMC_CONTROL_H */
/*
- *
* Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
*
- * Contact: Bumjin Im <bj.im@samsung.com>
- *
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* See the License for the specific language governing permissions and
* limitations under the License
*
- * @file ckmc-error.h
- * @author Yuseok Jeon(yuseok.jeon@samsung.com)
- * @version 1.0
- * @brief This file is implementation of client-common functions.
+ * @file ckmc-error.h
+ * @version 1.0
+ * @brief This file contains error codes of the Key Manager
+*/
+#ifndef __TIZEN_CORE_CKMC_ERROR_H_
+#define __TIZEN_CORE_CKMC_ERROR_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @addtogroup CAPI_KEY_MANAGER_MODULE
+ * @{
+ */
+
+/**
+ * @brief indicating the result of the one specific API is successful
+ */
+#define CKM_API_SUCCESS 0
+
+/**
+ * @brief indicating the socket between client and Central Key Manager failed
+ */
+#define CKM_API_ERROR_SOCKET -1
+
+/**
+ * @brief indicating the request from client is malformed
+ */
+#define CKM_API_ERROR_BAD_REQUEST -2
+
+/**
+ * @brief indicating the response from Central Key Manager is malformed
+ */
+#define CKM_API_ERROR_BAD_RESPONSE -3
+
+/**
+ * @brief indicating the transmitting request failed.
+ * @remarks This Error code is deprecated.
+ */
+#define CKM_API_ERROR_SEND_FAILED -4
+
+/**
+ * @brief indicating the receiving response failed.
+ * @remarks This Error code is deprecated.
+ */
+#define CKM_API_ERROR_RECV_FAILED -5
+
+/**
+ * @brief indicating the authentication between client and manager failed.
+ * @remarks This Error code is deprecated.
+ */
+#define CKM_API_ERROR_AUTHENTICATION_FAILED -6
+
+/**
+ * @brief indicating the API's input parameter is malformed
+ */
+#define CKM_API_ERROR_INPUT_PARAM -7
+
+/**
+ * @brief indicating the output buffer size which is passed as parameter is too small
+ */
+#define CKM_API_ERROR_BUFFER_TOO_SMALL -8
+
+/**
+ * @brief indicating system is running out of memory state
*/
+#define CKM_API_ERROR_OUT_OF_MEMORY -9
-#ifndef CKMC_ERROR_H
-#define CKMC_ERROR_H
+/**
+ * @brief indicating the access has been denied by Central Key Manager
+ */
+#define CKM_API_ERROR_ACCESS_DENIED -10
+
+/**
+ * @brief indicating Central Key Manager has been failed for some reason
+ */
+#define CKM_API_ERROR_SERVER_ERROR -11
+
+/**
+ * @brief indicating the database was not unlocked - user did not login
+ */
+#define CKM_API_ERROR_DB_LOCKED -12
+
+/**
+ * @brief indicating an internal error inside the database
+ */
+#define CKM_API_ERROR_DB_ERROR -13
+
+/**
+ * @brief indicating that provided alias already exists in the database
+ */
+#define CKM_API_ERROR_DB_ALIAS_EXISTS -14
+
+
+/**
+ * @brief indicating that request given to database returned no result
+ */
+#define CKM_API_ERROR_DB_ALIAS_UNKNOWN -15
+
+/**
+ * @brief indicating that CA certificate(s) were unknown and chain could not be created
+ */
+#define CKM_API_ERROR_VERIFICATION_FAILED -16
+
+/**
+ * @brief indicating that a provided file or binary has not a valid format
+ */
+#define CKM_API_ERROR_INVALID_FORMAT -17
+
+/**
+ * @brief indicating that provided file doesn't exists or cannot be accessed in the file system
+ */
+#define CKM_API_ERROR_FILE_ACCESS_DENIED -18
+
+/**
+ * @brief indicating the error with unknown reason
+ */
+#define CKM_API_ERROR_UNKNOWN -255
+
+
+/**
+ * @}
+ */
-#include <ckm/ckm-error.h>
+#ifdef __cplusplus
+}
+#endif
-#endif /* CKMC_ERROR_H */
+#endif /* __TIZEN_CORE_CKMC_ERROR_H_ */
*
*
* @file ckmc-manager.h
- * @author Yuseok Jeon(yuseok.jeon@samsung.com)
* @version 1.0
* @brief provides management functions(storing, retrieving, and removing) for keys, certificates and data of a user and additional crypto functions.
*/
-#ifndef CKMC_MANAGER_H
-#define CKMC_MANAGER_H
+#ifndef __TIZEN_CORE_CKMC_MANAGER_H
+#define __TIZEN_CORE_CKMC_MANAGER_H
#include <stddef.h>
#include <sys/types.h>
extern "C" {
#endif
-// key related functions
+/**
+ * @addtogroup CAPI_KEY_MANAGER_MODULE
+ * @{
+ */
+
+
+/**
+ * @brief Stores a key inside key manager based on the provided policy.
+ *
+ * @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 #CKM_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 #ckm_key structure.
+ * @remarks if password in policy is provided, the key is additionally encrypted with the password in policy.
+ *
+ * @param[in] alias is the name of a key to be stored
+ * @param[in] key has a key's binary value to be stored.
+ * @param[in] policy is about how to store a key securely.
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_INPUT_PARAM input parameter is invalid
+ * @retval #CKM_API_ERROR_DB_LOCKED a user key is not loaded in memory(a user is not logged in)
+ * @retval #CKM_API_ERROR_DB_ALIAS_EXISTS alias already exists.
+ * @retval #CKM_API_ERROR_INVALID_FORMAT the format of raw_key is not valid.
+ * @retval #CKM_API_ERROR_DB_ERROR failed due to other DB transaction unexpectedly.
+ *
+ * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ *
+ * @see ckm_remove_key()
+ * @see ckm_get_key()
+ * @see ckm_get_key_alias_list()
+ * @see #ckm_key
+ * @see #ckm_policy
+ */
int ckm_save_key(const char *alias, const ckm_key key, const ckm_policy policy);
+
+/**
+ * @brief Removes a key from key manager
+ *
+ * @remarks a client can remove only keys stored by the client.
+ *
+ * @param[in] alias is the name of a key to be removed
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_INPUT_PARAM input parameter is invalid
+ * @retval #CKM_API_ERROR_DB_LOCKED a user key is not loaded in memory(a user is not logged in)
+ * @retval #CKM_API_ERROR_DB_ERROR failed due to the error with unknown reason
+ * @retval #CKM_API_ERROR_DB_ALIAS_UNKNOWN alias doesn't exists.
+ *
+ * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ *
+ * @see ckm_save_key()
+ * @see ckm_get_key()
+ * @see ckm_get_key_alias_list()
+ */
int ckm_remove_key(const char *alias);
-int ckm_get_key(const char *alias, const char *password, ckm_key **key);
-int ckm_get_key_alias_list(ckm_alias_list** alias_list);
+/**
+ * @brief Get a key from key manager
+ *
+ * @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 ckm_key_free() if it is no longer needed.
+ *
+ * @param[in] alias is the name of a key to retrieve
+ * @param[in] password is used in decrypting a key value. If password of policy is provided in ckm_save_key(), the same password should be provided.
+ * @param[out] ppkey is a pointer to a newly created ckm_key handle
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_INPUT_PARAM input parameter is invalid
+ * @retval #CKM_API_ERROR_DB_LOCKED a user key is not loaded in memory(a user is not logged in)
+ * @retval #CKM_API_ERROR_DB_ERROR failed due to the error with unknown reason
+ * @retval #CKM_API_ERROR_DB_ALIAS_UNKNOWN alias doesn't exists.
+ *
+ * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ *
+ * @see ckm_save_key()
+ * @see ckm_remove_key()
+ * @see ckm_get_key_alias_list()
+ */
+int ckm_get_key(const char *alias, const char *password, ckm_key **ppkey);
+
+/**
+ * @brief Get a all alias of keys to which the client can access
+ *
+ * @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 ckm_alias_list_all_free() if it is no longer needed.
+ *
+ * @param[out] ppalias_list is a pointer to a newly created ckm_alias_list handle containing all available alias of keys. If there is no available key alias, *ppalias_list will be null.
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_INPUT_PARAM input parameter is invalid
+ * @retval #CKM_API_ERROR_DB_LOCKED a user key is not loaded in memory(a user is not logged in)
+ * @retval #CKM_API_ERROR_DB_ERROR failed due to the error with unknown reason
+ * @retval #CKM_API_ERROR_DB_ALIAS_UNKNOWN alias doesn't exists.
+ *
+ * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ *
+ * @see ckm_save_key()
+ * @see ckm_remove_key()
+ * @see ckm_get_key()
+ */
+int ckm_get_key_alias_list(ckm_alias_list** ppalias_list);
+
+
+
+
+/**
+ * @brief Stores a certificate inside key manager based on the provided policy.
+ *
+ * @param[in] alias is the name of a certificate to be stored
+ * @param[in] cert has a certificate's binary value to be stored.
+ * @param[in] policy is about how to store a certificate securely.
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_INPUT_PARAM input parameter is invalid
+ * @retval #CKM_API_ERROR_DB_LOCKED a user key is not loaded in memory(a user is not logged in)
+ * @retval #CKM_API_ERROR_DB_ALIAS_EXISTS alias already exists.
+ * @retval #CKM_API_ERROR_INVALID_FORMAT the format of raw_cert is not valid.
+ * @retval #CKM_API_ERROR_DB_ERROR failed due to other DB transaction unexpectedly.
+ *
+ * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ *
+ * @see ckm_remove_cert()
+ * @see ckm_get_cert()
+ * @see ckm_get_cert_alias_list()
+ * @see #ckm_cert
+ * @see #ckm_policy
+ */
int ckm_save_cert(const char *alias, const ckm_cert cert, const ckm_policy policy);
+
+/**
+ * @brief Removes a certificate from key manager
+ *
+ * @remarks a client can remove only certificates stored by the client.
+ *
+ * @param[in] alias is the name of a certificate to be removed
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_INPUT_PARAM input parameter is invalid
+ * @retval #CKM_API_ERROR_DB_LOCKED a user key is not loaded in memory(a user is not logged in)
+ * @retval #CKM_API_ERROR_DB_ERROR failed due to the error with unknown reason
+ * @retval #CKM_API_ERROR_DB_ALIAS_UNKNOWN alias doesn't exists.
+ *
+ * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ *
+ * @see ckm_save_cert()
+ * @see ckm_get_cert()
+ * @see ckm_get_cert_alias_list()
+ */
int ckm_remove_cert(const char *alias);
-int ckm_get_cert(const char *alias, const char *password, const ckm_cert **cert);
-int ckm_get_cert_alias_list(ckm_alias_list** alias_list);
+/**
+ * @brief Get a certificate from key manager
+ *
+ * @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 ckm_cert_free() if it is no longer needed.
+ *
+ * @param[in] alias is the name of a certificate to retrieve
+ * @param[in] password is used in decrypting a certificate value. If password of policy is provided in ckm_save_cert(), the same password should be provided.
+ * @param[out] ppcert is a pointer to a newly created ckm_cert handle
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_INPUT_PARAM input parameter is invalid
+ * @retval #CKM_API_ERROR_DB_LOCKED a user key is not loaded in memory(a user is not logged in)
+ * @retval #CKM_API_ERROR_DB_ERROR failed due to the error with unknown reason
+ * @retval #CKM_API_ERROR_DB_ALIAS_UNKNOWN alias doesn't exists.
+ *
+ * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ *
+ * @see ckm_save_cert()
+ * @see ckm_remove_cert()
+ * @see ckm_get_cert_alias_list()
+ */
+int ckm_get_cert(const char *alias, const char *password, const ckm_cert **ppcert);
+
+/**
+ * @brief Get a all alias of certificates to which the client can access
+ *
+ * @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 ckm_alias_list_all_free() if it is no longer needed.
+ *
+ * @param[out] ppalias_list is a pointer to a newly created ckm_alias_list handle containing all available alias of keys. If there is no available key alias, *ppalias_list will be null.
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_INPUT_PARAM input parameter is invalid
+ * @retval #CKM_API_ERROR_DB_LOCKED a user key is not loaded in memory(a user is not logged in)
+ * @retval #CKM_API_ERROR_DB_ERROR failed due to the error with unknown reason
+ * @retval #CKM_API_ERROR_DB_ALIAS_UNKNOWN alias doesn't exists.
+ *
+ * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ *
+ * @see ckm_save_cert()
+ * @see ckm_remove_cert()
+ * @see ckm_get_cert()
+ */
+int ckm_get_cert_alias_list(ckm_alias_list** ppalias_list);
+
+
+
+
+/**
+ * @brief Stores a data inside key manager based on the provided policy.
+ *
+ * @param[in] alias is the name of a data to be stored
+ * @param[in] data has a binary value to be stored.
+ * @param[in] policy is about how to store a data securely.
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_INPUT_PARAM input parameter is invalid
+ * @retval #CKM_API_ERROR_DB_LOCKED a user key is not loaded in memory(a user is not logged in)
+ * @retval #CKM_API_ERROR_DB_ALIAS_EXISTS alias already exists.
+ * @retval #CKM_API_ERROR_DB_ERROR failed due to other DB transaction unexpectedly.
+ *
+ * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ *
+ * @see ckm_remove_data()
+ * @see ckm_get_data()
+ * @see ckm_get_data_alias_list()
+ * @see #ckm_raw_buffer
+ * @see #ckm_policy
+ */
int ckm_save_data(const char *alias, ckm_raw_buffer data, const ckm_policy policy);
+
+/**
+ * @brief Removes a data from key manager
+ *
+ * @remarks a client can remove only data stored by the client.
+ *
+ * @param[in] alias is the name of a data to be removed
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_INPUT_PARAM input parameter is invalid
+ * @retval #CKM_API_ERROR_DB_LOCKED a user key is not loaded in memory(a user is not logged in)
+ * @retval #CKM_API_ERROR_DB_ERROR failed due to the error with unknown reason
+ * @retval #CKM_API_ERROR_DB_ALIAS_UNKNOWN alias doesn't exists.
+ *
+ * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ *
+ * @see ckm_save_data()
+ * @see ckm_get_data()
+ * @see ckm_get_data_alias_list()
+ */
int ckm_remove_data(const char *alias);
-int ckm_get_data(const char *alias, const char *password, ckm_raw_buffer **data);
-int ckm_get_data_alias_list(ckm_alias_list** alias_list);
+/**
+ * @brief Get a data from key manager
+ *
+ * @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 ckm_buffer_free() if it is no longer needed.
+ *
+ * @param[in] alias is the name of a data to retrieve
+ * @param[in] password is used in decrypting a data value. If password of policy is provided in ckm_save_data(), the same password should be provided.
+ * @param[out] ppdata is a pointer to a newly created ckm_raw_buffer handle
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_INPUT_PARAM input parameter is invalid
+ * @retval #CKM_API_ERROR_DB_LOCKED a user key is not loaded in memory(a user is not logged in)
+ * @retval #CKM_API_ERROR_DB_ERROR failed due to the error with unknown reason
+ * @retval #CKM_API_ERROR_DB_ALIAS_UNKNOWN alias doesn't exists.
+ *
+ * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ *
+ * @see ckm_save_data()
+ * @see ckm_remove_data()
+ * @see ckm_get_data_alias_list()
+ */
+int ckm_get_data(const char *alias, const char *password, ckm_raw_buffer **ppdata);
-// crypto functions
+/**
+ * @brief Get a all alias of data to which the client can access
+ *
+ * @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 ckm_alias_list_all_free() if it is no longer needed.
+ *
+ * @param[out] ppalias_list is a pointer to a newly created ckm_alias_list handle containing all available alias of keys. If there is no available key alias, *ppalias_list will be null.
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_INPUT_PARAM input parameter is invalid
+ * @retval #CKM_API_ERROR_DB_LOCKED a user key is not loaded in memory(a user is not logged in)
+ * @retval #CKM_API_ERROR_DB_ERROR failed due to the error with unknown reason
+ * @retval #CKM_API_ERROR_DB_ALIAS_UNKNOWN alias doesn't exists.
+ *
+ * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ *
+ * @see ckm_save_data()
+ * @see ckm_remove_data()
+ * @see ckm_get_data()
+ */
+int ckm_get_data_alias_list(ckm_alias_list** ppalias_list);
+
+
+
+
+/**
+ * @brief Creates RSA private/public key pair and stores them inside key manager based on each policy.
+ *
+ * @remarks if password in policy is provided, the key is additionally encrypted with the password in policy.
+ *
+ * @param[in] size is the size of key strength to be created. 1024, 2048, and 4096 are supported.
+ * @param[in] private_key_alias is the name of private key to be stored.
+ * @param[in] public_key_alias is the name of public key to be stored.
+ * @param[in] policy_private_key is about how to store a private key securely.
+ * @param[in] policy_public_key is about how to store a public key securely.
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_INPUT_PARAM input parameter is invalid
+ * @retval #CKM_API_ERROR_DB_LOCKED a user key is not loaded in memory(a user is not logged in)
+ * @retval #CKM_API_ERROR_DB_ALIAS_EXISTS alias already exists.
+ * @retval #CKM_API_ERROR_DB_ERROR failed due to other DB transaction unexpectedly.
+ *
+ * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ *
+ * @see ckm_create_key_pair_ecdsa()
+ * @see ckm_create_signature()
+ * @see ckm_verify_signature()
+ */
int ckm_create_key_pair_rsa(const size_t size, const char *private_key_alias, const char *public_key_alias, const ckm_policy policy_private_key, const ckm_policy policy_public_key);
+
+/**
+ * @brief Creates ECDSA private/public key pair and stores them inside key manager based on each policy.
+ *
+ * @remarks if password in policy is provided, the key is additionally encrypted with the password in policy.
+ *
+ * @param[in] type is the type of eliptic curve of ECDSA.
+ * @param[in] private_key_alias is the name of private key to be stored.
+ * @param[in] public_key_alias is the name of public key to be stored.
+ * @param[in] policy_private_key is about how to store a private key securely.
+ * @param[in] policy_public_key is about how to store a public key securely.
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_INPUT_PARAM input parameter is invalid
+ * @retval #CKM_API_ERROR_DB_LOCKED a user key is not loaded in memory(a user is not logged in)
+ * @retval #CKM_API_ERROR_DB_ALIAS_EXISTS alias already exists.
+ * @retval #CKM_API_ERROR_DB_ERROR failed due to other DB transaction unexpectedly.
+ *
+ * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ *
+ * @see ckm_create_key_pair_rsa()
+ * @see ckm_create_signature()
+ * @see ckm_verify_signature()
+ * @see #ckm_ec_type
+ */
int ckm_create_key_pair_ecdsa(const ckm_ec_type type, const char *private_key_alias, const char *public_key_alias, const ckm_policy policy_private_key, const ckm_policy policy_public_key);
-int ckm_create_signature(const char *private_key_alias, const char *password, const ckm_raw_buffer message, const ckm_hash_algo hash, const ckm_rsa_padding_algo padding, ckm_raw_buffer **signature);
+
+/**
+ * @brief Creates a signature on a given message using a private key and returns the signature
+ *
+ * @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 ckm_buffer_free() if it is no longer needed.
+ *
+ *
+ * @param[in] private_key_alias is the name of private key.
+ * @param[in] password is used in decrypting a private key value.
+ * @param[in] message is signed with a private key .
+ * @param[in] hash is the hash algorithm used in creating signature.
+ * @param[in] padding is the RSA padding algorithm used in creating signature. It is used only when the signature algorithm is RSA.
+ * @param[out] ppsignature is a pointer to a newly created signature's. If an error occurs, *ppsignature will be null.
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_INPUT_PARAM input parameter is invalid
+ * @retval #CKM_API_ERROR_DB_LOCKED a user key is not loaded in memory(a user is not logged in)
+ * @retval #CKM_API_ERROR_DB_ALIAS_UNKNOWN alias doesn't exists.
+ *
+ * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ *
+ * @see ckm_create_key_pair_rsa()
+ * @see ckm_create_key_pair_ecdsa()
+ * @see ckm_verify_signature()
+ * @see ckm_buffer_free()
+ * @see #ckm_hash_algo
+ * @see #ckm_rsa_padding_algo
+ */
+int ckm_create_signature(const char *private_key_alias, const char *password, const ckm_raw_buffer message, const ckm_hash_algo hash, const ckm_rsa_padding_algo padding, ckm_raw_buffer **ppsignature);
+
+/**
+ * @brief Verify a given signature on a given message using a public key and returns the signature status.
+ *
+ * @remarks If password of policy is provided during storing a key, the same password should be provided.
+ *
+ * @param[in] public_key_alias is the name of public key.
+ * @param[in] password is used in decrypting a public key value.
+ * @param[in] message is a input on which the signature is created.
+ * @param[in] signature is verified with public key.
+ * @param[in] hash is the hash algorithm used in verifying signature.
+ * @param[in] padding is the RSA padding algorithm used in verifying signature. It is used only when the signature algorithm is RSA.
+ *
+ * @return 0 on success and the signature is valid, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_VERIFICATION_FAILED the signature is invalid
+ * @retval #CKM_API_ERROR_INPUT_PARAM input parameter is invalid
+ * @retval #CKM_API_ERROR_DB_LOCKED a user key is not loaded in memory(a user is not logged in)
+ * @retval #CKM_API_ERROR_DB_ALIAS_UNKNOWN alias doesn't exists.
+ *
+ * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ *
+ * @see ckm_create_key_pair_rsa()
+ * @see ckm_create_key_pair_ecdsa()
+ * @see ckm_verify_signature()
+ * @see #ckm_hash_algo
+ * @see #ckm_rsa_padding_algo
+ */
int ckm_verify_signature(const char *public_key_alias, const char *password, const ckm_raw_buffer message, const ckm_raw_buffer signature, const ckm_hash_algo hash, const ckm_rsa_padding_algo padding);
-int ckm_get_cert_chain(const ckm_cert *cert, const ckm_cert_list *untrustedcerts, ckm_cert_list **cert_chain_list);
-int ckm_get_cert_chain_with_alias(const ckm_cert *cert, const ckm_alias_list *untrustedcerts, ckm_cert_list **cert_chain_list);
+/**
+ * @brief Verify a certificate chain and return that chain.
+ *
+ * @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 ckm_cert_list_all_free() if it is no longer needed.
+ *
+ * @param[in] cert is the certificate to be verified
+ * @param[in] untrustedcerts is the untrusted CA certificates to be used in verifying a certificate chain.
+ * @param[out] ppcert_chain_list is 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 #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_VERIFICATION_FAILED the certificate chain is not valid
+ * @retval #CKM_API_ERROR_INPUT_PARAM input parameter is invalid
+ * @retval #CKM_API_ERROR_DB_LOCKED a user key is not loaded in memory(a user is not logged in)
+ * @retval #CKM_API_ERROR_INVALID_FORMAT the format of certificate is not valid.
+ *
+ * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ *
+ * @see ckm_get_cert_chain_with_alias())
+ * @see ckm_cert_list_all_free()
+ */
+int ckm_get_cert_chain(const ckm_cert *cert, const ckm_cert_list *untrustedcerts, ckm_cert_list **ppcert_chain_list);
+
+/**
+ * @brief Verify a certificate chain using a alias list of untrusted certificates and return that chain.
+ *
+ * @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 ckm_cert_list_all_free() if it is no longer needed.
+ *
+ * @param[in] cert is the certificate to be verified
+ * @param[in] untrustedcerts is an alias list of untrusted CA certificates stored in key manager to be used in verifying a certificate chain.
+ * @param[out] ppcert_chain_list is 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 #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_VERIFICATION_FAILED the certificate chain is not valid
+ * @retval #CKM_API_ERROR_INPUT_PARAM input parameter is invalid
+ * @retval #CKM_API_ERROR_DB_LOCKED a user key is not loaded in memory(a user is not logged in)
+ * @retval #CKM_API_ERROR_DB_ALIAS_UNKNOWN alias doesn't exists.
+ * @retval #CKM_API_ERROR_INVALID_FORMAT the format of certificate is not valid.
+ *
+ * @pre User must be already logged in and his user key is already loaded into memory in plain text form.
+ *
+ * @see ckm_get_cert_chain())
+ * @see ckm_cert_list_all_free()
+ */
+int ckm_get_cert_chain_with_alias(const ckm_cert *cert, const ckm_alias_list *untrustedcerts, ckm_cert_list **ppcert_chain_list);
#ifdef __cplusplus
}
#endif
+/**
+ * @}
+ */
+
-#endif /* CKMC_MANAGER_H */
+#endif /* __TIZEN_CORE_CKMC_MANAGER_H */
*
*
* @file ckmc-type.h
- * @author Yuseok Jeon(yuseok.jeon@samsung.com)
* @version 1.0
- * @brief Definitions of struct for CAPI
+ * @brief Definitions of struct for the Key Manager's CAPI and their utility functions
*/
-#ifndef CKMC_TYPE_H
-#define CKMC_TYPE_H
+#ifndef __TIZEN_CORE_CKMC_TYPE_H
+#define __TIZEN_CORE_CKMC_TYPE_H
#include <stddef.h>
extern "C" {
#endif
+/**
+ * @addtogroup CAPI_KEY_MANAGER_MODULE
+ * @{
+ */
+
+/**
+ * @brief Enumeration for key types of key manager.
+ */
typedef enum ckm_key_type_t {
- CKM_KEY_NONE,
- CKM_KEY_RSA_PUBLIC,
- CKM_KEY_RSA_PRIVATE,
- CKM_KEY_ECDSA_PUBLIC,
- CKM_KEY_ECDSA_PRIVATE,
- CKM_KEY_AES
+ CKM_KEY_NONE =0, /**< key type not specified */
+ CKM_KEY_RSA_PUBLIC, /**< RSA public key */
+ CKM_KEY_RSA_PRIVATE, /**< RSA private key */
+ CKM_KEY_ECDSA_PUBLIC, /**< ECDSA public key */
+ CKM_KEY_ECDSA_PRIVATE, /**< ECDSA private key */
} ckm_key_type;
+/**
+ * @brief Enumeration for data format.
+ */
typedef enum ckm_data_format_t {
- CKM_FORM_DER_BASE64,
- CKM_FORM_DER,
- CKM_FORM_PEM
+ CKM_FORM_DER_BASE64 =0, /**< DER format base64 encoded data */
+ CKM_FORM_DER, /**< DER encoded data */
+ CKM_FORM_PEM /**< PEM encoded data. It consists of the DER format base64 encoded with additional header and footer lines */
} ckm_data_format;
+/**
+ * @brief Enumeration for eliptic curve.
+ */
typedef enum ckm_ec_type_t {
- CKM_EC_PRIME192V1,
- CKM_EC_PRIME256V1,
- CKM_EC_SECP384R1
+ CKM_EC_PRIME192V1 =0, /**< Elliptic curve domain "secp192r1" listed in "SEC 2" recommended elliptic curve domain */
+ CKM_EC_PRIME256V1, /**< "SEC 2" recommended elliptic curve domain - secp256r1 */
+ CKM_EC_SECP384R1 /**< NIST curve P-384 (covers "secp384r1", the elliptic curve domain listed in See SEC 2 */
} ckm_ec_type;
+/**
+ * @brief Enumeration for bool type used within key manager CAPI.
+ */
typedef enum ckm_bool_t {
- CKM_FALSE,
- CKM_TRUE
+ CKM_FALSE =0, /**< false */
+ CKM_TRUE /**< true */
} ckm_bool;
+/**
+ * @brief Enumeration for hash algorithm.
+ */
typedef enum ckm_hash_algo_t {
- CKM_HASH_SHA1,
- CKM_HASH_SHA256,
- CKM_HASH_SHA384,
- CKM_HASH_SHA512
+ CKM_HASH_SHA1 =0, /**< Hash Algorithm SHA1 */
+ CKM_HASH_SHA256, /**< Hash Algorithm SHA256 */
+ CKM_HASH_SHA384, /**< Hash Algorithm SHA384 */
+ CKM_HASH_SHA512 /**< Hash Algorithm SHA512 */
} ckm_hash_algo;
+/**
+ * @brief Enumeration for RSA padding algorithm.
+ */
typedef enum ckm_rsa_padding_algo_t {
- CKM_PKCS1_PADDING,
- CKM_X931_PADDING
+ CKM_PKCS1_PADDING =0, /**< PKCS#1 Padding */
+ CKM_X931_PADDING /**< X9.31 padding */
} ckm_rsa_padding_algo;
+
+
+
+/**
+ * @brief binary buffer used in key manager CAPI
+ * @details @a data is byte array containing some binary data
+ * @a size is the size of the binary data
+ */
typedef struct ckm_raw_buff_t{
unsigned char* data;
size_t size;
} ckm_raw_buffer;
+/**
+ * @brief a policy for storing key/certificate/binary data
+ * @details if @a password is not null, the data(or key, or certificate) is stored encrypted with this password inside key manager
+ * if @a extractable true, key may be extracted from storage
+ * if @a restricted true, only key owner can see data
+ */
typedef struct ckm_policy_t {
char* password; // byte array used to encrypt data inside CKM
ckm_bool extractable; // if true key may be extracted from storage
ckm_bool restricted; // if true only key owner may see data
} ckm_policy;
+/**
+ * @brief key structure used in key manager CAPI
+ * @details @a raw_key is byte array of key. raw_key may be encrypted with password.
+ * @a key_size is the byte size of raw_key
+ * @a key_type is the raw_key's type
+ * if @a password is byte array used to decrypt raw_key inside key manager.
+ */
typedef struct ckm_key_t {
unsigned char* raw_key;
size_t key_size;
ckm_key_type key_type;
- char* password; // byte array used to encrypt data inside CKM
+ char* password; // byte array used to decrypt data raw_key inside key manager
} ckm_key;
+/**
+ * @brief certificate structure used in key manager CAPI
+ * @details @a raw_cert is byte array of certificate.
+ * @a cert_size is the byte size of raw_cert
+ * @a data_format is the raw_cert's encoding format
+ */
typedef struct ckm_cert_t {
unsigned char* raw_cert;
size_t cert_size;
ckm_data_format data_format;
} ckm_cert;
+/**
+ * @brief linked list structure of alias
+ * @details @a alias is a name of key, certificate or data stored in key manager.
+ * @a next is a pointer pointing to the next ckm_alias_list
+ */
typedef struct ckm_alias_list_t {
char *alias;
struct ckm_alias_list_t *next;
} ckm_alias_list;
+/**
+ * @brief linked list structure of ckm_cert
+ * @details @a cert is a pointer of ckm_cert.
+ * @a next is a pointer pointing to the next ckm_cert_list
+ */
typedef struct ckm_cert_list_t {
ckm_cert *cert;
struct ckm_cert_list_t *next;
} ckm_cert_list;
+
+
+/**
+ * @brief Creates a new ckm_key handle and returns it.
+ *
+ * @remarks A newly created ckm_key should be destroyed by calling ckm_key_free() if it is no longer needed.
+ *
+ * @param[in] raw_key is byte array of key. raw_key may be encrypted with password
+ * @param[in] key_size is the byte size of raw_key
+ * @param[in] key_type is the raw_key's type
+ * @param[in] password is byte array used to decrypt raw_key inside key manager. If raw_key is not encrypted, password can be null.
+ * @return a newly created ckm_key handle
+ * @retval If successful, a newly created ckm_key handle will be returned
+ * @retval If out of memory, returns a null value.
+ * @see ckm_key_free()
+ * @see #ckm_key
+ */
ckm_key *ckm_key_new(unsigned char *raw_key, size_t key_size, ckm_key_type key_type, char *password);
+
+/**
+ * @brief Destroys the ckm_key handle and releases all its resources.
+ * @param[in] key a ckm_key handle to destroy
+ * @see ckm_key_new()
+ */
void ckm_key_free(ckm_key *key);
+
+
+
+/**
+ * @brief Creates a new ckm_raw_buffer handle and returns it.
+ *
+ * @remarks A newly created ckm_raw_buffer should be destroyed by calling ckm_buffer_free() if it is no longer needed.
+ *
+ * @param[in] data is byte array of buffer.
+ * @param[in] size is the byte size of buffer
+ * @return a newly created ckm_raw_buffer handle
+ * @retval If successful, a newly created ckm_raw_buffer handle will be returned
+ * @retval If out of memory, returns a null value.
+ * @see ckm_buffer_free()
+ * @see #ckm_raw_buffer
+ */
ckm_raw_buffer * ckm_buffer_new(unsigned char *data, size_t size);
+
+/**
+ * @brief Destroys the ckm_raw_buffer handle and releases all its resources.
+ * @param[in] buffer a ckm_raw_buffer handle to destroy
+ * @see ckm_buffer_new()
+ */
void ckm_buffer_free(ckm_raw_buffer *buffer);
+
+
+
+/**
+ * @brief Creates a new ckm_cert handle and returns it.
+ *
+ * @remarks A newly created ckm_cert should be destroyed by calling ckm_cert_free() if it is no longer needed.
+ *
+ * @param[in] raw_cert is byte array of certificate.
+ * @param[in] cert_size is the byte size of raw_cert.
+ * @param[in] data_format is the encoding format of raw_cert
+ * @return a newly created ckm_cert handle
+ * @retval If successful, a newly created ckm_cert handle will be returned
+ * @retval If out of memory, returns a null value.
+ * @see ckm_cert_free()
+ * @see ckm_load_cert_from_file()
+ * @see ckm_load_from_pkcs12_file
+ * @see #ckm_cert
+ */
ckm_cert *ckm_cert_new(unsigned char *raw_cert, size_t cert_size, ckm_data_format data_format);
+/**
+ * @brief Destroys the ckm_cert handle and releases all its resources.
+ * @param[in] buffer a ckm_cert handle to destroy
+ * @see ckm_cert_new()
+ * @see ckm_load_cert_from_file()
+ * @see ckm_load_from_pkcs12_file
+ */
void ckm_cert_free(ckm_cert *cert);
+/**
+ * @brief Create a new ckm_cert handle from a given file and returns it.
+ *
+ * @remarks A newly created ckm_cert should be destroyed by calling ckm_cert_free() if it is no longer needed.
+ *
+ * @param[in] file_path is a path of certificate file to be loaded. The only DER or PEM encoded certificate file is supported.
+ * @param[out] cert is the pointer of newly created ckm_cert handle
+ * @return #CKM_API_SUCCESS on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_OUT_OF_MEMORY not enough memory space
+ * @retval #CKM_API_ERROR_INVALID_FORMAT invalid certificate file format
+ * @retval #CKM_API_ERROR_FILE_ACCESS_DENIED provided file doesn't exists or cannot be accessed
+ * @see ckm_cert_free()
+ * @see ckm_cert_new()
+ * @see ckm_load_from_pkcs12_file()
+ * @see #ckm_cert
+ */
int ckm_load_cert_from_file(const char *file_path, ckm_cert **cert);
+
+/**
+ * @brief Create a new ckm_key(private key), ckm_cert(certificate), and ckm_cert_list(CA certificates) handle from a given PKCS#12 file and returns them.
+ *
+ * @remarks A newly created ckm_key, ckm_cert, and ckm_cert_list should be destroyed by calling ckm_key_free(), ckm_cert_free(), and ckm_cert_list_all_free() if they are no longer needed.
+ *
+ * @param[in] file_path is a path of PKCS12 file to be loaded.
+ * @param[in] passphrase is used to decrypt the PCKS12 file. If PKCS12 file is not encrypted, passphrase can be null.
+ * @param[out] private_key is the pointer of newly created ckm_key handle for a private key
+ * @param[out] cert is the pointer of newly created ckm_cert handle for a certificate. It is null if the PKCS12 file doesn't contain a certificate.
+ * @param[out] ca_cert_list is the pointer of newly created ckm_cert_list handle for CA certificates. It is null if the PKCS12 file doesn't contain CA certificates.
+ * @return #CKM_API_SUCCESS on success, otherwise a negative error value
+ * @retval #CKM_API_SUCCESS Successful
+ * @retval #CKM_API_ERROR_OUT_OF_MEMORY not enough memory space
+ * @retval #CKM_API_ERROR_INVALID_FORMAT invalid PKCS12 file format
+ * @retval #CKM_API_ERROR_FILE_ACCESS_DENIED provided file doesn't exists or cannot be accessed
+ * @see ckm_key_free()
+ * @see ckm_cert_free()
+ * @see ckm_cert_list_all_free()
+ * @see #ckm_key
+ * @see #ckm_cert
+ * @see #ckm_cert_list
+ */
int ckm_load_from_pkcs12_file(const char *file_path, const char *passphrase, ckm_key **private_key, ckm_cert **cert, ckm_cert_list **ca_cert_list);
+
+
+/**
+ * @brief Creates a new ckm_alias_list handle and returns it. The alias pointer in the returned ckm_alias_list handle points to the provided characters and the next is null.
+ *
+ * @remarks A newly created ckm_alias_list should be destroyed by calling ckm_alias_list_free() or ckm_alias_list_all_free() if it is no longer needed.
+ *
+ * @param[in] alias is the first item to be set in the newly created ckm_alias_list.
+ * @return a newly created ckm_alias_list handle
+ * @retval If successful, a newly created ckm_alias_list handle will be returned
+ * @retval If out of memory, returns a null value.
+ * @see ckm_alias_list_add()
+ * @see ckm_alias_list_free()
+ * @see ckm_alias_list_all_free()
+ * @see #ckm_alias_list
+ */
ckm_alias_list *ckm_alias_list_new(char *alias);
+
+/**
+ * @brief Creates a new ckm_alias_list handle, add it to a previous ckm_alias_list and returns it. The alias pointer in the returned ckm_alias_list handle points to the provided characters and the next is null.
+ *
+ * @param[in] previous the last ckm_alias_list handle to which a newly created ckm_alias_list is added
+ * @param[in] alias is an item to be set in the newly created ckm_alias_list.
+ * @return a newly added ckm_alias_list handle. It should be given as previous when ckm_cert_list_add() is called again.
+ * @retval If successful, a newly created ckm_alias_list handle will be returned
+ * @retval If out of memory, returns a null value.
+ * @see ckm_alias_list_add()
+ * @see ckm_alias_list_free()
+ * @see ckm_alias_list_all_free()
+ * @see #ckm_alias_list
+ */
ckm_alias_list *ckm_alias_list_add(ckm_alias_list *previous, char *alias);
+
+/**
+ * @brief Destroys the ckm_alias_list handle and releases resources of ckm_alias_list from the provided first handle cascadingly.
+ *
+ * @remarks It does not destroy an alias itself in ckm_alias_list.
+ *
+ * @param[in] buffer the first ckm_alias_list handle to destroy
+ * @see ckm_alias_list_new()
+ * @see ckm_alias_list_add()
+ * @see ckm_alias_list_all_free()
+ * @see #ckm_alias_list
+ */
void ckm_alias_list_free(ckm_alias_list *first);
+
+/**
+ * @brief Destroys the ckm_alias_list handle and releases all its resources from the provided first handle cascadingly.
+ *
+ * @remarks It also destroy an alias in ckm_alias_list.
+ *
+ * @param[in] buffer the first ckm_alias_list handle to destroy
+ * @see ckm_alias_list_new()
+ * @see ckm_alias_list_add()
+ * @see ckm_alias_list_free()
+ * @see #ckm_alias_list
+ */
void ckm_alias_list_all_free(ckm_alias_list *cert_list);
+
+
+
+/**
+ * @brief Creates a new ckm_cert_list handle and returns it. The cert pointer in the returned ckm_cert_list handle points to the provided ckm_cert and the next is null.
+ *
+ * @remarks A newly created ckm_cert_list should be destroyed by calling ckm_cert_list_free() or ckm_cert_list_all_free() if it is no longer needed.
+ *
+ * @param[in] cert is the first item to be set in the newly created ckm_cert_list.
+ * @return a newly created ckm_cert_list handle
+ * @retval If successful, a newly created ckm_cert_list handle will be returned
+ * @retval If out of memory, returns a null value.
+ * @see ckm_cert_list_add()
+ * @see ckm_cert_list_free()
+ * @see ckm_cert_list_all_free()
+ * @see #ckm_cert_list
+ */
ckm_cert_list *ckm_cert_list_new(ckm_cert *cert);
+
+/**
+ * @brief Creates a new ckm_cert_list handle, add it to a previous ckm_cert_list and returns it. The cert pointer in the returned ckm_alias_list handle points to the provided ckm_cert and the next is null.
+ *
+ * @param[in] previous the last ckm_cert_list handle to which a newly created ckm_cert_list is added
+ * @param[in] cert is an item to be set in the newly created ckm_cert_list.
+ * @return a newly added ckm_cert_list handle. It should be given as previous when ckm_cert_list_add() is called again.
+ * @retval If successful, a newly created ckm_cert_list handle will be returned
+ * @retval If out of memory, returns a null value.
+ * @see ckm_cert_list_add()
+ * @see ckm_cert_list_free()
+ * @see ckm_cert_list_all_free()
+ * @see #ckm_cert_list
+ */
ckm_cert_list *ckm_cert_list_add(ckm_cert_list *previous, ckm_cert *cert);
+
+/**
+ * @brief Destroys the ckm_cert_list handle and releases resources of ckm_cert_list from the provided first handle cascadingly.
+ *
+ * @remarks It does not destroy an ckm_cert itself in ckm_cert_list.
+ *
+ * @param[in] buffer the first ckm_cert_list handle to destroy
+ * @see ckm_cert_list_new()
+ * @see ckm_cert_list_add()
+ * @see ckm_cert_list_all_free()
+ * @see #ckm_cert_list
+ */
void ckm_cert_list_free(ckm_cert_list *first);
+
+/**
+ * @brief Destroys the ckm_cert_list handle and releases all its resources from the provided first handle cascadingly.
+ *
+ * @remarks It also destroy an ckm_cert in ckm_cert_list.
+ *
+ * @param[in] buffer the first ckm_cert_list handle to destroy
+ * @see ckm_cert_list_new()
+ * @see ckm_cert_list_add()
+ * @see ckm_cert_list_free()
+ * @see #ckm_cert_list
+ */
void ckm_cert_list_all_free(ckm_cert_list *cert_list);
+/**
+ * @}
+ */
+
#ifdef __cplusplus
}
#endif
-#endif /* CKMC_TYPE_H */
+#endif /* __TIZEN_CORE_CKMC_TYPE_H */
projects / platform / core / security / key-manager.git / commitdiff