src/include/ckmc/ckmc-type.h

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