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
19 * @brief Definitions of struct for the Key Manager's CAPI and their utility functions.
23 #ifndef __TIZEN_CORE_CKMC_TYPE_H__
24 #define __TIZEN_CORE_CKMC_TYPE_H__
29 #include <ckmc/ckmc-error.h>
32 #define KEY_MANAGER_CAPI __attribute__((visibility("default")))
41 * @addtogroup CAPI_KEY_MANAGER_TYPES_MODULE
47 * Note: on tizen 3.0 owner id is equal to pkgId.
48 * Preinstalled system(uid < 5000) and user (uid >= 5000) applications
49 * does not have any pkgId. That's why ckm uses special "virtual"
50 * pkgid for them. The virtual strings are defined under:
51 * ckmc_owner_id_system
56 * @deprecated Deprecated since 3.0. [Use ckmc_owner_id_separator instead]
57 * @brief Separator between alias and label.
59 * @remarks Alias can be provided as an alias alone, or together with label - in this
60 * case, separator " " (space bar) is used to separate label and alias.
61 * @see #ckmc_owner_id_separator
63 KEY_MANAGER_CAPI extern char const *const ckmc_label_name_separator;
67 * @brief Separator between alias and owner id.
69 * @remarks Alias can be provided as an alias alone, or together with owner id.
70 * In this case, separator " " (space bar) is used to separate id and alias.
71 * @see ckmc_alias_new()
73 KEY_MANAGER_CAPI extern char const *const ckmc_owner_id_separator;
77 * @brief The owner of system database.
79 * @remarks #ckmc_owner_id_system contains id connected with all system applications that run with
80 * uid less than 5000. Client should use #ckmc_owner_id_system to access data owned by
81 * system application and stored in system database. Client must have permission to access
83 * @see ckmc_alias_new()
85 KEY_MANAGER_CAPI extern char const *const ckmc_owner_id_system;
89 * @brief Enumeration for key types of key manager.
92 typedef enum __ckmc_key_type {
93 CKMC_KEY_NONE = 0, /**< Key type not specified */
94 CKMC_KEY_RSA_PUBLIC, /**< RSA public key */
95 CKMC_KEY_RSA_PRIVATE, /**< RSA private key */
96 CKMC_KEY_ECDSA_PUBLIC, /**< ECDSA public key */
97 CKMC_KEY_ECDSA_PRIVATE, /**< ECDSA private key */
98 CKMC_KEY_DSA_PUBLIC, /**< DSA public key */
99 CKMC_KEY_DSA_PRIVATE, /**< DSA private key */
100 CKMC_KEY_AES, /**< AES key */
105 * @brief Enumeration for data format.
108 typedef enum __ckmc_data_format {
109 CKMC_FORM_DER_BASE64 = 0, /**< DER format base64 encoded data */
110 CKMC_FORM_DER, /**< DER encoded data */
111 CKMC_FORM_PEM /**< PEM encoded data. It consists of the DER format base64 encoded
112 with additional header and footer lines. */
113 } ckmc_data_format_e;
117 * @brief Enumeration for elliptic curve.
120 typedef enum __ckmc_ec_type {
121 CKMC_EC_PRIME192V1 = 0, /**< Elliptic curve domain "secp192r1" listed in "SEC 2" recommended
122 elliptic curve domain */
123 CKMC_EC_PRIME256V1, /**< "SEC 2" recommended elliptic curve domain - secp256r1 */
124 CKMC_EC_SECP384R1 /**< NIST curve P-384(covers "secp384r1", the elliptic curve domain
125 listed in See SEC 2 */
130 * @brief Enumeration for hash algorithm.
133 typedef enum __ckmc_hash_algo {
134 CKMC_HASH_NONE = 0, /**< No Hash Algorithm */
135 CKMC_HASH_SHA1, /**< Hash Algorithm SHA1 */
136 CKMC_HASH_SHA256, /**< Hash Algorithm SHA256 */
137 CKMC_HASH_SHA384, /**< Hash Algorithm SHA384 */
138 CKMC_HASH_SHA512 /**< Hash Algorithm SHA512 */
143 * @brief Enumeration for RSA padding algorithm.
146 typedef enum __ckmc_rsa_padding_algo {
147 CKMC_NONE_PADDING = 0, /**< No Padding */
148 CKMC_PKCS1_PADDING, /**< PKCS#1 Padding */
149 CKMC_X931_PADDING /**< X9.31 padding */
150 } ckmc_rsa_padding_algo_e;
154 * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif
155 * [Use #ckmc_permission_e instead]
156 * @brief Enumeration for database access rights.
159 typedef enum __ckmc_access_right {
160 CKMC_AR_READ = 0, /**< Access right for read*/
161 CKMC_AR_READ_REMOVE /**< Access right for read and remove*/
162 } ckmc_access_right_e;
166 * @brief Enumeration for permissions to access/modify alias.
167 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
169 typedef enum __ckmc_permission {
170 CKMC_PERMISSION_NONE = 0x00, /**< Clear permissions */
171 CKMC_PERMISSION_READ = 0x01, /**< Read allowed */
172 CKMC_PERMISSION_REMOVE = 0x02 /**< Remove allowed */
177 * @brief The structure for binary buffer used in key manager CAPI.
180 typedef struct __ckmc_raw_buff {
181 unsigned char *data; /**< Byte array containing binary data */
182 size_t size; /**< The size of the binary data */
187 * @brief The structure for a policy for storing key/certificate/binary data.
190 typedef struct __ckmc_policy {
191 char *password; /**< Byte array used to encrypt data inside CKM. If it is not NULL, the data
192 (or key, or certificate) is stored encrypted with this password inside
194 bool extractable; /**< If true key may be extracted from storage */
199 * @brief The structure for key used in key manager CAPI.
202 typedef struct __ckmc_key {
204 *raw_key; /**< Byte array of key. raw_key may be encrypted with password */
205 size_t key_size; /**< The byte size of raw_key */
206 ckmc_key_type_e key_type; /**< The raw_key's type */
207 char *password; /**< Byte array used to decrypt data raw_key inside key manager. */
212 * @brief The structure for certificate used in key manager CAPI.
215 typedef struct __ckmc_cert {
216 unsigned char *raw_cert; /**< Byte array of certificate */
217 size_t cert_size; /**< Byte size of raw_cert */
218 ckmc_data_format_e data_format; /**< Raw_cert's encoding format */
223 * @brief The structure for linked list of alias.
226 typedef struct __ckmc_alias_list {
227 char *alias; /**< The name of key, certificate or data stored in key manager */
228 struct __ckmc_alias_list *next; /**< The pointer pointing to the next #ckmc_alias_list_s */
231 struct ckmc_alias_info_s;
234 * @brief The structure of alias and additional information about it.
237 typedef struct ckmc_alias_info_s ckmc_alias_info_s;
240 * @brief The structure for linked list of alias with additional information.
243 typedef struct __ckmc_alias_info_list_s {
244 struct ckmc_alias_info_s* info; /**< The pointer pointing to the alias structure with additional
246 struct __ckmc_alias_info_list_s* next; /**< The pointer pointing to the next
247 #ckmc_alias_info_list_s */
248 } ckmc_alias_info_list_s;
252 * @brief The structure for linked list of #ckmc_cert_s.
255 typedef struct __ckmc_cert_list {
256 ckmc_cert_s *cert; /**< The pointer of #ckmc_cert_s */
257 struct __ckmc_cert_list *next; /**< The pointer pointing to the next #ckmc_cert_list_s */
262 * @brief Enumeration for OCSP status.
263 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
265 typedef enum __ckmc_ocsp_status {
266 CKMC_OCSP_STATUS_GOOD = 0, /**< OCSP status is good */
267 CKMC_OCSP_STATUS_REVOKED, /**< The certificate is revoked */
268 CKMC_OCSP_STATUS_UNKNOWN, /**< Unknown error */
269 CKMC_OCSP_ERROR_UNSUPPORTED, /**< The certificate does not provide OCSP extension */
270 CKMC_OCSP_ERROR_INVALID_URL, /**< The invalid URL in certificate OCSP extension */
271 CKMC_OCSP_ERROR_INVALID_RESPONSE, /**< The invalid response from OCSP server */
272 CKMC_OCSP_ERROR_REMOTE, /**< OCSP remote server error */
273 CKMC_OCSP_ERROR_NET, /**< Network connection error */
274 CKMC_OCSP_ERROR_INTERNAL /**< OpenSSL API error */
275 } ckmc_ocsp_status_e;
279 * @brief The structure for PKCS12 used in key manager CAPI.
280 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
282 typedef struct __ckmc_pkcs12 {
283 ckmc_key_s *priv_key; /**< The private key, may be NULL */
284 ckmc_cert_s *cert; /**< The certificate, may be NULL */
285 ckmc_cert_list_s *ca_chain; /**< The chain certificate list, may be NULL */
290 * @brief Enumeration for crypto algorithm parameters.
292 * @see #ckmc_algo_type_e
294 typedef enum __ckmc_param_name {
295 CKMC_PARAM_ALGO_TYPE = 1, /**< integer - type of algorithm (see #ckmc_algo_type_e) */
297 CKMC_PARAM_ED_IV = 101, /**< 16B buffer (up to 2^64-1 bytes long in case of AES GCM) */
298 CKMC_PARAM_ED_CTR_LEN, /**< integer - ctr length in bits*/
299 CKMC_PARAM_ED_AAD, /**< buffer - Additional Authentication Data for AES GCM */
300 CKMC_PARAM_ED_TAG_LEN, /**< integer - tag length in bits */
301 CKMC_PARAM_ED_LABEL, /**< buffer - RSA OAEP label (not supported at the moment) */
303 CKMC_PARAM_KDF_PRF = 401, /**< integer - pseudo-random function number (see #ckmc_kdf_prf_e)
305 CKMC_PARAM_KDF_LEN, /**< integer - length of the derived key in bytes. The value must be one of
306 {16, 24, 32} (Since 6.5) */
308 CKMC_PARAM_KBKDF_MODE, /**< integer - KDF mode number (see #ckmc_kbkdf_mode_e) (Since 6.5) */
309 CKMC_PARAM_KBKDF_LABEL, /**< buffer - the purpose for the derived key. Conflicts with
310 #CKMC_PARAM_KBKDF_FIXED_INPUT (Since 6.5) */
312 CKMC_PARAM_KBKDF_CONTEXT, /**< buffer - information related to the derived key. Conflicts with
313 #CKMC_PARAM_KBKDF_FIXED_INPUT (Since 6.5) */
315 CKMC_PARAM_KBKDF_FIXED_INPUT, /**< buffer - KBKDF fixed input replacing context and label
316 (Since 6.5). Conflicts with:
317 - #CKMC_PARAM_KBKDF_LABEL,
318 - #CKMC_PARAM_KBKDF_CONTEXT,
319 - #CKMC_PARAM_KBKDF_LLEN,
320 - #CKMC_PARAM_KBKDF_NO_SEPARATOR */
321 CKMC_PARAM_KBKDF_COUNTER_LOCATION, /**< integer - specifies location of the counter in KBKDF
322 (see #ckmc_kbkdf_counter_location_e) (Since 6.5) */
323 CKMC_PARAM_KBKDF_RLEN, /**< integer - specifies the length of the counter representation in bits
324 in KBKDF. The value must be one of {8, 16, 24, 32}. If not set, the
325 default value = 32 will be used. (Since 6.5) */
326 CKMC_PARAM_KBKDF_LLEN, /**< integer - specifies the length of the length suffix representation
327 in bits in KBKDF. The value must be one of {0, 8, 16, 24, 32}. If set to
328 0 the length suffix will be skipped. If not set, the default value = 32
329 will be used. The length suffix is skipped if
330 #CKMC_PARAM_KBKDF_FIXED_INPUT is passed and this parameter conflicts
331 with it. (Since 6.5) */
332 CKMC_PARAM_KBKDF_NO_SEPARATOR, /**< integer - presence of this parameter will skip the zero
333 octet separator between label and context in KBKDF.
334 All values are allowed. This parameter conflicts with
335 #CKMC_PARAM_KBKDF_FIXED_INPUT. (Since 6.5) */
337 CKMC_PARAM_ECDH_PUBKEY, /**< buffer - EC public key in DER form (see #ckmc_key_s) (Since 6.5) */
341 * @brief Enumeration for key derivation function pseudo-random function parameter.
344 * @see ckmc_key_derive()
345 * @see #ckmc_param_name_e
347 typedef enum __ckmc_kdf_prf {
348 CKMC_KDF_PRF_HMAC_SHA256 = 1, /**< HMAC SHA256 */
349 CKMC_KDF_PRF_HMAC_SHA384, /**< HMAC SHA384 */
350 CKMC_KDF_PRF_HMAC_SHA512, /**< HMAC SHA512 */
354 * @brief Enumeration for key based key derivation function mode.
357 * @see ckmc_key_derive()
358 * @see #ckmc_param_name_e
360 typedef enum __ckmc_kbkdf_mode {
361 CKMC_KBKDF_MODE_COUNTER = 1, /**< KBKDF counter mode */
365 * @brief Enumeration for KBKDF counter location relative to fixed input.
368 * @see ckmc_key_derive()
369 * @see #ckmc_param_name_e
371 typedef enum __ckmc_kbkdf_counter_location {
372 CKMC_KBKDF_COUNTER_BEFORE_FIXED = 1, /**< Counter is located before fixed input */
373 CKMC_KBKDF_COUNTER_AFTER_FIXED, /**< Counter is located after fixed input */
374 CKMC_KBKDF_COUNTER_MIDDLE_FIXED, /**< Counter is located in the middle of the fixed input
375 (between context and label). This setting requires setting
376 #CKMC_PARAM_KBKDF_LABEL and #CKMC_PARAM_KBKDF_CONTEXT and
377 conflicts with #CKMC_PARAM_KBKDF_FIXED_INPUT. If this location
378 is used the separator will be skipped regardless of the
379 #CKMC_PARAM_KBKDF_NO_SEPARATOR parameter */
380 } ckmc_kbkdf_counter_location_e;
383 * @brief Algorithm parameter list handle.
385 * @remarks Each parameter list must have at least one #CKMC_PARAM_ALGO_TYPE parameter that
386 * identifies the algorithm. See #ckmc_algo_type_e for available algorithms and additional
387 * parameters they support.
388 * @see ckmc_generate_new_params()
389 * @see ckmc_param_list_new()
390 * @see ckmc_param_list_set_integer()
391 * @see ckmc_param_list_set_buffer()
392 * @see ckmc_param_list_get_integer()
393 * @see ckmc_param_list_get_buffer()
394 * @see ckmc_param_list_free()
395 * @see #ckmc_algo_type_e
396 * @see #ckmc_param_name_e
398 typedef struct __ckmc_param_list *ckmc_param_list_h;
402 * @brief Enumeration for crypto algorithm types.
404 * @see #ckmc_param_name_e
406 typedef enum __ckmc_algo_type {
407 CKMC_ALGO_AES_CTR = 1, /**< AES-CTR algorithm
408 Supported parameters:
409 - #CKMC_PARAM_ALGO_TYPE = #CKMC_ALGO_AES_CTR (mandatory),
410 - #CKMC_PARAM_ED_IV = 16-byte initialization vector (mandatory)
411 - #CKMC_PARAM_ED_CTR_LEN = length of counter block in bits
412 (optional, only 128b is supported at the moment) */
414 CKMC_ALGO_AES_CBC, /**< AES-CBC algorithm
415 Supported parameters:
416 - #CKMC_PARAM_ALGO_TYPE = #CKMC_ALGO_AES_CBC (mandatory),
417 - #CKMC_PARAM_ED_IV = 16-byte initialization vector (mandatory) */
419 CKMC_ALGO_AES_GCM, /**< AES-GCM algorithm
420 Supported parameters:
421 - #CKMC_PARAM_ALGO_TYPE = #CKMC_ALGO_AES_GCM (mandatory),
422 - #CKMC_PARAM_ED_IV = initialization vector (mandatory)
423 - #CKMC_PARAM_ED_TAG_LEN = GCM tag length in bits. One of
424 {32, 64, 96, 104, 112, 120, 128} (optional, if not present, the
425 length 128 is used; since Tizen 5.0, if TrustZone backend is used,
426 32 and 64 lengths are not supported)
427 - #CKMC_PARAM_ED_AAD = additional authentication data(optional) */
429 CKMC_ALGO_AES_CFB, /**< AES-CFB algorithm
430 Supported parameters:
431 - #CKMC_PARAM_ALGO_TYPE = #CKMC_ALGO_AES_CFB (mandatory),
432 - #CKMC_PARAM_ED_IV = 16-byte initialization vector (mandatory) */
434 CKMC_ALGO_RSA_OAEP, /**< RSA-OAEP algorithm
435 Supported parameters:
436 - #CKMC_PARAM_ALGO_TYPE = #CKMC_ALGO_RSA_OAEP (mandatory),
437 - #CKMC_PARAM_ED_LABEL = label to be associated with the message
438 (optional, not supported at the moment) */
440 CKMC_ALGO_KBKDF, /**< Key based key derivation algorithm
441 Supported parameters:
442 - #CKMC_PARAM_ALGO_TYPE = #CKMC_ALGO_KBKDF (mandatory),
443 - #CKMC_PARAM_KDF_PRF = pseudo-random function (see #ckmc_kdf_prf_e)
445 - #CKMC_PARAM_KBKDF_MODE = KDF mode (see #ckmc_kbkdf_mode_e) (mandatory),
446 - #CKMC_PARAM_KBKDF_LABEL = the purpose for the derived key (optional),
447 - #CKMC_PARAM_KBKDF_CONTEXT = information related to the derived key
449 - #CKMC_PARAM_KDF_LEN = length of the derived key (mandatory)
450 - #CKMC_PARAM_KBKDF_FIXED_INPUT = replacement for context and label (optional),
451 - #CKMC_PARAM_KBKDF_COUNTER_LOCATION = counter location
452 (see #ckmc_kbkdf_counter_location_e) (mandatory),
453 - #CKMC_PARAM_KBKDF_RLEN = length of the counter representation (optional),
454 - #CKMC_PARAM_KBKDF_LLEN = length of the length suffix representation
456 - #CKMC_PARAM_KBKDF_NO_SEPARATOR = existence of zero separator (optional) */
458 CKMC_ALGO_ECDH, /**< ECDH shared secret key agreement protocol
459 Supported parameters (all are required):
460 - #CKMC_PARAM_ALGO_TYPE = #CKMC_ALGO_ECDH,
461 - #CKMC_PARAM_ECDH_PUBKEY = peer's public key (see #ckmc_key_s) */
465 * @brief Gets the alias from #ckmc_alias_info_s structure.
467 * @remarks The @a alias should not be released.
468 * The @a alias can be used until #ckmc_alias_info_s is released.
469 * @param[in] info The pointer to the #ckmc_alias_info_s structure
470 * @param[out] alias The pointer to the alias
471 * @return #CKMC_ERROR_NONE on success,
472 * othervise a negative error value
473 * @retval #CKMC_ERROR_NONE Successful
474 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
475 * @see #ckmc_alias_info_s
477 int ckmc_alias_info_get_alias(const ckmc_alias_info_s* info, char** alias);
480 * @brief Gets the password protection status from #ckmc_alias_info_s structure.
482 * @param[in] info The pointer to the #ckmc_alias_info_s structure
483 * @param[out] is_password_protected The pointer to the password protection flag
484 * @return #CKMC_ERROR_NONE on success,
485 * othervise a negative error value
486 * @retval #CKMC_ERROR_NONE Successful
487 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
488 * @see #ckmc_alias_info_s
490 int ckmc_alias_info_is_password_protected(const ckmc_alias_info_s* info, bool* is_password_protected);
493 * @brief Destroys the #ckmc_alias_info_list_s handle and releases resources of
494 * #ckmc_alias_info_list_s from the provided first handle cascadingly.
496 * @param[in] first The first #ckmc_alias_info_list_s handle to destroy
497 * @see #ckmc_alias_info_list_s
499 void ckmc_alias_info_list_all_free(ckmc_alias_info_list_s *first);
502 * @brief Creates a new full alias which is a concatenation of @a owner_id and @a alias.
504 * @remarks @a full_alias should be freed with free() after use.
505 * @remarks Returns #CKMC_ERROR_INVALID_PARAMETER if any of parameter is NULL.
506 * @remarks Returns #CKMC_ERROR_INVALID_PARAMETER if @a owner_id is empty.
507 * @param[in] owner_id Data owner's id. This should be package id if data owner is
508 * application. If you want to access data stored by system
509 * services, it should be #ckmc_owner_id_system
510 * @param[in] alias Data alias
511 * @param[out] full_alias The newly created alias which is a concatenation of
512 * @a owner_id, #ckmc_owner_id_separator and @a alias.
513 * Destroy by free() after use
514 * @return #CKMC_ERROR_NONE on success,
515 * otherwise a negative error value
516 * @retval #CKMC_ERROR_NONE Successful
517 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
518 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
519 * @see #ckmc_owner_id_separator
520 * @see #ckmc_owner_id_system
522 int ckmc_alias_new(const char *owner_id, const char *alias, char **full_alias);
526 * @brief Creates a new #ckmc_key_s handle and returns it.
527 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
528 * @remarks You must destroy the newly created #ckmc_key_s by calling ckmc_key_free() if it is no
530 * @param[in] raw_key The byte array of key. The @a raw_key may be encrypted with password.
531 * @param[in] key_size The byte size of @a raw_key
532 * @param[in] key_type The type of @a raw_key
533 * @param[in] password The byte array used to decrypt @a raw_key inside key manager. If @a raw_key
534 * is not encrypted, @a password can be NULL
535 * @param[out] ppkey The pointer to a newly created #ckmc_key_s handle
536 * @return #CKMC_ERROR_NONE on success,
537 * otherwise a negative error value
538 * @retval #CKMC_ERROR_NONE Successful
539 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
540 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
541 * @see ckmc_key_free()
544 int ckmc_key_new(unsigned char *raw_key,
546 ckmc_key_type_e key_type,
552 * @brief Destroys the #ckmc_key_s handle and releases all its resources.
554 * @param[in] key The #ckmc_key_s handle to destroy
556 void ckmc_key_free(ckmc_key_s *key);
560 * @brief Creates a new #ckmc_raw_buffer_s handle and returns it.
561 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
562 * @remarks You must destroy the newly created #ckmc_raw_buffer_s by calling ckmc_buffer_free() if
563 * it is no longer needed.
564 * @param[in] data The byte array of buffer
565 * @param[in] size The byte size of buffer
566 * @param[out] ppbuffer The pointer to a newly created #ckmc_raw_buffer_s handle
567 * @return #CKMC_ERROR_NONE on success,
568 * otherwise a negative error value
569 * @retval #CKMC_ERROR_NONE Successful
570 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
571 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
572 * @see ckmc_buffer_free()
573 * @see #ckmc_raw_buffer_s
575 int ckmc_buffer_new(unsigned char *data, size_t size, ckmc_raw_buffer_s **ppbuffer);
579 * @brief Destroys the #ckmc_raw_buffer_s handle and releases all its resources.
581 * @param[in] buffer The #ckmc_raw_buffer_s structure to destroy
583 void ckmc_buffer_free(ckmc_raw_buffer_s *buffer);
587 * @brief Creates a new #ckmc_cert_s handle and returns it.
588 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
589 * @remarks You must destroy the newly created #ckmc_cert_s by calling ckmc_cert_free() if it is no
591 * @param[in] raw_cert The byte array of certificate
592 * @param[in] cert_size The byte size of raw_cert
593 * @param[in] data_format The encoding format of raw_cert
594 * @param[out] ppcert The pointer to a newly created #ckmc_cert_s handle
595 * @return #CKMC_ERROR_NONE on success,
596 * otherwise a negative error value
597 * @retval #CKMC_ERROR_NONE Successful
598 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
599 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
600 * @see ckmc_cert_free()
601 * @see ckmc_load_cert_from_file()
604 int ckmc_cert_new(unsigned char *raw_cert,
606 ckmc_data_format_e data_format,
607 ckmc_cert_s **ppcert);
611 * @brief Destroys the #ckmc_cert_s handle and releases all its resources.
613 * @param[in] cert The #ckmc_cert_s handle to destroy
614 * @see ckmc_load_cert_from_file()
616 void ckmc_cert_free(ckmc_cert_s *cert);
620 * @brief Creates a new #ckmc_cert_s handle from a given file and returns it.
622 * @remarks You must destroy the newly created #ckmc_cert_s by calling ckmc_cert_free() if it is no
624 * @param[in] file_path The path of certificate file to be loaded. Only DER or PEM encoded
625 * certificate file is supported
626 * @param[out] cert The pointer of newly created #ckmc_cert_s handle
627 * @return #CKMC_ERROR_NONE on success,
628 * otherwise a negative error value
629 * @retval #CKMC_ERROR_NONE Successful
630 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory space
631 * @retval #CKMC_ERROR_INVALID_FORMAT Invalid certificate file format
632 * @retval #CKMC_ERROR_FILE_ACCESS_DENIED Provided file does not exist or cannot be accessed
633 * @see ckmc_cert_free()
636 int ckmc_load_cert_from_file(const char *file_path, ckmc_cert_s **cert);
640 * @brief Creates a new #ckmc_pkcs12_s handle and returns it.
641 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
642 * @remarks You must destroy the newly created #ckmc_pkcs12_s by calling ckmc_pkcs12_free() if it is
644 * @remarks On success, private_key, cert && ca_cert_list ownership is transferred into newly
645 * returned @a pkcs12_bundle.
646 * @param[in] private_key #ckmc_key_s handle to the private key (optional)
647 * @param[in] cert #ckmc_cert_s handle to the certificate (optional)
648 * @param[in] ca_cert_list #ckmc_cert_list_s list of chain certificate handles (optional)
649 * @param[out] pkcs12_bundle The pointer to a newly created #ckmc_pkcs12_s handle
650 * @return #CKMC_ERROR_NONE on success,
651 * otherwise a negative error value
652 * @retval #CKMC_ERROR_NONE Successful
653 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid or @a private_key, @a cert and
654 * @a ca_cert_list all are NULL
655 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
656 * @see ckmc_pkcs12_free()
657 * @see ckmc_pkcs12_load()
660 * @see #ckmc_cert_list_s
661 * @see #ckmc_pkcs12_s
663 int ckmc_pkcs12_new(ckmc_key_s *private_key,
665 ckmc_cert_list_s *ca_cert_list,
666 ckmc_pkcs12_s **pkcs12_bundle);
670 * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif
671 * [Use ckmc_pkcs12_load() instead]
672 * @brief Creates a new #ckmc_key_s (@a private_key), #ckmc_cert_s (@a cert),
673 * and #ckmc_cert_list_s (@a ca_cert_list) handle from a given PKCS#12 file and returns them.
675 * @remarks You must destroy the newly created @a private_key, @a cert and @a ca_cert_list
676 by calling ckmc_key_free(), ckmc_cert_free(), and ckmc_cert_list_all_free() if they are
678 * @param[in] file_path The path of PKCS12 file to be loaded
679 * @param[in] passphrase The passphrase used to decrypt the PCKS12 file. If PKCS12 file is not
680 * encrypted, passphrase can be NULL
681 * @param[out] private_key The pointer of newly created #ckmc_key_s handle for a private key
682 * @param[out] cert The pointer of newly created #ckmc_cert_s handle for a certificate. It is NULL
683 * if the PKCS12 file does not contain a certificate
684 * @param[out] ca_cert_list The pointer of newly created #ckmc_cert_list_s handle for CA
685 * certificates. It is NULL if the PKCS12 file does not contain
687 * @return #CKMC_ERROR_NONE on success,
688 * otherwise a negative error value
689 * @retval #CKMC_ERROR_NONE Successful
690 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory space
691 * @retval #CKMC_ERROR_INVALID_FORMAT Invalid PKCS12 file format
692 * @retval #CKMC_ERROR_FILE_ACCESS_DENIED Provided file does not exist or cannot be accessed
693 * @see ckmc_pkcs12_new()
694 * @see ckmc_pkcs12_load()
695 * @see ckmc_key_free()
696 * @see ckmc_cert_free()
697 * @see ckmc_cert_list_all_free()
700 * @see #ckmc_cert_list_s
702 int ckmc_load_from_pkcs12_file(const char *file_path,
703 const char *passphrase,
704 ckmc_key_s **private_key,
706 ckmc_cert_list_s **ca_cert_list) TIZEN_DEPRECATED_API;
710 * @brief Creates a new #ckmc_pkcs12_s handle from a given PKCS#12 file and returns it.
711 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
712 * @remarks You must destroy the newly created #ckmc_pkcs12_s by calling ckmc_pkcs12_free() if they
713 * are no longer needed.
714 * @param[in] file_path The path of PKCS12 file to be loaded
715 * @param[in] passphrase The passphrase used to decrypt the PCKS12 file. If PKCS12 file is not
716 * encrypted, passphrase can be NULL
717 * @param[out] pkcs12_bundle The pointer of newly created #ckmc_cert_list_s handle for
718 * CA certificates. It is NULL if the PKCS12 file does not contain
720 * @return #CKMC_ERROR_NONE on success,
721 * otherwise a negative error value
722 * @retval #CKMC_ERROR_NONE Successful
723 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
724 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory space
725 * @retval #CKMC_ERROR_INVALID_FORMAT Invalid PKCS12 file format
726 * @retval #CKMC_ERROR_FILE_ACCESS_DENIED Provided file does not exist or cannot be accessed
727 * @see ckmc_pkcs12_free()
728 * @see #ckmc_pkcs12_s
730 int ckmc_pkcs12_load(const char *file_path, const char *passphrase, ckmc_pkcs12_s **pkcs12_bundle);
734 * @brief Destroys the #ckmc_pkcs12_s handle and releases all its resources.
735 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
736 * @param[in] pkcs12 The #ckmc_pkcs12_s handle to destroy
737 * @see ckmc_pkcs12_new()
738 * @see ckmc_pkcs12_load()
740 void ckmc_pkcs12_free(ckmc_pkcs12_s *pkcs12);
744 * @brief Creates a new #ckmc_alias_list_s handle and returns it. The alias pointer in the returned
745 * #ckmc_alias_list_s handle points to the provided characters and next is NULL.
746 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
747 * @remarks You must destroy the newly created #ckmc_alias_list_s by calling ckmc_alias_list_free()
748 * or ckmc_alias_list_all_free() if it is no longer needed.
749 * @param[in] alias The first item to be set in the newly created #ckmc_alias_list_s
750 * @param[out] ppalias_list The pointer to a newly created #ckmc_alias_list_s handle
751 * @return #CKMC_ERROR_NONE on success,
752 * otherwise a negative error value
753 * @retval #CKMC_ERROR_NONE Successful
754 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
755 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
756 * @see ckmc_alias_list_all_free()
757 * @see #ckmc_alias_list_s
759 int ckmc_alias_list_new(char *alias, ckmc_alias_list_s **ppalias_list);
763 * @brief Creates a new #ckmc_alias_list_s handle, adds it to a previous #ckmc_alias_list_s and
764 * returns it. The alias pointer in the returned #ckmc_alias_list_s handle points to the
765 * provided characters and next is NULL.
766 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
767 * @remarks You must destroy the newly created @a pplast using ckmc_alias_list_free()
768 * @param[in] previous The last #ckmc_alias_list_s handle to which a newly created
769 * #ckmc_alias_list_s is added
770 * @param[in] alias The item to be set in the newly created #ckmc_alias_list_s
771 * @param[out] pplast The pointer to a newly created and added #ckmc_alias_list_s handle
772 * @return #CKMC_ERROR_NONE on success,
773 * otherwise a negative error value
774 * @retval #CKMC_ERROR_NONE Successful
775 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
776 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
777 * @see ckmc_alias_list_all_free()
778 * @see #ckmc_alias_list_s
780 int ckmc_alias_list_add(ckmc_alias_list_s *previous, char *alias, ckmc_alias_list_s **pplast);
784 * @brief Destroys the #ckmc_alias_list_s handle and releases resources of #ckmc_alias_list_s from
785 * the provided first handle cascadingly.
786 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
787 * @remarks It does not destroy an alias itself in #ckmc_alias_list_s.
788 * @param[in] first The first #ckmc_alias_list_s handle to destroy
789 * @see ckmc_alias_list_all_free()
790 * @see #ckmc_alias_list_s
792 void ckmc_alias_list_free(ckmc_alias_list_s *first);
796 * @brief Destroys the #ckmc_alias_list_s handle and releases all its resources from the provided
797 * first handle cascadingly.
798 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
799 * @remarks It also destroys the alias in #ckmc_alias_list_s.
800 * @param[in] first The first #ckmc_alias_list_s handle to destroy
801 * @see #ckmc_alias_list_s
803 void ckmc_alias_list_all_free(ckmc_alias_list_s *first);
807 * @brief Creates a new #ckmc_cert_list_s handle and returns it. The cert pointer in the returned
808 * #ckmc_cert_list_s handle points to the provided #ckmc_cert_s and next is NULL.
809 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
810 * @remarks You must destroy the newly created #ckmc_cert_list_s by calling ckmc_cert_list_free() or
811 * ckmc_cert_list_all_free() if it is no longer needed.
812 * @param[in] cert The first item to be set in the newly created #ckmc_cert_list_s
813 * @param[out] ppalias_list The pointer to a newly created #ckmc_alias_list_s handle
814 * @return #CKMC_ERROR_NONE on success,
815 * otherwise a negative error value
816 * @retval #CKMC_ERROR_NONE Successful
817 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
818 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
819 * @see ckmc_cert_list_all_free()
820 * @see #ckmc_cert_list_s
822 int ckmc_cert_list_new(ckmc_cert_s *cert, ckmc_cert_list_s **ppalias_list);
826 * @brief Creates a new #ckmc_cert_list_s handle, adds it to a previous #ckmc_cert_list_s and
827 * returns it. The cert pointer in the returned #ckmc_alias_list_s handle points to the
828 * provided #ckmc_cert_s and next is NULL.
829 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
830 * @remarks You must destroy the newly created @a pplast using ckmc_cert_list_free()
831 * @param[in] previous The last #ckmc_cert_list_s handle to which a newly created #ckmc_cert_list_s
833 * @param[in] cert The item to be set in the newly created #ckmc_cert_list_s
834 * @param[out] pplast The pointer to a newly created and added #ckmc_alias_list_s handle
835 * @return #CKMC_ERROR_NONE on success,
836 * otherwise a negative error value
837 * @retval #CKMC_ERROR_NONE Successful
838 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
839 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
840 * @see ckmc_cert_list_all_free()
841 * @see #ckmc_cert_list_s
843 int ckmc_cert_list_add(ckmc_cert_list_s *previous, ckmc_cert_s *cert, ckmc_cert_list_s **pplast);
847 * @brief Destroys the #ckmc_cert_list_s handle and releases resources of #ckmc_cert_list_s from the
848 * provided first handle cascadingly.
849 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
850 * @remarks It does not destroy #ckmc_cert_s itself in #ckmc_cert_list_s.
851 * @param[in] first The first #ckmc_cert_list_s handle to destroy
852 * @see ckmc_cert_list_all_free()
853 * @see #ckmc_cert_list_s
855 void ckmc_cert_list_free(ckmc_cert_list_s *first);
859 * @brief Destroys the #ckmc_cert_list_s handle and releases all its resources from the provided
860 * first handle cascadingly.
862 * @remarks It also destroys #ckmc_cert_s in #ckmc_cert_list_s.
863 * @param[in] first The first #ckmc_cert_list_s handle to destroy
864 * @see #ckmc_cert_list_s
866 void ckmc_cert_list_all_free(ckmc_cert_list_s *first);
870 * @brief Creates new parameter list.
872 * @remarks Caller is responsible for freeing it with ckmc_param_list_free().
873 * @param[in] pparams Double pointer to the handle of param list to which the newly created
874 * algorithm param list will be assigned
875 * @return #CKMC_ERROR_NONE on success,
876 * otherwise a negative error value
877 * @retval #CKMC_ERROR_NONE Successful
878 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
879 * @see ckmc_param_list_set_integer()
880 * @see ckmc_param_list_set_buffer()
881 * @see ckmc_param_list_free()
882 * @see ckmc_generate_new_params()
883 * @see #ckmc_param_list_h
884 * @see #ckmc_param_name_e
885 * @see #ckmc_algo_type_e
887 int ckmc_param_list_new(ckmc_param_list_h *pparams);
891 * @brief Sets integer parameter to the list.
893 * @remarks Caller is responsible for #ckmc_param_list_h creation.
894 * @param[in] params Algorithm param list handle created with ckmc_param_list_new() or
895 * ckmc_generate_new_params(). New param with @a name and @a value will be set
897 * @param[in] name Name of parameter to set. Existing parameter will be overwritten. Passing invalid
898 * parameter name will result in an error
899 * @param[in] value Value of the parameter in form of a integer
900 * @return #CKMC_ERROR_NONE on success,
901 * otherwise a negative error value
902 * @retval #CKMC_ERROR_NONE Successful
903 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
904 * @see ckmc_param_list_new()
905 * @see ckmc_param_list_set_buffer()
906 * @see ckmc_param_list_get_integer()
907 * @see ckmc_param_list_get_buffer()
908 * @see ckmc_param_list_free()
909 * @see ckmc_generate_new_params()
910 * @see #ckmc_param_list_h
911 * @see #ckmc_param_name_e
912 * @see #ckmc_algo_type_e
914 int ckmc_param_list_set_integer(ckmc_param_list_h params, ckmc_param_name_e name, uint64_t value);
918 * @brief Sets buffer parameter to the list.
920 * @remarks Caller is responsible for #ckmc_param_list_h creation.
921 * @param[in] params Algorithm param list handle created with ckmc_param_list_new() or
922 * ckmc_generate_new_params(). New param with @a name and @a buffer will be set
924 * @param[in] name Name of parameter to set. Existing parameter will be overwritten. Passing invalid
925 * parameter name will result in an error
926 * @param[in] buffer Value of the parameter in form of a buffer. Caller is responsible for creating
927 * and freeing the buffer
928 * @return #CKMC_ERROR_NONE on success,
929 * otherwise a negative error value
930 * @retval #CKMC_ERROR_NONE Successful
931 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
932 * @see ckmc_param_list_new()
933 * @see ckmc_param_list_set_integer()
934 * @see ckmc_param_list_get_integer()
935 * @see ckmc_param_list_get_buffer()
936 * @see ckmc_param_list_free()
937 * @see ckmc_generate_new_params()
938 * @see #ckmc_param_list_h
939 * @see #ckmc_param_name_e
940 * @see #ckmc_algo_type_e
942 int ckmc_param_list_set_buffer(ckmc_param_list_h params,
943 ckmc_param_name_e name,
944 const ckmc_raw_buffer_s *buffer);
948 * @brief Gets integer parameter from the list.
950 * @remarks Caller is responsible for #ckmc_param_list_h creation.
951 * @param[in] params Algorithm param list handle created with ckmc_param_list_new() or
952 * ckmc_generate_new_params() which contains param with @a name
953 * @param[in] name Name of parameter to get
954 * @param[out] pvalue Value of the parameter in form of a integer
955 * @return #CKMC_ERROR_NONE on success,
956 * otherwise a negative error value
957 * @retval #CKMC_ERROR_NONE Successful
958 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
959 * @see ckmc_param_list_new()
960 * @see ckmc_param_list_set_integer()
961 * @see ckmc_param_list_set_buffer()
962 * @see ckmc_param_list_get_buffer()
963 * @see ckmc_param_list_free()
964 * @see ckmc_generate_new_params()
965 * @see #ckmc_param_list_h
966 * @see #ckmc_param_name_e
967 * @see #ckmc_algo_type_e
969 int ckmc_param_list_get_integer(ckmc_param_list_h params, ckmc_param_name_e name, uint64_t *pvalue);
973 * @brief Gets buffer parameter from the list.
975 * @remarks Caller is responsible for #ckmc_param_list_h creation.
976 * @remarks You must destroy the @a ppbuffer using ckmc_buffer_free()
977 * @param[in] params Algorithm param list handle created with ckmc_param_list_new() or
978 * ckmc_generate_new_params() which contains param with @a name
979 * @param[in] name Name of parameter to get
980 * @param[out] ppbuffer Value of the parameter in form of a buffer
981 * @return #CKMC_ERROR_NONE on success,
982 * otherwise a negative error value
983 * @retval #CKMC_ERROR_NONE Successful
984 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
985 * @see ckmc_param_list_new()
986 * @see ckmc_param_list_set_integer()
987 * @see ckmc_param_list_set_buffer()
988 * @see ckmc_param_list_get_integer()
989 * @see ckmc_param_list_free()
990 * @see ckmc_generate_new_params()
991 * @see ckmc_buffer_free()
992 * @see #ckmc_param_list_h
993 * @see #ckmc_param_name_e
994 * @see #ckmc_algo_type_e
996 int ckmc_param_list_get_buffer(ckmc_param_list_h params,
997 ckmc_param_name_e name,
998 ckmc_raw_buffer_s **ppbuffer);
1002 * @brief Frees previously allocated list of algorithm params.
1004 * @param[in] params First element of the list to be freed
1005 * @see ckmc_param_list_new()
1006 * @see ckmc_param_list_set_integer()
1007 * @see ckmc_param_list_set_buffer()
1008 * @see ckmc_param_list_get_integer()
1009 * @see ckmc_param_list_get_buffer()
1010 * @see ckmc_generate_new_params()
1011 * @see #ckmc_param_list_h
1012 * @see #ckmc_param_name_e
1013 * @see #ckmc_algo_type_e
1015 void ckmc_param_list_free(ckmc_param_list_h params);
1019 * @brief Generates algorithm parameters for a given algorithm type and set them to the list.
1021 * @remarks Caller is responsible for #ckmc_param_list_h destruction.
1022 * @remarks Algorithm parameters are set to default values. Optional fields are left empty.
1023 * Initialization vectors are left empty (they have to be set manually).
1024 * Caller is responsible for freeing the list with ckmc_param_list_free().
1025 * @remarks If the function returns error, provided param list may contain some of default
1027 * @param[in] type Type of the algorithm
1028 * @param[out] pparams Newly generated handle of param list which should be freed by caller after
1030 * @return #CKMC_ERROR_NONE on success,
1031 * otherwise a negative error value
1032 * @retval #CKMC_ERROR_NONE Successful
1033 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
1034 * @see ckmc_param_list_new()
1035 * @see ckmc_param_list_set_integer()
1036 * @see ckmc_param_list_set_buffer()
1037 * @see ckmc_param_list_get_integer()
1038 * @see ckmc_param_list_get_buffer()
1039 * @see ckmc_param_list_free()
1040 * @see #ckmc_param_list_h
1041 * @see #ckmc_param_name_e
1042 * @see #ckmc_algo_type_e
1044 int ckmc_generate_new_params(ckmc_algo_type_e type, ckmc_param_list_h *pparams);
1057 #endif /* __TIZEN_CORE_CKMC_TYPE_H__ */