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