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