src/include/ckmc/ckmc-manager.h

   1 /*
   2  * Copyright (c) 2000 - 2019 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,
  20  *        certificates and data of a user and additional crypto functions.
  21  */
  22
  23
  24 #ifndef __TIZEN_CORE_CKMC_MANAGER_H
  25 #define __TIZEN_CORE_CKMC_MANAGER_H
  26
  27
  28 #include <stddef.h>
  29 #include <sys/types.h>
  30 #include <tizen.h>
  31 #include <ckmc/ckmc-type.h>
  32 #include <ckmc/ckmc-error.h>
  33
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39
  40 /**
  41  * @addtogroup CAPI_KEY_MANAGER_CLIENT_MODULE
  42  * @{
  43  */
  44
  45
  46 /**
  47  * @brief Stores a key inside key manager based on the provided policy.
  48  * @since_tizen 2.3
  49  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
  50  * @remarks Currently API supports seven types of keys. These are RSA public/private key, DSA public/private key, ECDSA public/private key, and AES symmetric key.
  51  * @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.
  52  * @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.
  53  * @remarks If password in policy is provided, the key is additionally encrypted with the password in the policy.
  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  * @return @c 0 on success,
  58  *         otherwise a negative error value
  59  * @retval #CKMC_ERROR_NONE Successful
  60  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
  61  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
  62  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists
  63  * @retval #CKMC_ERROR_INVALID_FORMAT The format of raw_key is not valid
  64  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
  65  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
  66  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
  67  * @see ckmc_remove_alias()
  68  * @see ckmc_get_key()
  69  * @see ckmc_get_key_alias_list()
  70  * @see #ckmc_key_s
  71  * @see #ckmc_policy_s
  72  */
  73 int ckmc_save_key(const char *alias, const ckmc_key_s key, const ckmc_policy_s policy);
  74
  75
  76 /**
  77  * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif [Use ckmc_remove_alias() instead]
  78  * @brief Removes a key from key manager.
  79  * @since_tizen 2.3
  80  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
  81  * @remarks To remove key, client must have remove permission to the specified key.
  82  * @remarks The key owner can remove by default.
  83  * @param[in] alias The name of a key to be removed
  84  * @return @c 0 on success,
  85  *         otherwise a negative error value
  86  * @retval #CKMC_ERROR_NONE Successful
  87  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
  88  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
  89  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
  90  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
  91  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
  92  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
  93  * @see ckmc_save_key()
  94  * @see ckmc_get_key()
  95  * @see ckmc_get_key_alias_list()
  96  */
  97 int ckmc_remove_key(const char *alias)
  98 TIZEN_DEPRECATED_API;
  99
 100
 101 /**
 102  * @brief Gets a key from key manager.
 103  * @since_tizen 2.3
 104  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 105  * @remarks A client can access only data stored by the client.
 106  * @remarks You must destroy the newly created @a ppkey by calling ckmc_key_free() if it is no longer needed.
 107  * @param[in] alias The name of a key to retrieve
 108  * @param[in] password The password used in decrypting a key value \n
 109  *                     If password of policy is provided in ckmc_save_key(), the same password should be provided
 110  * @param[out] ppkey The pointer to a newly created ckmc_key_s handle
 111  * @return @c 0 on success,
 112  *         otherwise a negative error value
 113  * @retval #CKMC_ERROR_NONE Successful
 114  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 115  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 116  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 117  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 118  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 119  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Decryption failed because password is incorrect
 120  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 121  * @see ckmc_save_key()
 122  * @see ckmc_remove_alias()
 123  * @see ckmc_get_key_alias_list()
 124  */
 125 int ckmc_get_key(const char *alias, const char *password, ckmc_key_s **ppkey);
 126
 127
 128 /**
 129  * @brief Gets all the alias of keys that the client can access.
 130  * @since_tizen 2.3
 131  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 132  * @remarks A client can access only data stored by the client.
 133  * @remarks You must destroy the newly created @a ppalias_list by calling ckmc_alias_list_all_free()
 134  *          if it is no longer needed.
 135  * @param[out] ppalias_list The pointer to a newly created ckmc_alias_list_s handle containing all
 136  *                          available alias of keys \n
 137  *                          If there is no available key alias, *ppalias_list will be null
 138  * @return @c 0 on success,
 139  *         otherwise a negative error value
 140  * @retval #CKMC_ERROR_NONE Successful
 141  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 142  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 143  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 144  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 145  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 146  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 147  * @see ckmc_save_key()
 148  * @see ckmc_remove_alias()
 149  * @see ckmc_get_key()
 150  */
 151 int ckmc_get_key_alias_list(ckmc_alias_list_s **ppalias_list);
 152
 153
 154 /**
 155  * @brief Gets the information about all the aliases of keys that the client can access.
 156  * @since_tizen 5.5
 157  * @remarks A client can access only data stored by the client and the entries from system database
 158  * if it was explicitly permitted to.
 159  * @remarks You must destroy the newly created @a ppalias_list by calling ckmc_alias_info_list_all_free()
 160  *          if it is no longer needed.
 161  * @param[out] ppalias_list The pointer to a newly created ckmc_alias_info_list_s handle containing
 162  *                          information about all key aliases \n
 163  *                          If there is no available key alias, *ppalias_list will be null
 164  * @return @c 0 on success,
 165  *         otherwise a negative error value
 166  * @retval #CKMC_ERROR_NONE Successful
 167  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 168  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 169  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 170  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 171  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 172  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 173  * @see ckmc_save_key()
 174  * @see ckmc_remove_alias()
 175  * @see ckmc_get_key()
 176  */
 177 int ckmc_get_key_alias_info_list(ckmc_alias_info_list_s **ppalias_list);
 178
 179
 180 /**
 181  * @brief Stores a certificate inside key manager based on the provided policy.
 182  * @since_tizen 2.3
 183  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0
 184  * @remarks The certificate's binary value will be converted and saved as binary DER encoded certificates.
 185  * @param[in] alias The name of a certificate to be stored
 186  * @param[in] cert The certificate's binary value to be stored
 187  * @param[in] policy The policy about how to store a certificate securely
 188  * @return @c 0 on success,
 189  *         otherwise a negative error value
 190  * @retval #CKMC_ERROR_NONE Successful
 191  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 192  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 193  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists
 194  * @retval #CKMC_ERROR_INVALID_FORMAT The format of raw_cert is not valid
 195  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 196  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 197  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 198  * @see ckmc_remove_alias()
 199  * @see ckmc_get_cert()
 200  * @see ckmc_get_cert_alias_list()
 201  * @see #ckmc_cert_s
 202  * @see #ckmc_policy_s
 203  */
 204 int ckmc_save_cert(const char *alias, const ckmc_cert_s cert, const ckmc_policy_s policy);
 205
 206
 207 /**
 208  * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif [Use ckmc_remove_alias() instead]
 209  * @brief Removes a certificate from key manager.
 210  * @since_tizen 2.3
 211  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 212  * @remarks To remove certificate, client must have remove permission to the specified certificate.
 213  * @remarks The key owner can remove by default.
 214  * @param[in] alias The name of a certificate to be removed
 215  * @return @c 0 on success,
 216  *         otherwise a negative error value
 217  * @retval #CKMC_ERROR_NONE Successful
 218  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 219  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 220  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 221  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 222  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 223  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 224  * @see ckmc_save_cert()
 225  * @see ckmc_get_cert()
 226  * @see ckmc_get_cert_alias_list()
 227  */
 228 int ckmc_remove_cert(const char *alias)
 229 TIZEN_DEPRECATED_API;
 230
 231
 232 /**
 233  * @brief Gets a certificate from key manager.
 234  * @since_tizen 2.3
 235  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 236  * @remarks A client can access only certificate stored by the client.
 237  * @remarks A DER encoded certificate will be returned as a return value.
 238  * @remarks You must destroy the newly created @a ppcert by calling ckmc_cert_free() if it is no longer needed.
 239  * @param[in] alias The name of a certificate to retrieve
 240  * @param[in] password The password used in decrypting a certificate value \n
 241  *                     If password of policy is provided in ckmc_save_cert(), the same password
 242  *                     should be provided
 243  * @param[out] ppcert The pointer to a newly created ckmc_cert_s handle
 244  * @return @c 0 on success,
 245  *         otherwise a negative error value
 246  * @retval #CKMC_ERROR_NONE Successful
 247  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 248  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 249  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 250  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exists
 251  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 252  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Decryption failed because password is incorrect
 253  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 254  * @see ckmc_save_cert()
 255  * @see ckmc_remove_alias()
 256  * @see ckmc_get_cert_alias_list()
 257  */
 258 int ckmc_get_cert(const char *alias, const char *password, ckmc_cert_s **ppcert);
 259
 260
 261 /**
 262  * @brief Gets all alias of certificates which the client can access.
 263  * @since_tizen 2.3
 264  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 265  * @remarks A client can access only data stored by the client.
 266  * @remarks You must destroy the newly created @a ppalias_list by calling ckmc_alias_list_all_free() if it is no longer needed.
 267  * @param[out] ppalias_list The pointer to a newly created ckmc_alias_list_s handle containing all available alias of keys \n
 268  *                          If there is no available key alias, *ppalias_list will be null
 269  * @return @c 0 on success,
 270  *         otherwise a negative error value
 271  * @retval #CKMC_ERROR_NONE Successful
 272  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 273  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 274  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 275  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 276  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 277  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 278  * @see ckmc_save_cert()
 279  * @see ckmc_remove_alias()
 280  * @see ckmc_get_cert()
 281  */
 282 int ckmc_get_cert_alias_list(ckmc_alias_list_s **ppalias_list);
 283
 284
 285 /**
 286  * @brief Gets the information about all the aliases of certificates that the client can access.
 287  * @since_tizen 5.5
 288  * @remarks A client can access only data stored by the client and the entries from system database
 289  * if it was explicitly permitted to.
 290  * @remarks You must destroy the newly created @a ppalias_list by calling ckmc_alias_info_list_all_free()
 291  *          if it is no longer needed.
 292  * @param[out] ppalias_list The pointer to a newly created ckmc_alias_info_list_s handle containing
 293  *                          information about all certificate aliases \n
 294  *                          If there is no available certificate alias, *ppalias_list will be null
 295  * @return @c 0 on success,
 296  *         otherwise a negative error value
 297  * @retval #CKMC_ERROR_NONE Successful
 298  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 299  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 300  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 301  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 302  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 303  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 304  * @see ckmc_save_cert()
 305  * @see ckmc_remove_alias()
 306  * @see ckmc_get_cert()
 307  */
 308 int ckmc_get_cert_alias_info_list(ckmc_alias_info_list_s **ppalias_list);
 309
 310
 311 /**
 312  * @brief Stores PKCS12's contents inside key manager based on the provided policies. All items from the PKCS12 will use the same alias.
 313  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 314  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 315  * @param[in] alias The name of a data to be stored
 316  * @param[in] pkcs Pointer to the pkcs12 structure to be saved
 317  * @param[in] key_policy The policy about how to store pkcs's private key
 318  * @param[in] cert_policy The policy about how to store pkcs's certificate
 319  * @return @c 0 on success,
 320  *         otherwise a negative error value
 321  * @retval #CKMC_ERROR_NONE Successful
 322  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 323  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 324  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists
 325  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 326  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 327  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 328  * @see ckmc_remove_alias()
 329  * @see ckmc_get_pkcs12()
 330  * @see ckmc_get_data_alias_list()
 331  * @see ckmc_pkcs12_load()
 332  * @see #ckmc_pkcs12_s
 333  * @see #ckmc_policy_s
 334  */
 335 int ckmc_save_pkcs12(const char *alias, const ckmc_pkcs12_s *pkcs, const ckmc_policy_s key_policy,const ckmc_policy_s cert_policy);
 336
 337
 338 /**
 339  * @brief Gets a pkcs12 from key manager.
 340  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 341  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 342  * @remarks A client can access only data stored by the client.
 343  * @remarks You must destroy the newly created @a pkcs12 by calling ckmc_pkcs12_free() if it is no longer needed.
 344  * @param[in] alias The name of a data to retrieve
 345  * @param[in] key_password Password that was used to encrypt privateKey (may be NULL)
 346  * @param[in] cert_password Password used to encrypt certificates (may be NULL)
 347  * @param[out] pkcs12 The pointer to a newly created ckmc_pkcs12_s handle
 348  * @return @c 0 on success,
 349  *         otherwise a negative error value
 350  * @retval #CKMC_ERROR_NONE Successful
 351  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 352  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 353  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 354  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 355  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 356  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED key_password or cert_password does not match with password used to encrypt data
 357  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 358  * @see ckmc_save_pkcs12()
 359  * @see ckmc_remove_alias()
 360  */
 361 int ckmc_get_pkcs12(const char *alias, const char *key_password, const char *cert_password, ckmc_pkcs12_s **pkcs12);
 362
 363
 364 /**
 365  * @brief Stores a data inside key manager based on the provided policy.
 366  * @since_tizen 2.3
 367  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 368  * @param[in] alias The name of a data to be stored
 369  * @param[in] data The binary value to be stored
 370  * @param[in] policy The policy about how to store a data securely
 371  * @return @c 0 on success,
 372  *         otherwise a negative error value
 373  * @retval #CKMC_ERROR_NONE Successful
 374  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 375  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 376  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists
 377  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 378  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 379  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 380  * @see ckmc_remove_alias()
 381  * @see ckmc_get_data()
 382  * @see ckmc_get_data_alias_list()
 383  * @see #ckmc_raw_buffer_s
 384  * @see #ckmc_policy_s
 385  */
 386 int ckmc_save_data(const char *alias, ckmc_raw_buffer_s data, const ckmc_policy_s policy);
 387
 388
 389 /**
 390  * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif [Use ckmc_remove_alias() instead]
 391  * @brief Removes a data from key manager.
 392  * @since_tizen 2.3
 393  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 394  * @remarks To remove data, client must have remove permission to the specified data object.
 395  * @remarks The data owner can remove by default.
 396  * @param[in] alias The name of a data to be removed
 397  * @return @c 0 on success,
 398  *         otherwise a negative error value
 399  * @retval #CKMC_ERROR_NONE Successful
 400  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 401  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 402  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 403  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 404  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 405  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 406  * @see ckmc_save_data()
 407  * @see ckmc_get_data()
 408  * @see ckmc_get_data_alias_list()
 409  */
 410 int ckmc_remove_data(const char *alias)
 411 TIZEN_DEPRECATED_API;
 412
 413
 414 /**
 415  * @brief Gets a data from key manager.
 416  * @since_tizen 2.3
 417  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 418  * @remarks A client can access only data stored by the client.
 419  * @remarks You must destroy the newly created @a ppdata by calling ckmc_buffer_free() if it is no longer needed.
 420  * @param[in] alias The name of a data to retrieve
 421  * @param[in] password The password used in decrypting a data value \n
 422  *                     If password of policy is provided in ckmc_save_data(), the same password
 423  *                     should be provided
 424  * @param[out] ppdata The pointer to a newly created ckmc_raw_buffer_s handle
 425  * @return @c 0 on success,
 426  *         otherwise a negative error value
 427  * @retval #CKMC_ERROR_NONE Successful
 428  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 429  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 430  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 431  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 432  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 433  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Decryption failed because password is incorrect
 434  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 435  * @see ckmc_save_data()
 436  * @see ckmc_remove_alias()
 437  * @see ckmc_get_data_alias_list()
 438  */
 439 int ckmc_get_data(const char *alias, const char *password, ckmc_raw_buffer_s **ppdata);
 440
 441
 442 /**
 443  * @brief Gets all alias of data which the client can access.
 444  * @since_tizen 2.3
 445  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 446  * @remarks A client can access only data stored by the client.
 447  * @remarks You must destroy the newly created @a ppalias_list by calling ckmc_alias_list_all_free() if it is no longer needed.
 448  * @param[out] ppalias_list The pointer to a newly created ckmc_alias_list_s handle containing all available alias of keys \n
 449  *                          If there is no available key alias, *ppalias_list will be null
 450  * @return @c 0 on success,
 451  *         otherwise a negative error value
 452  * @retval #CKMC_ERROR_NONE Successful
 453  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 454  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 455  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 456  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 457  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 458  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 459  * @see ckmc_save_data()
 460  * @see ckmc_remove_alias()
 461  * @see ckmc_get_data()
 462  */
 463 int ckmc_get_data_alias_list(ckmc_alias_list_s **ppalias_list);
 464
 465
 466 /**
 467  * @brief Gets the information about all the aliases of data that the client can access.
 468  * @since_tizen 5.5
 469  * @remarks A client can access only data stored by the client and the entries from system database
 470  * if it was explicitly permitted to.
 471  * @remarks You must destroy the newly created @a ppalias_list by calling ckmc_alias_info_list_all_free()
 472  * if it is no longer needed.
 473  * @param[out] ppalias_list The pointer to a newly created ckmc_alias_info_list_s handle containing
 474  *                          information about all data aliases \n
 475  *                          If there is no available data alias, *ppalias_list will be null
 476  * @return @c 0 on success,
 477  *         otherwise a negative error value
 478  * @retval #CKMC_ERROR_NONE Successful
 479  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 480  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 481  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 482  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 483  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 484  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 485  * @see ckmc_save_data()
 486  * @see ckmc_remove_alias()
 487  * @see ckmc_get_data()
 488  */
 489 int ckmc_get_data_alias_info_list(ckmc_alias_info_list_s **ppalias_list);
 490
 491
 492 /**
 493  * @brief Creates RSA private/public key pair and stores them inside key manager based on each policy.
 494  * @since_tizen 2.3
 495  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 496  * @remarks If password in the policy is provided, the key is additionally encrypted with the password in the policy.
 497  * @param[in] size The size of key strength to be created \n
 498  *                 @c 1024, @c 2048, and @c 4096 are supported
 499  * @param[in] private_key_alias The name of private key to be stored
 500  * @param[in] public_key_alias The name of public key to be stored
 501  * @param[in] policy_private_key The policy about how to store a private key securely
 502  * @param[in] policy_public_key The policy about how to store a public key securely
 503  * @return @c 0 on success,
 504  *         otherwise a negative error value
 505  * @retval #CKMC_ERROR_NONE Successful
 506  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 507  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 508  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists
 509  * @retval #CKMC_ERROR_DB_ERROR Failed due to other DB transaction unexpectedly
 510  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 511  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 512  * @see ckmc_create_key_pair_dsa()
 513  * @see ckmc_create_key_pair_ecdsa()
 514  * @see ckmc_create_signature()
 515  * @see ckmc_verify_signature()
 516  */
 517 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);
 518
 519
 520 /**
 521  * @brief Creates DSA private/public key pair and stores them inside key manager based on each policy.
 522  * @since_tizen 2.3
 523  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 524  * @remarks If password in the policy is provided, the key is additionally encrypted with the password in the policy.
 525  * @param[in] size The size of key strength to be created \n
 526  *                 @c 1024, @c 2048, @c 3072 and @c 4096 are supported
 527  * @param[in] private_key_alias The name of private key to be stored
 528  * @param[in] public_key_alias The name of public key to be stored
 529  * @param[in] policy_private_key The policy about how to store a private key securely
 530  * @param[in] policy_public_key The policy about how to store a public key securely
 531  * @return @c 0 on success,
 532  *         otherwise a negative error value
 533  * @retval #CKMC_ERROR_NONE Successful
 534  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 535  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 536  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists
 537  * @retval #CKMC_ERROR_DB_ERROR Failed due to other DB transaction unexpectedly
 538  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 539  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 540  * @see ckmc_create_key_pair_rsa()
 541  * @see ckmc_create_key_pair_ecdsa()
 542  * @see ckmc_create_signature()
 543  * @see ckmc_verify_signature()
 544  */
 545 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);
 546
 547
 548 /**
 549  * @brief Creates ECDSA private/public key pair and stores them inside key manager based on each policy.
 550  * @since_tizen 2.3
 551  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 552  * @remarks If password in the policy is provided, the key is additionally encrypted with the password in the policy.
 553  * @param[in] type The type of elliptic curve of ECDSA
 554  * @param[in] private_key_alias The name of private key to be stored
 555  * @param[in] public_key_alias The name of public key to be stored
 556  * @param[in] policy_private_key The policy about how to store a private key securely
 557  * @param[in] policy_public_key The policy about how to store a public key securely
 558  * @return @c 0 on success,
 559  *         otherwise a negative error value
 560  * @retval #CKMC_ERROR_NONE Successful
 561  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 562  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 563  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists
 564  * @retval #CKMC_ERROR_DB_ERROR Failed due to other DB transaction unexpectedly
 565  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 566  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 567  * @see ckmc_create_key_pair_rsa()
 568  * @see ckmc_create_key_pair_dsa()
 569  * @see ckmc_create_signature()
 570  * @see ckmc_verify_signature()
 571  * @see #ckmc_ec_type_e
 572  */
 573 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);
 574
 575
 576 /**
 577  * @brief Creates AES key and stores it inside key manager based on the policy.
 578  * @since_tizen 3.0
 579  * @remarks If password in the policy is provided, the key is additionally encrypted with the password in the policy.
 580  * @param[in] size The size of key strength to be created \n
 581  *                 @c 128, @c 192 and @c 256 are supported
 582  * @param[in] key_alias The name of key to be stored
 583  * @param[in] key_policy The policy about how to store the key securely
 584  * @return @c 0 on success,
 585  *         otherwise a negative error value
 586  * @retval #CKMC_ERROR_NONE Successful
 587  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 588  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 589  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists
 590  * @retval #CKMC_ERROR_DB_ERROR Failed due to other DB transaction unexpectedly
 591  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 592  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 593  * @see ckmc_create_key_pair_rsa()
 594  * @see ckmc_create_key_pair_dsa()
 595  * @see ckmc_create_key_pair_ecdsa()
 596  * @see #ckmc_policy_s
 597  */
 598 int ckmc_create_key_aes(size_t size, const char *key_alias, ckmc_policy_s key_policy);
 599
 600
 601 /**
 602  * @brief Creates a signature on a given message using a private key and returns the signature.
 603  * @since_tizen 2.3
 604  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 605  * @remarks If password of policy is provided during storing a key, the same password should be provided.
 606  * @remarks You must destroy the newly created @a ppsignature by calling ckmc_buffer_free() if it is no longer needed.
 607  * @param[in] private_key_alias The name of private key
 608  * @param[in] password The password used in decrypting a private key value
 609  * @param[in] message The message that is signed with a private key
 610  * @param[in] hash The hash algorithm used in creating signature. CKMC_HASH_NONE is invalid for DSA & ECDSA
 611  * @param[in] padding The RSA padding algorithm used in creating signature \n
 612  *                    It is used only when the signature algorithm is RSA. If
 613  *                    @a padding is CKMC_NONE_PADDING you must use CKMC_HASH_NONE
 614  *                    and the message must be equal to key length
 615  * @param[out] ppsignature The pointer to a newly created signature \n
 616  *                         If an error occurs, @a *ppsignature will be null
 617  * @return @c 0 on success,
 618  *         otherwise a negative error value
 619  * @retval #CKMC_ERROR_NONE Successful
 620  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 621  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 622  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 623  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 624  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 625  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Decryption failed because password is incorrect
 626  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 627  * @see ckmc_create_key_pair_rsa()
 628  * @see ckmc_create_key_pair_ecdsa()
 629  * @see ckmc_verify_signature()
 630  * @see ckmc_buffer_free()
 631  * @see #ckmc_hash_algo_e
 632  * @see #ckmc_rsa_padding_algo_e
 633  */
 634 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);
 635
 636
 637 /**
 638  * @brief Verifies a given signature on a given message using a public key and returns the signature status.
 639  * @since_tizen 2.3
 640  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 641  * @remarks If password of policy is provided during storing a key, the same password should be provided.
 642  * @param[in] public_key_alias The name of public key
 643  * @param[in] password The password used in decrypting a public key value
 644  * @param[in] message The input on which the signature is created
 645  * @param[in] signature The signature that is verified with public key
 646  * @param[in] hash The hash algorithm used in verifying signature. CKMC_HASH_NONE is invalid for DSA & ECDSA
 647  * @param[in] padding The RSA padding algorithm used in verifying signature \n
 648  *                    It is used only when the signature algorithm is RSA. If
 649  *                    @a padding is CKMC_NONE_PADDING you must use CKMC_HASH_NONE
 650  *                    and the message must be equal to key length
 651  * @return @c 0 on success and the signature is valid,
 652  *         otherwise a negative error value
 653  * @retval #CKMC_ERROR_NONE Successful
 654  * @retval #CKMC_ERROR_VERIFICATION_FAILED The signature is invalid
 655  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 656  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 657  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 658  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 659  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 660  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Decryption failed because password is incorrect
 661  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 662  * @see ckmc_create_key_pair_rsa()
 663  * @see ckmc_create_key_pair_ecdsa()
 664  * @see ckmc_create_signature()
 665  * @see #ckmc_hash_algo_e
 666  * @see #ckmc_rsa_padding_algo_e
 667  */
 668 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);
 669
 670
 671 /**
 672  * @brief Verifies a certificate chain and returns that chain.
 673  * @since_tizen 2.3
 674  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 675  * @remarks The trusted root certificate of the chain should exist in the system's certificate storage.
 676  * @remarks You must destroy the newly created @a ppcert_chain_list by calling ckmc_cert_list_all_free() if it is no longer needed.
 677  * @param[in] cert The certificate to be verified
 678  * @param[in] untrustedcerts The untrusted CA certificates to be used in verifying a certificate chain
 679  * @param[out] ppcert_chain_list The pointer to a newly created certificate chain's handle \n
 680  *                               If an error occurs, @a *ppcert_chain_list will be null
 681  * @return @c 0 on success and the signature is valid,
 682  *         otherwise a negative error value
 683  * @retval #CKMC_ERROR_NONE Successful
 684  * @retval #CKMC_ERROR_VERIFICATION_FAILED The certificate chain is not valid
 685  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 686  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 687  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 688  * @retval #CKMC_ERROR_INVALID_FORMAT The format of certificate is not valid
 689  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 690  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Decryption failed because password is incorrect
 691  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 692  * @see ckmc_cert_list_all_free()
 693  */
 694 int ckmc_get_cert_chain(const ckmc_cert_s *cert, const ckmc_cert_list_s *untrustedcerts, ckmc_cert_list_s **ppcert_chain_list);
 695
 696
 697 /**
 698  * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif [Use ckmc_get_cert_chain() instead]
 699  * @brief Verifies a certificate chain using an alias list of untrusted certificates and return that chain.
 700  * @since_tizen 2.3
 701  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 702  * @remarks The trusted root certificate of the chain should exist in the system's certificate storage.
 703  * @remarks You must destroy the newly created @a ppcert_chain_list by calling ckmc_cert_list_all_free() if it is no longer needed.
 704  * @remarks @a untrustedcerts shouldn't be protected with optional password.
 705  * @param[in] cert The certificate to be verified
 706  * @param[in] untrustedcerts The alias list of untrusted CA certificates stored in key manager to be used in verifying a certificate chain
 707  * @param[out] ppcert_chain_list The pointer to a newly created certificate chain's handle \n
 708  *                               If an error occurs, @a *ppcert_chain_list will be null
 709  * @return @c 0 on success and the signature is valid,
 710  *         otherwise a negative error value
 711  * @retval #CKMC_ERROR_NONE Successful
 712  * @retval #CKMC_ERROR_VERIFICATION_FAILED The certificate chain is not valid
 713  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 714  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 715  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 716  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 717  * @retval #CKMC_ERROR_INVALID_FORMAT The format of certificate is not valid
 718  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 719  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Some certificates were encrypted with password and could not be used
 720  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 721  * @see ckmc_get_cert_chain()
 722  * @see ckmc_cert_list_all_free()
 723  */
 724 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) TIZEN_DEPRECATED_API;
 725
 726
 727 /**
 728  * @brief Verifies a certificate chain and returns that chain using user-entered, trusted, and untrusted CA certificates.
 729  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 730  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 731  * @remarks If the trusted root certificates are provided as a user input, these certificates do not need to exist in the system's certificate storage.
 732  * @remarks You must destroy the newly created @a ppcert_chain_list by calling ckmc_cert_list_all_free() if it is no longer needed.
 733  * @param[in] cert The certificate to be verified
 734  * @param[in] untrustedcerts The untrusted CA certificates to be used in verifying a certificate chain
 735  * @param[in] trustedcerts The trusted CA certificates to be used in verifying a certificate chain
 736  * @param[in] use_trustedsystemcerts The flag indicating the use of the trusted root certificates in the system's certificate storage
 737  * @param[out] ppcert_chain_list The pointer to a newly created certificate chain's handle \n
 738  *                               If an error occurs, @a *ppcert_chain_list will be null
 739  * @return @c 0 on success and the signature is valid,
 740  *         otherwise a negative error value
 741  * @retval #CKMC_ERROR_NONE Successful
 742  * @retval #CKMC_ERROR_VERIFICATION_FAILED The certificate chain is not valid
 743  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 744  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 745  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 746  * @retval #CKMC_ERROR_INVALID_FORMAT The format of certificate is not valid
 747  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 748  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 749  * @see ckmc_cert_list_all_free()
 750  */
 751 int ckmc_get_cert_chain_with_trustedcert(const ckmc_cert_s *cert, const ckmc_cert_list_s *untrustedcerts, const ckmc_cert_list_s *trustedcerts, const bool use_trustedsystemcerts, ckmc_cert_list_s **ppcert_chain_list);
 752
 753
 754 /**
 755  * @brief Perform OCSP that checks certificate is whether revoked or not.
 756  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 757  * @privlevel public
 758  * @privilege %http://tizen.org/privilege/internet
 759  * @remarks %http://tizen.org/privilege/internet (public level privilege) is required to use this API instead of %http://tizen.org/privilege/keymanager (public level privilege) since 3.0.
 760  * @param[in] pcert_chain_list Valid certificate chain to perform OCSP check
 761  * @param[out] ocsp_status The pointer to status result of OCSP check
 762  * @return @c 0 on success,
 763  *         otherwise a negative error value
 764  * @retval #CKMC_ERROR_NONE Successful
 765  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 766  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 767  * @retval #CKMC_ERROR_NOT_SUPPORTED Device needed to run API is not supported
 768  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 769  * @pre @a pcert_chain_list is created with ckmc_get_certificate_chain() or
 770  *      ckmc_get_certificate_chain_with_alias().
 771  * @see ckmc_get_cert_chain())
 772  * @see ckmc_cert_list_all_free()
 773  */
 774 int ckmc_ocsp_check(const ckmc_cert_list_s *pcert_chain_list, ckmc_ocsp_status_e *ocsp_status);
 775
 776
 777 /**
 778  * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif [Use ckmc_set_permission() instead]
 779  * @brief Allows another application to access client's application data.
 780  * @since_tizen 2.3
 781  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 782  * @remarks Data identified by @a alias should exist.
 783  * @param[in] alias Data alias for which access will be granted
 784  * @param[in] accessor Package id of the application that will gain access rights
 785  * @param[in] granted Rights granted for @a accessor application
 786  * @return @c 0 on success,
 787  *         otherwise a negative error value
 788  * @retval #CKMC_ERROR_NONE Successful
 789  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 790  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 791  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 792  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 793  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 794  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 795  * @see ckmc_deny_access()
 796  */
 797 int ckmc_allow_access(const char *alias, const char *accessor, ckmc_access_right_e granted) TIZEN_DEPRECATED_API;
 798
 799
 800 /**
 801  * @brief Allows another application to access client's application data.
 802  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 803  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 804  * @remarks Data identified by @a alias should exist.
 805  * @param[in] alias Data alias for which access will be granted
 806  * @param[in] accessor Package id of the application that will gain access rights
 807  * @param[in] permissions Mask of permissions granted for @a accessor application
 808  *                        (#ckmc_permission_e)
 809  *                        (previous permission mask will be replaced with the new mask value)
 810  * @return @c 0 on success,
 811  *         otherwise a negative error value
 812  * @retval #CKMC_ERROR_NONE Successful
 813  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 814  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 815  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 816  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 817  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 818  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 819  */
 820 int ckmc_set_permission(const char *alias, const char *accessor, int permissions);
 821
 822
 823 /**
 824  * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif [Use ckmc_set_permission() instead]
 825  * @brief Revokes another application's access to client's application data.
 826  * @since_tizen 2.3
 827  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 828  * @remarks Data identified by @a alias should exist.
 829  * @remarks Only access previously granted with ckmc_allow_access can be revoked.
 830  * @param[in] alias Data alias for which access will be revoked
 831  * @param[in] accessor Package id of the application that will lose access rights
 832  * @return @c 0 on success,
 833  *         otherwise a negative error value
 834  * @retval #CKMC_ERROR_NONE Successful
 835  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid or the @a accessor doesn't have access to @a alias
 836  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 837  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 838  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 839  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 840  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 841  * @see ckmc_allow_access()
 842  * @see ckmc_set_permission()
 843  */
 844 int ckmc_deny_access(const char *alias, const char *accessor) TIZEN_DEPRECATED_API;
 845
 846
 847 /**
 848  * @brief Removes an entry (no matter of type) from the key manager.
 849  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 850  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to use this API since 3.0.
 851  * @remarks To remove item, client must have remove permission to the specified item.
 852  * @remarks The item owner can remove by default.
 853  * @param[in] alias Item alias to be removed
 854  * @return @c 0 on success,
 855  *         otherwise a negative error value
 856  * @retval #CKMC_ERROR_NONE Successful
 857  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 858  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 859  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 860  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 861  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 862  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 863  * @see ckmc_save_key()
 864  * @see ckmc_save_cert()
 865  * @see ckmc_save_data()
 866  * @see ckmc_save_pkcs12()
 867  * @see ckmc_create_key_pair_rsa()
 868  * @see ckmc_create_key_pair_dsa()
 869  * @see ckmc_create_key_pair_ecdsa()
 870  */
 871 int ckmc_remove_alias(const char *alias);
 872
 873
 874 /**
 875  * @brief Encrypts data using selected key and algorithm.
 876  * @since_tizen 3.0
 877  * @remarks Key identified by @a key_alias should exist.
 878  * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and
 879  *                   #ckmc_algo_type_e for details
 880  * @param[in] key_alias Alias of the key to be used for encryption
 881  * @param[in] password The password used in decrypting a key value \n
 882  *                     If password of the policy is provided in ckmc_save_key(), the same
 883  *                     password should be provided
 884  * @param[in] decrypted Data to be encrypted. In case of AES algorithm there are no restrictions on the size of data,
 885  *                      if S/W backend is used. If module uses TEE backend (since Tizen 5.0 on chosen images),
 886  *                      maximum size of data is implementation-specific and at least 500 kB.
 887  *                      For RSA the size must be smaller or equal to key size in bytes - 42.
 888  *                      Example: for 1024 RSA key the maximum data size is 1024/8 - 42 = 86.
 889  * @param[out] ppencrypted Encrypted data (some algorithms may return additional information embedded in encrypted data.
 890  *                         AES GCM is an example) \n
 891  *                         The caller is responsible for freeing @a encrypted with ckmc_buffer_free()
 892  * @return @c 0 on success,
 893  *         otherwise a negative error value
 894  * @retval #CKMC_ERROR_NONE Successful
 895  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid
 896  *                                       mandatory algorithm parameter or RSA data too long, decrypted = NULL,
 897  *                                       ppencrypted = NULL)
 898  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 899  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 900  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Key with given alias does not exist
 901  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 902  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Key decryption failed because password is incorrect
 903  * @retval #CKMC_ERROR_SERVER_ERROR Too big data size or unsupported GCM mode (32 and 64 bit tag lengths not supported on TEE backend) or internal error
 904  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 905  * @see ckmc_buffer_free()
 906  * @see ckmc_param_list_new()
 907  * @see ckmc_param_list_free()
 908  * @see ckmc_param_list_set_integer()
 909  * @see ckmc_param_list_set_buffer()
 910  * @see ckmc_generate_new_params()
 911  * @see #ckmc_param_list_h
 912  * @see #ckmc_param_name_e
 913  * @see #ckmc_algo_type_e
 914  */
 915 int ckmc_encrypt_data(ckmc_param_list_h params, const char *key_alias, const char *password, const ckmc_raw_buffer_s decrypted, ckmc_raw_buffer_s **ppencrypted);
 916
 917
 918 /**
 919  * @brief Decrypts data using selected key and algorithm.
 920  * @since_tizen 3.0
 921  * @remarks Key identified by @a key_alias should exist.
 922  * @param[in] params Algorithm parameter list handle. You should use the same parameters that were used for encryption.
 923  *                   See #ckmc_param_list_h and #ckmc_algo_type_e for details
 924  * @param[in] key_alias Alias of the key to be used for encryption
 925  * @param[in] password The password used in decrypting a key value \n
 926  *                     If password of the policy is provided in ckmc_save_key(), the same password should be provided
 927  * @param[in] encrypted Data to be decrypted (some algorithms may require additional information embedded in encrypted data. AES GCM is an example)
 928  *                      Since Tizen 5.0, on chosen images where module is using TEE backend, data size is limited to at least 500 kB
 929  *                      (TEE implementation-specific).
 930  * @param[out] ppdecrypted Decrypted data \n
 931  *                         The caller is responsible for freeing @a decrypted with ckmc_buffer_free()
 932  * @return @c 0 on success,
 933  *         otherwise a negative error value
 934  * @retval #CKMC_ERROR_NONE Successful
 935  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid
 936  *                                       mandatory algorithm parameter, GCM tag authentication failed, key or data is wrong,
 937  *                                       in case of RSA key is wrong or data too long, encrypted = NULL, ppdecrypted = NULL)
 938  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 939  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 940  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Key with given alias does not exist
 941  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 942  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Key decryption failed because password is incorrect
 943  * @retval #CKMC_ERROR_SERVER_ERROR Too big data size or unsupported GCM mode (32 and 64 bit tag lengths not supported on TEE backend) or internal error
 944  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 945  * @see ckmc_buffer_free()
 946  * @see ckmc_param_list_new()
 947  * @see ckmc_param_list_free()
 948  * @see ckmc_param_list_set_integer()
 949  * @see ckmc_param_list_set_buffer()
 950  * @see ckmc_generate_new_params()
 951  * @see #ckmc_param_list_h
 952  * @see #ckmc_param_name_e
 953  * @see #ckmc_algo_type_e
 954  */
 955 int ckmc_decrypt_data(ckmc_param_list_h params, const char *key_alias, const char *password, const ckmc_raw_buffer_s encrypted, ckmc_raw_buffer_s **ppdecrypted);
 956
 957
 958 #ifdef __cplusplus
 959 }
 960 #endif
 961
 962
 963 /**
 964  * @}
 965  */
 966
 967
 968 #endif /* __TIZEN_CORE_CKMC_MANAGER_H */