src/include/ckmc/ckmc-type.h

   1 /*
   2  * Copyright (c) 2000 - 2019 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License
  15  *
  16  *
  17  * @file ckmc-type.h
  18  * @version 1.0
  19  * @brief Definitions of struct for the Key Manager's CAPI and their utility functions.
  20  */
  21
  22
  23 #ifndef __TIZEN_CORE_CKMC_TYPE_H
  24 #define __TIZEN_CORE_CKMC_TYPE_H
  25
  26
  27 #include <stddef.h>
  28 #include <stdint.h>
  29 #include <ckmc/ckmc-error.h>
  30
  31
  32 #define KEY_MANAGER_CAPI __attribute__((visibility("default")))
  33
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39
  40 /**
  41  * @addtogroup CAPI_KEY_MANAGER_TYPES_MODULE
  42  * @{
  43  */
  44
  45
  46 /*
  47  * Note: on tizen 3.0 owner id is equal to pkgId.
  48  *       Preinstalled system(uid < 5000) and user (uid >= 5000) applications
  49  *       does not have any pkgId. That's why ckm uses special "virtual"
  50  *       pkgid for them. The virtual strings are defined under:
  51  *                       ckmc_owner_id_system
  52  */
  53
  54
  55 /**
  56  * @deprecated Deprecated since 3.0. [Use ckmc_owner_id_separator instead]
  57  * @brief Separator between alias and label.
  58  * @since_tizen 2.3
  59  * @remarks Alias can be provided as an alias alone, or together with label - in this
  60  *          case, separator " " (space bar) is used to separate label and alias.
  61  * @see #ckmc_owner_id_separator
  62  */
  63 KEY_MANAGER_CAPI extern char const *const ckmc_label_name_separator;
  64
  65
  66 /**
  67  * @brief Separator between alias and owner id.
  68  * @since_tizen 3.0
  69  * @remarks Alias can be provided as an alias alone, or together with owner id.
  70  *          In this case, separator " " (space bar) is used to separate id and alias.
  71  * @see ckmc_alias_new()
  72  */
  73 KEY_MANAGER_CAPI extern char const *const ckmc_owner_id_separator;
  74
  75
  76 /**
  77  * @brief The owner of system database.
  78  * @since_tizen 3.0
  79  * @remarks #ckmc_owner_id_system contains id connected with all system applications that run with uid less than 5000.
  80  *          Client should use #ckmc_owner_id_system to access data owned by system application and stored in system database.
  81  *          Client must have permission to access proper row.
  82  * @see ckmc_alias_new()
  83  */
  84 KEY_MANAGER_CAPI extern char const *const ckmc_owner_id_system;
  85
  86
  87 /**
  88  * @brief Enumeration for key types of key manager.
  89  * @since_tizen 2.3
  90  */
  91 typedef enum __ckmc_key_type {
  92         CKMC_KEY_NONE = 0, /**< Key type not specified */
  93         CKMC_KEY_RSA_PUBLIC, /**< RSA public key */
  94         CKMC_KEY_RSA_PRIVATE, /**< RSA private key */
  95         CKMC_KEY_ECDSA_PUBLIC, /**< ECDSA public key */
  96         CKMC_KEY_ECDSA_PRIVATE, /**< ECDSA private key */
  97         CKMC_KEY_DSA_PUBLIC, /**< DSA public key */
  98         CKMC_KEY_DSA_PRIVATE, /**< DSA private key */
  99         CKMC_KEY_AES, /**< AES key */
 100 } ckmc_key_type_e;
 101
 102
 103 /**
 104  * @brief Enumeration for data format.
 105  * @since_tizen 2.3
 106  */
 107 typedef enum __ckmc_data_format {
 108         CKMC_FORM_DER_BASE64 = 0, /**< DER format base64 encoded data */
 109         CKMC_FORM_DER, /**< DER encoded data */
 110         CKMC_FORM_PEM /**< PEM encoded data. It consists of the DER format base64 encoded
 111                   with additional header and footer lines. */
 112 } ckmc_data_format_e;
 113
 114
 115 /**
 116  * @brief Enumeration for elliptic curve.
 117  * @since_tizen 2.3
 118  */
 119 typedef enum __ckmc_ec_type {
 120         CKMC_EC_PRIME192V1 = 0, /**< Elliptic curve domain "secp192r1" listed in "SEC 2" recommended
 121                             elliptic curve domain */
 122         CKMC_EC_PRIME256V1, /**< "SEC 2" recommended elliptic curve domain - secp256r1 */
 123         CKMC_EC_SECP384R1 /**< NIST curve P-384(covers "secp384r1", the elliptic curve domain
 124                       listed in See SEC 2 */
 125 } ckmc_ec_type_e;
 126
 127
 128 /**
 129  * @brief Enumeration for hash algorithm.
 130  * @since_tizen 2.3
 131  */
 132 typedef enum __ckmc_hash_algo {
 133         CKMC_HASH_NONE = 0, /**< No Hash Algorithm */
 134         CKMC_HASH_SHA1, /**< Hash Algorithm SHA1 */
 135         CKMC_HASH_SHA256, /**< Hash Algorithm SHA256 */
 136         CKMC_HASH_SHA384, /**< Hash Algorithm SHA384 */
 137         CKMC_HASH_SHA512 /**< Hash Algorithm SHA512 */
 138 } ckmc_hash_algo_e;
 139
 140
 141 /**
 142  * @brief Enumeration for RSA padding algorithm.
 143  * @since_tizen 2.3
 144  */
 145 typedef enum __ckmc_rsa_padding_algo {
 146         CKMC_NONE_PADDING = 0, /**< No Padding */
 147         CKMC_PKCS1_PADDING, /**< PKCS#1 Padding */
 148         CKMC_X931_PADDING /**< X9.31 padding */
 149 } ckmc_rsa_padding_algo_e;
 150
 151
 152 /**
 153  * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif [Use ckmc_permission_e() instead]
 154  * @brief Enumeration for database access rights.
 155  * @since_tizen 2.3
 156  */
 157 typedef enum __ckmc_access_right {
 158         CKMC_AR_READ = 0, /**< Access right for read*/
 159         CKMC_AR_READ_REMOVE /**< Access right for read and remove*/
 160 } ckmc_access_right_e;
 161
 162
 163 /**
 164  * @brief Enumeration for permissions to access/modify alias.
 165  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 166  */
 167 typedef enum __ckmc_permission {
 168         CKMC_PERMISSION_NONE = 0x00, /**< Clear permissions */
 169         CKMC_PERMISSION_READ = 0x01, /**< Read allowed */
 170         CKMC_PERMISSION_REMOVE = 0x02 /**< Remove allowed */
 171 } ckmc_permission_e;
 172
 173
 174 /**
 175  * @brief The structure for binary buffer used in key manager CAPI.
 176  * @since_tizen 2.3
 177  */
 178 typedef struct __ckmc_raw_buff {
 179         unsigned char *data; /**< Byte array containing binary data */
 180         size_t size; /**< The size of the binary data */
 181 } ckmc_raw_buffer_s;
 182
 183
 184 /**
 185  * @brief The structure for a policy for storing key/certificate/binary data.
 186  * @since_tizen 2.3
 187  */
 188 typedef struct __ckmc_policy {
 189         char *password; /**< Byte array used to encrypt data inside CKM. If it is not null, the data
 190                     (or key, or certificate) is stored encrypted with this password inside
 191                     key manager */
 192         bool extractable; /**< If true key may be extracted from storage */
 193 } ckmc_policy_s;
 194
 195
 196 /**
 197  * @brief The structure for key used in key manager CAPI.
 198  * @since_tizen 2.3
 199  */
 200 typedef struct __ckmc_key {
 201         unsigned char
 202         *raw_key; /**< Byte array of key. raw_key may be encrypted with password */
 203         size_t key_size; /**< The byte size of raw_key */
 204         ckmc_key_type_e key_type; /**< The raw_key's type */
 205         char *password; /**< Byte array used to decrypt data raw_key inside key manager. */
 206 } ckmc_key_s;
 207
 208
 209 /**
 210  * @brief The structure for certificate used in key manager CAPI.
 211  * @since_tizen 2.3
 212  */
 213 typedef struct __ckmc_cert {
 214         unsigned char *raw_cert; /**< Byte array of certificate */
 215         size_t cert_size; /**< Byte size of raw_cert */
 216         ckmc_data_format_e data_format; /**< Raw_cert's encoding format */
 217 } ckmc_cert_s;
 218
 219
 220 /**
 221  * @brief The structure for linked list of alias.
 222  * @since_tizen 2.3
 223  */
 224 typedef struct __ckmc_alias_list {
 225         char *alias; /**< The name of key, certificate or data stored in key manager */
 226         struct __ckmc_alias_list
 227                 *next; /**< The pointer pointing to the next ckmc_alias_list_s */
 228 } ckmc_alias_list_s;
 229
 230 struct ckmc_alias_info_s;
 231
 232 /**
 233  * @brief The structure of alias and additional information about it.
 234  * @since_tizen 5.0
 235  */
 236 typedef struct ckmc_alias_info_s ckmc_alias_info_s;
 237
 238 /**
 239  * @brief The structure for linked list of alias with additional information.
 240  * @since_tizen 5.0
 241  */
 242 typedef struct __ckmc_alias_info_list_s {
 243         struct ckmc_alias_info_s* info; /**< The pointer pointing to the alias structure
 244                                           with additional information */
 245         struct __ckmc_alias_info_list_s*
 246                 next; /**< The pointer pointing to the next ckmc_alias_info_list_s */
 247 } ckmc_alias_info_list_s;
 248
 249
 250 /**
 251  * @brief The structure for linked list of ckmc_cert_s
 252  * @since_tizen 2.3
 253  */
 254 typedef struct __ckmc_cert_list {
 255         ckmc_cert_s *cert; /**< The pointer of ckmc_cert_s */
 256         struct __ckmc_cert_list
 257                 *next; /**< The pointer pointing to the next ckmc_cert_list_s */
 258 } ckmc_cert_list_s;
 259
 260
 261 /**
 262  * @brief Enumeration for OCSP status.
 263  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 264  */
 265 typedef enum __ckmc_ocsp_status {
 266         CKMC_OCSP_STATUS_GOOD = 0, /**< OCSP status is good */
 267         CKMC_OCSP_STATUS_REVOKED, /**< The certificate is revoked */
 268         CKMC_OCSP_STATUS_UNKNOWN, /**< Unknown error */
 269         CKMC_OCSP_ERROR_UNSUPPORTED, /**< The certificate does not provide OCSP extension */
 270         CKMC_OCSP_ERROR_INVALID_URL, /**< The invalid URL in certificate OCSP extension */
 271         CKMC_OCSP_ERROR_INVALID_RESPONSE, /**< The invalid response from OCSP server */
 272         CKMC_OCSP_ERROR_REMOTE, /**< OCSP remote server error */
 273         CKMC_OCSP_ERROR_NET, /**< Network connection error */
 274         CKMC_OCSP_ERROR_INTERNAL /**< OpenSSL API error */
 275 } ckmc_ocsp_status_e;
 276
 277
 278 /**
 279  * @brief The structure for PKCS12 used in key manager CAPI.
 280  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 281  */
 282 typedef struct __ckmc_pkcs12 {
 283         ckmc_key_s *priv_key; /**< The private key, may be null */
 284         ckmc_cert_s *cert; /**< The certificate, may be null */
 285         ckmc_cert_list_s *ca_chain; /**< The chain certificate list, may be null */
 286 } ckmc_pkcs12_s;
 287
 288
 289 /**
 290  * @brief Enumeration for crypto algorithm parameters.
 291  * @since_tizen 3.0
 292  * @see #ckmc_algo_type_e
 293  */
 294 typedef enum __ckmc_param_name {
 295         CKMC_PARAM_ALGO_TYPE = 1,
 296
 297         CKMC_PARAM_ED_IV = 101, /**< 16B buffer (up to 2^64-1 bytes long in case of AES GCM) */
 298         CKMC_PARAM_ED_CTR_LEN, /**< integer - ctr length in bits*/
 299         CKMC_PARAM_ED_AAD, /**< buffer */
 300         CKMC_PARAM_ED_TAG_LEN, /**< integer - tag length in bits */
 301         CKMC_PARAM_ED_LABEL /**< buffer */
 302 } ckmc_param_name_e;
 303
 304
 305 /**
 306  * @brief Algorithm parameter list handle.
 307  * @since_tizen 3.0
 308  * @remarks Each parameter list must have at least one CKMC_PARAM_ALGO_TYPE parameter that identifies the algorithm.
 309  *          See #ckmc_algo_type_e for available algorithms and additional parameters they support.
 310  * @see ckmc_generate_new_params()
 311  * @see ckmc_param_list_new()
 312  * @see ckmc_param_list_set_integer()
 313  * @see ckmc_param_list_set_buffer()
 314  * @see ckmc_param_list_get_integer()
 315  * @see ckmc_param_list_get_buffer()
 316  * @see ckmc_param_list_free()
 317  * @see #ckmc_algo_type_e
 318  * @see #ckmc_param_name_e
 319  */
 320 typedef struct __ckmc_param_list *ckmc_param_list_h;
 321
 322
 323 /**
 324  * @brief Enumeration for crypto algorithm types.
 325  * @since_tizen 3.0
 326  * @see #ckmc_param_name_e
 327  */
 328 typedef enum __ckmc_algo_type {
 329         CKMC_ALGO_AES_CTR = 1, /**< AES-CTR algorithm
 330                            Supported parameters:
 331                            - CKMC_PARAM_ALGO_TYPE = CKMC_ALGO_AES_CTR(mandatory),
 332                            - CKMC_PARAM_ED_IV = 16-byte initialization vector(mandatory)
 333                            - CKMC_PARAM_ED_CTR_LEN = length of counter block in bits
 334                            (optional, only 128b is supported at the moment) */
 335
 336         CKMC_ALGO_AES_CBC, /**< AES-CBC algorithm
 337                        Supported parameters:
 338                        - CKMC_PARAM_ALGO_TYPE = CKMC_ALGO_AES_CBC(mandatory),
 339                        - CKMC_PARAM_ED_IV = 16-byte initialization vector(mandatory) */
 340
 341         CKMC_ALGO_AES_GCM, /**< AES-GCM algorithm
 342                        Supported parameters:
 343                        - CKMC_PARAM_ALGO_TYPE = CKMC_ALGO_AES_GCM(mandatory),
 344                        - CKMC_PARAM_ED_IV = initialization vector(mandatory)
 345                        - CKMC_PARAM_ED_TAG_LEN = GCM tag length in bits. One of
 346                        {32, 64, 96, 104, 112, 120, 128} (optional, if not present, the
 347                        length 128 is used; since Tizen 5.0, if TrustZone backend is used,
 348                        32 and 64 lengths are not supported)
 349                        - CKMC_PARAM_ED_AAD = additional authentication data(optional) */
 350
 351         CKMC_ALGO_AES_CFB, /**< AES-CFB algorithm
 352                        Supported parameters:
 353                        - CKMC_PARAM_ALGO_TYPE = CKMC_ALGO_AES_CFB(mandatory),
 354                        - CKMC_PARAM_ED_IV = 16-byte initialization vector(mandatory) */
 355
 356         CKMC_ALGO_RSA_OAEP /**< RSA-OAEP algorithm
 357                        Supported parameters:
 358                        - CKMC_PARAM_ALGO_TYPE = CKMC_ALGO_RSA_OAEP(required),
 359                        - CKMC_PARAM_ED_LABEL = label to be associated with the message
 360                        (optional, not supported at the moment) */
 361 } ckmc_algo_type_e;
 362
 363 /**
 364  * @brief Gets the alias from #ckmc_alias_info_s structure.
 365  * @since_tizen 5.0
 366  * @remarks The @a alias should not be released.
 367  *          The @a alias can be used until #ckmc_alias_info_s is released.
 368  * @param[in] info The pointer to the #ckmc_alias_info_s structure
 369  * @param[out] alias The pointer to the alias
 370  * @return #CKMC_ERROR_NONE on success,
 371  *         othervise a negative error value
 372  * @retval #CKMC_ERROR_NONE Successful
 373  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 374  * @see #ckmc_alias_info_s
 375  */
 376 int ckmc_alias_info_get_alias(const ckmc_alias_info_s* info, char** alias);
 377
 378 /**
 379  * @brief Gets the password protection status from #ckmc_alias_info_s structure.
 380  * @since_tizen 5.0
 381  * @param[in] info The pointer to the #ckmc_alias_info_s structure
 382  * @param[out] is_password_protected The pointer to the password protection flag
 383  * @return #CKMC_ERROR_NONE on success,
 384  *         othervise a negative error value
 385  * @retval #CKMC_ERROR_NONE Successful
 386  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 387  * @see #ckmc_alias_info_s
 388  */
 389 int ckmc_alias_info_is_password_protected(const ckmc_alias_info_s* info, bool* is_password_protected);
 390
 391 /**
 392  * @brief Destroys the #ckmc_alias_info_list_s handle and releases resources of #ckmc_alias_info_list_s from the provided first handle cascadingly.
 393  * @since_tizen 5.0
 394  * @param[in] first The first #ckmc_alias_info_list_s handle to destroy
 395  * @see #ckmc_alias_info_list_s
 396  */
 397 void ckmc_alias_info_list_all_free(ckmc_alias_info_list_s *first);
 398
 399 /**
 400  * @brief Creates a new full alias which is a concatenation of @a owner_id and @a alias.
 401  * @since_tizen 3.0
 402  * @remarks @a full_alias should be freed with free() after use.
 403  * @remarks Returns #CKMC_ERROR_INVALID_PARAMETER if any of parameter is NULL.
 404  * @remarks Returns #CKMC_ERROR_INVALID_PARAMETER if @a owner_id is empty.
 405  * @param[in] owner_id Data owner's id. This should be package id if data owner is
 406  *                     application. If you want to access data stored by system
 407  *                     services, it should be #ckmc_owner_id_system
 408  * @param[in] alias Data alias
 409  * @param[out] full_alias The newly created alias which is a concatenation of
 410  *                        @a owner_id, #ckmc_owner_id_separator and @a alias.
 411  *                        Destroy by free() after use
 412  * @return #CKMC_ERROR_NONE on success,
 413  *         otherwise a negative error value
 414  * @retval #CKMC_ERROR_NONE Successful
 415  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 416  * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
 417  * @see #ckmc_owner_id_separator
 418  * @see #ckmc_owner_id_system
 419  */
 420 int ckmc_alias_new(const char *owner_id, const char *alias, char **full_alias);
 421
 422
 423 /**
 424  * @brief Creates a new #ckmc_key_s handle and returns it.
 425  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 426  * @remarks You must destroy the newly created #ckmc_key_s by calling ckmc_key_free() if it is no longer needed.
 427  * @param[in] raw_key The byte array of key \n
 428  *                    @a raw_key may be encrypted with password
 429  * @param[in] key_size The byte size of @a raw_key
 430  * @param[in] key_type The @a raw_key's type
 431  * @param[in] password The byte array used to decrypt @a raw_key inside key manager \n
 432  *                     If @a raw_key is not encrypted, @a password can be null
 433  * @param[out] ppkey The pointer to a newly created #ckmc_key_s handle
 434  * @return #CKMC_ERROR_NONE on success,
 435  *         otherwise a negative error value
 436  * @retval #CKMC_ERROR_NONE Successful
 437  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 438  * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
 439  * @see ckmc_key_free()
 440  * @see #ckmc_key_s
 441  */
 442 int ckmc_key_new(unsigned char *raw_key, size_t key_size, ckmc_key_type_e key_type, char *password, ckmc_key_s **ppkey);
 443
 444
 445 /**
 446  * @brief Destroys the #ckmc_key_s handle and releases all its resources.
 447  * @since_tizen 2.3
 448  * @param[in] key The #ckmc_key_s handle to destroy
 449  */
 450 void ckmc_key_free(ckmc_key_s *key);
 451
 452
 453 /**
 454  * @brief Creates a new #ckmc_raw_buffer_s handle and returns it.
 455  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 456  * @remarks You must destroy the newly created #ckmc_raw_buffer_s by calling ckmc_buffer_free() if it is no longer needed.
 457  * @param[in] data The byte array of buffer
 458  * @param[in] size The byte size of buffer
 459  * @param[out] ppbuffer The pointer to a newly created #ckmc_raw_buffer_s handle
 460  * @return #CKMC_ERROR_NONE on success,
 461  *         otherwise a negative error value
 462  * @retval #CKMC_ERROR_NONE Successful
 463  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 464  * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
 465  * @see ckmc_buffer_free()
 466  * @see #ckmc_raw_buffer_s
 467  */
 468 int ckmc_buffer_new(unsigned char *data, size_t size, ckmc_raw_buffer_s **ppbuffer);
 469
 470
 471 /**
 472  * @brief Destroys the #ckmc_raw_buffer_s handle and releases all its resources.
 473  * @since_tizen 2.3
 474  * @param[in] buffer The #ckmc_raw_buffer_s structure to destroy
 475  */
 476 void ckmc_buffer_free(ckmc_raw_buffer_s *buffer);
 477
 478
 479 /**
 480  * @brief Creates a new #ckmc_cert_s handle and returns it.
 481  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 482  * @remarks You must destroy the newly created #ckmc_cert_s by calling ckmc_cert_free() if it is no longer needed.
 483  * @param[in] raw_cert The byte array of certificate
 484  * @param[in] cert_size The byte size of raw_cert
 485  * @param[in] data_format The encoding format of raw_cert
 486  * @param[out] ppcert The pointer to a newly created #ckmc_cert_s handle
 487  * @return #CKMC_ERROR_NONE on success,
 488  *         otherwise a negative error value
 489  * @retval #CKMC_ERROR_NONE Successful
 490  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 491  * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
 492  * @see ckmc_cert_free()
 493  * @see ckmc_load_cert_from_file()
 494  * @see #ckmc_cert_s
 495  */
 496 int ckmc_cert_new(unsigned char *raw_cert, size_t cert_size, ckmc_data_format_e data_format, ckmc_cert_s **ppcert);
 497
 498
 499 /**
 500  * @brief Destroys the #ckmc_cert_s handle and releases all its resources.
 501  * @since_tizen 2.3
 502  * @param[in] cert The #ckmc_cert_s handle to destroy
 503  * @see ckmc_load_cert_from_file()
 504  */
 505 void ckmc_cert_free(ckmc_cert_s *cert);
 506
 507
 508 /**
 509  * @brief Creates a new #ckmc_cert_s handle from a given file and returns it.
 510  * @since_tizen 2.3
 511  * @remarks You must destroy the newly created #ckmc_cert_s by calling ckmc_cert_free() if it is no longer needed.
 512  * @param[in] file_path The path of certificate file to be loaded \n
 513  *                      The only DER or PEM encoded certificate file is supported
 514  * @param[out] cert The pointer of newly created #ckmc_cert_s handle
 515  * @return #CKMC_ERROR_NONE on success,
 516  *         otherwise a negative error value
 517  * @retval #CKMC_ERROR_NONE Successful
 518  * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory space
 519  * @retval #CKMC_ERROR_INVALID_FORMAT Invalid certificate file format
 520  * @retval #CKMC_ERROR_FILE_ACCESS_DENIED Provided file does not exist or cannot be accessed
 521  * @see ckmc_cert_free()
 522  * @see #ckmc_cert_s
 523  */
 524 int ckmc_load_cert_from_file(const char *file_path, ckmc_cert_s **cert);
 525
 526
 527 /**
 528  * @brief Creates a new #ckmc_pkcs12_s handle and returns it.
 529  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 530  * @remarks You must destroy the newly created #ckmc_pkcs12_s by calling ckmc_pkcs12_free() if it is no longer needed.
 531  * @remarks On success, private_key, cert && ca_cert_list ownership is transferred into newly returned ckmc_pkcs12_s.
 532  * @param[in] private_key #ckmc_key_s handle to the private key (optional)
 533  * @param[in] cert #ckmc_cert_s handle to the certificate (optional)
 534  * @param[in] ca_cert_list #ckmc_cert_list_s list of chain certificate handles (optional)
 535  * @param[out] pkcs12_bundle The pointer to a newly created #ckmc_pkcs12_s handle
 536  * @return #CKMC_ERROR_NONE on success,
 537  *         otherwise a negative error value
 538  * @retval #CKMC_ERROR_NONE Successful
 539  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid or private_key, cert and ca_cert_list all are null
 540  * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
 541  * @see ckmc_pkcs12_free()
 542  * @see ckmc_pkcs12_load()
 543  * @see #ckmc_key_s
 544  * @see #ckmc_cert_s
 545  * @see #ckmc_cert_list_s
 546  * @see #ckmc_pkcs12_s
 547  */
 548 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);
 549
 550
 551 /**
 552  * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif [Use ckmc_pkcs12_load() instead]
 553  * @brief Creates a new #ckmc_key_s (@a private_key), #ckmc_cert_s (@a cert), and #ckmc_cert_list_s (@a ca_cert_list) handle from a given PKCS#12 file and returns them.
 554  * @since_tizen 2.3
 555  * @remarks You must destroy the newly created #ckmc_key_s, #ckmc_cert_s, and
 556  *          #ckmc_cert_list_s by calling ckmc_key_free(), ckmc_cert_free(), and
 557  *          ckmc_cert_list_all_free() if they are no longer needed.
 558  * @param[in] file_path The path of PKCS12 file to be loaded
 559  * @param[in] passphrase The passphrase used to decrypt the PCKS12 file \n
 560  *                       If PKCS12 file is not encrypted, passphrase can be null
 561  * @param[out] private_key The pointer of newly created #ckmc_key_s handle for a private key
 562  * @param[out] cert The pointer of newly created #ckmc_cert_s handle for a certificate \n
 563  *                  It is null if the PKCS12 file does not contain a certificate
 564  * @param[out] ca_cert_list The pointer of newly created #ckmc_cert_list_s handle for CA certificates \n
 565  *                          It is null if the PKCS12 file does not contain CA certificates
 566  * @return #CKMC_ERROR_NONE on success,
 567  *         otherwise a negative error value
 568  * @retval #CKMC_ERROR_NONE Successful
 569  * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory space
 570  * @retval #CKMC_ERROR_INVALID_FORMAT Invalid PKCS12 file format
 571  * @retval #CKMC_ERROR_FILE_ACCESS_DENIED Provided file does not exist or cannot be accessed
 572  * @see ckmc_pkcs12_new()
 573  * @see ckmc_pkcs12_load()
 574  * @see ckmc_key_free()
 575  * @see ckmc_cert_free()
 576  * @see ckmc_cert_list_all_free()
 577  * @see #ckmc_key_s
 578  * @see #ckmc_cert_s
 579  * @see #ckmc_cert_list_s
 580  */
 581 int ckmc_load_from_pkcs12_file(const char *file_path, const char *passphrase, ckmc_key_s **private_key, ckmc_cert_s **cert, ckmc_cert_list_s **ca_cert_list) TIZEN_DEPRECATED_API;
 582
 583
 584 /**
 585  * @brief Creates a new #ckmc_pkcs12_s handle from a given PKCS#12 file and returns it.
 586  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 587  * @remarks You must destroy the newly created #ckmc_pkcs12_s by calling ckmc_pkcs12_free() if they are no longer needed.
 588  * @param[in] file_path The path of PKCS12 file to be loaded
 589  * @param[in] passphrase The passphrase used to decrypt the PCKS12 file \n
 590  *                       If PKCS12 file is not encrypted, passphrase can be null
 591  * @param[out] pkcs12_bundle The pointer of newly created #ckmc_cert_list_s handle for CA certificates \n
 592  *                           It is null if the PKCS12 file does not contain CA certificates
 593  * @return #CKMC_ERROR_NONE on success,
 594  *         otherwise a negative error value
 595  * @retval #CKMC_ERROR_NONE Successful
 596  * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory space
 597  * @retval #CKMC_ERROR_INVALID_FORMAT Invalid PKCS12 file format
 598  * @retval #CKMC_ERROR_FILE_ACCESS_DENIED Provided file does not exist or cannot be accessed
 599  * @see ckmc_pkcs12_free()
 600  * @see #ckmc_pkcs12_s
 601  */
 602 int ckmc_pkcs12_load(const char *file_path, const char *passphrase, ckmc_pkcs12_s **pkcs12_bundle);
 603
 604
 605 /**
 606  * @brief Destroys the #ckmc_pkcs12_s handle and releases all its resources.
 607  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 608  * @param[in] pkcs12 The #ckmc_pkcs12_s handle to destroy
 609  * @see ckmc_pkcs12_new()
 610  * @see ckmc_pkcs12_load()
 611  */
 612 void ckmc_pkcs12_free(ckmc_pkcs12_s *pkcs12);
 613
 614
 615 /**
 616  * @brief Creates a new #ckmc_alias_list_s handle and returns it.
 617  *        The alias pointer in the returned #ckmc_alias_list_s handle points to the provided characters and next is null.
 618  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 619  * @remarks You must destroy the newly created #ckmc_alias_list_s
 620  *          by calling ckmc_alias_list_free() or ckmc_alias_list_all_free() if it is no longer needed.
 621  * @param[in] alias The first item to be set in the newly created #ckmc_alias_list_s
 622  * @param[out] ppalias_list The pointer to a newly created #ckmc_alias_list_s handle
 623  * @return #CKMC_ERROR_NONE on success,
 624  *         otherwise a negative error value
 625  * @retval #CKMC_ERROR_NONE Successful
 626  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 627  * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
 628  * @see ckmc_alias_list_all_free()
 629  * @see #ckmc_alias_list_s
 630  */
 631 int ckmc_alias_list_new(char *alias, ckmc_alias_list_s **ppalias_list);
 632
 633
 634 /**
 635  * @brief Creates a new #ckmc_alias_list_s handle, adds it to a previous #ckmc_alias_list_s and returns it.
 636  *        The alias pointer in the returned #ckmc_alias_list_s handle points to the provided characters and next is null.
 637  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 638  * @param[in] previous The last #ckmc_alias_list_s handle to which a newly created #ckmc_alias_list_s is added
 639  * @param[in] alias The item to be set in the newly created #ckmc_alias_list_s
 640  * @param[out] pplast The pointer to a newly created and added #ckmc_alias_list_s handle
 641  * @return #CKMC_ERROR_NONE on success,
 642  *         otherwise a negative error value
 643  * @retval #CKMC_ERROR_NONE Successful
 644  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 645  * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
 646  * @see ckmc_alias_list_all_free()
 647  * @see #ckmc_alias_list_s
 648  */
 649 int ckmc_alias_list_add(ckmc_alias_list_s *previous, char *alias, ckmc_alias_list_s **pplast);
 650
 651
 652 /**
 653  * @brief Destroys the #ckmc_alias_list_s handle and releases resources of #ckmc_alias_list_s from the provided first handle cascadingly.
 654  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 655  * @remarks It does not destroy an alias itself in #ckmc_alias_list_s.
 656  * @param[in] first The first #ckmc_alias_list_s handle to destroy
 657  * @see ckmc_alias_list_all_free()
 658  * @see #ckmc_alias_list_s
 659  */
 660 void ckmc_alias_list_free(ckmc_alias_list_s *first);
 661
 662
 663 /**
 664  * @brief Destroys the #ckmc_alias_list_s handle and releases all its resources from the provided first handle cascadingly.
 665  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 666  * @remarks It also destroys the alias in #ckmc_alias_list_s.
 667  * @param[in] first The first #ckmc_alias_list_s handle to destroy
 668  * @see #ckmc_alias_list_s
 669  */
 670 void ckmc_alias_list_all_free(ckmc_alias_list_s *first);
 671
 672
 673 /**
 674  * @brief Creates a new #ckmc_cert_list_s handle and returns it.
 675  *        The cert pointer in the returned #ckmc_cert_list_s handle points to the provided #ckmc_cert_s and next is null.
 676  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 677  * @remarks You must destroy the newly created #ckmc_cert_list_s by calling ckmc_cert_list_free() or ckmc_cert_list_all_free() if it is no longer needed.
 678  * @param[in] cert The first item to be set in the newly created #ckmc_cert_list_s
 679  * @param[out] ppalias_list The pointer to a newly created #ckmc_alias_list_s handle
 680  * @return #CKMC_ERROR_NONE on success,
 681  *         otherwise a negative error value
 682  * @retval #CKMC_ERROR_NONE Successful
 683  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 684  * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
 685  * @see ckmc_cert_list_all_free()
 686  * @see #ckmc_cert_list_s
 687  */
 688 int ckmc_cert_list_new(ckmc_cert_s *cert, ckmc_cert_list_s **ppalias_list);
 689
 690
 691 /**
 692  * @brief Creates a new #ckmc_cert_list_s handle, adds it to a previous #ckmc_cert_list_s and returns it.
 693  *        The cert pointer in the returned #ckmc_alias_list_s handle points to the provided #ckmc_cert_s and next is null.
 694  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 695  * @param[in] previous The last #ckmc_cert_list_s handle to which a newly created #ckmc_cert_list_s is added
 696  * @param[in] cert The item to be set in the newly created #ckmc_cert_list_s
 697  * @param[out] pplast The pointer to a newly created and added #ckmc_alias_list_s handle
 698  * @return #CKMC_ERROR_NONE on success,
 699  *         otherwise a negative error value
 700  * @retval #CKMC_ERROR_NONE Successful
 701  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 702  * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
 703  * @see ckmc_cert_list_all_free()
 704  * @see #ckmc_cert_list_s
 705  */
 706 int ckmc_cert_list_add(ckmc_cert_list_s *previous, ckmc_cert_s *cert, ckmc_cert_list_s **pplast);
 707
 708
 709 /**
 710  * @brief Destroys the #ckmc_cert_list_s handle and releases resources of #ckmc_cert_list_s from the provided first handle cascadingly.
 711  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 712  * @remarks It does not destroy #ckmc_cert_s itself in #ckmc_cert_list_s.
 713  * @param[in] first The first #ckmc_cert_list_s handle to destroy
 714  * @see ckmc_cert_list_all_free()
 715  * @see #ckmc_cert_list_s
 716  */
 717 void ckmc_cert_list_free(ckmc_cert_list_s *first);
 718
 719
 720 /**
 721  * @brief Destroys the #ckmc_cert_list_s handle and releases all its resources from the provided first handle cascadingly.
 722  * @since_tizen 2.3
 723  * @remarks It also destroys #ckmc_cert_s in #ckmc_cert_list_s.
 724  * @param[in] first The first #ckmc_cert_list_s handle to destroy
 725  * @see #ckmc_cert_list_s
 726  */
 727 void ckmc_cert_list_all_free(ckmc_cert_list_s *first);
 728
 729
 730 /**
 731  * @brief Creates new parameter list.
 732  * @since_tizen 3.0
 733  * @remarks Caller is responsible for freeing it with ckmc_param_list_free().
 734  * @param[in] pparams Double pointer to the handle of param list to which the newly created algorithm param list will be assigned
 735  * @return #CKMC_ERROR_NONE on success,
 736  *         otherwise a negative error value
 737  * @retval #CKMC_ERROR_NONE Successful
 738  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 739  * @see ckmc_param_list_set_integer()
 740  * @see ckmc_param_list_set_buffer()
 741  * @see ckmc_param_list_free()
 742  * @see ckmc_generate_new_params()
 743  * @see #ckmc_param_list_h
 744  * @see #ckmc_param_name_e
 745  * @see #ckmc_algo_type_e
 746  */
 747 int ckmc_param_list_new(ckmc_param_list_h *pparams);
 748
 749
 750 /**
 751  * @brief Sets integer parameter to the list.
 752  * @since_tizen 3.0
 753  * @remarks Caller is responsible for #ckmc_param_list_h creation.
 754  * @param[in] params Algorithm param list handle created with ckmc_param_list_new() or ckmc_generate_new_params() \n
 755  *                   New param with @a name and @a value will be set here
 756  * @param[in] name Name of parameter to set \n
 757  *                 Existing parameter will be overwritten \n
 758  *                 Passing invalid parameter name will result in an error
 759  * @param[in] value Value of the parameter in form of a integer
 760  * @return #CKMC_ERROR_NONE on success,
 761  *         otherwise a negative error value
 762  * @retval #CKMC_ERROR_NONE Successful
 763  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 764  * @see ckmc_param_list_new()
 765  * @see ckmc_param_list_set_buffer()
 766  * @see ckmc_param_list_get_integer()
 767  * @see ckmc_param_list_get_buffer()
 768  * @see ckmc_param_list_free()
 769  * @see ckmc_generate_new_params()
 770  * @see #ckmc_param_list_h
 771  * @see #ckmc_param_name_e
 772  * @see #ckmc_algo_type_e
 773  */
 774 int ckmc_param_list_set_integer(ckmc_param_list_h params, ckmc_param_name_e name, uint64_t value);
 775
 776
 777 /**
 778  * @brief Sets buffer parameter to the list.
 779  * @since_tizen 3.0
 780  * @remarks Caller is responsible for #ckmc_param_list_h creation.
 781  * @param[in] params Algorithm param list handle created with ckmc_param_list_new() or ckmc_generate_new_params()
 782  *                   New param with @a name and @a buffer will be set here
 783  * @param[in] name Name of parameter to set \n
 784  *                 Existing parameter will be overwritten \n
 785  *                 Passing invalid parameter name will result in an error
 786  * @param[in] buffer Value of the parameter in form of a buffer \n
 787  *                   Caller is responsible for creating and freeing the buffer
 788  * @return #CKMC_ERROR_NONE on success,
 789  *         otherwise a negative error value
 790  * @retval #CKMC_ERROR_NONE Successful
 791  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 792  * @see ckmc_param_list_new()
 793  * @see ckmc_param_list_set_integer()
 794  * @see ckmc_param_list_get_integer()
 795  * @see ckmc_param_list_get_buffer()
 796  * @see ckmc_param_list_free()
 797  * @see ckmc_generate_new_params()
 798  * @see #ckmc_param_list_h
 799  * @see #ckmc_param_name_e
 800  * @see #ckmc_algo_type_e
 801  */
 802 int ckmc_param_list_set_buffer(ckmc_param_list_h params, ckmc_param_name_e name, const ckmc_raw_buffer_s *buffer);
 803
 804
 805 /**
 806  * @brief Gets integer parameter from the list.
 807  * @since_tizen 3.0
 808  * @remarks Caller is responsible for #ckmc_param_list_h creation.
 809  * @param[in] params Algorithm param list handle created with ckmc_param_list_new() or ckmc_generate_new_params()
 810  *                   which contains param with @a name
 811  * @param[in] name Name of parameter to get
 812  * @param[out] pvalue Value of the parameter in form of a integer
 813  * @return #CKMC_ERROR_NONE on success,
 814  *         otherwise a negative error value
 815  * @retval #CKMC_ERROR_NONE Successful
 816  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 817  * @see ckmc_param_list_new()
 818  * @see ckmc_param_list_set_integer()
 819  * @see ckmc_param_list_set_buffer()
 820  * @see ckmc_param_list_get_buffer()
 821  * @see ckmc_param_list_free()
 822  * @see ckmc_generate_new_params()
 823  * @see #ckmc_param_list_h
 824  * @see #ckmc_param_name_e
 825  * @see #ckmc_algo_type_e
 826  */
 827 int ckmc_param_list_get_integer(ckmc_param_list_h params, ckmc_param_name_e name, uint64_t *pvalue);
 828
 829
 830 /**
 831  * @brief Gets buffer parameter from the list.
 832  * @since_tizen 3.0
 833  * @remarks Caller is responsible for #ckmc_param_list_h creation.
 834  * @param[in] params Algorithm param list handle created with ckmc_param_list_new() or ckmc_generate_new_params()
 835  *                   which contains param with @a name
 836  * @param[in] name Name of parameter to get
 837  * @param[out] ppbuffer Value of the parameter in form of a buffer \n
 838  *                      Caller is responsible for creating and freeing the buffer
 839  * @return #CKMC_ERROR_NONE on success,
 840  *         otherwise a negative error value
 841  * @retval #CKMC_ERROR_NONE Successful
 842  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 843  * @see ckmc_param_list_new()
 844  * @see ckmc_param_list_set_integer()
 845  * @see ckmc_param_list_set_buffer()
 846  * @see ckmc_param_list_get_integer()
 847  * @see ckmc_param_list_free()
 848  * @see ckmc_generate_new_params()
 849  * @see ckmc_buffer_free()
 850  * @see #ckmc_param_list_h
 851  * @see #ckmc_param_name_e
 852  * @see #ckmc_algo_type_e
 853  */
 854 int ckmc_param_list_get_buffer(ckmc_param_list_h params, ckmc_param_name_e name, ckmc_raw_buffer_s **ppbuffer);
 855
 856
 857 /**
 858  * @brief Frees previously allocated list of algorithm params.
 859  * @since_tizen 3.0
 860  * @param[in] params First element of the list to be freed
 861  * @see ckmc_param_list_new()
 862  * @see ckmc_param_list_set_integer()
 863  * @see ckmc_param_list_set_buffer()
 864  * @see ckmc_param_list_get_integer()
 865  * @see ckmc_param_list_get_buffer()
 866  * @see ckmc_generate_new_params()
 867  * @see #ckmc_param_list_h
 868  * @see #ckmc_param_name_e
 869  * @see #ckmc_algo_type_e
 870  */
 871 void ckmc_param_list_free(ckmc_param_list_h params);
 872
 873
 874 /**
 875  * @brief Generates algorithm parameters for a given algorithm type and set them to the list.
 876  * @since_tizen 3.0
 877  * @remarks Caller is responsible for #ckmc_param_list_h destruction.
 878  * @remarks Algorithm parameters are set to default values. Optional fields are left empty.
 879  *          Initialization vectors are left empty (they have to be set manually).
 880  *          Caller is responsible for freeing the list with ckmc_param_list_free().
 881  * @remarks If the function returns error, provided param list may contain some of default parameters.
 882  * @param[in] type Type of the algorithm
 883  * @param[out] pparams Newly generated handle of param list which should be freed by caller after use
 884  * @return #CKMC_ERROR_NONE on success,
 885  *         otherwise a negative error value
 886  * @retval #CKMC_ERROR_NONE Successful
 887  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 888  * @see ckmc_param_list_new()
 889  * @see ckmc_param_list_set_integer()
 890  * @see ckmc_param_list_set_buffer()
 891  * @see ckmc_param_list_get_integer()
 892  * @see ckmc_param_list_get_buffer()
 893  * @see ckmc_param_list_free()
 894  * @see #ckmc_param_list_h
 895  * @see #ckmc_param_name_e
 896  * @see #ckmc_algo_type_e
 897  */
 898 int ckmc_generate_new_params(ckmc_algo_type_e type, ckmc_param_list_h *pparams);
 899
 900
 901 /**
 902  * @}
 903  */
 904
 905
 906 #ifdef __cplusplus
 907 }
 908 #endif
 909
 910
 911 #endif /* __TIZEN_CORE_CKMC_TYPE_H */