2 * Copyright (c) 2000 - 2021 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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
17 * @file ckmc-manager.h
19 * @brief Provides management functions(storing, retrieving, and removing) for keys,
20 * certificates and data of a user and additional crypto functions.
24 #ifndef __TIZEN_CORE_CKMC_MANAGER_H__
25 #define __TIZEN_CORE_CKMC_MANAGER_H__
29 #include <sys/types.h>
31 #include <ckmc/ckmc-type.h>
32 #include <ckmc/ckmc-error.h>
41 * @addtogroup CAPI_KEY_MANAGER_CLIENT_MODULE
47 * @brief Stores a key inside key manager based on the provided policy.
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
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()
75 * @see ckmc_get_key_alias_list()
79 int ckmc_save_key(const char *alias, const ckmc_key_s key, const ckmc_policy_s policy);
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.
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()
105 int ckmc_remove_key(const char *alias)
106 TIZEN_DEPRECATED_API;
110 * @brief Gets a key from key manager.
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()
134 int ckmc_get_key(const char *alias, const char *password, ckmc_key_s **ppkey);
138 * @brief Gets all the alias of keys that the client can access.
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()
161 int ckmc_get_key_alias_list(ckmc_alias_list_s **ppalias_list);
165 * @brief Gets the information about all the aliases of keys that the client can access.
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
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()
188 int ckmc_get_key_alias_info_list(ckmc_alias_info_list_s **ppalias_list);
192 * @brief Stores a certificate inside key manager based on the provided policy.
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
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()
215 * @see #ckmc_policy_s
217 int ckmc_save_cert(const char *alias, const ckmc_cert_s cert, const ckmc_policy_s policy);
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.
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()
243 int ckmc_remove_cert(const char *alias)
244 TIZEN_DEPRECATED_API;
248 * @brief Gets a certificate from key manager.
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
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()
274 int ckmc_get_cert(const char *alias, const char *password, ckmc_cert_s **ppcert);
278 * @brief Gets all alias of certificates which the client can access.
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()
301 int ckmc_get_cert_alias_list(ckmc_alias_list_s **ppalias_list);
305 * @brief Gets the information about all the aliases of certificates that the client can access.
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
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()
328 int ckmc_get_cert_alias_info_list(ckmc_alias_info_list_s **ppalias_list);
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
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);
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
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()
389 int ckmc_get_pkcs12(const char *alias,
390 const char *key_password,
391 const char *cert_password,
392 ckmc_pkcs12_s **pkcs12);
396 * @brief Stores a data inside key manager based on the provided policy.
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
418 int ckmc_save_data(const char *alias, ckmc_raw_buffer_s data, const ckmc_policy_s policy);
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.
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()
444 int ckmc_remove_data(const char *alias)
445 TIZEN_DEPRECATED_API;
449 * @brief Gets a data from key manager.
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
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()
474 int ckmc_get_data(const char *alias, const char *password, ckmc_raw_buffer_s **ppdata);
478 * @brief Gets all alias of data which the client can access.
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
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()
501 int ckmc_get_data_alias_list(ckmc_alias_list_s **ppalias_list);
505 * @brief Gets the information about all the aliases of data that the client can access.
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
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()
528 int ckmc_get_data_alias_info_list(ckmc_alias_info_list_s **ppalias_list);
532 * @brief Creates RSA private/public key pair and stores them inside key manager based on each
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
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()
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);
567 * @brief Creates DSA private/public key pair and stores them inside key manager based on each policy.
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
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()
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);
601 * @brief Creates ECDSA private/public key pair and stores them inside key manager based on each policy.
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
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);
635 * @brief Creates AES key and stores it inside key manager based on the policy.
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
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
657 int ckmc_create_key_aes(size_t size, const char *key_alias, ckmc_policy_s key_policy);
661 * @brief Creates a signature on a given message using a private key and returns the signature.
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
667 * @remarks You must destroy the newly created @a ppsignature by calling ckmc_buffer_free() if it is
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
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
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);
705 * @brief Verifies a given signature on a given message using a public key and returns the signature
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
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
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
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);
747 * @brief Verifies a certificate chain and returns that chain.
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
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
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()
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);
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
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
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
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()
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;
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
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()
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);
855 * @brief Performs OCSP that checks certificate is whether revoked or not.
856 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
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)
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()
876 int ckmc_ocsp_check(const ckmc_cert_list_s *pcert_chain_list,
877 ckmc_ocsp_status_e *ocsp_status);
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.
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()
902 int ckmc_allow_access(const char *alias,
903 const char *accessor,
904 ckmc_access_right_e granted) TIZEN_DEPRECATED_API;
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.
928 int ckmc_set_permission(const char *alias, const char *accessor, int permissions);
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.
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
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()
955 int ckmc_deny_access(const char *alias, const char *accessor) TIZEN_DEPRECATED_API;
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()
983 int ckmc_remove_alias(const char *alias);
987 * @brief Encrypts data using selected key and algorithm.
991 * @remarks Key identified by @a key_alias should exist.
992 * @remarks You must destroy @a ppencrypted with ckmc_buffer_free().
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.
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
1024 * @pre User is already logged in and the user key is already loaded into memory in plain text form.
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
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);
1044 * @brief Decrypts data using selected key and algorithm.
1048 * @remarks Key identified by @a key_alias should exist.
1049 * @remarks You must destroy @a ppdecrypted with ckmc_buffer_free().
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
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
1082 * @pre User is already logged in and the user key is already loaded into memory in plain text form.
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
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);
1102 * @brief Unwraps one key with another and stores it inside key manager.
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 must not be set to #CKMC_KEY_NONE.
1109 * @remarks password in @a wrapped_key must be set to NULL. There's no need to additionally encrypt
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
1114 * @remarks Note that the backend may impose limit on the maximum size of @a wrapped_key
1115 * (ckmc_backend_get_max_chunk_size()).
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
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
1148 * @pre User is already logged in and the user key is already loaded into memory in plain text form.
1150 * @see ckmc_export_wrapped_key()
1152 * @see #ckmc_param_list_h
1153 * @see #ckmc_policy_s
1155 int ckmc_import_wrapped_key(const ckmc_param_list_h params,
1156 const char *wrapping_key_alias,
1157 const char *wrapping_key_password,
1159 const ckmc_key_s *wrapped_key,
1160 const ckmc_policy_s policy);
1164 * @brief Wraps one key with another and returns it to the client.
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().
1172 * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e
1173 * for details. Supported algorithms:
1174 * - #CKMC_ALGO_AES_CTR,
1175 * - #CKMC_ALGO_AES_CBC,
1176 * - #CKMC_ALGO_AES_GCM,
1177 * - #CKMC_ALGO_AES_CFB,
1178 * - #CKMC_ALGO_RSA_OAEP
1179 * @param[in] wrapping_key_alias The name of the wrapping key
1180 * @param[in] wrapping_key_password An optional password of the wrapping key
1181 * @param[in] alias The name of the key to be wrapped and exported
1182 * @param[in] password An optional password used to decrypt the key pointed by @a alias
1183 * @param[out] ppwrapped_key The wrapped key. In #CKMC_ALGO_AES_GCM mode it includes the GCM tag
1184 * appended at the end.
1186 * @return @c 0 on success, otherwise a negative error value
1187 * @retval #CKMC_ERROR_NONE Successful
1188 * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager, the
1189 * wrapping key or the key being wrapped
1190 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory
1191 * algorithm parameter, GCM tag authentication failed,
1192 * @a wrapping_key_alias = NULL, @a alias = NULL,
1193 * @a ppwrapped_key = NULL)
1194 * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
1195 * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a wrapping_key_alias or @a alias does not exist
1196 * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
1197 * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Wrapping key decryption failed because
1198 * @a wrapping_key_password is incorrect
1199 * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
1201 * @pre User is already logged in and the user key is already loaded into memory in plain text form.
1203 * @see ckmc_import_wrapped_key()
1205 * @see #ckmc_param_list_h
1207 int ckmc_export_wrapped_key(const ckmc_param_list_h params,
1208 const char *wrapping_key_alias,
1209 const char *wrapping_key_password,
1211 const char *password,
1212 ckmc_key_s **ppwrapped_key);
1216 * @brief Derives a secret or key from another key/secret and stores it inside key manager.
1220 * @remarks In case of #CKMC_ALGO_KBKDF algorithm, the secret pointed to by @a secret_alias must be
1221 * a binary data or a symmetric key (#CKMC_KEY_AES). The derived key pointed to by
1222 * @a new_key_alias will be a symmetric one. It will be stored as a #CKMC_KEY_AES.
1223 * @remarks In case of #CKMC_ALGO_ECDH algorithm, the key pointed to by @a secret_alias must be a
1224 * private EC key (#CKMC_KEY_ECDSA_PRIVATE). The derived secret pointed to by
1225 * @a new_key_alias will be in binary data form.
1227 * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e
1228 * for details. Supported algorithms:
1229 * - #CKMC_ALGO_KBKDF,
1230 * - #CKMC_ALGO_ECDH,
1231 * @param[in] secret_alias Alias of the secret/key to use as an input
1232 * @param[in] secret_password Optional password of the secret/key used as an input
1233 * @param[in] new_key_alias The name under which the derived key or secret will be stored
1234 * @param[in] new_key_policy Policy used to store the derived key or secret
1236 * @return @c 0 on success, otherwise a negative error value
1237 * @retval #CKMC_ERROR_NONE Successful
1238 * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager, the secret
1239 * or to create the new key/secret
1240 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory
1241 * algorithm parameter, @a secret_alias = NULL,
1242 * @a new_key_alias = NULL)
1243 * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
1244 * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a secret_alias does not exist
1245 * @retval #CKMC_ERROR_DB_ALIAS_EXISTS @a new_key_alias already exists
1246 * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
1247 * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Secret decryption failed because @a secret_password is
1249 * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
1251 * @pre User is already logged in and the user key is already loaded into memory in plain text form.
1254 * @snippet key_derive.cpp KEY_DERIVE example
1256 * @see #ckmc_param_list_h
1257 * @see #ckmc_policy_s
1259 int ckmc_key_derive(const ckmc_param_list_h params,
1260 const char *secret_alias,
1261 const char *secret_password,
1262 const char *new_key_alias,
1263 ckmc_policy_s new_key_policy);
1266 * @brief Sets up a symmetric encryption or decryption context with given key and parameters.
1270 * @remarks The newly created @a context must be destroyed using ckmc_cipher_free() when it's no
1272 * @remarks To perform the encryption/decryption, one or more calls to ckmc_cipher_update() must be
1273 * folowed by one call to ckmc_cipher_finalize().
1274 * @remarks To pass #CKMC_PARAM_ED_AAD in multiple chunks call the ckmc_cipher_initialize() multiple
1275 * times with consecutive portions of the AAD in the @a params and the @a context returned
1276 * from the first call. It must be done before the first call to ckmc_cipher_update().
1278 * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e
1279 * for details. Supported algorithms:
1280 * - #CKMC_ALGO_AES_GCM,
1281 * @param[in] key_alias Alias of the key to be used for encryption/decryption
1282 * @param[in] key_password Optional password of the key used for encryption/decryption
1283 * @param[in] encrypt Encryption/decryption switch (true=encryption, false=decryption)
1284 * @param[out] context Encryption/decryption context. Must point to NULL if it's the first call.
1285 * Otherwise, it must point to the previously returned context.
1287 * @return @c 0 on success, otherwise a negative error value
1288 * @retval #CKMC_ERROR_NONE Successful
1289 * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager or the key
1290 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory
1291 * algorithm parameter, @a key_alias = NULL,
1292 * @a context = NULL)
1293 * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in)
1294 * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a key_alias does not exist
1295 * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error
1296 * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Key decryption failed because @a key_password is
1298 * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
1300 * @pre User is already logged in and the user key is already loaded into memory in plain text form.
1302 * @see #ckmc_cipher_ctx_h
1303 * @see ckmc_cipher_update()
1304 * @see ckmc_cipher_finalize()
1305 * @see ckmc_cipher_free()
1307 int ckmc_cipher_initialize(ckmc_param_list_h params,
1308 const char *key_alias,
1309 const char *key_password,
1311 ckmc_cipher_ctx_h *context);
1314 * @brief Performs symmetric encryption or decryption of the input and places the result in the
1319 * @remarks The function may be called multiple times to encrypt succcessive blocks of data.
1320 * @remarks The newly created @a ppout must be destroyed using ckmc_buffer_free() when it's no
1322 * @remarks Note that the backend may impose limit on the maximum size of processed data
1323 * (ckmc_backend_get_max_chunk_size()).
1325 * @param[in] context Encryption/decryption context created with ckmc_cipher_initialize()
1326 * @param[in] in Encryption/decryption input
1327 * @param[out] ppout Encryption/decryption output. Will be set to NULL if the output is empty.
1329 * @return @c 0 on success, otherwise a negative error value
1330 * @retval #CKMC_ERROR_NONE Successful
1331 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (@a context = NULL,
1333 * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
1335 * @see #ckmc_cipher_ctx_h
1336 * @see ckmc_cipher_initialize()
1337 * @see ckmc_cipher_finalize()
1338 * @see ckmc_cipher_free()
1340 int ckmc_cipher_update(ckmc_cipher_ctx_h context,
1341 const ckmc_raw_buffer_s in,
1342 ckmc_raw_buffer_s **ppout);
1345 * @brief Finalizes symmetric encryption or decryption and returns remaining output if any.
1349 * @remarks After the call to this function the ckmc_cipher_update() can be called no more.
1350 * @remarks The newly created @a ppout must be destroyed using ckmc_buffer_free() when it's no
1352 * @remarks When using #CKMC_ALGO_AES_GCM decryption the GCM tag must be passed as @a in. In other
1353 * cases @a in should be set to NULL.
1354 * @remarks When using #CKMC_ALGO_AES_GCM encryption the GCM tag will be returned in @a ppout.
1356 * @param[in] context Encryption/decryption context created with ckmc_cipher_initialize()
1357 * @param[in] in Optional additional decryption input required by some of the modes.
1358 * @param[out] ppout Encryption/decryption output. Will be set to NULL if the output is empty.
1360 * @return @c 0 on success, otherwise a negative error value
1361 * @retval #CKMC_ERROR_NONE Successful
1362 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (@a context = NULL,
1364 * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
1366 * @see #ckmc_cipher_ctx_h
1367 * @see ckmc_cipher_initialize()
1368 * @see ckmc_cipher_update()
1369 * @see ckmc_cipher_free()
1371 int ckmc_cipher_finalize(ckmc_cipher_ctx_h context,
1372 const ckmc_raw_buffer_s *in,
1373 ckmc_raw_buffer_s **ppout);
1376 * @brief Destroys the encryption/decryption context and releases all its resources.
1380 * @param[in] context Encryption/decryption context created with ckmc_cipher_initialize()
1382 * @see #ckmc_cipher_ctx_h
1383 * @see ckmc_cipher_initialize()
1384 * @see ckmc_cipher_update()
1385 * @see ckmc_cipher_finalize()
1387 void ckmc_cipher_free(ckmc_cipher_ctx_h context);
1390 * @brief Retrieves backend information.
1394 * @remarks The newly created @a ppinfo must be destroyed using ckmc_backend_info_free() when it's
1397 * @param[in] backend Backend identifier
1398 * @param[out] ppinfo Backend information handle
1400 * @return @c 0 on success, otherwise a negative error value
1401 * @retval #CKMC_ERROR_NONE Successful
1402 * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager
1403 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (@a backend is invalid,
1405 * @retval #CKMC_ERROR_SERVER_ERROR Unknown error
1407 * @see #ckmc_backend_id_e
1408 * @see #ckmc_backend_info_h
1409 * @see ckmc_alias_info_get_backend()
1410 * @see ckmc_backend_get_max_chunk_size()
1411 * @see ckmc_backend_info_free()
1413 int ckmc_get_backend_info(ckmc_backend_id_e backend, ckmc_backend_info_h* ppinfo);
1425 #endif /* __TIZEN_CORE_CKMC_MANAGER_H__ */