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  * @deprecated Deprecated since 6.5. Use raw OpenSSL instead.
 856  * @brief Performs OCSP that checks certificate is whether revoked or not.
 857  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 858  * @privlevel public
 859  * @privilege %http://tizen.org/privilege/internet
 860  * @remarks %http://tizen.org/privilege/internet (public level privilege) is required to use this
 861  *          function instead of %http://tizen.org/privilege/keymanager (public level privilege)
 862  *          since 3.0.
 863  * @param[in] pcert_chain_list Valid certificate chain to perform OCSP check
 864  * @param[out] ocsp_status The pointer to status result of OCSP check
 865  * @return @c 0 on success,
 866  *         otherwise a negative error value
 867  * @retval #CKMC_ERROR_NONE Successful
 868  * @retval #CKMC_ERROR_NOT_SUPPORTED Device needed to run API is not supported
 869  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
 870  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 871  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 872  * @pre @a pcert_chain_list is created with ckmc_get_certificate_chain() or
 873  *      ckmc_get_certificate_chain_with_alias().
 874  * @see ckmc_get_cert_chain())
 875  * @see ckmc_cert_list_all_free()
 876  */
 877 int ckmc_ocsp_check(const ckmc_cert_list_s *pcert_chain_list,
 878                     ckmc_ocsp_status_e *ocsp_status) TIZEN_DEPRECATED_API;
 879
 880
 881 /**
 882  * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif
 883  *             [Use ckmc_set_permission() instead]
 884  * @brief Allows another application to access client's application data.
 885  * @since_tizen 2.3
 886  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 887  *          use this function since 3.0.
 888  * @remarks Data identified by @a alias should exist.
 889  * @param[in] alias Data alias for which access will be granted
 890  * @param[in] accessor Package id of the application that will gain access rights
 891  * @param[in] granted Rights granted for @a accessor application
 892  * @return @c 0 on success,
 893  *         otherwise a negative error value
 894  * @retval #CKMC_ERROR_NONE Successful
 895  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager or modify permissions
 896  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 897  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 898  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 899  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 900  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 901  * @see ckmc_deny_access()
 902  */
 903 int ckmc_allow_access(const char *alias,
 904                       const char *accessor,
 905                       ckmc_access_right_e granted) TIZEN_DEPRECATED_API;
 906
 907
 908 /**
 909  * @brief Allows another application to access client's application data.
 910  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 911  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 912  *          use this function since 3.0.
 913  * @remarks Data identified by @a alias should exist.
 914  * @param[in] alias Data alias for which access will be granted
 915  * @param[in] accessor Package id of the application that will gain access rights
 916  * @param[in] permissions Mask of permissions granted for @a accessor application
 917  *                        (#ckmc_permission_e)
 918  *                        (previous permission mask will be replaced with the new mask value)
 919  * @return @c 0 on success,
 920  *         otherwise a negative error value
 921  * @retval #CKMC_ERROR_NONE Successful
 922  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager or modify permissions
 923  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 924  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 925  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 926  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 927  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 928  */
 929 int ckmc_set_permission(const char *alias, const char *accessor, int permissions);
 930
 931
 932 /**
 933  * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif
 934  *             [Use ckmc_set_permission() instead]
 935  * @brief Revokes another application's access to client's application data.
 936  * @since_tizen 2.3
 937  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 938  *          use this function since 3.0.
 939  * @remarks Data identified by @a alias should exist.
 940  * @remarks Only access previously granted with ckmc_allow_access() can be revoked.
 941  * @param[in] alias Data alias for which access will be revoked
 942  * @param[in] accessor Package id of the application that will lose access rights
 943  * @return @c 0 on success,
 944  *         otherwise a negative error value
 945  * @retval #CKMC_ERROR_NONE Successful
 946  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager or modify permissions
 947  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid or the @a accessor doesn't have
 948  *                                       access to @a alias
 949  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 950  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
 951  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 952  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 953  * @see ckmc_allow_access()
 954  * @see ckmc_set_permission()
 955  */
 956 int ckmc_deny_access(const char *alias, const char *accessor) TIZEN_DEPRECATED_API;
 957
 958
 959 /**
 960  * @brief Removes an entry (no matter of type) from the key manager.
 961  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 962  * @remarks %http://tizen.org/privilege/keymanager (public level privilege) is no longer required to
 963  *          use this function since 3.0.
 964  * @remarks To remove item, client must have remove permission to the specified item.
 965  * @remarks The item owner can remove by default.
 966  * @param[in] alias Item alias to be removed
 967  * @return @c 0 on success,
 968  *         otherwise a negative error value
 969  * @retval #CKMC_ERROR_NONE Successful
 970  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager or the item to remove
 971  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
 972  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
 973  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
 974  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Alias does not exist
 975  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 976  * @see ckmc_save_key()
 977  * @see ckmc_save_cert()
 978  * @see ckmc_save_data()
 979  * @see ckmc_save_pkcs12()
 980  * @see ckmc_create_key_pair_rsa()
 981  * @see ckmc_create_key_pair_dsa()
 982  * @see ckmc_create_key_pair_ecdsa()
 983  */
 984 int ckmc_remove_alias(const char *alias);
 985
 986
 987 /**
 988  * @brief Encrypts data using selected key and algorithm.
 989  *
 990  * @since_tizen 3.0
 991  *
 992  * @remarks Key identified by @a key_alias should exist.
 993  * @remarks You must destroy @a ppencrypted with ckmc_buffer_free().
 994  *
 995  * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e
 996  *                   for details. Supported algorithms:
 997  *                   - #CKMC_ALGO_AES_CTR,
 998  *                   - #CKMC_ALGO_AES_CBC,
 999  *                   - #CKMC_ALGO_AES_GCM,
1000  *                   - #CKMC_ALGO_AES_CFB,
1001  *                   - #CKMC_ALGO_RSA_OAEP
1002  * @param[in] key_alias Alias of the key to be used for encryption
1003  * @param[in] password The password used in decrypting a key value. If password of the policy is
1004  *                     provided in ckmc_save_key(), the same password should be provided
1005  * @param[in] decrypted Data to be encrypted. In case of AES algorithm the backend may impose limit
1006  *                      on the maximum size of processed data
1007  *                      (@see ckmc_backend_get_max_chunk_size()). For RSA the size must be smaller
1008  *                      or equal to key size in bytes - 42.
1009  *                      Example: for 1024 RSA key the maximum data size is 1024/8 - 42 = 86.
1010  * @param[out] ppencrypted Encrypted data. In #CKMC_ALGO_AES_GCM mode it includes the GCM tag
1011  *                         appended at the end.
1012  *
1013  * @return @c 0 on success, otherwise a negative error value
1014  * @retval #CKMC_ERROR_NONE Successful
1015  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager or the encrypting key
1016  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory
1017  *                                       algorithm parameter or RSA data too long, decrypted = NULL,
1018  *                                       ppencrypted = NULL)
1019  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
1020  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
1021  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Key with given alias does not exist
1022  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Key decryption failed because password is incorrect
1023  * @retval #CKMC_ERROR_SERVER_ERROR Too big data size or unsupported GCM mode (32 and 64 bit tag
1024  *                                  lengths not supported on TEE backend) or internal error
1025  *
1026  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
1027  *
1028  * @see ckmc_buffer_free()
1029  * @see ckmc_param_list_new()
1030  * @see ckmc_param_list_free()
1031  * @see ckmc_param_list_set_integer()
1032  * @see ckmc_param_list_set_buffer()
1033  * @see ckmc_generate_new_params()
1034  * @see #ckmc_param_list_h
1035  * @see #ckmc_param_name_e
1036  * @see #ckmc_algo_type_e
1037  */
1038 int ckmc_encrypt_data(ckmc_param_list_h params,
1039                       const char *key_alias,
1040                       const char *password,
1041                       const ckmc_raw_buffer_s decrypted,
1042                       ckmc_raw_buffer_s **ppencrypted);
1043
1044
1045 /**
1046  * @brief Decrypts data using selected key and algorithm.
1047  *
1048  * @since_tizen 3.0
1049  *
1050  * @remarks Key identified by @a key_alias should exist.
1051  * @remarks You must destroy @a ppdecrypted with ckmc_buffer_free().
1052  *
1053  * @param[in] params Algorithm parameter list handle. You should use the same parameters that were
1054  *                   used for encryption. See #ckmc_param_list_h and #ckmc_algo_type_e for details.
1055  *                   Supported algorithms:
1056  *                   - #CKMC_ALGO_AES_CTR,
1057  *                   - #CKMC_ALGO_AES_CBC,
1058  *                   - #CKMC_ALGO_AES_GCM,
1059  *                   - #CKMC_ALGO_AES_CFB,
1060  *                   - #CKMC_ALGO_RSA_OAEP
1061  * @param[in] key_alias Alias of the key to be used for encryption
1062  * @param[in] password The password used in decrypting a key value. If password of the policy is
1063  *                     provided in ckmc_save_key(), the same password should be provided
1064  * @param[in] encrypted Data to be decrypted. #CKMC_ALGO_AES_GCM mode requires GCM tag to be
1065  *                      appended at the end. In case of AES algorithm the backend may impose limit
1066  *                      on the maximum size of processed data
1067  *                      (@see ckmc_backend_get_max_chunk_size()). For RSA the size must be smaller
1068  *                      or equal to key size in bytes - 42.
1069  * @param[out] ppdecrypted Decrypted data
1070  *
1071  * @return @c 0 on success, otherwise a negative error value
1072  * @retval #CKMC_ERROR_NONE Successful
1073  * @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager or the decrypting key
1074  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory
1075  *                                       algorithm parameter, GCM tag authentication failed, key or
1076  *                                       data is wrong, in case of RSA key is wrong or data too
1077  *                                       long, encrypted = NULL, ppdecrypted = NULL)
1078  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
1079  * @retval #CKMC_ERROR_DB_ERROR Failed due to the error with unknown reason
1080  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Key with given alias does not exist
1081  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Key decryption failed because password is incorrect
1082  * @retval #CKMC_ERROR_SERVER_ERROR Too big data size or unsupported GCM mode (32 and 64 bit tag
1083  *                                  lengths not supported on TEE backend) or internal error
1084  *
1085  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
1086  *
1087  * @see ckmc_buffer_free()
1088  * @see ckmc_param_list_new()
1089  * @see ckmc_param_list_free()
1090  * @see ckmc_param_list_set_integer()
1091  * @see ckmc_param_list_set_buffer()
1092  * @see ckmc_generate_new_params()
1093  * @see #ckmc_param_list_h
1094  * @see #ckmc_param_name_e
1095  * @see #ckmc_algo_type_e
1096  */
1097 int ckmc_decrypt_data(ckmc_param_list_h params,
1098                       const char *key_alias,
1099                       const char *password,
1100                       const ckmc_raw_buffer_s encrypted,
1101                       ckmc_raw_buffer_s **ppdecrypted);
1102
1103
1104 /**
1105  * @brief Unwraps one key with another and stores it inside key manager.
1106  *
1107  * @since_tizen 6.0
1108  *
1109  * @remarks The wrapping key must be either symmetric (#CKMC_KEY_AES) or private RSA
1110  *          (#CKMC_KEY_RSA_PRIVATE).
1111  * @remarks key_type in @a wrapped_key may be set to #CKMC_KEY_NONE as an input. In such case the
1112  *          key type is determined inside key manager during storing keys.
1113  * @remarks password in @a wrapped_key must be set to NULL. There's no need to additionally encrypt
1114  *          a wrapped key.
1115  * @remarks If password in @a policy is provided, the stored key is additionally encrypted with it.
1116  * @remarks If extractable in @a policy is set to false, the stored key may still be exported in a
1117  *          wrapped form.
1118  * @remarks Note that the backend may impose limit on the maximum size of @a wrapped_key
1119  *          (@see ckmc_backend_get_max_chunk_size()).
1120  *
1121  * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e
1122  *                   for details. Supported algorithms:
1123  *                   - #CKMC_ALGO_AES_CTR,
1124  *                   - #CKMC_ALGO_AES_CBC,
1125  *                   - #CKMC_ALGO_AES_GCM,
1126  *                   - #CKMC_ALGO_AES_CFB,
1127  *                   - #CKMC_ALGO_RSA_OAEP
1128  * @param[in] wrapping_key_alias The name of the wrapping key.
1129  * @param[in] wrapping_key_password An optional password of the wrapping key
1130  * @param[in] alias The name of a key to be stored
1131  * @param[in] wrapped_key The wrapped key to be unwrapped and stored. #CKMC_ALGO_AES_GCM mode
1132  *                        requires GCM tag to be appended at the end of the @a wrapped_key.
1133  * @param[in] policy The policy about how to store a key securely
1134  *
1135  * @return @c 0 on success, otherwise a negative error value
1136  * @retval #CKMC_ERROR_NONE Successful
1137  * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager, the
1138  *                                       wrapping key or to create the unwrapped key
1139  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory
1140  *                                       algorithm parameter, GCM tag authentication failed,
1141  *                                       @a wrapping_key_alias = NULL, @a alias = NULL,
1142  *                                       @a wrapped_key = NULL)
1143  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
1144  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a wrapping_key_alias does not exist
1145  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS @a alias already exists
1146  * @retval #CKMC_ERROR_INVALID_FORMAT The format of @a wrapped_key is not valid
1147  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
1148  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Wrapping key decryption failed because
1149  *                                           @a wrapping_key_password is incorrect
1150  * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
1151  *
1152  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
1153  *
1154  * @see ckmc_export_wrapped_key()
1155  * @see #ckmc_key_s
1156  * @see #ckmc_param_list_h
1157  * @see #ckmc_policy_s
1158  */
1159 int ckmc_import_wrapped_key(const ckmc_param_list_h params,
1160                             const char *wrapping_key_alias,
1161                             const char *wrapping_key_password,
1162                             const char *alias,
1163                             const ckmc_key_s *wrapped_key,
1164                             const ckmc_policy_s policy);
1165
1166
1167 /**
1168  * @brief Wraps one key with another and returns it to the client.
1169  *
1170  * @since_tizen 6.0
1171  *
1172  * @remarks The wrapping key must be either symmetric (#CKMC_KEY_AES) or public RSA
1173  *          (#CKMC_KEY_RSA_PUBLIC).
1174  * @remarks The @a ppwrapped_key should be released using ckmc_key_free().
1175  *
1176  * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e
1177  *                   for details. Supported algorithms:
1178  *                   - #CKMC_ALGO_AES_CTR,
1179  *                   - #CKMC_ALGO_AES_CBC,
1180  *                   - #CKMC_ALGO_AES_GCM,
1181  *                   - #CKMC_ALGO_AES_CFB,
1182  *                   - #CKMC_ALGO_RSA_OAEP
1183  * @param[in] wrapping_key_alias The name of the wrapping key
1184  * @param[in] wrapping_key_password An optional password of the wrapping key
1185  * @param[in] alias The name of the key to be wrapped and exported
1186  * @param[in] password An optional password used to decrypt the key pointed by @a alias
1187  * @param[out] ppwrapped_key The wrapped key. In #CKMC_ALGO_AES_GCM mode it includes the GCM tag
1188  *                           appended at the end.
1189  *
1190  * @return @c 0 on success, otherwise a negative error value
1191  * @retval #CKMC_ERROR_NONE Successful
1192  * @retval #CKMC_ERROR_PERMISSION_DENIED Insuffucient permissions to access key manager, the
1193  *                                       wrapping key or the key being wrapped
1194  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory
1195  *                                       algorithm parameter, GCM tag authentication failed,
1196  *                                       @a wrapping_key_alias = NULL, @a alias = NULL,
1197  *                                       @a ppwrapped_key = NULL)
1198  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
1199  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a wrapping_key_alias or @a alias does not exist
1200  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
1201  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Wrapping key decryption failed because
1202  *                                           @a wrapping_key_password is incorrect
1203  * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
1204  *
1205  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
1206  *
1207  * @see ckmc_import_wrapped_key()
1208  * @see #ckmc_key_s
1209  * @see #ckmc_param_list_h
1210  */
1211 int ckmc_export_wrapped_key(const ckmc_param_list_h params,
1212                             const char *wrapping_key_alias,
1213                             const char *wrapping_key_password,
1214                             const char *alias,
1215                             const char *password,
1216                             ckmc_key_s **ppwrapped_key);
1217
1218
1219 /**
1220  * @brief Derives a secret or key from another key/secret and stores it inside key manager.
1221  *
1222  * @since_tizen 6.0
1223  *
1224  * @remarks In case of #CKMC_ALGO_KBKDF algorithm, the secret pointed to by @a secret_alias must be
1225  *          a binary data or a symmetric key (#CKMC_KEY_AES). The derived key pointed to by
1226  *          @a new_key_alias will be a symmetric one. It will be stored as a #CKMC_KEY_AES.
1227  * @remarks In case of #CKMC_ALGO_ECDH algorithm, the key pointed to by @a secret_alias must be a
1228  *          private EC key (#CKMC_KEY_ECDSA_PRIVATE). The derived secret pointed to by
1229  *          @a new_key_alias  will be in binary data form.
1230  *
1231  * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e
1232  *                   for details. Supported algorithms:
1233  *                   - #CKMC_ALGO_KBKDF,
1234  *                   - #CKMC_ALGO_ECDH,
1235  * @param[in] secret_alias Alias of the secret/key to use as an input
1236  * @param[in] secret_password Optional password of the secret/key used as an input
1237  * @param[in] new_key_alias The name under which the derived key or secret will be stored
1238  * @param[in] new_key_policy Policy used to store the derived key or secret
1239  *
1240  * @return @c 0 on success, otherwise a negative error value
1241  * @retval #CKMC_ERROR_NONE Successful
1242  * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager, the secret
1243  *                                       or to create the new key/secret
1244  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory
1245  *                                       algorithm parameter, @a secret_alias = NULL,
1246  *                                       @a new_key_alias = NULL)
1247  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
1248  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a secret_alias does not exist
1249  * @retval #CKMC_ERROR_DB_ALIAS_EXISTS @a new_key_alias already exists
1250  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
1251  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Secret decryption failed because @a secret_password is
1252  *                                           incorrect
1253  * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
1254  *
1255  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
1256  *
1257  * @par Example
1258  * @snippet key_derive.cpp KEY_DERIVE example
1259  *
1260  * @see #ckmc_param_list_h
1261  * @see #ckmc_policy_s
1262  */
1263 int ckmc_key_derive(const ckmc_param_list_h params,
1264                     const char *secret_alias,
1265                     const char *secret_password,
1266                     const char *new_key_alias,
1267                     ckmc_policy_s new_key_policy);
1268
1269 /**
1270  * @brief Sets up a symmetric encryption or decryption context with given key and parameters.
1271  *
1272  * @since_tizen 6.0
1273  *
1274  * @remarks The newly created @a context must be destroyed using ckmc_cipher_free() when it's no
1275  *          longer needed.
1276  * @remarks To perform the encryption/decryption, one or more calls to ckmc_cipher_update() must be
1277  *          folowed by one call to ckmc_cipher_finalize().
1278  * @remarks To pass #CKMC_PARAM_ED_AAD in multiple chunks call the ckmc_cipher_initialize() multiple
1279  *          times with consecutive portions of the AAD in the @a params and the @a context returned
1280  *          from the first call. It must be done before the first call to ckmc_cipher_update().
1281  *
1282  * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e
1283  *                   for details. Supported algorithms:
1284  *                   - #CKMC_ALGO_AES_GCM,
1285  * @param[in] key_alias Alias of the key to be used for encryption/decryption
1286  * @param[in] key_password Optional password of the key used for encryption/decryption
1287  * @param[in] encrypt Encryption/decryption switch (true=encryption, false=decryption)
1288  * @param[out] context Encryption/decryption context. Must point to NULL if it's the first call.
1289  *                     Otherwise, it must point to the previously returned context.
1290  *
1291  * @return @c 0 on success, otherwise a negative error value
1292  * @retval #CKMC_ERROR_NONE Successful
1293  * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager or the key
1294  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory
1295  *                                       algorithm parameter, @a key_alias = NULL,
1296  *                                       @a context = NULL)
1297  * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
1298  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a key_alias does not exist
1299  * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
1300  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Key decryption failed because @a key_password is
1301  *                                           incorrect
1302  * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
1303  *
1304  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
1305  *
1306  * @see #ckmc_cipher_ctx_h
1307  * @see ckmc_cipher_update()
1308  * @see ckmc_cipher_finalize()
1309  * @see ckmc_cipher_free()
1310  */
1311 int ckmc_cipher_initialize(ckmc_param_list_h params,
1312                            const char *key_alias,
1313                            const char *key_password,
1314                            bool encrypt,
1315                            ckmc_cipher_ctx_h *context);
1316
1317 /**
1318  * @brief Performs symmetric encryption or decryption of the input and places the result in the
1319  *        output.
1320  *
1321  * @since_tizen 6.0
1322  *
1323  * @remarks The function may be called multiple times to encrypt succcessive blocks of data.
1324  * @remarks The newly created @a ppout must be destroyed using ckmc_buffer_free() when it's no
1325  *          longer needed.
1326  * @remarks Note that the backend may impose limit on the maximum size of processed data
1327  *          (@see ckmc_backend_get_max_chunk_size()).
1328  *
1329  * @param[in] context Encryption/decryption context created with ckmc_cipher_initialize()
1330  * @param[in] in Encryption/decryption input
1331  * @param[out] ppout Encryption/decryption output. Will be set to NULL if the output is empty.
1332  *
1333  * @return @c 0 on success, otherwise a negative error value
1334  * @retval #CKMC_ERROR_NONE Successful
1335  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (@a context = NULL,
1336  *                                       @a ppout = NULL)
1337  * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
1338  *
1339  * @see #ckmc_cipher_ctx_h
1340  * @see ckmc_cipher_initialize()
1341  * @see ckmc_cipher_finalize()
1342  * @see ckmc_cipher_free()
1343  */
1344 int ckmc_cipher_update(ckmc_cipher_ctx_h context,
1345                        const ckmc_raw_buffer_s in,
1346                        ckmc_raw_buffer_s **ppout);
1347
1348 /**
1349  * @brief Finalizes symmetric encryption or decryption and returns remaining output if any.
1350  *
1351  * @since_tizen 6.0
1352  *
1353  * @remarks After the call to this function the ckmc_cipher_update() can be called no more.
1354  * @remarks The newly created @a ppout must be destroyed using ckmc_buffer_free() when it's no
1355  *          longer needed.
1356  * @remarks When using #CKMC_ALGO_AES_GCM decryption the GCM tag must be passed as @a in. In other
1357  *          cases @a in should be set to NULL.
1358  * @remarks When using #CKMC_ALGO_AES_GCM encryption the GCM tag will be returned in @a ppout.
1359  *
1360  * @param[in] context Encryption/decryption context created with ckmc_cipher_initialize()
1361  * @param[in] in Optional additional decryption input required by some of the modes.
1362  * @param[out] ppout Encryption/decryption output. Will be set to NULL if the output is empty.
1363  *
1364  * @return @c 0 on success, otherwise a negative error value
1365  * @retval #CKMC_ERROR_NONE Successful
1366  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (@a context = NULL,
1367  *                                       @a ppout = NULL)
1368  * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
1369  *
1370  * @see #ckmc_cipher_ctx_h
1371  * @see ckmc_cipher_initialize()
1372  * @see ckmc_cipher_update()
1373  * @see ckmc_cipher_free()
1374  */
1375 int ckmc_cipher_finalize(ckmc_cipher_ctx_h context,
1376                          const ckmc_raw_buffer_s *in,
1377                          ckmc_raw_buffer_s **ppout);
1378
1379 /**
1380  * @brief Destroys the encryption/decryption context and releases all its resources.
1381  *
1382  * @since_tizen 6.0
1383  *
1384  * @param[in] context Encryption/decryption context created with ckmc_cipher_initialize()
1385  *
1386  * @see #ckmc_cipher_ctx_h
1387  * @see ckmc_cipher_initialize()
1388  * @see ckmc_cipher_update()
1389  * @see ckmc_cipher_finalize()
1390  */
1391 void ckmc_cipher_free(ckmc_cipher_ctx_h context);
1392
1393 /**
1394  * @brief Retrieves backend information.
1395  *
1396  * @since_tizen 6.0
1397  *
1398  * @remarks The newly created @a ppinfo must be destroyed using ckmc_backend_info_free() when it's
1399  *          no longer needed.
1400  *
1401  * @param[in] backend Backend identifier
1402  * @param[out] ppinfo Backend information handle
1403  *
1404  * @return @c 0 on success, otherwise a negative error value
1405  * @retval #CKMC_ERROR_NONE Successful
1406  * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager
1407  * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (@a backend is invalid,
1408  *                                       @a ppinfo = NULL)
1409  * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
1410  *
1411  * @see #ckmc_backend_id_e
1412  * @see #ckmc_backend_info_h
1413  * @see ckmc_alias_info_get_backend()
1414  * @see ckmc_backend_get_max_chunk_size()
1415  * @see ckmc_backend_info_free()
1416  */
1417 int ckmc_get_backend_info(ckmc_backend_id_e backend, ckmc_backend_info_h* ppinfo);
1418
1419 #ifdef __cplusplus
1420 }
1421 #endif
1422
1423
1424 /**
1425  * @}
1426  */
1427
1428
1429 #endif /* __TIZEN_CORE_CKMC_MANAGER_H__ */