src/include/ckmc/ckmc-type.h

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