2 * Copyright (c) 2000 - 2014 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.
22 #ifndef __TIZEN_CORE_CKMC_TYPE_H
23 #define __TIZEN_CORE_CKMC_TYPE_H
26 #include <ckmc/ckmc-error.h>
28 #define KEY_MANAGER_CAPI __attribute__((visibility("default")))
36 * @addtogroup CAPI_KEY_MANAGER_TYPES_MODULE
41 * @brief Enumeration for key types of key manager.
44 typedef enum __ckmc_key_type {
45 CKMC_KEY_NONE = 0, /**< key type not specified */
46 CKMC_KEY_RSA_PUBLIC, /**< RSA public key */
47 CKMC_KEY_RSA_PRIVATE, /**< RSA private key */
48 CKMC_KEY_ECDSA_PUBLIC, /**< ECDSA public key */
49 CKMC_KEY_ECDSA_PRIVATE, /**< ECDSA private key */
53 * @brief Enumeration for data format.
56 typedef enum __ckmc_data_format {
57 CKMC_FORM_DER_BASE64 = 0, /**< DER format base64 encoded data */
58 CKMC_FORM_DER, /**< DER encoded data */
59 CKMC_FORM_PEM /**< PEM encoded data. It consists of the DER format base64 encoded with additional header and footer lines. */
63 * @brief Enumeration for elliptic curve.
66 typedef enum __ckmc_ec_type {
67 CKMC_EC_PRIME192V1 = 0, /**< Elliptic curve domain "secp192r1" listed in "SEC 2" recommended elliptic curve domain */
68 CKMC_EC_PRIME256V1, /**< "SEC 2" recommended elliptic curve domain - secp256r1 */
69 CKMC_EC_SECP384R1 /**< NIST curve P-384 (covers "secp384r1", the elliptic curve domain listed in See SEC 2 */
73 * @brief Enumeration for hash algorithm.
76 typedef enum __ckmc_hash_algo {
77 CKMC_HASH_SHA1 = 0, /**< Hash Algorithm SHA1 */
78 CKMC_HASH_SHA256, /**< Hash Algorithm SHA256 */
79 CKMC_HASH_SHA384, /**< Hash Algorithm SHA384 */
80 CKMC_HASH_SHA512 /**< Hash Algorithm SHA512 */
84 * @brief Enumeration for RSA padding algorithm.
87 typedef enum __ckmc_rsa_padding_algo {
88 CKMC_PKCS1_PADDING = 0, /**< PKCS#1 Padding */
89 CKMC_X931_PADDING /**< X9.31 padding */
90 } ckmc_rsa_padding_algo_e;
93 * @brief the structure for binary buffer used in key manager CAPI.
96 typedef struct __ckmc_raw_buff {
97 unsigned char* data; /**< Byte array containing binary data */
98 size_t size; /**< The size of the binary data */
102 * @brief The structure for a policy for storing key/certificate/binary data.
105 typedef struct __ckmc_policy {
106 char* password; /**< Byte array used to encrypt data inside CKM. If it is not null, the data(or key, or certificate) is stored encrypted with this password inside key manager */
107 bool extractable; /**< If true key may be extracted from storage */
111 * @brief The structure for key used in key manager CAPI.
114 typedef struct __ckmc_key {
115 unsigned char* raw_key; /**< Byte array of key. raw_key may be encrypted with password */
116 size_t key_size; /**< The byte size of raw_key */
117 ckmc_key_type_e key_type; /**< The raw_key's type */
118 char* password; /**< Byte array used to decrypt data raw_key inside key manager. */
122 * @brief The structure for certificate used in key manager CAPI.
125 typedef struct __ckmc_cert {
126 unsigned char* raw_cert; /**< Byte array of certificate */
127 size_t cert_size; /**< Byte size of raw_cert */
128 ckmc_data_format_e data_format; /**< Raw_cert's encoding format */
132 * @brief The structure for linked list of alias.
135 typedef struct __ckmc_alias_list {
136 char *alias; /**< The name of key, certificate or data stored in key manager */
137 struct __ckmc_alias_list *next; /**< The pointer pointing to the next ckmc_alias_list_s */
141 * @brief The structure for linked list of ckmc_cert_s
144 typedef struct __ckmc_cert_list {
145 ckmc_cert_s *cert; /**< The pointer of ckmc_cert_s */
146 struct __ckmc_cert_list *next; /**< The pointer pointing to the next ckmc_cert_list_s */
151 * @brief Creates a new @a ckmc_key_s handle and returns it.
155 * @remarks You must destroy the newly created @a ckmc_key_s by calling ckmc_key_free() if it is no longer needed.
157 * @param[in] raw_key The byte array of key \n
158 * @a raw_key may be encrypted with password.
159 * @param[in] key_size The byte size of @a raw_key
160 * @param[in] key_type The @a raw_key's type
161 * @param[in] password The byte array used to decrypt @a raw_key inside key manager \n
162 * If @a raw_key is not encrypted, @a password can be null.
163 * @param[out] ppkey The pointer to a newly created @a ckmc_key_s handle
165 * @return @c 0 on success,
166 * otherwise a negative error value
168 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
169 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
171 * @see ckmc_key_free()
174 int ckmc_key_new(unsigned char *raw_key, size_t key_size,
175 ckmc_key_type_e key_type, char *password, ckmc_key_s **ppkey);
178 * @brief Destroys the @a ckmc_key_s handle and releases all its resources.
182 * @param[in] key The @a ckmc_key_s handle to destroy
185 void ckmc_key_free(ckmc_key_s *key);
189 * @brief Creates a new @a ckmc_raw_buffer_s handle and returns it.
193 * @remarks You must destroy the newly created @a ckmc_raw_buffer_s by calling ckmc_buffer_free() if it is no longer needed.
195 * @param[in] data The byte array of buffer
196 * @param[in] size The byte size of buffer
197 * @param[out] ppbuffer The pointer to a newly created @a ckmc_buffer_s handle
199 * @return @c 0 on success,
200 * otherwise a negative error value
202 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
203 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
205 * @see ckmc_buffer_free()
206 * @see #ckmc_raw_buffer_s
208 int ckmc_buffer_new(unsigned char *data, size_t size,ckmc_raw_buffer_s **ppbuffer);
211 * @brief Destroys the @a ckmc_raw_buffer_s handle and releases all its resources.
215 * @param[in] buffer The @a ckmc_raw_buffer_s handle to destroy
218 void ckmc_buffer_free(ckmc_raw_buffer_s *buffer);
222 * @brief Creates a new @a ckmc_cert_s handle and returns it.
226 * @remarks You must destroy the newly created @a ckmc_cert_s by calling ckmc_cert_free() if it is no longer needed.
228 * @param[in] raw_cert The byte array of certificate
229 * @param[in] cert_size The byte size of raw_cert
230 * @param[in] data_format The encoding format of raw_cert
231 * @param[out] ppcert The pointer to a newly created @a ckmc_cert_s handle
233 * @return @c 0 on success,
234 * otherwise a negative error value
236 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
237 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
239 * @see ckmc_cert_free()
240 * @see ckmc_load_cert_from_file()
241 * @see ckmc_load_from_pkcs12_file
244 int ckmc_cert_new(unsigned char *raw_cert, size_t cert_size,
245 ckmc_data_format_e data_format, ckmc_cert_s **ppcert);
248 * @brief Destroys the @a ckmc_cert handle and releases all its resources.
252 * @param[in] cert The @a ckmc_cert_s handle to destroy
254 * @see ckmc_load_cert_from_file()
255 * @see ckmc_load_from_pkcs12_file
257 void ckmc_cert_free(ckmc_cert_s *cert);
260 * @brief Creates a new @a ckmc_cert_s handle from a given file and returns it.
264 * @remarks You must destroy the newly created @a ckmc_cert_s by calling ckmc_cert_free() if it is no longer needed.
266 * @param[in] file_path The path of certificate file to be loaded \n
267 * The only DER or PEM encoded certificate file is supported.
268 * @param[out] cert The pointer of newly created @a ckmc_cert_s handle
270 * @return #CKMC_ERROR_NONE on success,
271 * otherwise a negative error value
273 * @retval #CKMC_ERROR_NONE Successful
274 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory space
275 * @retval #CKMC_ERROR_INVALID_FORMAT Invalid certificate file format
276 * @retval #CKMC_ERROR_FILE_ACCESS_DENIED Provided file does not exist or cannot be accessed
278 * @see ckmc_cert_free()
279 * @see ckmc_load_from_pkcs12_file()
282 int ckmc_load_cert_from_file(const char *file_path, ckmc_cert_s **cert);
285 * @brief Creates a new @a ckmc_key_s(private key), @a ckmc_cert_s(certificate), and @a ckmc_cert_list_s(CA certificates) handle from a given PKCS#12 file and returns them.
289 * @remarks You must destroy the newly created @a ckmc_key_s, @a ckmc_cert_s, and @a ckmc_cert_list_s by calling ckmc_key_free(), ckmc_cert_free(), and ckmc_cert_list_all_free() if they are no longer needed.
291 * @param[in] file_path The path of PKCS12 file to be loaded
292 * @param[in] passphrase The passphrase used to decrypt the PCKS12 file \n
293 * If PKCS12 file is not encrypted, passphrase can be null.
294 * @param[out] private_key The pointer of newly created @a ckmc_key_s handle for a private key
295 * @param[out] cert The pointer of newly created @a ckmc_cert_s handle for a certificate \n
296 * It is null if the PKCS12 file does not contain a certificate.
297 * @param[out] ca_cert_list The pointer of newly created @a ckmc_cert_list_s handle for CA certificates \n
298 * It is null if the PKCS12 file does not contain CA certificates.
300 * @return #CKMC_ERROR_NONE on success,
301 * otherwise a negative error value
303 * @retval #CKMC_ERROR_NONE Successful
304 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory space
305 * @retval #CKMC_ERROR_INVALID_FORMAT Invalid PKCS12 file format
306 * @retval #CKMC_ERROR_FILE_ACCESS_DENIED Provided file does not exist or cannot be accessed
308 * @see ckmc_key_free()
309 * @see ckmc_cert_free()
310 * @see ckmc_cert_list_all_free()
313 * @see #ckmc_cert_list_s
315 int ckmc_load_from_pkcs12_file(const char *file_path, const char *passphrase,
316 ckmc_key_s **private_key, ckmc_cert_s **cert,
317 ckmc_cert_list_s **ca_cert_list);
321 * @brief Creates a new @a ckmc_alias_list_s handle and returns it.
322 * The alias pointer in the returned @a ckmc_alias_list_s handle points to the provided characters and next is null.
326 * @remarks You must destroy the newly created @a ckmc_alias_list_s by calling ckmc_alias_list_free() or ckmc_alias_list_all_free() if it is no longer needed.
328 * @param[in] alias The first item to be set in the newly created @a ckmc_alias_list_s
329 * @param[out] ppalias_list The pointer to a newly created @a ckmc_alias_list_s handle
331 * @return @c 0 on success,
332 * otherwise a negative error value
334 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
335 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
337 * @see ckmc_alias_list_all_free()
338 * @see #ckmc_alias_list_s
340 int ckmc_alias_list_new(char *alias, ckmc_alias_list_s **ppalias_list);
344 * @brief Creates a new @a ckmc_alias_list_s handle, adds it to a previous @a ckmc_alias_list_s and returns it.
345 * The alias pointer in the returned @a ckmc_alias_list_s handle points to the provided characters and next is null.
349 * @param[in] previous The last @a ckmc_alias_list_s handle to which a newly created @a ckmc_alias_list_s is added
350 * @param[in] alias The item to be set in the newly created @a ckmc_alias_list_s
351 * @param[out] pplast The pointer to a newly created and added @a ckmc_alias_list_s handle
353 * @return @c 0 on success,
354 * otherwise a negative error value
356 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
357 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
359 * @see ckmc_alias_list_all_free()
360 * @see #ckmc_alias_list_s
362 int ckmc_alias_list_add(ckmc_alias_list_s *previous,
363 char *alias, ckmc_alias_list_s **pplast);
367 * @brief Destroys the @a ckmc_alias_list_s handle and releases resources of @a ckmc_alias_list_s from the provided first handle cascadingly.
371 * @remarks It does not destroy an alias itself in @a ckmc_alias_list_s.
373 * @param[in] first The first @a ckmc_alias_list_s handle to destroy
375 * @see ckmc_alias_list_all_free()
376 * @see #ckmc_alias_list_s
378 void ckmc_alias_list_free(ckmc_alias_list_s *first);
381 * @brief Destroys the @a ckmc_alias_list_s handle and releases all its resources from the provided first handle cascadingly.
385 * @remarks It also destroys the alias in @a ckmc_alias_list_s.
387 * @param[in] first The first @a ckmc_alias_list_s handle to destroy
389 * @see #ckmc_alias_list_s
391 void ckmc_alias_list_all_free(ckmc_alias_list_s *first);
395 * @brief Creates a new @a ckmc_cert_list_s handle and returns it.
396 * The cert pointer in the returned @a ckmc_cert_list_s handle points to the provided @a ckmc_cert_s and next is null.
400 * @remarks You must destroy the newly created @a ckmc_cert_list_s by calling ckmc_cert_list_free() or ckmc_cert_list_all_free() if it is no longer needed.
402 * @param[in] cert The first item to be set in the newly created @a ckmc_cert_list_s
403 * @param[out] ppalias_list The pointer to a newly created @a ckmc_alias_list_s handle
405 * @return @c 0 on success,
406 * otherwise a negative error value
408 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
409 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
411 * @see ckmc_cert_list_all_free()
412 * @see #ckmc_cert_list_s
414 int ckmc_cert_list_new(ckmc_cert_s *cert, ckmc_cert_list_s **ppalias_list);
418 * @brief Creates a new @a ckmc_cert_list_s handle, adds it to a previous @a ckmc_cert_list_s and returns it.
419 * The cert pointer in the returned @a ckmc_alias_list_s handle points to the provided @a ckmc_cert_s and next is null.
423 * @param[in] previous The last @a ckmc_cert_list_s handle to which a newly created @a ckmc_cert_list_s is added
424 * @param[in] cert The item to be set in the newly created @a ckmc_cert_list_s
425 * @param[out] pplast The pointer to a newly created and added @a ckmc_alias_list_s handle
427 * @return @c 0 on success,
428 * otherwise a negative error value
430 * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid
431 * @retval #CKMC_ERROR_OUT_OF_MEMORY Not enough memory
433 * @see ckmc_cert_list_all_free()
434 * @see #ckmc_cert_list_s
436 int ckmc_cert_list_add(ckmc_cert_list_s *previous,
437 ckmc_cert_s *cert, ckmc_cert_list_s **pplast);
441 * @brief Destroys the @a ckmc_cert_list_s handle and releases resources of @a ckmc_cert_list_s from the provided first handle cascadingly.
445 * @remarks It does not destroy @a ckmc_cert_s itself in @a ckmc_cert_list_s.
447 * @param[in] first The first @a ckmc_cert_list_s handle to destroy
449 * @see ckmc_cert_list_all_free()
450 * @see #ckmc_cert_list_s
452 void ckmc_cert_list_free(ckmc_cert_list_s *first);
455 * @brief Destroys the @a ckmc_cert_list_s handle and releases all its resources from the provided first handle cascadingly.
459 * @remarks It also destroys @a ckmc_cert_s in ckmc_cert_list_s.
461 * @param[in] first The first @a ckmc_cert_list_s handle to destroy
463 * @see #ckmc_cert_list_s
465 void ckmc_cert_list_all_free(ckmc_cert_list_s *first);
475 #endif /* __TIZEN_CORE_CKMC_TYPE_H */