src/include/ckmc/ckmc-manager.h

   1 /*
   2  * Copyright (c) 2000 - 2021 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
  50  *          use this function since 3.0.
  51  * @remarks Currently API supports seven types of keys. These are RSA public/private key,
  52  *          DSA public/private key, ECDSA public/private key, and AES symmetric key.
  53  * @remarks key_type in key may be set to #CKMC_KEY_NONE as an input. key_type is determined inside
  54  *          key manager during storing keys.
  55  * @remarks Some private key files are protected by a password. If raw_key in key read from those
  56  *          encrypted files is encrypted with a password, the password should be provided in
  57  *          the #ckmc_key_s structure.
  58  * @remarks If password in policy is provided, the key is additionally encrypted with the password
  59  *          in the policy.
  60  * @param[in] alias The name of a key to be stored
  61  * @param[in] key The key's binary value to be stored
  62  * @param[in] policy The policy about how to store a key securely
  63  * @return @c 0 on success,
  64  *         otherwise a negative error value
  65  * @retval #CKMC_ERROR_NONE Successful
  66  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
  67  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
  68  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
  69  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists
  70  * @retval #CKMC_ERROR_INVALID_FORMAT The format of raw_key is not valid
  71  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
  72  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
  73  * @see ckmc_remove_alias()
  74  * @see ckmc_get_key()
  75  * @see ckmc_get_key_alias_list()
  76  * @see #ckmc_key_s
  77  * @see #ckmc_policy_s
  78  */
  79 int ckmc_save_key(const char *alias, const ckmc_key_s key, const ckmc_policy_s policy);
  80
  81
  82 /**
  83  * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif
  84  *             [Use ckmc_remove_alias() instead]
  85  * @brief Removes a key from key manager.
  86  * @since_tizen 2.3
  87  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
  88  *          use this function since 3.0.
  89  * @remarks To remove key, client must have remove permission to the specified key.
  90  * @remarks The key owner can remove by default.
  91  * @param[in] alias The name of a key to be removed
  92  * @return @c 0 on success,
  93  *         otherwise a negative error value
  94  * @retval #CKMC_ERROR_NONE Successful
  95  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
  96  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
  97  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
  98  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
  99  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 100  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 101  * @see ckmc_save_key()
 102  * @see ckmc_get_key()
 103  * @see ckmc_get_key_alias_list()
 104  */
 105 int ckmc_remove_key(const char *alias)
 106 TIZEN_DEPRECATED_API;
 107
 108
 109 /**
 110  * @brief Gets a key from key manager.
 111  * @since_tizen 2.3
 112  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 113  *          use this function since 3.0.
 114  * @remarks A client can access only data stored by the client.
 115  * @remarks You must destroy the newly created @a ppkey by calling ckmc_key_free() if it is no longer needed.
 116  * @param[in] alias The name of a key to retrieve
 117  * @param[in] password The password used in decrypting a key value. If password of policy is
 118  *                     provided in ckmc_save_key(), the same password should be provided
 119  * @param[out] ppkey The pointer to a newly created ckmc_key_s handle
 120  * @return @c 0 on success,
 121  *         otherwise a negative error value
 122  * @retval #CKMC_ERROR_NONE Successful
 123  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 124  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 125  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 126  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 127  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 128  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Decryption failed because password is incorrect
 129  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 130  * @see ckmc_save_key()
 131  * @see ckmc_remove_alias()
 132  * @see ckmc_get_key_alias_list()
 133  */
 134 int ckmc_get_key(const char *alias, const char *password, ckmc_key_s **ppkey);
 135
 136
 137 /**
 138  * @brief Gets all the alias of keys that the client can access.
 139  * @since_tizen 2.3
 140  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 141  *          use this function since 3.0.
 142  * @remarks A client can access only data stored by the client.
 143  * @remarks You must destroy the newly created @a ppalias_list by calling ckmc_alias_list_all_free()
 144  *          if it is no longer needed.
 145  * @param[out] ppalias_list The pointer to a newly created #ckmc_alias_list_s handle containing all
 146  *                          available alias of keys. If there is no available key alias,
 147  *                          *ppalias_list will be NULL
 148  * @return @c 0 on success,
 149  *         otherwise a negative error value
 150  * @retval #CKMC_ERROR_NONE Successful
 151  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 152  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 153  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 154  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 155  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 156  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 157  * @see ckmc_save_key()
 158  * @see ckmc_remove_alias()
 159  * @see ckmc_get_key()
 160  */
 161 int ckmc_get_key_alias_list(ckmc_alias_list_s **ppalias_list);
 162
 163
 164 /**
 165  * @brief Gets the information about all the aliases of keys that the client can access.
 166  * @since_tizen 5.5
 167  * @remarks A client can access only data stored by the client and the entries from system database
 168  * if it was explicitly permitted to.
 169  * @remarks You must destroy the newly created @a ppalias_list by calling
 170  *          ckmc_alias_info_list_all_free() if it is no longer needed.
 171  * @param[out] ppalias_list The pointer to a newly created ckmc_alias_info_list_s handle containing
 172  *                          information about all key aliases. If there is no available key alias,
 173  *                          *ppalias_list will be NULL
 174  * @return @c 0 on success,
 175  *         otherwise a negative error value
 176  * @retval #CKMC_ERROR_NONE Successful
 177  * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager or to read
 178  *                                       the alias list
 179  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 180  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 181  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 182  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 183  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 184  * @see ckmc_save_key()
 185  * @see ckmc_remove_alias()
 186  * @see ckmc_get_key()
 187  */
 188 int ckmc_get_key_alias_info_list(ckmc_alias_info_list_s **ppalias_list);
 189
 190
 191 /**
 192  * @brief Stores a certificate inside key manager based on the provided policy.
 193  * @since_tizen 2.3
 194  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 195  *          use this function since 3.0
 196  * @remarks The certificate's binary value will be converted and saved as binary DER encoded
 197  *          certificates.
 198  * @param[in] alias The name of a certificate to be stored
 199  * @param[in] cert The certificate's binary value to be stored
 200  * @param[in] policy The policy about how to store a certificate securely
 201  * @return @c 0 on success,
 202  *         otherwise a negative error value
 203  * @retval #CKMC_ERROR_NONE Successful
 204  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 205  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 206  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 207  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists
 208  * @retval #CKMC_ERROR_INVALID_FORMAT The format of raw_cert is not valid
 209  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 210  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 211  * @see ckmc_remove_alias()
 212  * @see ckmc_get_cert()
 213  * @see ckmc_get_cert_alias_list()
 214  * @see #ckmc_cert_s
 215  * @see #ckmc_policy_s
 216  */
 217 int ckmc_save_cert(const char *alias, const ckmc_cert_s cert, const ckmc_policy_s policy);
 218
 219
 220 /**
 221  * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif
 222  *             [Use ckmc_remove_alias() instead]
 223  * @brief Removes a certificate from key manager.
 224  * @since_tizen 2.3
 225  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 226  *          use this function since 3.0.
 227  * @remarks To remove certificate, client must have remove permission to the specified certificate.
 228  * @remarks The key owner can remove by default.
 229  * @param[in] alias The name of a certificate to be removed
 230  * @return @c 0 on success,
 231  *         otherwise a negative error value
 232  * @retval #CKMC_ERROR_NONE Successful
 233  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 234  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 235  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 236  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 237  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 238  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 239  * @see ckmc_save_cert()
 240  * @see ckmc_get_cert()
 241  * @see ckmc_get_cert_alias_list()
 242  */
 243 int ckmc_remove_cert(const char *alias)
 244 TIZEN_DEPRECATED_API;
 245
 246
 247 /**
 248  * @brief Gets a certificate from key manager.
 249  * @since_tizen 2.3
 250  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 251  *          use this function since 3.0.
 252  * @remarks A client can access only certificate stored by the client.
 253  * @remarks A DER encoded certificate will be returned as a return value.
 254  * @remarks You must destroy the newly created @a ppcert by calling ckmc_cert_free() if it is no
 255  *          longer needed.
 256  * @param[in] alias The name of a certificate to retrieve
 257  * @param[in] password The password used in decrypting a certificate value. If password of policy is
 258  *                     provided in ckmc_save_cert(), the same password should be provided
 259  * @param[out] ppcert The pointer to a newly created ckmc_cert_s handle
 260  * @return @c 0 on success,
 261  *         otherwise a negative error value
 262  * @retval #CKMC_ERROR_NONE Successful
 263  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 264  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 265  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 266  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 267  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exists
 268  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Decryption failed because password is incorrect
 269  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 270  * @see ckmc_save_cert()
 271  * @see ckmc_remove_alias()
 272  * @see ckmc_get_cert_alias_list()
 273  */
 274 int ckmc_get_cert(const char *alias, const char *password, ckmc_cert_s **ppcert);
 275
 276
 277 /**
 278  * @brief Gets all alias of certificates which the client can access.
 279  * @since_tizen 2.3
 280  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 281  *          use this function since 3.0.
 282  * @remarks A client can access only data stored by the client.
 283  * @remarks You must destroy the newly created @a ppalias_list by calling ckmc_alias_list_all_free()
 284  *          if it is no longer needed.
 285  * @param[out] ppalias_list The pointer to a newly created ckmc_alias_list_s handle containing all
 286  *                          available alias of keys. If there is no available key alias,
 287  *                          *ppalias_list will be NULL
 288  * @return @c 0 on success,
 289  *         otherwise a negative error value
 290  * @retval #CKMC_ERROR_NONE Successful
 291  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 292  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 293  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 294  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 295  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 296  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 297  * @see ckmc_save_cert()
 298  * @see ckmc_remove_alias()
 299  * @see ckmc_get_cert()
 300  */
 301 int ckmc_get_cert_alias_list(ckmc_alias_list_s **ppalias_list);
 302
 303
 304 /**
 305  * @brief Gets the information about all the aliases of certificates that the client can access.
 306  * @since_tizen 5.5
 307  * @remarks A client can access only data stored by the client and the entries from system database
 308  * if it was explicitly permitted to.
 309  * @remarks You must destroy the newly created @a ppalias_list by calling
 310  *          ckmc_alias_info_list_all_free() if it is no longer needed.
 311  * @param[out] ppalias_list The pointer to a newly created ckmc_alias_info_list_s handle containing
 312  *                          information about all certificate aliases. If there is no available
 313  *                          certificate alias, *ppalias_list will be NULL
 314  * @return @c 0 on success,
 315  *         otherwise a negative error value
 316  * @retval #CKMC_ERROR_NONE Successful
 317  * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager or to read
 318  *                                       the alias list
 319  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 320  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 321  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 322  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 323  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 324  * @see ckmc_save_cert()
 325  * @see ckmc_remove_alias()
 326  * @see ckmc_get_cert()
 327  */
 328 int ckmc_get_cert_alias_info_list(ckmc_alias_info_list_s **ppalias_list);
 329
 330
 331 /**
 332  * @brief Stores PKCS12's contents inside key manager based on the provided policies. All items from
 333  *        the PKCS12 will use the same alias.
 334  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 335  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 336  *          use this function since 3.0.
 337  * @param[in] alias The name of a data to be stored
 338  * @param[in] pkcs Pointer to the pkcs12 structure to be saved
 339  * @param[in] key_policy The policy about how to store pkcs's private key
 340  * @param[in] cert_policy The policy about how to store pkcs's certificate
 341  * @return @c 0 on success,
 342  *         otherwise a negative error value
 343  * @retval #CKMC_ERROR_NONE Successful
 344  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 345  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 346  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 347  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists
 348  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 349  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 350  * @see ckmc_remove_alias()
 351  * @see ckmc_get_pkcs12()
 352  * @see ckmc_get_data_alias_list()
 353  * @see ckmc_pkcs12_load()
 354  * @see #ckmc_pkcs12_s
 355  * @see #ckmc_policy_s
 356  */
 357 int ckmc_save_pkcs12(const char *alias,
 358                      const ckmc_pkcs12_s *pkcs,
 359                      const ckmc_policy_s key_policy,
 360                      const ckmc_policy_s cert_policy);
 361
 362
 363 /**
 364  * @brief Gets a pkcs12 from key manager.
 365  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 366  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 367  *          use this function since 3.0.
 368  * @remarks A client can access only data stored by the client.
 369  * @remarks You must destroy the newly created @a pkcs12 by calling ckmc_pkcs12_free() if it is no
 370  *          longer needed.
 371  * @param[in] alias The name of a data to retrieve
 372  * @param[in] key_password Password that was used to encrypt privateKey (may be NULL)
 373  * @param[in] cert_password Password used to encrypt certificates (may be NULL)
 374  * @param[out] pkcs12 The pointer to a newly created ckmc_pkcs12_s handle
 375  * @return @c 0 on success,
 376  *         otherwise a negative error value
 377  * @retval #CKMC_ERROR_NONE Successful
 378  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 379  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 380  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 381  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 382  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 383  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED key_password or cert_password does not match with
 384  *                                           password used to encrypt data
 385  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 386  * @see ckmc_save_pkcs12()
 387  * @see ckmc_remove_alias()
 388  */
 389 int ckmc_get_pkcs12(const char *alias,
 390                     const char *key_password,
 391                     const char *cert_password,
 392                     ckmc_pkcs12_s **pkcs12);
 393
 394
 395 /**
 396  * @brief Stores a data inside key manager based on the provided policy.
 397  * @since_tizen 2.3
 398  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 399  *          use this function since 3.0.
 400  * @param[in] alias The name of a data to be stored
 401  * @param[in] data The binary value to be stored
 402  * @param[in] policy The policy about how to store a data securely
 403  * @return @c 0 on success,
 404  *         otherwise a negative error value
 405  * @retval #CKMC_ERROR_NONE Successful
 406  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 407  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 408  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 409  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists
 410  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 411  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 412  * @see ckmc_remove_alias()
 413  * @see ckmc_get_data()
 414  * @see ckmc_get_data_alias_list()
 415  * @see #ckmc_raw_buffer_s
 416  * @see #ckmc_policy_s
 417  */
 418 int ckmc_save_data(const char *alias, ckmc_raw_buffer_s data, const ckmc_policy_s policy);
 419
 420
 421 /**
 422  * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif
 423  *             [Use ckmc_remove_alias() instead]
 424  * @brief Removes a data from key manager.
 425  * @since_tizen 2.3
 426  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 427  *          use this function since 3.0.
 428  * @remarks To remove data, client must have remove permission to the specified data object.
 429  * @remarks The data owner can remove by default.
 430  * @param[in] alias The name of a data to be removed
 431  * @return @c 0 on success,
 432  *         otherwise a negative error value
 433  * @retval #CKMC_ERROR_NONE Successful
 434  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 435  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 436  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 437  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 438  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 439  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 440  * @see ckmc_save_data()
 441  * @see ckmc_get_data()
 442  * @see ckmc_get_data_alias_list()
 443  */
 444 int ckmc_remove_data(const char *alias)
 445 TIZEN_DEPRECATED_API;
 446
 447
 448 /**
 449  * @brief Gets a data from key manager.
 450  * @since_tizen 2.3
 451  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 452  *          use this function since 3.0.
 453  * @remarks A client can access only data stored by the client.
 454  * @remarks You must destroy the newly created @a ppdata by calling ckmc_buffer_free() if it is no
 455  *          longer needed.
 456  * @param[in] alias The name of a data to retrieve
 457  * @param[in] password The password used in decrypting a data value. If password of policy is
 458  *                     provided in ckmc_save_data(), the same password should be provided
 459  * @param[out] ppdata The pointer to a newly created ckmc_raw_buffer_s handle
 460  * @return @c 0 on success,
 461  *         otherwise a negative error value
 462  * @retval #CKMC_ERROR_NONE Successful
 463  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 464  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 465  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 466  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 467  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 468  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Decryption failed because password is incorrect
 469  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 470  * @see ckmc_save_data()
 471  * @see ckmc_remove_alias()
 472  * @see ckmc_get_data_alias_list()
 473  */
 474 int ckmc_get_data(const char *alias, const char *password, ckmc_raw_buffer_s **ppdata);
 475
 476
 477 /**
 478  * @brief Gets all alias of data which the client can access.
 479  * @since_tizen 2.3
 480  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 481  *          use this function since 3.0.
 482  * @remarks A client can access only data stored by the client.
 483  * @remarks You must destroy the newly created @a ppalias_list by calling ckmc_alias_list_all_free()
 484  *          if it is no longer needed.
 485  * @param[out] ppalias_list The pointer to a newly created ckmc_alias_list_s handle containing all
 486  *             available alias of keys. If there is no available key alias, *ppalias_list will be
 487  *             NULL
 488  * @return @c 0 on success,
 489  *         otherwise a negative error value
 490  * @retval #CKMC_ERROR_NONE Successful
 491  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 492  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 493  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 494  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 495  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 496  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 497  * @see ckmc_save_data()
 498  * @see ckmc_remove_alias()
 499  * @see ckmc_get_data()
 500  */
 501 int ckmc_get_data_alias_list(ckmc_alias_list_s **ppalias_list);
 502
 503
 504 /**
 505  * @brief Gets the information about all the aliases of data that the client can access.
 506  * @since_tizen 5.5
 507  * @remarks A client can access only data stored by the client and the entries from system database
 508  * if it was explicitly permitted to.
 509  * @remarks You must destroy the newly created @a ppalias_list by calling
 510  *          ckmc_alias_info_list_all_free() if it is no longer needed.
 511  * @param[out] ppalias_list The pointer to a newly created ckmc_alias_info_list_s handle containing
 512  *                          information about all data aliases. If there is no available data alias,
 513  *                          *ppalias_list will be NULL
 514  * @return @c 0 on success,
 515  *         otherwise a negative error value
 516  * @retval #CKMC_ERROR_NONE Successful
 517  * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager or to read
 518  *                                       the alias list
 519  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 520  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 521  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 522  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 523  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 524  * @see ckmc_save_data()
 525  * @see ckmc_remove_alias()
 526  * @see ckmc_get_data()
 527  */
 528 int ckmc_get_data_alias_info_list(ckmc_alias_info_list_s **ppalias_list);
 529
 530
 531 /**
 532  * @brief Creates RSA private/public key pair and stores them inside key manager based on each
 533  *        policy.
 534  * @since_tizen 2.3
 535  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 536  *          use this function since 3.0.
 537  * @remarks If password in the policy is provided, the key is additionally encrypted with the
 538  *          password in the policy.
 539  * @param[in] size The size of key strength to be created. @c 1024, @c 2048, and @c 4096 are
 540  *                 supported
 541  * @param[in] private_key_alias The name of private key to be stored
 542  * @param[in] public_key_alias The name of public key to be stored
 543  * @param[in] policy_private_key The policy about how to store a private key securely
 544  * @param[in] policy_public_key The policy about how to store a public key securely
 545  * @return @c 0 on success,
 546  *         otherwise a negative error value
 547  * @retval #CKMC_ERROR_NONE Successful
 548  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 549  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 550  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 551  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists
 552  * @retval #CKMC_ERROR_DB_ERROR Failed due to other DB transaction unexpectedly
 553  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 554  * @see ckmc_create_key_pair_dsa()
 555  * @see ckmc_create_key_pair_ecdsa()
 556  * @see ckmc_create_signature()
 557  * @see ckmc_verify_signature()
 558  */
 559 int ckmc_create_key_pair_rsa(const size_t size,
 560                              const char *private_key_alias,
 561                              const char *public_key_alias,
 562                              const ckmc_policy_s policy_private_key,
 563                              const ckmc_policy_s policy_public_key);
 564
 565
 566 /**
 567  * @brief Creates DSA private/public key pair and stores them inside key manager based on each policy.
 568  * @since_tizen 2.3
 569  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 570  *          use this function since 3.0.
 571  * @remarks If password in the policy is provided, the key is additionally encrypted with the
 572  *          password in the policy.
 573  * @param[in] size The size of key strength to be created. @c 1024, @c 2048, @c 3072 and @c 4096 are
 574  *                 supported
 575  * @param[in] private_key_alias The name of private key to be stored
 576  * @param[in] public_key_alias The name of public key to be stored
 577  * @param[in] policy_private_key The policy about how to store a private key securely
 578  * @param[in] policy_public_key The policy about how to store a public key securely
 579  * @return @c 0 on success,
 580  *         otherwise a negative error value
 581  * @retval #CKMC_ERROR_NONE Successful
 582  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 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  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 588  * @see ckmc_create_key_pair_rsa()
 589  * @see ckmc_create_key_pair_ecdsa()
 590  * @see ckmc_create_signature()
 591  * @see ckmc_verify_signature()
 592  */
 593 int ckmc_create_key_pair_dsa(const size_t size,
 594                              const char *private_key_alias,
 595                              const char *public_key_alias,
 596                              const ckmc_policy_s policy_private_key,
 597                              const ckmc_policy_s policy_public_key);
 598
 599
 600 /**
 601  * @brief Creates ECDSA private/public key pair and stores them inside key manager based on each policy.
 602  * @since_tizen 2.3
 603  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 604  *          use this function since 3.0.
 605  * @remarks If password in the policy is provided, the key is additionally encrypted with the
 606  *          password in the policy.
 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  * @return @c 0 on success,
 613  *         otherwise a negative error value
 614  * @retval #CKMC_ERROR_NONE Successful
 615  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 616  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 617  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 618  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists
 619  * @retval #CKMC_ERROR_DB_ERROR Failed due to other DB transaction unexpectedly
 620  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 621  * @see ckmc_create_key_pair_rsa()
 622  * @see ckmc_create_key_pair_dsa()
 623  * @see ckmc_create_signature()
 624  * @see ckmc_verify_signature()
 625  * @see #ckmc_ec_type_e
 626  */
 627 int ckmc_create_key_pair_ecdsa(const ckmc_ec_type_e type,
 628                                const char *private_key_alias,
 629                                const char *public_key_alias,
 630                                const ckmc_policy_s policy_private_key,
 631                                const ckmc_policy_s policy_public_key);
 632
 633
 634 /**
 635  * @brief Creates AES key and stores it inside key manager based on the policy.
 636  * @since_tizen 3.0
 637  * @remarks If password in the policy is provided, the key is additionally encrypted with the
 638  *          password in the policy.
 639  * @param[in] size The size of key strength to be created. @c 128, @c 192 and @c 256 are supported
 640  * @param[in] key_alias The name of key to be stored
 641  * @param[in] key_policy The policy about how to store the key securely
 642  * @return @c 0 on success,
 643  *         otherwise a negative error value
 644  * @retval #CKMC_ERROR_NONE Successful
 645  * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager or to create
 646  *                                       the key
 647  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 648  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 649  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS Alias already exists
 650  * @retval #CKMC_ERROR_DB_ERROR Failed due to other DB transaction unexpectedly
 651  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 652  * @see ckmc_create_key_pair_rsa()
 653  * @see ckmc_create_key_pair_dsa()
 654  * @see ckmc_create_key_pair_ecdsa()
 655  * @see #ckmc_policy_s
 656  */
 657 int ckmc_create_key_aes(size_t size, const char *key_alias, ckmc_policy_s key_policy);
 658
 659
 660 /**
 661  * @brief Creates a signature on a given message using a private key and returns the signature.
 662  * @since_tizen 2.3
 663  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 664  *          use this function since 3.0.
 665  * @remarks If password of policy is provided during storing a key, the same password should be
 666  *          provided.
 667  * @remarks You must destroy the newly created @a ppsignature by calling ckmc_buffer_free() if it is
 668  *          no longer needed.
 669  * @param[in] private_key_alias The name of private key
 670  * @param[in] password The password used in decrypting a private key value
 671  * @param[in] message The message that is signed with a private key
 672  * @param[in] hash The hash algorithm used in creating signature. CKMC_HASH_NONE is invalid for DSA
 673  *                 & ECDSA
 674  * @param[in] padding The RSA padding algorithm used in creating signature. It is used only when the signature algorithm is RSA. If
 675  *                    @a padding is CKMC_NONE_PADDING you must use CKMC_HASH_NONE
 676  *                    and the message must be equal to key length
 677  * @param[out] ppsignature The pointer to a newly created signature. If an error occurs,
 678  *                         *ppsignature will be NULL
 679  * @return @c 0 on success,
 680  *         otherwise a negative error value
 681  * @retval #CKMC_ERROR_NONE Successful
 682  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 683  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 684  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 685  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 686  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 687  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Decryption failed because password is incorrect
 688  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 689  * @see ckmc_create_key_pair_rsa()
 690  * @see ckmc_create_key_pair_ecdsa()
 691  * @see ckmc_verify_signature()
 692  * @see ckmc_buffer_free()
 693  * @see #ckmc_hash_algo_e
 694  * @see #ckmc_rsa_padding_algo_e
 695  */
 696 int ckmc_create_signature(const char *private_key_alias,
 697                           const char *password,
 698                           const ckmc_raw_buffer_s message,
 699                           const ckmc_hash_algo_e hash,
 700                           const ckmc_rsa_padding_algo_e padding,
 701                           ckmc_raw_buffer_s **ppsignature);
 702
 703
 704 /**
 705  * @brief Verifies a given signature on a given message using a public key and returns the signature
 706  *        status.
 707  * @since_tizen 2.3
 708  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 709  *          use this function since 3.0.
 710  * @remarks If password of policy is provided during storing a key, the same password should be
 711  *          provided.
 712  * @param[in] public_key_alias The name of public key
 713  * @param[in] password The password used in decrypting a public key value
 714  * @param[in] message The input on which the signature is created
 715  * @param[in] signature The signature that is verified with public key
 716  * @param[in] hash The hash algorithm used in verifying signature. CKMC_HASH_NONE is invalid for DSA
 717  *                 & ECDSA
 718  * @param[in] padding The RSA padding algorithm used in verifying signature. It is used only when
 719  *                    the signature algorithm is RSA. If @a padding is CKMC_NONE_PADDING you must
 720  *                    use CKMC_HASH_NONE and the message must be equal to key length
 721  * @return @c 0 on success and the signature is valid,
 722  *         otherwise a negative error value
 723  * @retval #CKMC_ERROR_NONE Successful
 724  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 725  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 726  * @retval #CKMC_ERROR_VERIFICATION_FAILED The signature is invalid
 727  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 728  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 729  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 730  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Decryption failed because password is incorrect
 731  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 732  * @see ckmc_create_key_pair_rsa()
 733  * @see ckmc_create_key_pair_ecdsa()
 734  * @see ckmc_create_signature()
 735  * @see #ckmc_hash_algo_e
 736  * @see #ckmc_rsa_padding_algo_e
 737  */
 738 int ckmc_verify_signature(const char *public_key_alias,
 739                           const char *password,
 740                           const ckmc_raw_buffer_s message,
 741                           const ckmc_raw_buffer_s signature,
 742                           const ckmc_hash_algo_e hash,
 743                           const ckmc_rsa_padding_algo_e padding);
 744
 745
 746 /**
 747  * @brief Verifies a certificate chain and returns that chain.
 748  * @since_tizen 2.3
 749  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 750  *          use this function since 3.0.
 751  * @remarks The trusted root certificate of the chain should exist in the system's certificate
 752  *          storage.
 753  * @remarks You must destroy the newly created @a ppcert_chain_list by calling
 754  *          ckmc_cert_list_all_free() if it is no longer needed.
 755  * @param[in] cert The certificate to be verified
 756  * @param[in] untrustedcerts The untrusted CA certificates to be used in verifying a certificate
 757  *                           chain
 758  * @param[out] ppcert_chain_list The pointer to a newly created certificate chain's handle. If an
 759  *                               error occurs, *ppcert_chain_list will be NULL
 760  * @return @c 0 on success and the signature is valid,
 761  *         otherwise a negative error value
 762  * @retval #CKMC_ERROR_NONE Successful
 763  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 764  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 765  * @retval #CKMC_ERROR_VERIFICATION_FAILED The certificate chain is not valid
 766  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 767  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 768  * @retval #CKMC_ERROR_INVALID_FORMAT The format of certificate is not valid
 769  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Decryption failed because password is incorrect
 770  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 771  * @see ckmc_cert_list_all_free()
 772  */
 773 int ckmc_get_cert_chain(const ckmc_cert_s *cert,
 774                         const ckmc_cert_list_s *untrustedcerts,
 775                         ckmc_cert_list_s **ppcert_chain_list);
 776
 777
 778 /**
 779  * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif
 780  *             [Use ckmc_get_cert_chain() instead]
 781  * @brief Verifies a certificate chain using an alias list of untrusted certificates and return that
 782  *        chain.
 783  * @since_tizen 2.3
 784  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 785  *          use this function since 3.0.
 786  * @remarks The trusted root certificate of the chain should exist in the system's certificate
 787  *          storage.
 788  * @remarks You must destroy the newly created @a ppcert_chain_list by calling
 789  *          ckmc_cert_list_all_free() if it is no longer needed.
 790  * @remarks @a untrustedcerts shouldn't be protected with optional password.
 791  * @param[in] cert The certificate to be verified
 792  * @param[in] untrustedcerts The alias list of untrusted CA certificates stored in key manager to be
 793  *                           used in verifying a certificate chain
 794  * @param[out] ppcert_chain_list The pointer to a newly created certificate chain's handle. If an
 795  *                               error occurs, *ppcert_chain_list will be NULL
 796  * @return @c 0 on success and the signature is valid,
 797  *         otherwise a negative error value
 798  * @retval #CKMC_ERROR_NONE Successful
 799  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 800  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 801  * @retval #CKMC_ERROR_VERIFICATION_FAILED The certificate chain is not valid
 802  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 803  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 804  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 805  * @retval #CKMC_ERROR_INVALID_FORMAT The format of certificate is not valid
 806  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Some certificates were encrypted with password and
 807  *                                           could not be used
 808  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 809  * @see ckmc_get_cert_chain()
 810  * @see ckmc_cert_list_all_free()
 811  */
 812 int ckmc_get_cert_chain_with_alias(const ckmc_cert_s *cert,
 813                                    const ckmc_alias_list_s *untrustedcerts,
 814                                    ckmc_cert_list_s **ppcert_chain_list) TIZEN_DEPRECATED_API;
 815
 816
 817 /**
 818  * @brief Verifies a certificate chain and returns that chain using user-entered, trusted, and
 819  *        untrusted CA certificates.
 820  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 821  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 822  *          use this function since 3.0.
 823  * @remarks If the trusted root certificates are provided as a user input, these certificates do not
 824  *          need to exist in the system's certificate storage.
 825  * @remarks You must destroy the newly created @a ppcert_chain_list by calling
 826  *          ckmc_cert_list_all_free() if it is no longer needed.
 827  * @param[in] cert The certificate to be verified
 828  * @param[in] untrustedcerts The untrusted CA certificates to be used in verifying a certificate
 829  *                           chain
 830  * @param[in] trustedcerts The trusted CA certificates to be used in verifying a certificate chain
 831  * @param[in] use_trustedsystemcerts The flag indicating the use of the trusted root certificates in
 832  *                                   the system's certificate storage
 833  * @param[out] ppcert_chain_list The pointer to a newly created certificate chain's handle. If an
 834  *                               error occurs, *ppcert_chain_list will be NULL
 835  * @return @c 0 on success and the signature is valid,
 836  *         otherwise a negative error value
 837  * @retval #CKMC_ERROR_NONE Successful
 838  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 839  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 840  * @retval #CKMC_ERROR_VERIFICATION_FAILED The certificate chain is not valid
 841  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 842  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 843  * @retval #CKMC_ERROR_INVALID_FORMAT The format of certificate is not valid
 844  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 845  * @see ckmc_cert_list_all_free()
 846  */
 847 int ckmc_get_cert_chain_with_trustedcert(const ckmc_cert_s *cert,
 848                                          const ckmc_cert_list_s *untrustedcerts,
 849                                          const ckmc_cert_list_s *trustedcerts,
 850                                          const bool use_trustedsystemcerts,
 851                                          ckmc_cert_list_s **ppcert_chain_list);
 852
 853
 854 /**
 855  * @brief Performs OCSP that checks certificate is whether revoked or not.
 856  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 857  * @privlevel public
 858  * @privilege %http://tizen.org/privilege/internet
 859  * @remarks %http://tizen.org/privilege/internet (public level privilege) is required to use this
 860  *          function instead of %http://tizen.org/privilege/keymanager (public level privilege)
 861  *          since 3.0.
 862  * @param[in] pcert_chain_list Valid certificate chain to perform OCSP check
 863  * @param[out] ocsp_status The pointer to status result of OCSP check
 864  * @return @c 0 on success,
 865  *         otherwise a negative error value
 866  * @retval #CKMC_ERROR_NONE Successful
 867  * @retval #CKMC_ERROR_NOT_SUPPORTED Device needed to run API is not supported
 868  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 869  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 870  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 871  * @pre @a pcert_chain_list is created with ckmc_get_cert_chain() or
 872  *      ckmc_get_cert_chain_with_alias().
 873  * @see ckmc_get_cert_chain())
 874  * @see ckmc_cert_list_all_free()
 875  */
 876 int ckmc_ocsp_check(const ckmc_cert_list_s *pcert_chain_list,
 877                     ckmc_ocsp_status_e *ocsp_status);
 878
 879
 880 /**
 881  * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif
 882  *             [Use ckmc_set_permission() instead]
 883  * @brief Allows another application to access client's application data.
 884  * @since_tizen 2.3
 885  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 886  *          use this function since 3.0.
 887  * @remarks Data identified by @a alias should exist.
 888  * @param[in] alias Data alias for which access will be granted
 889  * @param[in] accessor Package id of the application that will gain access rights
 890  * @param[in] granted Rights granted for @a accessor application
 891  * @return @c 0 on success,
 892  *         otherwise a negative error value
 893  * @retval #CKMC_ERROR_NONE Successful
 894  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager or modify permissions
 895  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 896  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 897  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 898  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 899  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 900  * @see ckmc_deny_access()
 901  */
 902 int ckmc_allow_access(const char *alias,
 903                       const char *accessor,
 904                       ckmc_access_right_e granted) TIZEN_DEPRECATED_API;
 905
 906
 907 /**
 908  * @brief Allows another application to access client's application data.
 909  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 910  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 911  *          use this function since 3.0.
 912  * @remarks Data identified by @a alias should exist.
 913  * @param[in] alias Data alias for which access will be granted
 914  * @param[in] accessor Package id of the application that will gain access rights
 915  * @param[in] permissions Mask of permissions granted for @a accessor application
 916  *                        (#ckmc_permission_e)
 917  *                        (previous permission mask will be replaced with the new mask value)
 918  * @return @c 0 on success,
 919  *         otherwise a negative error value
 920  * @retval #CKMC_ERROR_NONE Successful
 921  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager or modify permissions
 922  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 923  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 924  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 925  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 926  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 927  */
 928 int ckmc_set_permission(const char *alias, const char *accessor, int permissions);
 929
 930
 931 /**
 932  * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif
 933  *             [Use ckmc_set_permission() instead]
 934  * @brief Revokes another application's access to client's application data.
 935  * @since_tizen 2.3
 936  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 937  *          use this function since 3.0.
 938  * @remarks Data identified by @a alias should exist.
 939  * @remarks Only access previously granted with ckmc_allow_access() can be revoked.
 940  * @param[in] alias Data alias for which access will be revoked
 941  * @param[in] accessor Package id of the application that will lose access rights
 942  * @return @c 0 on success,
 943  *         otherwise a negative error value
 944  * @retval #CKMC_ERROR_NONE Successful
 945  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager or modify permissions
 946  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid or the @a accessor doesn't have
 947  *                                       access to @a alias
 948  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 949  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 950  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 951  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 952  * @see ckmc_allow_access()
 953  * @see ckmc_set_permission()
 954  */
 955 int ckmc_deny_access(const char *alias, const char *accessor) TIZEN_DEPRECATED_API;
 956
 957
 958 /**
 959  * @brief Removes an entry (no matter of type) from the key manager.
 960  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 961  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 962  *          use this function since 3.0.
 963  * @remarks To remove item, client must have remove permission to the specified item.
 964  * @remarks The item owner can remove by default.
 965  * @param[in] alias Item alias to be removed
 966  * @return @c 0 on success,
 967  *         otherwise a negative error value
 968  * @retval #CKMC_ERROR_NONE Successful
 969  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager or the item to remove
 970  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 971  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 972  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 973  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 974  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 975  * @see ckmc_save_key()
 976  * @see ckmc_save_cert()
 977  * @see ckmc_save_data()
 978  * @see ckmc_save_pkcs12()
 979  * @see ckmc_create_key_pair_rsa()
 980  * @see ckmc_create_key_pair_dsa()
 981  * @see ckmc_create_key_pair_ecdsa()
 982  */
 983 int ckmc_remove_alias(const char *alias);
 984
 985
 986 /**
 987  * @brief Encrypts data using selected key and algorithm.
 988  *
 989  * @since_tizen 3.0
 990  *
 991  * @remarks Key identified by @a key_alias should exist.
 992  * @remarks You must destroy @a ppencrypted with ckmc_buffer_free().
 993  *
 994  * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e
 995  *                   for details. Supported algorithms:
 996  *                   - #CKMC_ALGO_AES_CTR,
 997  *                   - #CKMC_ALGO_AES_CBC,
 998  *                   - #CKMC_ALGO_AES_GCM,
 999  *                   - #CKMC_ALGO_AES_CFB,
1000  *                   - #CKMC_ALGO_RSA_OAEP
1001  * @param[in] key_alias Alias of the key to be used for encryption
1002  * @param[in] password The password used in decrypting a key value. If password of the policy is
1003  *                     provided in ckmc_save_key(), the same password should be provided
1004  * @param[in] decrypted Data to be encrypted. In case of AES algorithm the backend may impose limit
1005  *                      on the maximum size of processed data (ckmc_backend_get_max_chunk_size()).
1006  *                      For RSA the size must be smaller or equal to key size in bytes - 42.
1007  *                      Example: for 1024 RSA key the maximum data size is 1024/8 - 42 = 86.
1008  * @param[out] ppencrypted Encrypted data. In #CKMC_ALGO_AES_GCM mode it includes the GCM tag
1009  *                         appended at the end.
1010  *
1011  * @return @c 0 on success, otherwise a negative error value
1012  * @retval #CKMC_ERROR_NONE Successful
1013  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager or the encrypting key
1014  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory
1015  *                                       algorithm parameter or RSA data too long, decrypted = NULL,
1016  *                                       ppencrypted = NULL)
1017  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
1018  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
1019  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Key with given alias does not exist
1020  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Key decryption failed because password is incorrect
1021  * @retval #CKMC_ERROR_SERVER_ERROR Too big data size or unsupported GCM mode (32 and 64 bit tag
1022  *                                  lengths not supported on TEE backend) or internal error
1023  *
1024  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
1025  *
1026  * @see ckmc_buffer_free()
1027  * @see ckmc_param_list_new()
1028  * @see ckmc_param_list_free()
1029  * @see ckmc_param_list_set_integer()
1030  * @see ckmc_param_list_set_buffer()
1031  * @see ckmc_generate_new_params()
1032  * @see #ckmc_param_list_h
1033  * @see #ckmc_param_name_e
1034  * @see #ckmc_algo_type_e
1035  */
1036 int ckmc_encrypt_data(ckmc_param_list_h params,
1037                       const char *key_alias,
1038                       const char *password,
1039                       const ckmc_raw_buffer_s decrypted,
1040                       ckmc_raw_buffer_s **ppencrypted);
1041
1042
1043 /**
1044  * @brief Decrypts data using selected key and algorithm.
1045  *
1046  * @since_tizen 3.0
1047  *
1048  * @remarks Key identified by @a key_alias should exist.
1049  * @remarks You must destroy @a ppdecrypted with ckmc_buffer_free().
1050  *
1051  * @param[in] params Algorithm parameter list handle. You should use the same parameters that were
1052  *                   used for encryption. See #ckmc_param_list_h and #ckmc_algo_type_e for details.
1053  *                   Supported algorithms:
1054  *                   - #CKMC_ALGO_AES_CTR,
1055  *                   - #CKMC_ALGO_AES_CBC,
1056  *                   - #CKMC_ALGO_AES_GCM,
1057  *                   - #CKMC_ALGO_AES_CFB,
1058  *                   - #CKMC_ALGO_RSA_OAEP
1059  * @param[in] key_alias Alias of the key to be used for encryption
1060  * @param[in] password The password used in decrypting a key value. If password of the policy is
1061  *                     provided in ckmc_save_key(), the same password should be provided
1062  * @param[in] encrypted Data to be decrypted. #CKMC_ALGO_AES_GCM mode requires GCM tag to be
1063  *                      appended at the end. In case of AES algorithm the backend may impose limit
1064  *                      on the maximum size of processed data (ckmc_backend_get_max_chunk_size()).
1065  *                      For RSA the size must be smaller or equal to key size in bytes - 42.
1066  * @param[out] ppdecrypted Decrypted data
1067  *
1068  * @return @c 0 on success, otherwise a negative error value
1069  * @retval #CKMC_ERROR_NONE Successful
1070  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager or the decrypting key
1071  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory
1072  *                                       algorithm parameter, GCM tag authentication failed, key or
1073  *                                       data is wrong, in case of RSA key is wrong or data too
1074  *                                       long, encrypted = NULL, ppdecrypted = NULL)
1075  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
1076  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
1077  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Key with given alias does not exist
1078  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Key decryption failed because password is incorrect
1079  * @retval #CKMC_ERROR_SERVER_ERROR Too big data size or unsupported GCM mode (32 and 64 bit tag
1080  *                                  lengths not supported on TEE backend) or internal error
1081  *
1082  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
1083  *
1084  * @see ckmc_buffer_free()
1085  * @see ckmc_param_list_new()
1086  * @see ckmc_param_list_free()
1087  * @see ckmc_param_list_set_integer()
1088  * @see ckmc_param_list_set_buffer()
1089  * @see ckmc_generate_new_params()
1090  * @see #ckmc_param_list_h
1091  * @see #ckmc_param_name_e
1092  * @see #ckmc_algo_type_e
1093  */
1094 int ckmc_decrypt_data(ckmc_param_list_h params,
1095                       const char *key_alias,
1096                       const char *password,
1097                       const ckmc_raw_buffer_s encrypted,
1098                       ckmc_raw_buffer_s **ppdecrypted);
1099
1100
1101 /**
1102  * @brief Unwraps one key with another and stores it inside key manager.
1103  *
1104  * @since_tizen 6.0
1105  *
1106  * @remarks The wrapping key must be either symmetric (#CKMC_KEY_AES) or private RSA
1107  *          (#CKMC_KEY_RSA_PRIVATE).
1108  * @remarks key_type in @a wrapped_key can only be #CKMC_KEY_AES.
1109  * @remarks password in @a wrapped_key must be set to NULL. There's no need to additionally encrypt
1110  *          a wrapped key.
1111  * @remarks If password in @a policy is provided, the stored key is additionally encrypted with it.
1112  * @remarks If extractable in @a policy is set to false, the stored key may still be exported in a
1113  *          wrapped form.
1114  * @remarks Note that the backend may impose limit on the maximum size of @a wrapped_key
1115  *          (ckmc_backend_get_max_chunk_size()).
1116  *
1117  * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e
1118  *                   for details. Supported algorithms:
1119  *                   - #CKMC_ALGO_AES_CTR,
1120  *                   - #CKMC_ALGO_AES_CBC,
1121  *                   - #CKMC_ALGO_AES_GCM,
1122  *                   - #CKMC_ALGO_AES_CFB,
1123  *                   - #CKMC_ALGO_RSA_OAEP
1124  * @param[in] wrapping_key_alias The name of the wrapping key.
1125  * @param[in] wrapping_key_password An optional password of the wrapping key
1126  * @param[in] alias The name of a key to be stored
1127  * @param[in] wrapped_key The wrapped key to be unwrapped and stored. #CKMC_ALGO_AES_GCM mode
1128  *                        requires GCM tag to be appended at the end of the @a wrapped_key.
1129  * @param[in] policy The policy about how to store a key securely
1130  *
1131  * @return @c 0 on success, otherwise a negative error value
1132  * @retval #CKMC_ERROR_NONE Successful
1133  * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager, the
1134  *                                       wrapping key or to create the unwrapped key
1135  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory
1136  *                                       algorithm parameter, GCM tag authentication failed,
1137  *                                       @a wrapping_key_alias = NULL, @a alias = NULL,
1138  *                                       @a wrapped_key = NULL)
1139  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
1140  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a wrapping_key_alias does not exist
1141  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS @a alias already exists
1142  * @retval #CKMC_ERROR_INVALID_FORMAT The format of @a wrapped_key is not valid
1143  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
1144  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Wrapping key decryption failed because
1145  *                                           @a wrapping_key_password is incorrect
1146  * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
1147  *
1148  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
1149  *
1150  * @see ckmc_export_wrapped_key()
1151  * @see #ckmc_key_s
1152  * @see #ckmc_param_list_h
1153  * @see #ckmc_policy_s
1154  */
1155 int ckmc_import_wrapped_key(const ckmc_param_list_h params,
1156                             const char *wrapping_key_alias,
1157                             const char *wrapping_key_password,
1158                             const char *alias,
1159                             const ckmc_key_s *wrapped_key,
1160                             const ckmc_policy_s policy);
1161
1162
1163 /**
1164  * @brief Wraps one key with another and returns it to the client.
1165  *
1166  * @since_tizen 6.0
1167  *
1168  * @remarks The wrapping key must be either symmetric (#CKMC_KEY_AES) or public RSA
1169  *          (#CKMC_KEY_RSA_PUBLIC).
1170  * @remarks The @a ppwrapped_key should be released using ckmc_key_free().
1171  * @remarks The key denoted by @a alias can only be #CKMC_KEY_AES.
1172  *
1173  * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e
1174  *                   for details. Supported algorithms:
1175  *                   - #CKMC_ALGO_AES_CTR,
1176  *                   - #CKMC_ALGO_AES_CBC,
1177  *                   - #CKMC_ALGO_AES_GCM,
1178  *                   - #CKMC_ALGO_AES_CFB,
1179  *                   - #CKMC_ALGO_RSA_OAEP
1180  * @param[in] wrapping_key_alias The name of the wrapping key
1181  * @param[in] wrapping_key_password An optional password of the wrapping key
1182  * @param[in] alias The name of the key to be wrapped and exported
1183  * @param[in] password An optional password used to decrypt the key pointed by @a alias
1184  * @param[out] ppwrapped_key The wrapped key. In #CKMC_ALGO_AES_GCM mode it includes the GCM tag
1185  *                           appended at the end.
1186  *
1187  * @return @c 0 on success, otherwise a negative error value
1188  * @retval #CKMC_ERROR_NONE Successful
1189  * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager, the
1190  *                                       wrapping key or the key being wrapped
1191  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory
1192  *                                       algorithm parameter, GCM tag authentication failed,
1193  *                                       @a wrapping_key_alias = NULL, @a alias = NULL,
1194  *                                       @a ppwrapped_key = NULL)
1195  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
1196  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a wrapping_key_alias or @a alias does not exist
1197  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
1198  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Wrapping key decryption failed because
1199  *                                           @a wrapping_key_password is incorrect
1200  * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
1201  *
1202  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
1203  *
1204  * @see ckmc_import_wrapped_key()
1205  * @see #ckmc_key_s
1206  * @see #ckmc_param_list_h
1207  */
1208 int ckmc_export_wrapped_key(const ckmc_param_list_h params,
1209                             const char *wrapping_key_alias,
1210                             const char *wrapping_key_password,
1211                             const char *alias,
1212                             const char *password,
1213                             ckmc_key_s **ppwrapped_key);
1214
1215
1216 /**
1217  * @brief Derives a secret or key from another key/secret and stores it inside key manager.
1218  *
1219  * @since_tizen 6.0
1220  *
1221  * @remarks In case of #CKMC_ALGO_KBKDF algorithm, the secret pointed to by @a secret_alias must be
1222  *          a binary data or a symmetric key (#CKMC_KEY_AES). The derived key pointed to by
1223  *          @a new_key_alias will be a symmetric one. It will be stored as a #CKMC_KEY_AES.
1224  * @remarks In case of #CKMC_ALGO_ECDH algorithm, the key pointed to by @a secret_alias must be a
1225  *          private EC key (#CKMC_KEY_ECDSA_PRIVATE). The derived secret pointed to by
1226  *          @a new_key_alias  will be in binary data form.
1227  *
1228  * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e
1229  *                   for details. Supported algorithms:
1230  *                   - #CKMC_ALGO_KBKDF,
1231  *                   - #CKMC_ALGO_ECDH,
1232  * @param[in] secret_alias Alias of the secret/key to use as an input
1233  * @param[in] secret_password Optional password of the secret/key used as an input
1234  * @param[in] new_key_alias The name under which the derived key or secret will be stored
1235  * @param[in] new_key_policy Policy used to store the derived key or secret
1236  *
1237  * @return @c 0 on success, otherwise a negative error value
1238  * @retval #CKMC_ERROR_NONE Successful
1239  * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager, the secret
1240  *                                       or to create the new key/secret
1241  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory
1242  *                                       algorithm parameter, @a secret_alias = NULL,
1243  *                                       @a new_key_alias = NULL)
1244  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
1245  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a secret_alias does not exist
1246  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS @a new_key_alias already exists
1247  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
1248  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Secret decryption failed because @a secret_password is
1249  *                                           incorrect
1250  * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
1251  *
1252  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
1253  *
1254  * @par Example
1255  * @snippet key_derive.cpp KEY_DERIVE example
1256  *
1257  * @see #ckmc_param_list_h
1258  * @see #ckmc_policy_s
1259  */
1260 int ckmc_key_derive(const ckmc_param_list_h params,
1261                     const char *secret_alias,
1262                     const char *secret_password,
1263                     const char *new_key_alias,
1264                     ckmc_policy_s new_key_policy);
1265
1266 /**
1267  * @brief Sets up a symmetric encryption or decryption context with given key and parameters.
1268  *
1269  * @since_tizen 6.0
1270  *
1271  * @remarks The newly created @a context must be destroyed using ckmc_cipher_free() when it's no
1272  *          longer needed.
1273  * @remarks To perform the encryption/decryption, one or more calls to ckmc_cipher_update() must be
1274  *          folowed by one call to ckmc_cipher_finalize().
1275  * @remarks To pass #CKMC_PARAM_ED_AAD in multiple chunks call the ckmc_cipher_initialize() multiple
1276  *          times with consecutive portions of the AAD in the @a params and the @a context returned
1277  *          from the first call. It must be done before the first call to ckmc_cipher_update().
1278  *
1279  * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e
1280  *                   for details. Supported algorithms:
1281  *                   - #CKMC_ALGO_AES_GCM,
1282  * @param[in] key_alias Alias of the key to be used for encryption/decryption
1283  * @param[in] key_password Optional password of the key used for encryption/decryption
1284  * @param[in] encrypt Encryption/decryption switch (true=encryption, false=decryption)
1285  * @param[out] context Encryption/decryption context. Must point to NULL if it's the first call.
1286  *                     Otherwise, it must point to the previously returned context.
1287  *
1288  * @return @c 0 on success, otherwise a negative error value
1289  * @retval #CKMC_ERROR_NONE Successful
1290  * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager or the key
1291  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory
1292  *                                       algorithm parameter, @a key_alias = NULL,
1293  *                                       @a context = NULL)
1294  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
1295  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a key_alias does not exist
1296  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
1297  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Key decryption failed because @a key_password is
1298  *                                           incorrect
1299  * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
1300  *
1301  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
1302  *
1303  * @see #ckmc_cipher_ctx_h
1304  * @see ckmc_cipher_update()
1305  * @see ckmc_cipher_finalize()
1306  * @see ckmc_cipher_free()
1307  */
1308 int ckmc_cipher_initialize(ckmc_param_list_h params,
1309                            const char *key_alias,
1310                            const char *key_password,
1311                            bool encrypt,
1312                            ckmc_cipher_ctx_h *context);
1313
1314 /**
1315  * @brief Performs symmetric encryption or decryption of the input and places the result in the
1316  *        output.
1317  *
1318  * @since_tizen 6.0
1319  *
1320  * @remarks The function may be called multiple times to encrypt succcessive blocks of data.
1321  * @remarks The newly created @a ppout must be destroyed using ckmc_buffer_free() when it's no
1322  *          longer needed.
1323  * @remarks Note that the backend may impose limit on the maximum size of processed data
1324  *          (ckmc_backend_get_max_chunk_size()).
1325  *
1326  * @param[in] context Encryption/decryption context created with ckmc_cipher_initialize()
1327  * @param[in] in Encryption/decryption input
1328  * @param[out] ppout Encryption/decryption output. Will be set to NULL if the output is empty.
1329  *
1330  * @return @c 0 on success, otherwise a negative error value
1331  * @retval #CKMC_ERROR_NONE Successful
1332  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (@a context = NULL,
1333  *                                       @a ppout = NULL)
1334  * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
1335  *
1336  * @see #ckmc_cipher_ctx_h
1337  * @see ckmc_cipher_initialize()
1338  * @see ckmc_cipher_finalize()
1339  * @see ckmc_cipher_free()
1340  */
1341 int ckmc_cipher_update(ckmc_cipher_ctx_h context,
1342                        const ckmc_raw_buffer_s in,
1343                        ckmc_raw_buffer_s **ppout);
1344
1345 /**
1346  * @brief Finalizes symmetric encryption or decryption and returns remaining output if any.
1347  *
1348  * @since_tizen 6.0
1349  *
1350  * @remarks After the call to this function the ckmc_cipher_update() can be called no more.
1351  * @remarks The newly created @a ppout must be destroyed using ckmc_buffer_free() when it's no
1352  *          longer needed.
1353  * @remarks When using #CKMC_ALGO_AES_GCM decryption the GCM tag must be passed as @a in. In other
1354  *          cases @a in should be set to NULL.
1355  * @remarks When using #CKMC_ALGO_AES_GCM encryption the GCM tag will be returned in @a ppout.
1356  *
1357  * @param[in] context Encryption/decryption context created with ckmc_cipher_initialize()
1358  * @param[in] in Optional additional decryption input required by some of the modes.
1359  * @param[out] ppout Encryption/decryption output. Will be set to NULL if the output is empty.
1360  *
1361  * @return @c 0 on success, otherwise a negative error value
1362  * @retval #CKMC_ERROR_NONE Successful
1363  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (@a context = NULL,
1364  *                                       @a ppout = NULL)
1365  * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
1366  *
1367  * @see #ckmc_cipher_ctx_h
1368  * @see ckmc_cipher_initialize()
1369  * @see ckmc_cipher_update()
1370  * @see ckmc_cipher_free()
1371  */
1372 int ckmc_cipher_finalize(ckmc_cipher_ctx_h context,
1373                          const ckmc_raw_buffer_s *in,
1374                          ckmc_raw_buffer_s **ppout);
1375
1376 /**
1377  * @brief Destroys the encryption/decryption context and releases all its resources.
1378  *
1379  * @since_tizen 6.0
1380  *
1381  * @param[in] context Encryption/decryption context created with ckmc_cipher_initialize()
1382  *
1383  * @see #ckmc_cipher_ctx_h
1384  * @see ckmc_cipher_initialize()
1385  * @see ckmc_cipher_update()
1386  * @see ckmc_cipher_finalize()
1387  */
1388 void ckmc_cipher_free(ckmc_cipher_ctx_h context);
1389
1390 /**
1391  * @brief Retrieves backend information.
1392  *
1393  * @since_tizen 6.0
1394  *
1395  * @remarks The newly created @a ppinfo must be destroyed using ckmc_backend_info_free() when it's
1396  *          no longer needed.
1397  *
1398  * @param[in] backend Backend identifier
1399  * @param[out] ppinfo Backend information handle
1400  *
1401  * @return @c 0 on success, otherwise a negative error value
1402  * @retval #CKMC_ERROR_NONE Successful
1403  * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager
1404  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (@a backend is invalid,
1405  *                                       @a ppinfo = NULL)
1406  * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
1407  *
1408  * @see #ckmc_backend_id_e
1409  * @see #ckmc_backend_info_h
1410  * @see ckmc_alias_info_get_backend()
1411  * @see ckmc_backend_get_max_chunk_size()
1412  * @see ckmc_backend_info_free()
1413  */
1414 int ckmc_get_backend_info(ckmc_backend_id_e backend, ckmc_backend_info_h* ppinfo);
1415
1416 #ifdef __cplusplus
1417 }
1418 #endif
1419
1420
1421 /**
1422  * @}
1423  */
1424
1425
1426 #endif /* __TIZEN_CORE_CKMC_MANAGER_H__ */