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) */
304 CKMC_PARAM_KDF_LEN, /**< integer - length of the derived key in bytes. The value must be one of
307 CKMC_PARAM_KBKDF_MODE, /**< integer - KDF mode number (see #ckmc_kbkdf_mode_e) */
308 CKMC_PARAM_KBKDF_LABEL, /**< buffer - the purpose for the derived key. Conflicts with
309 #CKMC_PARAM_KBKDF_FIXED_INPUT */
311 CKMC_PARAM_KBKDF_CONTEXT, /**< buffer - information related to the derived key. Conflicts with
312 #CKMC_PARAM_KBKDF_FIXED_INPUT */
314 CKMC_PARAM_KBKDF_FIXED_INPUT, /**< buffer - KBKDF fixed input replacing context and label.
316 - #CKMC_PARAM_KBKDF_LABEL,
317 - #CKMC_PARAM_KBKDF_CONTEXT,
318 - #CKMC_PARAM_KBKDF_LLEN,
319 - #CKMC_PARAM_KBKDF_NO_SEPARATOR */
320 CKMC_PARAM_KBKDF_COUNTER_LOCATION, /**< integer - specifies location of the counter in KBKDF
321 (see #ckmc_kbkdf_counter_location_e) */
322 CKMC_PARAM_KBKDF_RLEN, /**< integer - specifies the length of the counter representation in bits
323 in KBKDF. The value must be one of {8, 16, 24, 32}. If not set, the
324 default value = 32 will be used */
325 CKMC_PARAM_KBKDF_LLEN, /**< integer - specifies the length of the length suffix representation
326 in bits in KBKDF. The value must be one of {0, 8, 16, 24, 32}. If set to
327 0 the length suffix will be skipped. If not set, the default value = 32
328 will be used. The length suffix is skipped if
329 #CKMC_PARAM_KBKDF_FIXED_INPUT is passed and this parameter conflicts
331 CKMC_PARAM_KBKDF_NO_SEPARATOR, /**< integer - presence of this parameter will skip the zero
332 octet separator between label and context in KBKDF.
333 All values are allowed. This parameter conflicts with
334 #CKMC_PARAM_KBKDF_FIXED_INPUT. */
336 CKMC_PARAM_ECDH_PUBKEY, /**< buffer - EC public key in DER form (see #ckmc_key_s) */
340 * @brief Enumeration for key derivation function pseudo-random function parameter
343 * @see ckmc_key_derive()
344 * @see #ckmc_param_name_e
346 typedef enum __ckmc_kdf_prf {
347 CKMC_KDF_PRF_HMAC_SHA256 = 1, /**< HMAC SHA256 */
348 CKMC_KDF_PRF_HMAC_SHA384, /**< HMAC SHA384 */
349 CKMC_KDF_PRF_HMAC_SHA512, /**< HMAC SHA512 */
353 * @brief Enumeration for key based key derivation function mode
356 * @see ckmc_key_derive()
357 * @see #ckmc_param_name_e
359 typedef enum __ckmc_kbkdf_mode {
360 CKMC_KBKDF_MODE_COUNTER = 1, /**< KBKDF counter mode */
364 * @brief Enumeration for KBKDF counter location relative to fixed input
367 * @see ckmc_key_derive()
368 * @see #ckmc_param_name_e
370 typedef enum __ckmc_kbkdf_counter_location {
371 CKMC_KBKDF_COUNTER_BEFORE_FIXED = 1, /**< Counter is located before fixed input */
372 CKMC_KBKDF_COUNTER_AFTER_FIXED, /**< Counter is located after fixed input */
373 CKMC_KBKDF_COUNTER_MIDDLE_FIXED, /**< Counter is located in the middle of the fixed input
374 (between context and label). This setting requires setting
375 #CKMC_PARAM_KBKDF_LABEL and #CKMC_PARAM_KBKDF_CONTEXT and
376 conflicts with #CKMC_PARAM_KBKDF_FIXED_INPUT. If this location
377 is used the separator will be skipped regardless of the
378 #CKMC_PARAM_KBKDF_NO_SEPARATOR parameter */
379 } ckmc_kbkdf_counter_location_e;
382 * @brief Algorithm parameter list handle.
384 * @remarks Each parameter list must have at least one #CKMC_PARAM_ALGO_TYPE parameter that
385 * identifies the algorithm. See #ckmc_algo_type_e for available algorithms and additional
386 * parameters they support.
387 * @see ckmc_generate_new_params()
388 * @see ckmc_param_list_new()
389 * @see ckmc_param_list_set_integer()
390 * @see ckmc_param_list_set_buffer()
391 * @see ckmc_param_list_get_integer()
392 * @see ckmc_param_list_get_buffer()
393 * @see ckmc_param_list_free()
394 * @see #ckmc_algo_type_e
395 * @see #ckmc_param_name_e
397 typedef struct __ckmc_param_list *ckmc_param_list_h;
401 * @brief Enumeration for crypto algorithm types.
403 * @see #ckmc_param_name_e
405 typedef enum __ckmc_algo_type {
406 CKMC_ALGO_AES_CTR = 1, /**< AES-CTR algorithm
407 Supported parameters:
408 - #CKMC_PARAM_ALGO_TYPE = #CKMC_ALGO_AES_CTR (mandatory),
409 - #CKMC_PARAM_ED_IV = 16-byte initialization vector (mandatory)
410 - #CKMC_PARAM_ED_CTR_LEN = length of counter block in bits
411 (optional, only 128b is supported at the moment) */
413 CKMC_ALGO_AES_CBC, /**< AES-CBC algorithm
414 Supported parameters:
415 - #CKMC_PARAM_ALGO_TYPE = #CKMC_ALGO_AES_CBC (mandatory),
416 - #CKMC_PARAM_ED_IV = 16-byte initialization vector (mandatory) */
418 CKMC_ALGO_AES_GCM, /**< AES-GCM algorithm
419 Supported parameters:
420 - #CKMC_PARAM_ALGO_TYPE = #CKMC_ALGO_AES_GCM (mandatory),
421 - #CKMC_PARAM_ED_IV = initialization vector (mandatory)
422 - #CKMC_PARAM_ED_TAG_LEN = GCM tag length in bits. One of
423 {32, 64, 96, 104, 112, 120, 128} (optional, if not present, the
424 length 128 is used; since Tizen 5.0, if TrustZone backend is used,
425 32 and 64 lengths are not supported)
426 - #CKMC_PARAM_ED_AAD = additional authentication data(optional) */
428 CKMC_ALGO_AES_CFB, /**< AES-CFB algorithm
429 Supported parameters:
430 - #CKMC_PARAM_ALGO_TYPE = #CKMC_ALGO_AES_CFB (mandatory),
431 - #CKMC_PARAM_ED_IV = 16-byte initialization vector (mandatory) */
433 CKMC_ALGO_RSA_OAEP, /**< RSA-OAEP algorithm
434 Supported parameters:
435 - #CKMC_PARAM_ALGO_TYPE = #CKMC_ALGO_RSA_OAEP (mandatory),
436 - #CKMC_PARAM_ED_LABEL = label to be associated with the message
437 (optional, not supported at the moment) */
439 CKMC_ALGO_KBKDF, /**< Key based key derivation algorithm
440 Supported parameters:
441 - CKMC_PARAM_ALGO_TYPE = CKMC_ALGO_KBKDF(mandatory),
442 - CKMC_PARAM_KDF_PRF = pseudo-random function (see #ckmc_kdf_prf_e)(mandatory),
443 - CKMC_PARAM_KBKDF_MODE = KDF mode (see #ckmc_kbkdf_mode_e)(mandatory),
444 - CKMC_PARAM_KBKDF_LABEL = the purpose for the derived key(optional),
445 - CKMC_PARAM_KBKDF_CONTEXT = information related to the derived key(optional),
446 - CKMC_PARAM_KDF_LEN = length of the derived key(mandatory)
447 - CKMC_PARAM_KBKDF_FIXED_INPUT = replacement for context and label(optional),
448 - CKMC_PARAM_KBKDF_COUNTER_LOCATION = counter location
449 (see #ckmc_kbkdf_counter_location_e)(mandatory),
450 - CKMC_PARAM_KBKDF_RLEN = length of the counter representation(optional),
451 - CKMC_PARAM_KBKDF_LLEN = length of the length suffix representation(optional),
452 - CKMC_PARAM_KBKDF_NO_SEPARATOR = existence of zero separator(optional) */
454 CKMC_ALGO_ECDH, /**< ECDH shared secret key agreement protocol
455 Supported parameters (all are required):
456 - CKMC_PARAM_ALGO_TYPE = CKMC_ALGO_ECDH,
457 - CKMC_PARAM_ECDH_PUBKEY = peer's public key (see #ckmc_key_s) */
461 * @brief Gets the alias from #ckmc_alias_info_s structure.
463 * @remarks The @a alias should not be released.
464 * The @a alias can be used until #ckmc_alias_info_s is released.
465 * @param[in] info The pointer to the #ckmc_alias_info_s structure
466 * @param[out] alias The pointer to the alias
467 * @return #CKMC_ERROR_NONE on success,
468 * othervise a negative error value
469 * @retval #CKMC_ERROR_NONE Successful
470 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
471 * @see #ckmc_alias_info_s
473 int ckmc_alias_info_get_alias(const ckmc_alias_info_s* info, char** alias);
476 * @brief Gets the password protection status from #ckmc_alias_info_s structure.
478 * @param[in] info The pointer to the #ckmc_alias_info_s structure
479 * @param[out] is_password_protected The pointer to the password protection flag
480 * @return #CKMC_ERROR_NONE on success,
481 * othervise a negative error value
482 * @retval #CKMC_ERROR_NONE Successful
483 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
484 * @see #ckmc_alias_info_s
486 int ckmc_alias_info_is_password_protected(const ckmc_alias_info_s* info, bool* is_password_protected);
489 * @brief Destroys the #ckmc_alias_info_list_s handle and releases resources of
490 * #ckmc_alias_info_list_s from the provided first handle cascadingly.
492 * @param[in] first The first #ckmc_alias_info_list_s handle to destroy
493 * @see #ckmc_alias_info_list_s
495 void ckmc_alias_info_list_all_free(ckmc_alias_info_list_s *first);
498 * @brief Creates a new full alias which is a concatenation of @a owner_id and @a alias.
500 * @remarks @a full_alias should be freed with free() after use.
501 * @remarks Returns #CKMC_ERROR_INVALID_PARAMETER if any of parameter is NULL.
502 * @remarks Returns #CKMC_ERROR_INVALID_PARAMETER if @a owner_id is empty.
503 * @param[in] owner_id Data owner's id. This should be package id if data owner is
504 * application. If you want to access data stored by system
505 * services, it should be #ckmc_owner_id_system
506 * @param[in] alias Data alias
507 * @param[out] full_alias The newly created alias which is a concatenation of
508 * @a owner_id, #ckmc_owner_id_separator and @a alias.
509 * Destroy by free() after use
510 * @return #CKMC_ERROR_NONE on success,
511 * otherwise a negative error value
512 * @retval #CKMC_ERROR_NONE Successful
513 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
514 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
515 * @see #ckmc_owner_id_separator
516 * @see #ckmc_owner_id_system
518 int ckmc_alias_new(const char *owner_id, const char *alias, char **full_alias);
522 * @brief Creates a new #ckmc_key_s handle and returns it.
523 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
524 * @remarks You must destroy the newly created #ckmc_key_s by calling ckmc_key_free() if it is no
526 * @param[in] raw_key The byte array of key. The @a raw_key may be encrypted with password.
527 * @param[in] key_size The byte size of @a raw_key
528 * @param[in] key_type The type of @a raw_key
529 * @param[in] password The byte array used to decrypt @a raw_key inside key manager. If @a raw_key
530 * is not encrypted, @a password can be NULL
531 * @param[out] ppkey The pointer to a newly created #ckmc_key_s handle
532 * @return #CKMC_ERROR_NONE on success,
533 * otherwise a negative error value
534 * @retval #CKMC_ERROR_NONE Successful
535 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
536 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
537 * @see ckmc_key_free()
540 int ckmc_key_new(unsigned char *raw_key,
542 ckmc_key_type_e key_type,
548 * @brief Destroys the #ckmc_key_s handle and releases all its resources.
550 * @param[in] key The #ckmc_key_s handle to destroy
552 void ckmc_key_free(ckmc_key_s *key);
556 * @brief Creates a new #ckmc_raw_buffer_s handle and returns it.
557 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
558 * @remarks You must destroy the newly created #ckmc_raw_buffer_s by calling ckmc_buffer_free() if
559 * it is no longer needed.
560 * @param[in] data The byte array of buffer
561 * @param[in] size The byte size of buffer
562 * @param[out] ppbuffer The pointer to a newly created #ckmc_raw_buffer_s handle
563 * @return #CKMC_ERROR_NONE on success,
564 * otherwise a negative error value
565 * @retval #CKMC_ERROR_NONE Successful
566 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
567 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
568 * @see ckmc_buffer_free()
569 * @see #ckmc_raw_buffer_s
571 int ckmc_buffer_new(unsigned char *data, size_t size, ckmc_raw_buffer_s **ppbuffer);
575 * @brief Destroys the #ckmc_raw_buffer_s handle and releases all its resources.
577 * @param[in] buffer The #ckmc_raw_buffer_s structure to destroy
579 void ckmc_buffer_free(ckmc_raw_buffer_s *buffer);
583 * @brief Creates a new #ckmc_cert_s handle and returns it.
584 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
585 * @remarks You must destroy the newly created #ckmc_cert_s by calling ckmc_cert_free() if it is no
587 * @param[in] raw_cert The byte array of certificate
588 * @param[in] cert_size The byte size of raw_cert
589 * @param[in] data_format The encoding format of raw_cert
590 * @param[out] ppcert The pointer to a newly created #ckmc_cert_s handle
591 * @return #CKMC_ERROR_NONE on success,
592 * otherwise a negative error value
593 * @retval #CKMC_ERROR_NONE Successful
594 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
595 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
596 * @see ckmc_cert_free()
597 * @see ckmc_load_cert_from_file()
600 int ckmc_cert_new(unsigned char *raw_cert,
602 ckmc_data_format_e data_format,
603 ckmc_cert_s **ppcert);
607 * @brief Destroys the #ckmc_cert_s handle and releases all its resources.
609 * @param[in] cert The #ckmc_cert_s handle to destroy
610 * @see ckmc_load_cert_from_file()
612 void ckmc_cert_free(ckmc_cert_s *cert);
616 * @brief Creates a new #ckmc_cert_s handle from a given file and returns it.
618 * @remarks You must destroy the newly created #ckmc_cert_s by calling ckmc_cert_free() if it is no
620 * @param[in] file_path The path of certificate file to be loaded. Only DER or PEM encoded
621 * certificate file is supported
622 * @param[out] cert The pointer of newly created #ckmc_cert_s handle
623 * @return #CKMC_ERROR_NONE on success,
624 * otherwise a negative error value
625 * @retval #CKMC_ERROR_NONE Successful
626 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory space
627 * @retval #CKMC_ERROR_INVALID_FORMAT Invalid certificate file format
628 * @retval #CKMC_ERROR_FILE_ACCESS_DENIED Provided file does not exist or cannot be accessed
629 * @see ckmc_cert_free()
632 int ckmc_load_cert_from_file(const char *file_path, ckmc_cert_s **cert);
636 * @brief Creates a new #ckmc_pkcs12_s handle and returns it.
637 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
638 * @remarks You must destroy the newly created #ckmc_pkcs12_s by calling ckmc_pkcs12_free() if it is
640 * @remarks On success, private_key, cert && ca_cert_list ownership is transferred into newly
641 * returned @a pkcs12_bundle.
642 * @param[in] private_key #ckmc_key_s handle to the private key (optional)
643 * @param[in] cert #ckmc_cert_s handle to the certificate (optional)
644 * @param[in] ca_cert_list #ckmc_cert_list_s list of chain certificate handles (optional)
645 * @param[out] pkcs12_bundle The pointer to a newly created #ckmc_pkcs12_s handle
646 * @return #CKMC_ERROR_NONE on success,
647 * otherwise a negative error value
648 * @retval #CKMC_ERROR_NONE Successful
649 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid or @a private_key, @a cert and
650 * @a ca_cert_list all are NULL
651 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
652 * @see ckmc_pkcs12_free()
653 * @see ckmc_pkcs12_load()
656 * @see #ckmc_cert_list_s
657 * @see #ckmc_pkcs12_s
659 int ckmc_pkcs12_new(ckmc_key_s *private_key,
661 ckmc_cert_list_s *ca_cert_list,
662 ckmc_pkcs12_s **pkcs12_bundle);
666 * @deprecated Deprecated since @if MOBILE 2.4. @elseif WEARABLE 3.0. @endif
667 * [Use ckmc_pkcs12_load() instead]
668 * @brief Creates a new #ckmc_key_s (@a private_key), #ckmc_cert_s (@a cert),
669 * and #ckmc_cert_list_s (@a ca_cert_list) handle from a given PKCS#12 file and returns them.
671 * @remarks You must destroy the newly created @a private_key, @a cert and @a ca_cert_list
672 by calling ckmc_key_free(), ckmc_cert_free(), and ckmc_cert_list_all_free() if they are
674 * @param[in] file_path The path of PKCS12 file to be loaded
675 * @param[in] passphrase The passphrase used to decrypt the PCKS12 file. If PKCS12 file is not
676 * encrypted, passphrase can be NULL
677 * @param[out] private_key The pointer of newly created #ckmc_key_s handle for a private key
678 * @param[out] cert The pointer of newly created #ckmc_cert_s handle for a certificate. It is NULL
679 * if the PKCS12 file does not contain a certificate
680 * @param[out] ca_cert_list The pointer of newly created #ckmc_cert_list_s handle for CA
681 * certificates. It is NULL if the PKCS12 file does not contain
683 * @return #CKMC_ERROR_NONE on success,
684 * otherwise a negative error value
685 * @retval #CKMC_ERROR_NONE Successful
686 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory space
687 * @retval #CKMC_ERROR_INVALID_FORMAT Invalid PKCS12 file format
688 * @retval #CKMC_ERROR_FILE_ACCESS_DENIED Provided file does not exist or cannot be accessed
689 * @see ckmc_pkcs12_new()
690 * @see ckmc_pkcs12_load()
691 * @see ckmc_key_free()
692 * @see ckmc_cert_free()
693 * @see ckmc_cert_list_all_free()
696 * @see #ckmc_cert_list_s
698 int ckmc_load_from_pkcs12_file(const char *file_path,
699 const char *passphrase,
700 ckmc_key_s **private_key,
702 ckmc_cert_list_s **ca_cert_list) TIZEN_DEPRECATED_API;
706 * @brief Creates a new #ckmc_pkcs12_s handle from a given PKCS#12 file and returns it.
707 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
708 * @remarks You must destroy the newly created #ckmc_pkcs12_s by calling ckmc_pkcs12_free() if they
709 * are no longer needed.
710 * @param[in] file_path The path of PKCS12 file to be loaded
711 * @param[in] passphrase The passphrase used to decrypt the PCKS12 file. If PKCS12 file is not
712 * encrypted, passphrase can be NULL
713 * @param[out] pkcs12_bundle The pointer of newly created #ckmc_cert_list_s handle for
714 * CA certificates. It is NULL if the PKCS12 file does not contain
716 * @return #CKMC_ERROR_NONE on success,
717 * otherwise a negative error value
718 * @retval #CKMC_ERROR_NONE Successful
719 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
720 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory space
721 * @retval #CKMC_ERROR_INVALID_FORMAT Invalid PKCS12 file format
722 * @retval #CKMC_ERROR_FILE_ACCESS_DENIED Provided file does not exist or cannot be accessed
723 * @see ckmc_pkcs12_free()
724 * @see #ckmc_pkcs12_s
726 int ckmc_pkcs12_load(const char *file_path, const char *passphrase, ckmc_pkcs12_s **pkcs12_bundle);
730 * @brief Destroys the #ckmc_pkcs12_s handle and releases all its resources.
731 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
732 * @param[in] pkcs12 The #ckmc_pkcs12_s handle to destroy
733 * @see ckmc_pkcs12_new()
734 * @see ckmc_pkcs12_load()
736 void ckmc_pkcs12_free(ckmc_pkcs12_s *pkcs12);
740 * @brief Creates a new #ckmc_alias_list_s handle and returns it. The alias pointer in the returned
741 * #ckmc_alias_list_s handle points to the provided characters and next is NULL.
742 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
743 * @remarks You must destroy the newly created #ckmc_alias_list_s by calling ckmc_alias_list_free()
744 * or ckmc_alias_list_all_free() if it is no longer needed.
745 * @param[in] alias The first item to be set in the newly created #ckmc_alias_list_s
746 * @param[out] ppalias_list The pointer to a newly created #ckmc_alias_list_s handle
747 * @return #CKMC_ERROR_NONE on success,
748 * otherwise a negative error value
749 * @retval #CKMC_ERROR_NONE Successful
750 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
751 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
752 * @see ckmc_alias_list_all_free()
753 * @see #ckmc_alias_list_s
755 int ckmc_alias_list_new(char *alias, ckmc_alias_list_s **ppalias_list);
759 * @brief Creates a new #ckmc_alias_list_s handle, adds it to a previous #ckmc_alias_list_s and
760 * returns it. The alias pointer in the returned #ckmc_alias_list_s handle points to the
761 * provided characters and next is NULL.
762 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
763 * @remarks You must destroy the newly created @a pplast using ckmc_alias_list_free()
764 * @param[in] previous The last #ckmc_alias_list_s handle to which a newly created
765 * #ckmc_alias_list_s is added
766 * @param[in] alias The item to be set in the newly created #ckmc_alias_list_s
767 * @param[out] pplast The pointer to a newly created and added #ckmc_alias_list_s handle
768 * @return #CKMC_ERROR_NONE on success,
769 * otherwise a negative error value
770 * @retval #CKMC_ERROR_NONE Successful
771 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
772 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
773 * @see ckmc_alias_list_all_free()
774 * @see #ckmc_alias_list_s
776 int ckmc_alias_list_add(ckmc_alias_list_s *previous, char *alias, ckmc_alias_list_s **pplast);
780 * @brief Destroys the #ckmc_alias_list_s handle and releases resources of #ckmc_alias_list_s from
781 * the provided first handle cascadingly.
782 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
783 * @remarks It does not destroy an alias itself in #ckmc_alias_list_s.
784 * @param[in] first The first #ckmc_alias_list_s handle to destroy
785 * @see ckmc_alias_list_all_free()
786 * @see #ckmc_alias_list_s
788 void ckmc_alias_list_free(ckmc_alias_list_s *first);
792 * @brief Destroys the #ckmc_alias_list_s handle and releases all its resources from the provided
793 * first handle cascadingly.
794 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
795 * @remarks It also destroys the alias in #ckmc_alias_list_s.
796 * @param[in] first The first #ckmc_alias_list_s handle to destroy
797 * @see #ckmc_alias_list_s
799 void ckmc_alias_list_all_free(ckmc_alias_list_s *first);
803 * @brief Creates a new #ckmc_cert_list_s handle and returns it. The cert pointer in the returned
804 * #ckmc_cert_list_s handle points to the provided #ckmc_cert_s and next is NULL.
805 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
806 * @remarks You must destroy the newly created #ckmc_cert_list_s by calling ckmc_cert_list_free() or
807 * ckmc_cert_list_all_free() if it is no longer needed.
808 * @param[in] cert The first item to be set in the newly created #ckmc_cert_list_s
809 * @param[out] ppalias_list The pointer to a newly created #ckmc_alias_list_s handle
810 * @return #CKMC_ERROR_NONE on success,
811 * otherwise a negative error value
812 * @retval #CKMC_ERROR_NONE Successful
813 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
814 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
815 * @see ckmc_cert_list_all_free()
816 * @see #ckmc_cert_list_s
818 int ckmc_cert_list_new(ckmc_cert_s *cert, ckmc_cert_list_s **ppalias_list);
822 * @brief Creates a new #ckmc_cert_list_s handle, adds it to a previous #ckmc_cert_list_s and
823 * returns it. The cert pointer in the returned #ckmc_alias_list_s handle points to the
824 * provided #ckmc_cert_s and next is NULL.
825 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
826 * @remarks You must destroy the newly created @a pplast using ckmc_cert_list_free()
827 * @param[in] previous The last #ckmc_cert_list_s handle to which a newly created #ckmc_cert_list_s
829 * @param[in] cert The item to be set in the newly created #ckmc_cert_list_s
830 * @param[out] pplast The pointer to a newly created and added #ckmc_alias_list_s handle
831 * @return #CKMC_ERROR_NONE on success,
832 * otherwise a negative error value
833 * @retval #CKMC_ERROR_NONE Successful
834 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
835 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
836 * @see ckmc_cert_list_all_free()
837 * @see #ckmc_cert_list_s
839 int ckmc_cert_list_add(ckmc_cert_list_s *previous, ckmc_cert_s *cert, ckmc_cert_list_s **pplast);
843 * @brief Destroys the #ckmc_cert_list_s handle and releases resources of #ckmc_cert_list_s from the
844 * provided first handle cascadingly.
845 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
846 * @remarks It does not destroy #ckmc_cert_s itself in #ckmc_cert_list_s.
847 * @param[in] first The first #ckmc_cert_list_s handle to destroy
848 * @see ckmc_cert_list_all_free()
849 * @see #ckmc_cert_list_s
851 void ckmc_cert_list_free(ckmc_cert_list_s *first);
855 * @brief Destroys the #ckmc_cert_list_s handle and releases all its resources from the provided
856 * first handle cascadingly.
858 * @remarks It also destroys #ckmc_cert_s in #ckmc_cert_list_s.
859 * @param[in] first The first #ckmc_cert_list_s handle to destroy
860 * @see #ckmc_cert_list_s
862 void ckmc_cert_list_all_free(ckmc_cert_list_s *first);
866 * @brief Creates new parameter list.
868 * @remarks Caller is responsible for freeing it with ckmc_param_list_free().
869 * @param[in] pparams Double pointer to the handle of param list to which the newly created
870 * algorithm param list will be assigned
871 * @return #CKMC_ERROR_NONE on success,
872 * otherwise a negative error value
873 * @retval #CKMC_ERROR_NONE Successful
874 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
875 * @see ckmc_param_list_set_integer()
876 * @see ckmc_param_list_set_buffer()
877 * @see ckmc_param_list_free()
878 * @see ckmc_generate_new_params()
879 * @see #ckmc_param_list_h
880 * @see #ckmc_param_name_e
881 * @see #ckmc_algo_type_e
883 int ckmc_param_list_new(ckmc_param_list_h *pparams);
887 * @brief Sets integer parameter to the list.
889 * @remarks Caller is responsible for #ckmc_param_list_h creation.
890 * @param[in] params Algorithm param list handle created with ckmc_param_list_new() or
891 * ckmc_generate_new_params(). New param with @a name and @a value will be set
893 * @param[in] name Name of parameter to set. Existing parameter will be overwritten. Passing invalid
894 * parameter name will result in an error
895 * @param[in] value Value of the parameter in form of a integer
896 * @return #CKMC_ERROR_NONE on success,
897 * otherwise a negative error value
898 * @retval #CKMC_ERROR_NONE Successful
899 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
900 * @see ckmc_param_list_new()
901 * @see ckmc_param_list_set_buffer()
902 * @see ckmc_param_list_get_integer()
903 * @see ckmc_param_list_get_buffer()
904 * @see ckmc_param_list_free()
905 * @see ckmc_generate_new_params()
906 * @see #ckmc_param_list_h
907 * @see #ckmc_param_name_e
908 * @see #ckmc_algo_type_e
910 int ckmc_param_list_set_integer(ckmc_param_list_h params, ckmc_param_name_e name, uint64_t value);
914 * @brief Sets buffer parameter to the list.
916 * @remarks Caller is responsible for #ckmc_param_list_h creation.
917 * @param[in] params Algorithm param list handle created with ckmc_param_list_new() or
918 * ckmc_generate_new_params(). New param with @a name and @a buffer will be set
920 * @param[in] name Name of parameter to set. Existing parameter will be overwritten. Passing invalid
921 * parameter name will result in an error
922 * @param[in] buffer Value of the parameter in form of a buffer. Caller is responsible for creating
923 * and freeing the buffer
924 * @return #CKMC_ERROR_NONE on success,
925 * otherwise a negative error value
926 * @retval #CKMC_ERROR_NONE Successful
927 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
928 * @see ckmc_param_list_new()
929 * @see ckmc_param_list_set_integer()
930 * @see ckmc_param_list_get_integer()
931 * @see ckmc_param_list_get_buffer()
932 * @see ckmc_param_list_free()
933 * @see ckmc_generate_new_params()
934 * @see #ckmc_param_list_h
935 * @see #ckmc_param_name_e
936 * @see #ckmc_algo_type_e
938 int ckmc_param_list_set_buffer(ckmc_param_list_h params,
939 ckmc_param_name_e name,
940 const ckmc_raw_buffer_s *buffer);
944 * @brief Gets integer parameter from the list.
946 * @remarks Caller is responsible for #ckmc_param_list_h creation.
947 * @param[in] params Algorithm param list handle created with ckmc_param_list_new() or
948 * ckmc_generate_new_params() which contains param with @a name
949 * @param[in] name Name of parameter to get
950 * @param[out] pvalue Value of the parameter in form of a integer
951 * @return #CKMC_ERROR_NONE on success,
952 * otherwise a negative error value
953 * @retval #CKMC_ERROR_NONE Successful
954 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
955 * @see ckmc_param_list_new()
956 * @see ckmc_param_list_set_integer()
957 * @see ckmc_param_list_set_buffer()
958 * @see ckmc_param_list_get_buffer()
959 * @see ckmc_param_list_free()
960 * @see ckmc_generate_new_params()
961 * @see #ckmc_param_list_h
962 * @see #ckmc_param_name_e
963 * @see #ckmc_algo_type_e
965 int ckmc_param_list_get_integer(ckmc_param_list_h params, ckmc_param_name_e name, uint64_t *pvalue);
969 * @brief Gets buffer parameter from the list.
971 * @remarks Caller is responsible for #ckmc_param_list_h creation.
972 * @remarks You must destroy the @a ppbuffer using ckmc_buffer_free()
973 * @param[in] params Algorithm param list handle created with ckmc_param_list_new() or
974 * ckmc_generate_new_params() which contains param with @a name
975 * @param[in] name Name of parameter to get
976 * @param[out] ppbuffer Value of the parameter in form of a buffer
977 * @return #CKMC_ERROR_NONE on success,
978 * otherwise a negative error value
979 * @retval #CKMC_ERROR_NONE Successful
980 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
981 * @see ckmc_param_list_new()
982 * @see ckmc_param_list_set_integer()
983 * @see ckmc_param_list_set_buffer()
984 * @see ckmc_param_list_get_integer()
985 * @see ckmc_param_list_free()
986 * @see ckmc_generate_new_params()
987 * @see ckmc_buffer_free()
988 * @see #ckmc_param_list_h
989 * @see #ckmc_param_name_e
990 * @see #ckmc_algo_type_e
992 int ckmc_param_list_get_buffer(ckmc_param_list_h params,
993 ckmc_param_name_e name,
994 ckmc_raw_buffer_s **ppbuffer);
998 * @brief Frees previously allocated list of algorithm params.
1000 * @param[in] params First element of the list to be freed
1001 * @see ckmc_param_list_new()
1002 * @see ckmc_param_list_set_integer()
1003 * @see ckmc_param_list_set_buffer()
1004 * @see ckmc_param_list_get_integer()
1005 * @see ckmc_param_list_get_buffer()
1006 * @see ckmc_generate_new_params()
1007 * @see #ckmc_param_list_h
1008 * @see #ckmc_param_name_e
1009 * @see #ckmc_algo_type_e
1011 void ckmc_param_list_free(ckmc_param_list_h params);
1015 * @brief Generates algorithm parameters for a given algorithm type and set them to the list.
1017 * @remarks Caller is responsible for #ckmc_param_list_h destruction.
1018 * @remarks Algorithm parameters are set to default values. Optional fields are left empty.
1019 * Initialization vectors are left empty (they have to be set manually).
1020 * Caller is responsible for freeing the list with ckmc_param_list_free().
1021 * @remarks If the function returns error, provided param list may contain some of default
1023 * @param[in] type Type of the algorithm
1024 * @param[out] pparams Newly generated handle of param list which should be freed by caller after
1026 * @return #CKMC_ERROR_NONE on success,
1027 * otherwise a negative error value
1028 * @retval #CKMC_ERROR_NONE Successful
1029 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
1030 * @see ckmc_param_list_new()
1031 * @see ckmc_param_list_set_integer()
1032 * @see ckmc_param_list_set_buffer()
1033 * @see ckmc_param_list_get_integer()
1034 * @see ckmc_param_list_get_buffer()
1035 * @see ckmc_param_list_free()
1036 * @see #ckmc_param_list_h
1037 * @see #ckmc_param_name_e
1038 * @see #ckmc_algo_type_e
1040 int ckmc_generate_new_params(ckmc_algo_type_e type, ckmc_param_list_h *pparams);
1053 #endif /* __TIZEN_CORE_CKMC_TYPE_H__ */