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 <ckmc/ckmc-error.h>
  27
  28 #define KEY_MANAGER_CAPI __attribute__((visibility("default")))
  29
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /**
  36  * @addtogroup CAPI_KEY_MANAGER_TYPES_MODULE
  37  * @{
  38  */
  39
  40 /**
  41  * @brief Enumeration for key types of key manager.
  42  * @since_tizen 2.3
  43  */
  44 typedef enum __ckmc_key_type {
  45     CKMC_KEY_NONE = 0,       /**< key type not specified */
  46     CKMC_KEY_RSA_PUBLIC,     /**< RSA public key */
  47     CKMC_KEY_RSA_PRIVATE,    /**< RSA private key */
  48     CKMC_KEY_ECDSA_PUBLIC,   /**< ECDSA public key */
  49     CKMC_KEY_ECDSA_PRIVATE,  /**< ECDSA private key */
  50     CKMC_KEY_DSA_PUBLIC,     /**< DSA public key */
  51     CKMC_KEY_DSA_PRIVATE,    /**< DSA private key */
  52     CKMC_KEY_AES,            /**< AES key, MJK: kept for binary compatibility with ckm-type.h::KeyType::KEY_AES*/
  53 } ckmc_key_type_e;
  54
  55 /**
  56  * @brief Enumeration for data format.
  57  * @since_tizen 2.3
  58  */
  59 typedef enum __ckmc_data_format {
  60     CKMC_FORM_DER_BASE64 = 0,  /**< DER format base64 encoded data */
  61     CKMC_FORM_DER,             /**< DER encoded data */
  62     CKMC_FORM_PEM              /**< PEM encoded data. It consists of the DER format base64 encoded with additional header and footer lines. */
  63 } ckmc_data_format_e;
  64
  65 /**
  66  * @brief Enumeration for elliptic curve.
  67  * @since_tizen 2.3
  68  */
  69 typedef enum __ckmc_ec_type {
  70     CKMC_EC_PRIME192V1 = 0, /**< Elliptic curve domain "secp192r1" listed in "SEC 2" recommended elliptic curve domain  */
  71     CKMC_EC_PRIME256V1,     /**< "SEC 2" recommended elliptic curve domain - secp256r1 */
  72     CKMC_EC_SECP384R1       /**< NIST curve P-384 (covers "secp384r1", the elliptic curve domain listed in See SEC 2 */
  73 } ckmc_ec_type_e;
  74
  75 /**
  76  * @brief Enumeration for hash algorithm.
  77  * @since_tizen 2.3
  78  */
  79 typedef enum __ckmc_hash_algo {
  80     CKMC_HASH_NONE = 0, /**< No Hash Algorithm  */
  81     CKMC_HASH_SHA1,     /**< Hash Algorithm SHA1  */
  82     CKMC_HASH_SHA256,   /**< Hash Algorithm SHA256  */
  83     CKMC_HASH_SHA384,   /**< Hash Algorithm SHA384  */
  84     CKMC_HASH_SHA512    /**< Hash Algorithm SHA512  */
  85 } ckmc_hash_algo_e;
  86
  87 /**
  88  * @brief Enumeration for RSA padding algorithm.
  89  * @since_tizen 2.3
  90  */
  91 typedef enum __ckmc_rsa_padding_algo {
  92     CKMC_NONE_PADDING = 0,  /**< No Padding */
  93     CKMC_PKCS1_PADDING,     /**< PKCS#1 Padding */
  94     CKMC_X931_PADDING       /**< X9.31 padding */
  95 } ckmc_rsa_padding_algo_e;
  96
  97 /**
  98  * @brief the structure for binary buffer used in key manager CAPI.
  99  * @since_tizen 2.3
 100  */
 101 typedef struct __ckmc_raw_buff {
 102     unsigned char* data; /**< Byte array containing binary data */
 103     size_t size;         /**< The size of the binary data */
 104 } ckmc_raw_buffer_s;
 105
 106 /**
 107  * @brief The structure for a policy for storing key/certificate/binary data.
 108  * @since_tizen 2.3
 109  */
 110 typedef struct __ckmc_policy {
 111     char* password;   /**< Byte array used to encrypt data inside CKM. If it is not null, the data(or key, or certificate) is stored encrypted with this password inside key manager */
 112     bool extractable; /**< If true key may be extracted from storage */
 113 } ckmc_policy_s;
 114
 115 /**
 116  * @brief The structure for key used in key manager CAPI.
 117  * @since_tizen 2.3
 118  */
 119 typedef struct __ckmc_key {
 120     unsigned char* raw_key;   /**< Byte array of key. raw_key may be encrypted with password */
 121     size_t key_size;          /**< The byte size of raw_key */
 122     ckmc_key_type_e key_type; /**< The raw_key's type */
 123     char* password;           /**< Byte array used to decrypt data raw_key inside key manager. */
 124 } ckmc_key_s;
 125
 126 /**
 127  * @brief The structure for certificate used in key manager CAPI.
 128  * @since_tizen 2.3
 129  */
 130 typedef struct __ckmc_cert {
 131     unsigned char* raw_cert;  /**< Byte array of certificate */
 132     size_t cert_size;         /**< Byte size of raw_cert */
 133     ckmc_data_format_e data_format; /**< Raw_cert's encoding format */
 134 } ckmc_cert_s;
 135
 136 /**
 137  * @brief The structure for linked list of alias.
 138  * @since_tizen 2.3
 139  */
 140 typedef struct __ckmc_alias_list {
 141     char *alias;  /**< The name of key, certificate or data stored in key manager */
 142     struct __ckmc_alias_list *next; /**< The pointer pointing to the next ckmc_alias_list_s */
 143 } ckmc_alias_list_s;
 144
 145 /**
 146  * @brief The structure for linked list of ckmc_cert_s
 147  * @since_tizen 2.3
 148  */
 149 typedef struct __ckmc_cert_list {
 150     ckmc_cert_s *cert; /**< The pointer of ckmc_cert_s */
 151     struct __ckmc_cert_list *next; /**< The pointer pointing to the next ckmc_cert_list_s */
 152 } ckmc_cert_list_s;
 153
 154 /**
 155  * @internal
 156  * @brief Creates a new @a ckmc_key_s handle and returns it.
 157  *
 158  * @since_tizen 2.3
 159  *
 160  * @remarks You must destroy the newly created @a ckmc_key_s by calling ckmc_key_free() if it is no longer needed.
 161  *
 162  * @param[in] raw_key  The byte array of key \n
 163  *                     @a raw_key may be encrypted with password.
 164  * @param[in] key_size The byte size of @a raw_key
 165  * @param[in] key_type The @a raw_key's type
 166  * @param[in] password The byte array used to decrypt @a raw_key inside key manager \n
 167  *                     If @a raw_key is not encrypted, @a password can be null.
 168  * @param[out] ppkey   The pointer to a newly created @a ckmc_key_s handle
 169  *
 170  * @return @c 0 on success,
 171  *         otherwise a negative error value
 172  *
 173  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 174  * @retval #CKMC_ERROR_OUT_OF_MEMORY     Not enough memory
 175  *
 176  * @see ckmc_key_free()
 177  * @see #ckmc_key_s
 178  */
 179 int ckmc_key_new(unsigned char *raw_key, size_t key_size,
 180         ckmc_key_type_e key_type, char *password, ckmc_key_s **ppkey);
 181
 182 /**
 183  * @brief Destroys the @a ckmc_key_s handle and releases all its resources.
 184  *
 185  * @since_tizen 2.3
 186  *
 187  * @param[in] key The @a ckmc_key_s handle to destroy
 188  *
 189  */
 190 void ckmc_key_free(ckmc_key_s *key);
 191
 192 /**
 193  * @internal
 194  * @brief Creates a new @a ckmc_raw_buffer_s handle and returns it.
 195  *
 196  * @since_tizen 2.3
 197  *
 198  * @remarks You must destroy the newly created @a ckmc_raw_buffer_s by calling ckmc_buffer_free() if it is no longer needed.
 199  *
 200  * @param[in]  data      The byte array of buffer
 201  * @param[in]  size      The byte size of buffer
 202  * @param[out] ppbuffer  The pointer to a newly created @a ckmc_buffer_s handle
 203  *
 204  * @return @c 0 on success,
 205  *         otherwise a negative error value
 206  *
 207  * @retval #CKMC_ERROR_INVALID_PARAMETER  Input parameter is invalid
 208  * @retval #CKMC_ERROR_OUT_OF_MEMORY      Not enough memory
 209  *
 210  * @see ckmc_buffer_free()
 211  * @see #ckmc_raw_buffer_s
 212  */
 213 int ckmc_buffer_new(unsigned char *data, size_t size,ckmc_raw_buffer_s **ppbuffer);
 214
 215 /**
 216  * @brief Destroys the @a ckmc_raw_buffer_s handle and releases all its resources.
 217  *
 218  * @since_tizen 2.3
 219  *
 220  * @param[in] buffer The @a ckmc_raw_buffer_s handle to destroy
 221  *
 222  */
 223 void ckmc_buffer_free(ckmc_raw_buffer_s *buffer);
 224
 225 /**
 226  * @internal
 227  * @brief Creates a new @a ckmc_cert_s handle and returns it.
 228  *
 229  * @since_tizen 2.3
 230  *
 231  * @remarks You must destroy the newly created @a ckmc_cert_s by calling ckmc_cert_free() if it is no longer needed.
 232  *
 233  * @param[in]  raw_cert     The byte array of certificate
 234  * @param[in]  cert_size    The byte size of raw_cert
 235  * @param[in]  data_format  The encoding format of raw_cert
 236  * @param[out] ppcert       The pointer to a newly created @a ckmc_cert_s handle
 237  *
 238  * @return @c 0 on success,
 239  *         otherwise a negative error value
 240  *
 241  * @retval #CKMC_ERROR_INVALID_PARAMETER  Input parameter is invalid
 242  * @retval #CKMC_ERROR_OUT_OF_MEMORY      Not enough memory
 243  *
 244  * @see ckmc_cert_free()
 245  * @see ckmc_load_cert_from_file()
 246  * @see ckmc_load_from_pkcs12_file
 247  * @see #ckmc_cert_s
 248  */
 249 int ckmc_cert_new(unsigned char *raw_cert, size_t cert_size,
 250         ckmc_data_format_e data_format, ckmc_cert_s **ppcert);
 251
 252 /**
 253  * @brief Destroys the @a ckmc_cert handle and releases all its resources.
 254  *
 255  * @since_tizen 2.3
 256  *
 257  * @param[in] cert The @a ckmc_cert_s handle to destroy
 258  *
 259  * @see ckmc_load_cert_from_file()
 260  * @see ckmc_load_from_pkcs12_file
 261  */
 262 void ckmc_cert_free(ckmc_cert_s *cert);
 263
 264 /**
 265  * @brief Creates a new @a ckmc_cert_s handle from a given file and returns it.
 266  *
 267  * @since_tizen 2.3
 268  *
 269  * @remarks You must destroy the newly created @a ckmc_cert_s by calling ckmc_cert_free() if it is no longer needed.
 270  *
 271  * @param[in]  file_path  The path of certificate file to be loaded \n
 272  *                        The only DER or PEM encoded certificate file is supported.
 273  * @param[out] cert       The pointer of newly created @a ckmc_cert_s handle
 274  *
 275  * @return #CKMC_ERROR_NONE on success,
 276  *         otherwise a negative error value
 277  *
 278  * @retval #CKMC_ERROR_NONE                Successful
 279  * @retval #CKMC_ERROR_OUT_OF_MEMORY       Not enough memory space
 280  * @retval #CKMC_ERROR_INVALID_FORMAT      Invalid certificate file format
 281  * @retval #CKMC_ERROR_FILE_ACCESS_DENIED  Provided file does not exist or cannot be accessed
 282  *
 283  * @see ckmc_cert_free()
 284  * @see ckmc_load_from_pkcs12_file()
 285  * @see #ckmc_cert_s
 286  */
 287 int ckmc_load_cert_from_file(const char *file_path, ckmc_cert_s **cert);
 288
 289 /**
 290  * @brief Creates a new @a ckmc_key_s(private key), @a ckmc_cert_s(certificate), and @a ckmc_cert_list_s(CA certificates) handle from a given PKCS#12 file and returns them.
 291  *
 292  * @since_tizen 2.3
 293  *
 294  * @remarks You must destroy the newly created @a ckmc_key_s, @a ckmc_cert_s, and @a ckmc_cert_list_s by calling ckmc_key_free(), ckmc_cert_free(), and ckmc_cert_list_all_free() if they are no longer needed.
 295  *
 296  * @param[in]  file_path    The path of PKCS12 file to be loaded
 297  * @param[in]  passphrase   The passphrase used to decrypt the PCKS12 file \n
 298  *                          If PKCS12 file is not encrypted, passphrase can be null.
 299  * @param[out] private_key  The pointer of newly created @a ckmc_key_s handle for a private key
 300  * @param[out] cert         The pointer of newly created @a ckmc_cert_s handle for a certificate \n
 301  *                          It is null if the PKCS12 file does not contain a certificate.
 302  * @param[out] ca_cert_list The pointer of newly created @a ckmc_cert_list_s handle for CA certificates \n
 303  *                          It is null if the PKCS12 file does not contain CA certificates.
 304  *
 305  * @return #CKMC_ERROR_NONE on success,
 306  *         otherwise a negative error value
 307  *
 308  * @retval #CKMC_ERROR_NONE                Successful
 309  * @retval #CKMC_ERROR_OUT_OF_MEMORY       Not enough memory space
 310  * @retval #CKMC_ERROR_INVALID_FORMAT      Invalid PKCS12 file format
 311  * @retval #CKMC_ERROR_FILE_ACCESS_DENIED  Provided file does not exist or cannot be accessed
 312  *
 313  * @see ckmc_key_free()
 314  * @see ckmc_cert_free()
 315  * @see ckmc_cert_list_all_free()
 316  * @see #ckmc_key_s
 317  * @see #ckmc_cert_s
 318  * @see #ckmc_cert_list_s
 319  */
 320 int ckmc_load_from_pkcs12_file(const char *file_path, const char *passphrase,
 321         ckmc_key_s **private_key, ckmc_cert_s **cert,
 322         ckmc_cert_list_s **ca_cert_list);
 323
 324 /**
 325  * @internal
 326  * @brief Creates a new @a ckmc_alias_list_s handle and returns it.
 327  *        The alias pointer in the returned @a ckmc_alias_list_s handle points to the provided characters and next is null.
 328  *
 329  * @since_tizen 2.3
 330  *
 331  * @remarks You must destroy the newly created @a ckmc_alias_list_s by calling ckmc_alias_list_free() or ckmc_alias_list_all_free() if it is no longer needed.
 332  *
 333  * @param[in]  alias        The first item to be set in the newly created @a ckmc_alias_list_s
 334  * @param[out] ppalias_list The pointer to a newly created @a ckmc_alias_list_s handle
 335  *
 336  * @return @c 0 on success,
 337  *         otherwise a negative error value
 338  *
 339  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 340  * @retval #CKMC_ERROR_OUT_OF_MEMORY     Not enough memory
 341  *
 342  * @see ckmc_alias_list_all_free()
 343  * @see #ckmc_alias_list_s
 344  */
 345 int ckmc_alias_list_new(char *alias, ckmc_alias_list_s **ppalias_list);
 346
 347 /**
 348  * @internal
 349  * @brief Creates a new @a ckmc_alias_list_s handle, adds it to a previous @a ckmc_alias_list_s and returns it.
 350  *        The alias pointer in the returned @a ckmc_alias_list_s handle points to the provided characters and next is null.
 351  *
 352  * @since_tizen 2.3
 353  *
 354  * @param[in]  previous  The last @a ckmc_alias_list_s handle to which a newly created @a ckmc_alias_list_s is added
 355  * @param[in]  alias     The item to be set in the newly created @a ckmc_alias_list_s
 356  * @param[out] pplast    The pointer to a newly created and added @a ckmc_alias_list_s handle
 357  *
 358  * @return @c 0 on success,
 359  *         otherwise a negative error value
 360  *
 361  * @retval #CKMC_ERROR_INVALID_PARAMETER  Input parameter is invalid
 362  * @retval #CKMC_ERROR_OUT_OF_MEMORY      Not enough memory
 363  *
 364  * @see ckmc_alias_list_all_free()
 365  * @see #ckmc_alias_list_s
 366  */
 367 int ckmc_alias_list_add(ckmc_alias_list_s *previous,
 368         char *alias, ckmc_alias_list_s **pplast);
 369
 370 /**
 371  * @internal
 372  * @brief Destroys the @a ckmc_alias_list_s handle and releases resources of @a ckmc_alias_list_s from the provided first handle cascadingly.
 373  *
 374  * @since_tizen 2.3
 375  *
 376  * @remarks It does not destroy an alias itself in @a ckmc_alias_list_s.
 377  *
 378  * @param[in] first The first @a ckmc_alias_list_s handle to destroy
 379  *
 380  * @see ckmc_alias_list_all_free()
 381  * @see #ckmc_alias_list_s
 382  */
 383 void ckmc_alias_list_free(ckmc_alias_list_s *first);
 384
 385 /**
 386  * @brief Destroys the @a ckmc_alias_list_s handle and releases all its resources from the provided first handle cascadingly.
 387  *
 388  * @since_tizen 2.3
 389  *
 390  * @remarks It also destroys the alias in @a ckmc_alias_list_s.
 391  *
 392  * @param[in] first The first @a ckmc_alias_list_s handle to destroy
 393  *
 394  * @see #ckmc_alias_list_s
 395  */
 396 void ckmc_alias_list_all_free(ckmc_alias_list_s *first);
 397
 398 /**
 399  * @internal
 400  * @brief Creates a new @a ckmc_cert_list_s handle and returns it.
 401  *        The cert pointer in the returned @a ckmc_cert_list_s handle points to the provided @a ckmc_cert_s and next is null.
 402  *
 403  * @since_tizen 2.3
 404  *
 405  * @remarks You must destroy the newly created @a ckmc_cert_list_s by calling ckmc_cert_list_free() or ckmc_cert_list_all_free() if it is no longer needed.
 406  *
 407  * @param[in]  cert          The first item to be set in the newly created @a ckmc_cert_list_s
 408  * @param[out] ppalias_list  The pointer to a newly created @a ckmc_alias_list_s handle
 409  *
 410  * @return @c 0 on success,
 411  *         otherwise a negative error value
 412  *
 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_list_all_free()
 417  * @see #ckmc_cert_list_s
 418  */
 419 int ckmc_cert_list_new(ckmc_cert_s *cert, ckmc_cert_list_s **ppalias_list);
 420
 421 /**
 422  * @internal
 423  * @brief Creates a new @a ckmc_cert_list_s handle, adds it to a previous @a ckmc_cert_list_s and returns it.
 424  *        The cert pointer in the returned @a ckmc_alias_list_s handle points to the provided @a ckmc_cert_s and next is null.
 425  *
 426  * @since_tizen 2.3
 427  *
 428  * @param[in]  previous  The last @a ckmc_cert_list_s handle to which a newly created @a ckmc_cert_list_s is added
 429  * @param[in]  cert      The item to be set in the newly created @a ckmc_cert_list_s
 430  * @param[out] pplast    The pointer to a newly created and added @a ckmc_alias_list_s handle
 431  *
 432  * @return @c 0 on success,
 433  *         otherwise a negative error value
 434  *
 435  * @retval #CKMC_ERROR_INVALID_PARAMETER  Input parameter is invalid
 436  * @retval #CKMC_ERROR_OUT_OF_MEMORY      Not enough memory
 437  *
 438  * @see ckmc_cert_list_all_free()
 439  * @see #ckmc_cert_list_s
 440  */
 441 int ckmc_cert_list_add(ckmc_cert_list_s *previous,
 442         ckmc_cert_s *cert, ckmc_cert_list_s **pplast);
 443
 444 /**
 445  * @internal
 446  * @brief Destroys the @a ckmc_cert_list_s handle and releases resources of @a ckmc_cert_list_s from the provided first handle cascadingly.
 447  *
 448  * @since_tizen 2.3
 449  *
 450  * @remarks It does not destroy @a ckmc_cert_s itself in @a ckmc_cert_list_s.
 451  *
 452  * @param[in] first The first @a ckmc_cert_list_s handle to destroy
 453  *
 454  * @see ckmc_cert_list_all_free()
 455  * @see #ckmc_cert_list_s
 456  */
 457 void ckmc_cert_list_free(ckmc_cert_list_s *first);
 458
 459 /**
 460  * @brief Destroys the @a ckmc_cert_list_s handle and releases all its resources from the provided first handle cascadingly.
 461  *
 462  * @since_tizen 2.3
 463  *
 464  * @remarks It also destroys @a ckmc_cert_s in ckmc_cert_list_s.
 465  *
 466  * @param[in] first The first @a ckmc_cert_list_s handle to destroy
 467  *
 468  * @see #ckmc_cert_list_s
 469  */
 470 void ckmc_cert_list_all_free(ckmc_cert_list_s *first);
 471
 472 /**
 473  * @}
 474  */
 475
 476 #ifdef __cplusplus
 477 }
 478 #endif
 479
 480 #endif /* __TIZEN_CORE_CKMC_TYPE_H */