X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=src%2Finclude%2Fckmc%2Fckmc-type.h;h=9a9669f6421de923102a6bbb3609d6ee5cf14592;hb=refs%2Fchanges%2F96%2F39296%2F10;hp=30f7c0fcb885b27ebc19918387172d9f960ed3e0;hpb=54711bf846e0350142f15024a8e8f7184fc70045;p=platform%2Fcore%2Fsecurity%2Fkey-manager.git diff --git a/src/include/ckmc/ckmc-type.h b/src/include/ckmc/ckmc-type.h index 30f7c0f..9a9669f 100644 --- a/src/include/ckmc/ckmc-type.h +++ b/src/include/ckmc/ckmc-type.h @@ -16,13 +16,14 @@ * * @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 #define __TIZEN_CORE_CKMC_TYPE_H #include +#include #include #define KEY_MANAGER_CAPI __attribute__((visibility("default"))) @@ -38,281 +39,488 @@ extern "C" { */ /** - * @brief Enumerates for key types of key manager. + * alias can be provided as an alias alone, or together with label - in this + * case, separator " " (space bar) is used to separate label and alias. + * @see key-manager_doc.h + */ +KEY_MANAGER_CAPI extern char const * const ckmc_label_name_separator; + +/** + * shared database label - user may be given permission to access shared + * database items. In such case, the alias should contain shared database + * label. + * @see ckmc_label_name_separator + * @see key-manager_doc.h + */ +KEY_MANAGER_CAPI extern char const * const ckmc_label_shared_owner; + +/** + * @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_DSA_PUBLIC, /**< DSA public key */ + CKMC_KEY_DSA_PRIVATE, /**< DSA private key */ + CKMC_KEY_AES, /**< AES 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_NONE = 0, /**< No Hash Algorithm */ + CKMC_HASH_SHA1, /**< Hash Algorithm SHA1 */ + CKMC_HASH_SHA256, /**< Hash Algorithm SHA256 */ + CKMC_HASH_SHA384, /**< Hash Algorithm SHA384 */ + CKMC_HASH_SHA512 /**< Hash Algorithm SHA512 */ } ckmc_hash_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_NONE_PADDING = 0, /**< No Padding */ + CKMC_PKCS1_PADDING, /**< PKCS#1 Padding */ + CKMC_X931_PADDING /**< X9.31 padding */ } ckmc_rsa_padding_algo_e; /** - * @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 + * @deprecated Deprecated since 2.4. [Use ckmc_permission_e() instead] + * @brief Enumeration for database access rights. + * @since_tizen 2.3 + */ +typedef enum __ckmc_access_right{ + CKMC_AR_READ = 0, /**< access right for read*/ + CKMC_AR_READ_REMOVE /**< access right for read and remove*/ +} ckmc_access_right_e; + +/** + * @brief Enumeration for permissions to access/modify alias. + * @since_tizen 2.4 + */ +typedef enum __ckmc_permission{ + CKMC_PERMISSION_NONE = 0x00, /**< clear permissions */ + CKMC_PERMISSION_READ = 0x01, /**< read allowed */ + CKMC_PERMISSION_REMOVE = 0x02 /**< remove allowed */ +} ckmc_permission_e; + +/** + * @brief the structure for binary buffer used in key manager CAPI. * @since_tizen 2.3 */ typedef struct __ckmc_raw_buff { - unsigned char* data; - size_t size; + 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 - * @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 + * @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 - 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 */ } ckmc_policy_s; /** - * @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. + * @brief The structure for key used in key manager CAPI. * @since_tizen 2.3 */ typedef struct __ckmc_key { - unsigned char* raw_key; - size_t key_size; - ckmc_key_type_e key_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 - * @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 + * @brief The structure for certificate used in key manager CAPI. * @since_tizen 2.3 */ typedef struct __ckmc_cert { - unsigned char* raw_cert; - size_t cert_size; - ckmc_data_format_e data_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 - * @details @a alias is a name of key, certificate or data stored in key manager. - * @a next is a pointer pointing to the next ckmc_alias_list_s + * @brief The structure for linked list of alias. * @since_tizen 2.3 */ typedef struct __ckmc_alias_list { - char *alias; - struct __ckmc_alias_list *next; + 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 - * @details @a cert is a pointer of ckmc_cert_s. - * @a next is a pointer pointing to the next ckmc_cert_list_s + * @brief The structure for linked list of ckmc_cert_s * @since_tizen 2.3 */ typedef struct __ckmc_cert_list { - ckmc_cert_s *cert; - struct __ckmc_cert_list *next; + ckmc_cert_s *cert; /**< The pointer of ckmc_cert_s */ + struct __ckmc_cert_list *next; /**< The pointer pointing to the next ckmc_cert_list_s */ } ckmc_cert_list_s; /** + * @brief Enumeration for OCSP status. + * @since_tizen 2.4 + */ +typedef enum __ckmc_ocsp_status { + CKMC_OCSP_STATUS_GOOD = 0, /**< OCSP status is good */ + CKMC_OCSP_STATUS_REVOKED, /**< certificate is revoked */ + CKMC_OCSP_STATUS_UNKNOWN, /**< unknown error */ + CKMC_OCSP_ERROR_UNSUPPORTED, /**< certificate does not provide OCSP extension */ + CKMC_OCSP_ERROR_INVALID_URL, /**< invalid URL in certificate OCSP extension */ + CKMC_OCSP_ERROR_INVALID_RESPONSE, /**< invalid response from OCSP server */ + CKMC_OCSP_ERROR_REMOTE, /**< OCSP remote server error */ + CKMC_OCSP_ERROR_NET, /**< network connection error */ + CKMC_OCSP_ERROR_INTERNAL /**< OpenSSL API error */ +} ckmc_ocsp_status_e; + +/** + * @brief The structure for PKCS12 used in key manager CAPI. + * @since_tizen 2.4 + */ +typedef struct __ckmc_pkcs12 { + ckmc_key_s *priv_key; /**< private key, may be null */ + ckmc_cert_s *cert; /**< certificate, may be null */ + ckmc_cert_list_s *ca_chain; /**< chain certificates list, may be null */ +} ckmc_pkcs12_s; + +/** + * @brief Enumeration for crypto algorithm parameters. + * @since_tizen 3.0 + */ +typedef enum __ckmc_param_name { + CKMC_PARAM_ALGO_TYPE = 1, + + // encryption & decryption + CKMC_PARAM_ED_IV = 101, /**< 16B buffer (up to 2^64-1 bytes long in case of AES GCM) */ + CKMC_PARAM_ED_CTR_LEN, /**< integer */ + CKMC_PARAM_ED_AAD, /**< buffer */ + CKMC_PARAM_ED_TAG_LEN, /**< integer */ + CKMC_PARAM_ED_LABEL, /**< buffer */ + + // key generation + CKMC_PARAM_GEN_KEY_LEN = 201, /**< integer */ + CKMC_PARAM_GEN_EC, /**< integer - elliptic curve (ckmc_ec_type_e) */ + + // sign & verify + CKMC_PARAM_SV_HASH_ALGO = 301, /**< integer - hash algorithm (ckmc_hash_algo_e) */ + CKMC_PARAM_SV_RSA_PADDING, /**< integer - RSA padding (ckmc_rsa_padding_algo_e) */ +}ckmc_param_name_e; + +/** + * @brief Structure for algorithm parameter list. + * @since_tizen 3.0 + */ +struct ckmc_param_list_s; + +/** + * @brief Enumeration for crypto algorithm types. + * @since_tizen 3.0 + */ +typedef enum __ckmc_algo_type { + CKMC_ALGO_AES_CTR = 1, /**< AES-CTR algorithm + Supported parameters: + - CKMC_PARAM_ALGO_TYPE, + - CKMC_PARAM_ED_IV + - CKMC_PARAM_ED_CTR_LEN (128 only) */ + + CKMC_ALGO_AES_CBC, /**< AES-CBC algorithm + Supported parameters: + - CKMC_PARAM_ALGO_TYPE, + - CKMC_PARAM_ED_IV */ + + CKMC_ALGO_AES_GCM, /**< AES-GCM algorithm + Supported parameters: + - CKMC_PARAM_ALGO_TYPE, + - CKMC_PARAM_ED_IV + - CKMC_PARAM_ED_TAG_LEN + - CKMC_PARAM_ED_AAD */ + + CKMC_ALGO_AES_CFB, /**< AES-CFB algorithm + Supported parameters: + - CKMC_PARAM_ALGO_TYPE, + - CKMC_PARAM_ED_IV */ + + CKMC_ALGO_RSA_OAEP, /**< RSA-OAEP algorithm + Supported parameters: + - CKMC_PARAM_ALGO_TYPE, + - CKMC_PARAM_ED_LABEL */ + + CKMC_ALGO_RSA_SV, /**< RSA algorithm used for signing/verification + Supported parameters: + - CKMC_PARAM_ALGO_TYPE, + - CKMC_PARAM_SV_HASH_ALGO + - CKMC_PARAM_SV_RSA_PADDING */ + + CKMC_ALGO_DSA_SV, /**< DSA algorithm used for signing/verification + Supported parameters: + - CKMC_PARAM_ALGO_TYPE, + - CKMC_PARAM_SV_HASH_ALGO */ + + CKMC_ALGO_ECDSA_SV, /**< ECDA algorithm used for signing/verification + Supported parameters: + - CKMC_PARAM_ALGO_TYPE, + - CKMC_PARAM_SV_HASH_ALGO */ + + CKMC_ALGO_RSA_GEN, /**< RSA algorithm used for key generation + Supported parameters: + - CKMC_PARAM_ALGO_TYPE, + - CKMC_PARAM_GEN_KEY_LEN */ + + CKMC_ALGO_DSA_GEN, /**< DSA algorithm used for key generation + Supported parameters: + - CKMC_PARAM_ALGO_TYPE, + - CKMC_PARAM_GEN_KEY_LEN */ + + CKMC_ALGO_ECDSA_GEN, /**< ECDA algorithm used for key generation + Supported parameters: + - CKMC_PARAM_ALGO_TYPE, + - CKMC_PARAM_GEN_EC */ +} ckmc_algo_type_e; + +/** * @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. - * - * @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 + * + * @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 + * * @see ckmc_key_free() * @see #ckmc_key_s */ -int ckmc_key_new(unsigned char *raw_key, size_t key_size, - ckmc_key_type_e key_type, char *password, ckmc_key_s **ppkey); +int ckmc_key_new(unsigned char *raw_key, + size_t key_size, + ckmc_key_type_e key_type, + char *password, ckmc_key_s **ppkey); /** - * @brief Destroys the 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 - * @see ckmc_key_new() + * @param[in] key The @a ckmc_key_s handle to destroy + * */ 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 - * @see ckmc_buffer_new() + * @param[in] buffer The @a ckmc_raw_buffer_s handle to destroy + * */ 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. - * - * @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 + * + * @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 + * * @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); +int ckmc_cert_new(unsigned char *raw_cert, + size_t cert_size, + ckmc_data_format_e data_format, + ckmc_cert_s **ppcert); /** - * @brief Destroys the 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 - * @see ckmc_cert_new() + * @param[in] cert The @a ckmc_cert_s handle to destroy + * * @see ckmc_load_cert_from_file() * @see ckmc_load_from_pkcs12_file */ void ckmc_cert_free(ckmc_cert_s *cert); /** - * @brief Creates a new 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. - * - * @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 + * + * @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 + * * @see ckmc_cert_free() - * @see ckmc_cert_new() - * @see ckmc_load_from_pkcs12_file() * @see #ckmc_cert_s */ 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. + * @internal + * @brief Creates a new @a ckmc_pkcs12_s handle and returns it. + * + * @since_tizen 2.4 + * + * @remarks You must destroy the newly created @a ckmc_pkcs12_s by calling ckmc_pkcs12_free() if it + * is no longer needed. + * @remarks On success, private_key, cert && ca_cert_list ownership is transferred into newly + * returned ckmc_pkcs12_s. + * + * @param[in] private_key @a ckmc_key_s handle to the private key (optional) + * @param[in] cert @a ckmc_cert_s handle to the certificate (optional) + * @param[in] ca_cert_list @a ckmc_cert_list_s list of chain certificate handles (optional) + * @param[out] pkcs12_bundle The pointer to a newly created @a ckmc_pkcs12_s handle + * + * @return @c 0 on success, + * otherwise a negative error value + * + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid or private_key, cert and + * ca_cert_list all are null. + * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory + * + * @see ckmc_pkcs12_free() + * @see ckmc_load_from_pkcs12_file() + * @see ckmc_pkcs12_load() + * @see #ckmc_key_s + * @see #ckmc_cert_s + * @see #ckmc_cert_list_s + * @see #ckmc_pkcs12_s + */ +int ckmc_pkcs12_new(ckmc_key_s *private_key, + ckmc_cert_s *cert, + ckmc_cert_list_s *ca_cert_list, + ckmc_pkcs12_s **pkcs12_bundle); + +/** + * @deprecated Deprecated since 2.4. [Use ckmc_pkcs12_load() instead] + * @brief Creates a new @a ckmc_key_s(private key), @a ckmc_cert_s(certificate), and + * @a ckmc_cert_list_s(CA certificates) handle from a given PKCS#12 file and returns them. * * @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_pkcs12_new() + * @see ckmc_pkcs12_load() * @see ckmc_key_free() * @see ckmc_cert_free() * @see ckmc_cert_list_all_free() @@ -320,27 +528,74 @@ int ckmc_load_cert_from_file(const char *file_path, ckmc_cert_s **cert); * @see #ckmc_cert_s * @see #ckmc_cert_list_s */ -int ckmc_load_from_pkcs12_file(const char *file_path, const char *passphrase, - ckmc_key_s **private_key, ckmc_cert_s **cert, - ckmc_cert_list_s **ca_cert_list); +int ckmc_load_from_pkcs12_file(const char *file_path, + const char *passphrase, + ckmc_key_s **private_key, ckmc_cert_s **cert, + ckmc_cert_list_s **ca_cert_list); + +/** + * @brief Creates a new @a ckmc_pkcs12_s handle from a given PKCS#12 file and returns it. + * + * @since_tizen 2.4 + * + * @remarks You must destroy the newly created @a ckmc_pkcs12_s by calling ckmc_pkcs12_free() if + * they are no longer needed. + * + * @param[in] file_path The path of PKCS12 file to be loaded + * @param[in] passphrase The passphrase used to decrypt the PCKS12 file \n + * If PKCS12 file is not encrypted, passphrase can be null. + * @param[out] ca_cert_list The pointer of newly created @a ckmc_cert_list_s handle for CA + * certificates \n + * It is null if the PKCS12 file does not contain CA certificates. + * + * @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_pkcs12_free() + * @see #ckmc_pkcs12_s + */ +int ckmc_pkcs12_load(const char *file_path, + const char *passphrase, + ckmc_pkcs12_s **pkcs12_bundle); + +/** + * @brief Destroys the @a ckmc_pkcs12_s handle and releases all its resources. + * + * @since_tizen 2.4 + * + * @param[in] pkcs12 The @a ckmc_pkcs12_s handle to destroy + * + * @see ckmc_pkcs12_new() + * @see ckmc_pkcs12_load() + */ +void ckmc_pkcs12_free(ckmc_pkcs12_s *pkcs12); /** * @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. - * - * @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() + * + * @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 + * * @see ckmc_alias_list_all_free() * @see #ckmc_alias_list_s */ @@ -348,79 +603,80 @@ int ckmc_alias_list_new(char *alias, ckmc_alias_list_s **ppalias_list); /** * @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 - * @see ckmc_alias_list_add() - * @see ckmc_alias_list_free() + * + * @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_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() * @see #ckmc_alias_list_s */ 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() * @see #ckmc_alias_list_s */ void ckmc_alias_list_all_free(ckmc_alias_list_s *first); -////////////////////////////////////////////////////////////////////////////////////// <- start /** * @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. - * - * @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() + * + * @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 + * * @see ckmc_cert_list_all_free() * @see #ckmc_cert_list_s */ @@ -428,61 +684,190 @@ int ckmc_cert_list_new(ckmc_cert_s *cert, ckmc_cert_list_s **ppalias_list); /** * @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. - * - * @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 - * @see ckmc_cert_list_add() - * @see ckmc_cert_list_free() + * @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_tizen 2.3 + * + * @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_all_free() * @see #ckmc_cert_list_s */ -int ckmc_cert_list_add(ckmc_cert_list_s *previous, - ckmc_cert_s *cert, ckmc_cert_list_s **pplast); +int ckmc_cert_list_add(ckmc_cert_list_s *previous, ckmc_cert_s *cert, ckmc_cert_list_s **pplast); /** * @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. + * @since_tizen 2.3 + * + * @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 * - * @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_all_free() * @see #ckmc_cert_list_s */ 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_tizen 2.3 * - * @since 2.3 - * @privlevel public - * @privilege %http://tizen.org/privilege/keymanager + * @remarks It also destroys @a ckmc_cert_s in ckmc_cert_list_s. * - * @remarks It also destroy an 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() * @see #ckmc_cert_list_s */ void ckmc_cert_list_all_free(ckmc_cert_list_s *first); /** + * @brief Creates new parameter list + * + * @since_tizen 3.0 + * + * @remarks Caller is responsible for freeing it with ckmc_param_list_free + * + * @param[in] ppparam_list Double pointer to the list variable to which the newly created list will + * be assigned. Last element of the list has param = NULL; + * + * @return @c 0 on success, otherwise a negative error value + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * + * @see ckmc_param_list_add_integer + * @see ckmc_param_list_add_buffer + * @see ckmc_param_list_free + * @see ckmc_generate_params + * @see #ckmc_param_list_s + * @see #ckmc_param_name_e + */ +int ckmc_param_list_new(ckmc_param_list_s **ppparams); + +/** + * @brief Adds integer parameter to the list + * + * @since_tizen 3.0 + * + * @remarks Caller is responsible for ckmc_param_list_s creation. + * @remarks Last element of the list has param = NULL; + * + * @param[in] previous Any element of the param list. + * @param[in] name Name of parameter to add. Each parameter name has an associated value type: + * integer or buffer. Passing a buffer parameter name will result in an error + * @param[in] value Value of the parameter in form of a integer. + * + * @return @c 0 on success, otherwise a negative error value + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * + * @see ckmc_param_list_new + * @see ckmc_param_list_add_buffer + * @see ckmc_param_list_free + * @see ckmc_generate_params + * @see #ckmc_param_list_s + * @see #ckmc_param_name_e + */ +int ckmc_param_list_add_integer(ckmc_param_list_s *params, + ckmc_param_name_e name, + uint64_t value); + +/** + * @brief Adds buffer parameter to the list + * + * @since_tizen 3.0 + * + * @remarks Caller is responsible for ckmc_param_list_s creation. + * @remarks Last element of the list has param = NULL; + * + * @param[in] previous Any element of the param list. + * @param[in] name Name of parameter to add. Each parameter name has an associated value type: + * integer or buffer. Passing an integer parameter name will result in an error + * @param[in] buffer Value of the parameter in form of a buffer. Caller is responsible for + * creating and freeing the buffer. + * + * @return @c 0 on success, otherwise a negative error value + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * + * @see ckmc_param_list_new + * @see ckmc_param_list_add_integer + * @see ckmc_param_list_free + * @see ckmc_generate_params + * @see #ckmc_param_list_s + * @see #ckmc_param_name_e + */ +int ckmc_param_list_add_buffer(ckmc_param_list_s *params, + ckmc_param_name_e name, + const ckmc_raw_buffer_s *buffer); + +/** + * @brief Frees previously allocated list of algorithm params + * + * @since_tizen 3.0 + * + * @param[in] first First element of the list to be freed. + * + * @see ckmc_param_list_new + * @see ckmc_param_list_add_integer + * @see ckmc_param_list_add_buffer + * @see ckmc_generate_params + * @see #ckmc_param_list_s + * @see #ckmc_param_name_e + */ +void ckmc_param_list_free(ckmc_param_list_s *params); + +/** + * @brief Generates algorithm parameters for a given algorithm type and adds them to the list. + * + * @since_tizen 3.0 + * + * @remarks Caller is responsible for ckmc_param_list_s creation and destruction. + * @remarks Algorithm parameters used for encryption could be then used for decryption but this + * function should not be used for generating decryption parameters only. + * @remarks Algorithm parameters are set to default values. Optional fields are left empty. + * Initialization vectors are randomly generated. Param list passed as ckmc_param_list_s + * will be extended with new params. Caller is responsible for freeing the list + * with ckmc_param_list_free. + * @remarks If the function returns error provided param list may contain some of default parameters + * + * @param[in] type Type of the algorithm + * @param[out] params List of params to be filled. List should be empty. Otherwise an error will + * be returned. + * + * @return @c 0 on success, otherwise a negative error value + * + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid + * + * @see ckmc_param_list_new + * @see ckmc_param_list_add_integer + * @see ckmc_param_list_add_buffer + * @see ckmc_param_list_free + * @see #ckmc_param_list_s + * @see #ckmc_param_name_e + */ +int ckmc_generate_params(ckmc_algo_type_e type, ckmc_param_list_s *params); + +/** * @} */