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