src/include/ckmc/ckmc-manager.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-manager.h
  18  * @version     1.0
  19  * @brief       Provides management functions(storing, retrieving, and removing) for keys, certificates and data of a user and additional crypto functions.
  20  */
  21
  22
  23 #ifndef __TIZEN_CORE_CKMC_MANAGER_H
  24 #define __TIZEN_CORE_CKMC_MANAGER_H
  25
  26 #include <stddef.h>
  27 #include <sys/types.h>
  28 #include <tizen.h>
  29 #include <ckmc/ckmc-type.h>
  30 #include <ckmc/ckmc-error.h>
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /**
  37  * @addtogroup CAPI_KEY_MANAGER_CLIENT_MODULE
  38  * @{
  39  */
  40
  41
  42 /**
  43  * @brief Stores a key inside key manager based on the provided policy.
  44  *
  45  * @since_tizen 2.3
  46  * @privlevel public
  47  * @privilege %http://tizen.org/privilege/keymanager
  48  *
  49  * @remarks Currently only six types of keys are supported for this API. These are RSA public/private key, DSA public/private key and ECDSA public/private key.
  50  * @remarks key_type in key may be set to #CKMC_KEY_NONE as an input. key_type is determined inside key manager during storing keys.
  51  * @remarks Some private key files are protected by a password. If raw_key in key read from those encrypted files is encrypted with a password, the password should be provided in the #ckmc_key_s structure.
  52  * @remarks If password in policy is provided, the key is additionally encrypted with the password in policy.
  53  *
  54  * @param[in] alias   The name of a key to be stored
  55  * @param[in] key     The key's binary value to be stored
  56  * @param[in] policy  The policy about how to store a key securely
  57  *
  58  * @return @c 0 on success,
  59  *         otherwise a negative error value
  60  *
  61  * @retval #CKMC_ERROR_NONE              Successful
  62  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
  63  * @retval #CKMC_ERROR_DB_LOCKED         A user key is not loaded in memory (a user is not logged in)
  64  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS   Alias already exists
  65  * @retval #CKMC_ERROR_INVALID_FORMAT    The format of raw_key is not valid
  66  * @retval #CKMC_ERROR_DB_ERROR          Failed due to a database error
  67  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
  68  *
  69  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
  70  *
  71  * @see ckmc_remove_key()
  72  * @see ckmc_get_key()
  73  * @see ckmc_get_key_alias_list()
  74  * @see #ckmc_key_s
  75  * @see #ckmc_policy_s
  76  */
  77 int ckmc_save_key(const char *alias, const ckmc_key_s key, const ckmc_policy_s policy);
  78
  79 /**
  80  * @brief Removes a key from key manager.
  81  *
  82  * @since_tizen 2.3
  83  * @privlevel public
  84  * @privilege %http://tizen.org/privilege/keymanager
  85  *
  86  * @remarks A client can remove only keys stored by the client.
  87  *
  88  * @param[in] alias The name of a key to be removed
  89  *
  90  * @return @c 0 on success,
  91  *         otherwise a negative error value
  92  *
  93  * @retval #CKMC_ERROR_NONE              Successful
  94  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
  95  * @retval #CKMC_ERROR_DB_LOCKED         A user key is not loaded in memory (a user is not logged in)
  96  * @retval #CKMC_ERROR_DB_ERROR          Failed due to a database error
  97  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN  Alias does not exist
  98  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
  99  *
 100  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 101  *
 102  * @see ckmc_save_key()
 103  * @see ckmc_get_key()
 104  * @see ckmc_get_key_alias_list()
 105  */
 106 int ckmc_remove_key(const char *alias);
 107
 108 /**
 109  * @brief Gets a key from key manager.
 110  *
 111  * @since_tizen 2.3
 112  * @privlevel public
 113  * @privilege %http://tizen.org/privilege/keymanager
 114  *
 115  * @remarks A client can access only data stored by the client.
 116  * @remarks You must destroy the newly created @a ppkey by calling ckmc_key_free() if it is no longer needed.
 117  *
 118  * @param[in] alias     The name of a key to retrieve
 119  * @param[in] password  The password used in decrypting a key value \n
 120  *                      If password of policy is provided in ckmc_save_key(), the same password should be provided.
 121  * @param[out] ppkey    The pointer to a newly created ckmc_key_s handle
 122  *
 123  * @return @c 0 on success,
 124  *         otherwise a negative error value
 125  *
 126  * @retval #CKMC_ERROR_NONE              Successful
 127  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 128  * @retval #CKMC_ERROR_DB_LOCKED         A user key is not loaded in memory (a user is not logged in)
 129  * @retval #CKMC_ERROR_DB_ERROR          Failed due to a database error
 130  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN  Alias does not exist
 131  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 132  *
 133  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 134  *
 135  * @see ckmc_save_key()
 136  * @see ckmc_remove_key()
 137  * @see ckmc_get_key_alias_list()
 138  */
 139 int ckmc_get_key(const char *alias, const char *password, ckmc_key_s **ppkey);
 140
 141 /**
 142  * @brief Gets all the alias of keys that the client can access.
 143  *
 144  * @since_tizen 2.3
 145  * @privlevel public
 146  * @privilege %http://tizen.org/privilege/keymanager
 147  *
 148  * @remarks A client can access only data stored by the client.
 149  * @remarks You must destroy the newly created @a ppalias_list by calling ckmc_alias_list_all_free() if it is no longer needed.
 150  *
 151  * @param[out] ppalias_list  The pointer to a newly created ckmc_alias_list_s handle containing all available alias of keys \n
 152  *                           If there is no available key alias, *ppalias_list will be null.
 153  *
 154  * @return @c 0 on success,
 155  *         otherwise a negative error value
 156  *
 157  * @retval #CKMC_ERROR_NONE              Successful
 158  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 159  * @retval #CKMC_ERROR_DB_LOCKED         A user key is not loaded in memory (a user is not logged in)
 160  * @retval #CKMC_ERROR_DB_ERROR          Failed due to a database error
 161  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN  Alias does not exist
 162  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 163  *
 164  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 165  *
 166  * @see ckmc_save_key()
 167  * @see ckmc_remove_key()
 168  * @see ckmc_get_key()
 169  */
 170 int ckmc_get_key_alias_list(ckmc_alias_list_s** ppalias_list);
 171
 172
 173
 174
 175 /**
 176  * @brief Stores a certificate inside key manager based on the provided policy.
 177  *
 178  * @since_tizen 2.3
 179  * @privlevel public
 180  * @privilege %http://tizen.org/privilege/keymanager
 181  *
 182  * @remarks the certificate's binary value will be converted and saved as binary DER encoded certificates.
 183  *
 184  * @param[in] alias  The name of a certificate to be stored
 185  * @param[in] cert   The certificate's binary value to be stored
 186  * @param[in] policy The policy about how to store a certificate securely
 187  *
 188  * @return @c 0 on success,
 189  *         otherwise a negative error value
 190  *
 191  * @retval #CKMC_ERROR_NONE               Successful
 192  * @retval #CKMC_ERROR_INVALID_PARAMETER  Input parameter is invalid
 193  * @retval #CKMC_ERROR_DB_LOCKED          A user key is not loaded in memory (a user is not logged in)
 194  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS    Alias already exists
 195  * @retval #CKMC_ERROR_INVALID_FORMAT     The format of raw_cert is not valid
 196  * @retval #CKMC_ERROR_DB_ERROR           Failed due to a database error
 197  * @retval #CKMC_ERROR_PERMISSION_DENIED  Failed to access key manager
 198  *
 199  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 200  *
 201  * @see ckmc_remove_cert()
 202  * @see ckmc_get_cert()
 203  * @see ckmc_get_cert_alias_list()
 204  * @see #ckmc_cert_s
 205  * @see #ckmc_policy_s
 206  */
 207 int ckmc_save_cert(const char *alias, const ckmc_cert_s cert, const ckmc_policy_s policy);
 208
 209 /**
 210  * @brief Removes a certificate from key manager.
 211  *
 212  * @since_tizen 2.3
 213  * @privlevel public
 214  * @privilege %http://tizen.org/privilege/keymanager
 215  *
 216  * @remarks A client can remove only certificates stored by the client.
 217  *
 218  * @param[in] alias The name of a certificate to be removed
 219  *
 220  * @return @c 0 on success,
 221  *         otherwise a negative error value
 222  *
 223  * @retval #CKMC_ERROR_NONE               Successful
 224  * @retval #CKMC_ERROR_INVALID_PARAMETER  Input parameter is invalid
 225  * @retval #CKMC_ERROR_DB_LOCKED          A user key is not loaded in memory (a user is not logged in)
 226  * @retval #CKMC_ERROR_DB_ERROR           Failed due to a database error
 227  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN   Alias does not exist
 228  * @retval #CKMC_ERROR_PERMISSION_DENIED  Failed to access key manager
 229  *
 230  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 231  *
 232  * @see ckmc_save_cert()
 233  * @see ckmc_get_cert()
 234  * @see ckmc_get_cert_alias_list()
 235  */
 236 int ckmc_remove_cert(const char *alias);
 237
 238 /**
 239  * @brief Gets a certificate from key manager.
 240  *
 241  * @since_tizen 2.3
 242  * @privlevel public
 243  * @privilege %http://tizen.org/privilege/keymanager
 244  *
 245  * @remarks A client can access only certificate stored by the client.
 246  * @remarks A DER encoded certificate will be returned as a return value.
 247  * @remarks You must destroy the newly created @a ppcert by calling ckmc_cert_free() if it is no longer needed.
 248  *
 249  * @param[in] alias    The name of a certificate to retrieve
 250  * @param[in] password The password used in decrypting a certificate value \n
 251  *                     If password of policy is provided in ckmc_save_cert(), the same password should be provided.
 252  * @param[out] ppcert  The pointer to a newly created ckmc_cert_s handle
 253  *
 254  * @return @c 0 on success,
 255  *         otherwise a negative error value
 256  *
 257  * @retval #CKMC_ERROR_NONE               Successful
 258  * @retval #CKMC_ERROR_INVALID_PARAMETER  Input parameter is invalid
 259  * @retval #CKMC_ERROR_DB_LOCKED          A user key is not loaded in memory (a user is not logged in)
 260  * @retval #CKMC_ERROR_DB_ERROR           Failed due to a database error
 261  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN   Alias does not exists
 262  * @retval #CKMC_ERROR_PERMISSION_DENIED  Failed to access key manager
 263  *
 264  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 265  *
 266  * @see ckmc_save_cert()
 267  * @see ckmc_remove_cert()
 268  * @see ckmc_get_cert_alias_list()
 269  */
 270 int ckmc_get_cert(const char *alias, const char *password, ckmc_cert_s **ppcert);
 271
 272 /**
 273  * @brief Gets all alias of certificates which the client can access.
 274  *
 275  * @since_tizen 2.3
 276  * @privlevel public
 277  * @privilege %http://tizen.org/privilege/keymanager
 278  *
 279  * @remarks A client can access only data stored by the client.
 280  * @remarks You must destroy the newly created @a ppalias_list by calling ckmc_alias_list_all_free() if it is no longer needed.
 281  *
 282  * @param[out] ppalias_list The pointer to a newly created ckmc_alias_list_s handle containing all available alias of keys \n
 283  *                          If there is no available key alias, *ppalias_list will be null.
 284  *
 285  * @return @c 0 on success,
 286  *         otherwise a negative error value
 287  *
 288  * @retval #CKMC_ERROR_NONE               Successful
 289  * @retval #CKMC_ERROR_INVALID_PARAMETER  Input parameter is invalid
 290  * @retval #CKMC_ERROR_DB_LOCKED          A user key is not loaded in memory (a user is not logged in)
 291  * @retval #CKMC_ERROR_DB_ERROR           Failed due to a database error
 292  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN   Alias does not exist
 293  * @retval #CKMC_ERROR_PERMISSION_DENIED  Failed to access key manager
 294  *
 295  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 296  *
 297  * @see ckmc_save_cert()
 298  * @see ckmc_remove_cert()
 299  * @see ckmc_get_cert()
 300  */
 301 int ckmc_get_cert_alias_list(ckmc_alias_list_s** ppalias_list);
 302
 303
 304
 305
 306 /**
 307  * @brief Stores PKCS12's contents inside key manager based on the provided policies.
 308  * All items from the PKCS12 will use the same alias.
 309  *
 310  * @since_tizen 2.3
 311  * @privlevel public
 312  * @privilege %http://tizen.org/privilege/keymanager
 313  *
 314  * @param[in] alias         The name of a data to be stored
 315  * @param[in] pkcs          Pointer to the pkcs12 structure to be saved
 316  * @param[in] key_policy    The policy about how to store pkcs's private key
 317  * @param[in] cert_policy   The policy about how to store pkcs's certificate
 318  *
 319  * @return @c 0 on success,
 320  *         otherwise a negative error value
 321  *
 322  * @retval #CKMC_ERROR_NONE               Successful
 323  * @retval #CKMC_ERROR_INVALID_PARAMETER  Input parameter is invalid
 324  * @retval #CKMC_ERROR_DB_LOCKED          A user key is not loaded in memory (a user is not logged in)
 325  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS    Alias already exists
 326  * @retval #CKMC_ERROR_DB_ERROR           Failed due to a database error
 327  * @retval #CKMC_ERROR_PERMISSION_DENIED  Failed to access key manager
 328  *
 329  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 330  *
 331  * @see ckmc_remove_pkcs12()
 332  * @see ckmc_get_pkcs12()
 333  * @see ckmc_get_data_alias_list()
 334  * @see ckmc_load_from_pkcs12_file2()
 335  * @see #ckmc_pkcs12_s
 336  * @see #ckmc_policy_s
 337  */
 338 int ckmc_save_pkcs12(const char *alias, const ckmc_pkcs12_s *pkcs, const ckmc_policy_s key_policy, const ckmc_policy_s cert_policy);
 339
 340 /**
 341  * @brief Removes all pkcs12 contents from key manager.
 342  *
 343  * @since_tizen 2.3
 344  * @privlevel public
 345  * @privilege %http://tizen.org/privilege/keymanager
 346  *
 347  * @remarks A client can remove only data stored by the client.
 348  *
 349  * @param[in] alias The name of pkcs12 to be removed
 350  *
 351  * @return @c 0 on success,
 352  *         otherwise a negative error value
 353  *
 354  * @retval #CKMC_ERROR_NONE               Successful
 355  * @retval #CKMC_ERROR_INVALID_PARAMETER  Input parameter is invalid
 356  * @retval #CKMC_ERROR_DB_LOCKED          A user key is not loaded in memory (a user is not logged in)
 357  * @retval #CKMC_ERROR_DB_ERROR           Failed due to a database error
 358  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN   Alias does not exist
 359  * @retval #CKMC_ERROR_PERMISSION_DENIED  Failed to access key manager
 360  *
 361  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 362  *
 363  * @see ckmc_save_pkcs12()
 364  * @see ckmc_get_pkcs12()
 365  */
 366 int ckmc_remove_pkcs12(const char *alias);
 367
 368 /**
 369  * @brief Gets a pkcs12 from key manager.
 370  *
 371  * @since_tizen 2.3
 372  * @privlevel public
 373  * @privilege %http://tizen.org/privilege/keymanager
 374  *
 375  * @remarks A client can access only data stored by the client.
 376  * @remarks You must destroy the newly created @a pkcs12 by calling ckmc_pkcs12_free() if it is no longer needed.
 377  *
 378  * @param[in]  alias     The name of a data to retrieve
 379  * @param[out] pkcs12    The pointer to a newly created ckmc_pkcs12_s handle
 380  *
 381  * @return @c 0 on success,
 382  *         otherwise a negative error value
 383  *
 384  * @retval #CKMC_ERROR_NONE               Successful
 385  * @retval #CKMC_ERROR_INVALID_PARAMETER  Input parameter is invalid
 386  * @retval #CKMC_ERROR_DB_LOCKED          A user key is not loaded in memory (a user is not logged in)
 387  * @retval #CKMC_ERROR_DB_ERROR           Failed due to a database error
 388  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN   Alias does not exist
 389  * @retval #CKMC_ERROR_PERMISSION_DENIED  Failed to access key manager
 390  *
 391  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 392  *
 393  * @see ckmc_save_pkcs12()
 394  * @see ckmc_remove_pkcs12()
 395  */
 396 int ckmc_get_pkcs12(const char *alias, ckmc_pkcs12_s **pkcs12);
 397
 398
 399
 400
 401 /**
 402  * @brief Stores a data inside key manager based on the provided policy.
 403  *
 404  * @since_tizen 2.3
 405  * @privlevel public
 406  * @privilege %http://tizen.org/privilege/keymanager
 407  *
 408  * @param[in] alias  The name of a data to be stored
 409  * @param[in] data   The binary value to be stored
 410  * @param[in] policy The policy about how to store a data securely
 411  *
 412  * @return @c 0 on success,
 413  *         otherwise a negative error value
 414  *
 415  * @retval #CKMC_ERROR_NONE               Successful
 416  * @retval #CKMC_ERROR_INVALID_PARAMETER  Input parameter is invalid
 417  * @retval #CKMC_ERROR_DB_LOCKED          A user key is not loaded in memory (a user is not logged in)
 418  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS    Alias already exists
 419  * @retval #CKMC_ERROR_DB_ERROR           Failed due to a database error
 420  * @retval #CKMC_ERROR_PERMISSION_DENIED  Failed to access key manager
 421  *
 422  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 423  *
 424  * @see ckmc_remove_data()
 425  * @see ckmc_get_data()
 426  * @see ckmc_get_data_alias_list()
 427  * @see #ckmc_raw_buffer_s
 428  * @see #ckmc_policy_s
 429  */
 430 int ckmc_save_data(const char *alias, ckmc_raw_buffer_s data, const ckmc_policy_s policy);
 431
 432 /**
 433  * @brief Removes a data from key manager.
 434  *
 435  * @since_tizen 2.3
 436  * @privlevel public
 437  * @privilege %http://tizen.org/privilege/keymanager
 438  *
 439  * @remarks A client can remove only data stored by the client.
 440  *
 441  * @param[in] alias The name of a data to be removed
 442  *
 443  * @return @c 0 on success,
 444  *         otherwise a negative error value
 445  *
 446  * @retval #CKMC_ERROR_NONE               Successful
 447  * @retval #CKMC_ERROR_INVALID_PARAMETER  Input parameter is invalid
 448  * @retval #CKMC_ERROR_DB_LOCKED          A user key is not loaded in memory (a user is not logged in)
 449  * @retval #CKMC_ERROR_DB_ERROR           Failed due to the error with unknown reason
 450  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN   Alias does not exist
 451  * @retval #CKMC_ERROR_PERMISSION_DENIED  Failed to access key manager
 452  *
 453  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 454  *
 455  * @see ckmc_save_data()
 456  * @see ckmc_get_data()
 457  * @see ckmc_get_data_alias_list()
 458  */
 459 int ckmc_remove_data(const char *alias);
 460
 461 /**
 462  * @brief Gets a data from key manager.
 463  *
 464  * @since_tizen 2.3
 465  * @privlevel public
 466  * @privilege %http://tizen.org/privilege/keymanager
 467  *
 468  * @remarks A client can access only data stored by the client.
 469  * @remarks You must destroy the newly created @a ppdata by calling ckmc_buffer_free() if it is no longer needed.
 470  *
 471  * @param[in]  alias     The name of a data to retrieve
 472  * @param[in]  password  The password used in decrypting a data value \n
 473  *                       If password of policy is provided in ckmc_save_data(), the same password should be provided.
 474  * @param[out] ppdata    The pointer to a newly created ckmc_raw_buffer_s handle
 475  *
 476  * @return @c 0 on success,
 477  *         otherwise a negative error value
 478  *
 479  * @retval #CKMC_ERROR_NONE               Successful
 480  * @retval #CKMC_ERROR_INVALID_PARAMETER  Input parameter is invalid
 481  * @retval #CKMC_ERROR_DB_LOCKED          A user key is not loaded in memory (a user is not logged in)
 482  * @retval #CKMC_ERROR_DB_ERROR           Failed due to the error with unknown reason
 483  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN   Alias does not exist
 484  * @retval #CKMC_ERROR_PERMISSION_DENIED  Failed to access key manager
 485  *
 486  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 487  *
 488  * @see ckmc_save_data()
 489  * @see ckmc_remove_data()
 490  * @see ckmc_get_data_alias_list()
 491  */
 492 int ckmc_get_data(const char *alias, const char *password, ckmc_raw_buffer_s **ppdata);
 493
 494 /**
 495  * @brief Gets all alias of data which the client can access.
 496  *
 497  * @since_tizen 2.3
 498  * @privlevel public
 499  * @privilege %http://tizen.org/privilege/keymanager
 500  *
 501  * @remarks A client can access only data stored by the client.
 502  * @remarks You must destroy the newly created @a ppalias_list by calling ckmc_alias_list_all_free() if it is no longer needed.
 503  *
 504  * @param[out] ppalias_list The pointer to a newly created ckmc_alias_list_s handle containing all available alias of keys \n
 505  *                          If there is no available key alias, *ppalias_list will be null.
 506  *
 507  * @return @c 0 on success,
 508  *         otherwise a negative error value
 509  *
 510  * @retval #CKMC_ERROR_NONE               Successful
 511  * @retval #CKMC_ERROR_INVALID_PARAMETER  Input parameter is invalid
 512  * @retval #CKMC_ERROR_DB_LOCKED          A user key is not loaded in memory (a user is not logged in)
 513  * @retval #CKMC_ERROR_DB_ERROR           Failed due to the error with unknown reason
 514  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN   Alias does not exist
 515  * @retval #CKMC_ERROR_PERMISSION_DENIED  Failed to access key manager
 516  *
 517  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 518  *
 519  * @see ckmc_save_data()
 520  * @see ckmc_remove_data()
 521  * @see ckmc_get_data()
 522  */
 523 int ckmc_get_data_alias_list(ckmc_alias_list_s** ppalias_list);
 524
 525
 526
 527
 528 /**
 529  * @brief Creates RSA private/public key pair and stores them inside key manager based on each policy.
 530  *
 531  * @since_tizen 2.3
 532  * @privlevel public
 533  * @privilege %http://tizen.org/privilege/keymanager
 534  *
 535  * @remarks If password in policy is provided, the key is additionally encrypted with the password in policy.
 536  *
 537  * @param[in] size                The size of key strength to be created \n
 538  *                                @c 1024, @c 2048, and @c 4096 are supported.
 539  * @param[in] private_key_alias   The name of private key to be stored
 540  * @param[in] public_key_alias    The name of public key to be stored
 541  * @param[in] policy_private_key  The policy about how to store a private key securely
 542  * @param[in] policy_public_key   The policy about how to store a public key securely
 543  *
 544  * @return @c 0 on success,
 545  *         otherwise a negative error value
 546  *
 547  * @retval #CKMC_ERROR_NONE               Successful
 548  * @retval #CKMC_ERROR_INVALID_PARAMETER  Input parameter is invalid
 549  * @retval #CKMC_ERROR_DB_LOCKED          A user key is not loaded in memory (a user is not logged in)
 550  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS    Alias already exists
 551  * @retval #CKMC_ERROR_DB_ERROR           Failed due to other DB transaction unexpectedly
 552  * @retval #CKMC_ERROR_PERMISSION_DENIED  Failed to access key manager
 553  *
 554  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 555  *
 556  * @see ckmc_create_key_pair_dsa()
 557  * @see ckmc_create_key_pair_ecdsa()
 558  * @see ckmc_create_signature()
 559  * @see ckmc_verify_signature()
 560  */
 561 int ckmc_create_key_pair_rsa(const size_t size, const char *private_key_alias, const char *public_key_alias, const ckmc_policy_s policy_private_key, const ckmc_policy_s policy_public_key);
 562
 563 /**
 564  * @brief Creates DSA private/public key pair and stores them inside key manager based on each policy.
 565  *
 566  * @since_tizen 2.3
 567  * @privlevel public
 568  * @privilege %http://tizen.org/privilege/keymanager
 569  *
 570  * @remarks If password in policy is provided, the key is additionally encrypted with the password in policy.
 571  *
 572  * @param[in] size                The size of key strength to be created \n
 573  *                                @c 1024, @c 2048, @c 3072 and @c 4096 are supported.
 574  * @param[in] private_key_alias   The name of private key to be stored
 575  * @param[in] public_key_alias    The name of public key to be stored
 576  * @param[in] policy_private_key  The policy about how to store a private key securely
 577  * @param[in] policy_public_key   The policy about how to store a public key securely
 578  *
 579  * @return @c 0 on success,
 580  *         otherwise a negative error value
 581  *
 582  * @retval #CKMC_ERROR_NONE               Successful
 583  * @retval #CKMC_ERROR_INVALID_PARAMETER  Input parameter is invalid
 584  * @retval #CKMC_ERROR_DB_LOCKED          A user key is not loaded in memory (a user is not logged in)
 585  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS    Alias already exists
 586  * @retval #CKMC_ERROR_DB_ERROR           Failed due to other DB transaction unexpectedly
 587  * @retval #CKMC_ERROR_PERMISSION_DENIED  Failed to access key manager
 588  *
 589  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 590  *
 591  * @see ckmc_create_key_pair_rsa()
 592  * @see ckmc_create_key_pair_ecdsa()
 593  * @see ckmc_create_signature()
 594  * @see ckmc_verify_signature()
 595  */
 596 int ckmc_create_key_pair_dsa(const size_t size, const char *private_key_alias, const char *public_key_alias, const ckmc_policy_s policy_private_key, const ckmc_policy_s policy_public_key);
 597
 598 /**
 599  * @brief Creates ECDSA private/public key pair and stores them inside key manager based on each policy.
 600  *
 601  * @since_tizen 2.3
 602  * @privlevel public
 603  * @privilege %http://tizen.org/privilege/keymanager
 604  *
 605  * @remarks If password in policy is provided, the key is additionally encrypted with the password in policy.
 606  *
 607  * @param[in] type                The type of elliptic curve of ECDSA
 608  * @param[in] private_key_alias   The name of private key to be stored
 609  * @param[in] public_key_alias    The name of public key to be stored
 610  * @param[in] policy_private_key  The policy about how to store a private key securely
 611  * @param[in] policy_public_key   The policy about how to store a public key securely
 612  *
 613  * @return @c 0 on success,
 614  *         otherwise a negative error value
 615  *
 616  * @retval #CKMC_ERROR_NONE               Successful
 617  * @retval #CKMC_ERROR_INVALID_PARAMETER  Input parameter is invalid
 618  * @retval #CKMC_ERROR_DB_LOCKED          A user key is not loaded in memory (a user is not logged in)
 619  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS    Alias already exists
 620  * @retval #CKMC_ERROR_DB_ERROR           Failed due to other DB transaction unexpectedly
 621  * @retval #CKMC_ERROR_PERMISSION_DENIED  Failed to access key manager
 622  *
 623  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 624  *
 625  * @see ckmc_create_key_pair_rsa()
 626  * @see ckmc_create_key_pair_dsa()
 627  * @see ckmc_create_signature()
 628  * @see ckmc_verify_signature()
 629  * @see #ckmc_ec_type_e
 630  */
 631 int ckmc_create_key_pair_ecdsa(const ckmc_ec_type_e type, const char *private_key_alias, const char *public_key_alias, const ckmc_policy_s policy_private_key, const ckmc_policy_s policy_public_key);
 632
 633 /**
 634  * @brief Creates a signature on a given message using a private key and returns the signature.
 635  *
 636  * @since_tizen 2.3
 637  * @privlevel public
 638  * @privilege %http://tizen.org/privilege/keymanager
 639  *
 640  * @remarks If password of policy is provided during storing a key, the same password should be provided.
 641  * @remarks You must destroy the newly created @a ppsignature by calling ckmc_buffer_free() if it is no longer needed.
 642  *
 643  * @param[in]  private_key_alias  The name of private key
 644  * @param[in]  password           The password used in decrypting a private key value
 645  * @param[in]  message            The message that is signed with a private key
 646  * @param[in]  hash               The hash algorithm used in creating signature
 647  * @param[in]  padding            The RSA padding algorithm used in creating signature \n
 648  *                                It is used only when the signature algorithm is RSA.
 649  * @param[out] ppsignature        The pointer to a newly created signature \n
 650  *                                If an error occurs, @a *ppsignature will be null.
 651  *
 652  * @return @c 0 on success,
 653  *         otherwise a negative error value
 654  *
 655  * @retval #CKMC_ERROR_NONE               Successful
 656  * @retval #CKMC_ERROR_INVALID_PARAMETER  Input parameter is invalid
 657  * @retval #CKMC_ERROR_DB_LOCKED          A user key is not loaded in memory (a user is not logged in)
 658  * @retval #CKMC_ERROR_DB_ERROR           Failed due to the error with unknown reason
 659  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN   Alias does not exist
 660  * @retval #CKMC_ERROR_PERMISSION_DENIED  Failed to access key manager
 661  *
 662  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 663  *
 664  * @see ckmc_create_key_pair_rsa()
 665  * @see ckmc_create_key_pair_ecdsa()
 666  * @see ckmc_verify_signature()
 667  * @see ckmc_buffer_free()
 668  * @see #ckmc_hash_algo_e
 669  * @see #ckmc_rsa_padding_algo_e
 670  */
 671 int ckmc_create_signature(const char *private_key_alias, const char *password, const ckmc_raw_buffer_s message, const ckmc_hash_algo_e hash, const ckmc_rsa_padding_algo_e padding, ckmc_raw_buffer_s **ppsignature);
 672
 673 /**
 674  * @brief Verifies a given signature on a given message using a public key and returns the signature status.
 675  *
 676  * @since_tizen 2.3
 677  * @privlevel public
 678  * @privilege %http://tizen.org/privilege/keymanager
 679  *
 680  * @remarks If password of policy is provided during storing a key, the same password should be provided.
 681  *
 682  * @param[in] public_key_alias  The name of public key
 683  * @param[in] password          The password used in decrypting a public key value
 684  * @param[in] message           The input on which the signature is created
 685  * @param[in] signature         The signature that is verified with public key
 686  * @param[in] hash              The hash algorithm used in verifying signature
 687  * @param[in] padding           The RSA padding algorithm used in verifying signature \n
 688  *                              It is used only when the signature algorithm is RSA.
 689  *
 690  * @return @c 0 on success and the signature is valid,
 691  *         otherwise a negative error value
 692  *
 693  * @retval #CKMC_ERROR_NONE                 Successful
 694  * @retval #CKMC_ERROR_VERIFICATION_FAILED  The signature is invalid
 695  * @retval #CKMC_ERROR_INVALID_PARAMETER    Input parameter is invalid
 696  * @retval #CKMC_ERROR_DB_LOCKED            A user key is not loaded in memory (a user is not logged in)
 697  * @retval #CKMC_ERROR_DB_ERROR             Failed due to the error with unknown reason
 698  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN     Alias does not exist
 699  * @retval #CKMC_ERROR_PERMISSION_DENIED    Failed to access key manager
 700  *
 701  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 702  *
 703  * @see ckmc_create_key_pair_rsa()
 704  * @see ckmc_create_key_pair_ecdsa()
 705  * @see ckmc_verify_signature()
 706  * @see #ckmc_hash_algo_e
 707  * @see #ckmc_rsa_padding_algo_e
 708  */
 709 int ckmc_verify_signature(const char *public_key_alias, const char *password, const ckmc_raw_buffer_s message, const ckmc_raw_buffer_s signature, const ckmc_hash_algo_e hash, const ckmc_rsa_padding_algo_e padding);
 710
 711 /**
 712  * @brief Verifies a certificate chain and returns that chain.
 713  *
 714  * @since_tizen 2.3
 715  * @privlevel public
 716  * @privilege %http://tizen.org/privilege/keymanager
 717  *
 718  * @remarks The trusted root certificate of the chain should exist in the system's certificate storage.
 719  * @remarks You must destroy the newly created @a ppcert_chain_list by calling ckmc_cert_list_all_free() if it is no longer needed.
 720  *
 721  * @param[in] cert               The certificate to be verified
 722  * @param[in] untrustedcerts     The untrusted CA certificates to be used in verifying a certificate chain
 723  * @param[out] ppcert_chain_list The pointer to a newly created certificate chain's handle \n
 724  *                               If an error occurs, @a *ppcert_chain_list will be null.
 725  *
 726  * @return @c 0 on success and the signature is valid,
 727  *         otherwise a negative error value
 728  *
 729  * @retval #CKMC_ERROR_NONE                 Successful
 730  * @retval #CKMC_ERROR_VERIFICATION_FAILED  The certificate chain is not valid
 731  * @retval #CKMC_ERROR_INVALID_PARAMETER    Input parameter is invalid
 732  * @retval #CKMC_ERROR_DB_LOCKED            A user key is not loaded in memory (a user is not logged in)
 733  * @retval #CKMC_ERROR_DB_ERROR             Failed due to the error with unknown reason
 734  * @retval #CKMC_ERROR_INVALID_FORMAT       The format of certificate is not valid
 735  * @retval #CKMC_ERROR_PERMISSION_DENIED    Failed to access key manager
 736  *
 737  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 738  *
 739  * @see ckmc_get_cert_chain_with_alias())
 740  * @see ckmc_cert_list_all_free()
 741  */
 742 int ckmc_get_cert_chain(const ckmc_cert_s *cert, const ckmc_cert_list_s *untrustedcerts, ckmc_cert_list_s **ppcert_chain_list);
 743
 744 /**
 745  * @brief Verifies a certificate chain using an alias list of untrusted certificates and return that chain.
 746  *
 747  * @since_tizen 2.3
 748  * @privlevel public
 749  * @privilege %http://tizen.org/privilege/keymanager
 750  *
 751  * @remarks The trusted root certificate of the chain should exist in the system's certificate storage.
 752  * @remarks You must destroy the newly created @a ppcert_chain_list by calling ckmc_cert_list_all_free() if it is no longer needed.
 753  *
 754  * @param[in] cert               The certificate to be verified
 755  * @param[in] untrustedcerts     The alias list of untrusted CA certificates stored in key manager to be used in verifying a certificate chain
 756  * @param[out] ppcert_chain_list The pointer to a newly created certificate chain's handle \n
 757  *                               If an error occurs, @a *ppcert_chain_list will be null.
 758  *
 759  * @return @c 0 on success and the signature is valid,
 760  *         otherwise a negative error value
 761  *
 762  * @retval #CKMC_ERROR_NONE                 Successful
 763  * @retval #CKMC_ERROR_VERIFICATION_FAILED  The certificate chain is not valid
 764  * @retval #CKMC_ERROR_INVALID_PARAMETER    Input parameter is invalid
 765  * @retval #CKMC_ERROR_DB_LOCKED            A user key is not loaded in memory (a user is not logged in)
 766  * @retval #CKMC_ERROR_DB_ERROR             Failed due to the error with unknown reason
 767  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN     Alias does not exist
 768  * @retval #CKMC_ERROR_INVALID_FORMAT       The format of certificate is not valid
 769  * @retval #CKMC_ERROR_PERMISSION_DENIED    Failed to access key manager
 770  *
 771  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 772  *
 773  * @see ckmc_get_cert_chain())
 774  * @see ckmc_cert_list_all_free()
 775  */
 776 int ckmc_get_cert_chain_with_alias(const ckmc_cert_s *cert, const ckmc_alias_list_s *untrustedcerts, ckmc_cert_list_s **ppcert_chain_list);
 777
 778 /**
 779  * @brief Allows another application to access client's application data
 780  *
 781  * @since_tizen 2.3
 782  * @privlevel public
 783  * @privilege %http://tizen.org/privilege/keymanager
 784  *
 785  * @remarks Data identified by @a alias should exist
 786  *
 787  * @param[in] alias       Data alias for which access will be granted
 788  * @param[in] accessor    Package id of the application that will gain access rights
 789  * @param[in] granted     Rights granted for @a accessor application
 790  *
 791  * @return @c 0 on success, otherwise a negative error value
 792  *
 793  * @retval #CKMC_ERROR_NONE                 Successful
 794  * @retval #CKMC_ERROR_INVALID_PARAMETER    Input parameter is invalid
 795  * @retval #CKMC_ERROR_DB_LOCKED            A user key is not loaded in memory (a user is not logged in)
 796  * @retval #CKMC_ERROR_DB_ERROR             Failed due to the error with unknown reason
 797  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN     Alias does not exist
 798  * @retval #CKMC_ERROR_PERMISSION_DENIED    Failed to access key manager
 799  *
 800  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 801  *
 802  * @see ckmc_deny_access()
 803  */
 804 int ckmc_allow_access(const char *alias, const char *accessor, ckmc_access_right_e granted);
 805
 806 /**
 807  * @brief Revokes another application's access to client's application data
 808  *
 809  * @since_tizen 2.3
 810  * @privlevel public
 811  * @privilege %http://tizen.org/privilege/keymanager
 812  *
 813  * @remarks Data identified by @a alias should exist
 814  * @remarks Only access previously granted with ckmc_allow_access can be revoked.
 815  *
 816  * @param[in] alias       Data alias for which access will be revoked
 817  * @param[in] accessor    Package id of the application that will lose access rights
 818  *
 819  * @return @c 0 on success, otherwise a negative error value
 820  *
 821  * @retval #CKMC_ERROR_NONE                 Successful
 822  * @retval #CKMC_ERROR_INVALID_PARAMETER    Input parameter is invalid or the @a accessor doesn't
 823  *                                          have access to @a alias
 824  * @retval #CKMC_ERROR_DB_LOCKED            A user key is not loaded in memory (a user is not logged in)
 825  * @retval #CKMC_ERROR_DB_ERROR             Failed due to the error with unknown reason
 826  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN     Alias does not exist
 827  * @retval #CKMC_ERROR_PERMISSION_DENIED    Failed to access key manager
 828  *
 829  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 830  *
 831  * @see ckmc_allow_access()
 832  */
 833 int ckmc_deny_access(const char *alias, const char *accessor);
 834
 835
 836 #ifdef __cplusplus
 837 }
 838 #endif
 839
 840 /**
 841  * @}
 842  */
 843
 844
 845 #endif /* __TIZEN_CORE_CKMC_MANAGER_H */