Tizen Native API  6.0
Key Manager Data Types

It defines data types used in these APIs and provides utility methods handling them.

Required Header

#include <ckmc/ckmc-type.h>

Overview

It defines data types for key, certificate, raw buffer, and linked list used in these APIs. It also provides new and free methods for them.

Functions

int ckmc_alias_info_get_alias (const ckmc_alias_info_s *info, char **alias)
 Gets the alias from ckmc_alias_info_s structure.
int ckmc_alias_info_is_password_protected (const ckmc_alias_info_s *info, bool *is_password_protected)
 Gets the password protection status from ckmc_alias_info_s structure.
void ckmc_alias_info_list_all_free (ckmc_alias_info_list_s *first)
 Destroys the ckmc_alias_info_list_s handle and releases resources of ckmc_alias_info_list_s from the provided first handle cascadingly.
int ckmc_alias_new (const char *owner_id, const char *alias, char **full_alias)
 Creates a new full alias which is a concatenation of owner_id and alias.
int ckmc_key_new (unsigned char *raw_key, size_t key_size, ckmc_key_type_e key_type, char *password, ckmc_key_s **ppkey)
 Creates a new ckmc_key_s handle and returns it.
void ckmc_key_free (ckmc_key_s *key)
 Destroys the ckmc_key_s handle and releases all its resources.
int ckmc_buffer_new (unsigned char *data, size_t size, ckmc_raw_buffer_s **ppbuffer)
 Creates a new ckmc_raw_buffer_s handle and returns it.
void ckmc_buffer_free (ckmc_raw_buffer_s *buffer)
 Destroys the ckmc_raw_buffer_s handle and releases all its resources.
int ckmc_cert_new (unsigned char *raw_cert, size_t cert_size, ckmc_data_format_e data_format, ckmc_cert_s **ppcert)
 Creates a new ckmc_cert_s handle and returns it.
void ckmc_cert_free (ckmc_cert_s *cert)
 Destroys the ckmc_cert_s handle and releases all its resources.
int ckmc_load_cert_from_file (const char *file_path, ckmc_cert_s **cert)
 Creates a new ckmc_cert_s handle from a given file and returns it.
int ckmc_pkcs12_new (ckmc_key_s *private_key, ckmc_cert_s *cert, ckmc_cert_list_s *ca_cert_list, ckmc_pkcs12_s **pkcs12_bundle)
 Creates a new ckmc_pkcs12_s handle and returns it.
int ckmc_load_from_pkcs12_file (const char *file_path, const char *passphrase, ckmc_key_s **private_key, ckmc_cert_s **cert, ckmc_cert_list_s **ca_cert_list) TIZEN_DEPRECATED_API
 Creates a new ckmc_key_s (private_key), ckmc_cert_s (cert), and ckmc_cert_list_s (ca_cert_list) handle from a given PKCS#12 file and returns them.
int ckmc_pkcs12_load (const char *file_path, const char *passphrase, ckmc_pkcs12_s **pkcs12_bundle)
 Creates a new ckmc_pkcs12_s handle from a given PKCS#12 file and returns it.
void ckmc_pkcs12_free (ckmc_pkcs12_s *pkcs12)
 Destroys the ckmc_pkcs12_s handle and releases all its resources.
int ckmc_alias_list_new (char *alias, ckmc_alias_list_s **ppalias_list)
 Creates a new ckmc_alias_list_s handle and returns it. The alias pointer in the returned ckmc_alias_list_s handle points to the provided characters and next is null.
int ckmc_alias_list_add (ckmc_alias_list_s *previous, char *alias, ckmc_alias_list_s **pplast)
 Creates a new ckmc_alias_list_s handle, adds it to a previous ckmc_alias_list_s and returns it. The alias pointer in the returned ckmc_alias_list_s handle points to the provided characters and next is null.
void ckmc_alias_list_free (ckmc_alias_list_s *first)
 Destroys the ckmc_alias_list_s handle and releases resources of ckmc_alias_list_s from the provided first handle cascadingly.
void ckmc_alias_list_all_free (ckmc_alias_list_s *first)
 Destroys the ckmc_alias_list_s handle and releases all its resources from the provided first handle cascadingly.
int ckmc_cert_list_new (ckmc_cert_s *cert, ckmc_cert_list_s **ppalias_list)
 Creates a new ckmc_cert_list_s handle and returns it. The cert pointer in the returned ckmc_cert_list_s handle points to the provided ckmc_cert_s and next is null.
int ckmc_cert_list_add (ckmc_cert_list_s *previous, ckmc_cert_s *cert, ckmc_cert_list_s **pplast)
 Creates a new ckmc_cert_list_s handle, adds it to a previous ckmc_cert_list_s and returns it. The cert pointer in the returned ckmc_alias_list_s handle points to the provided ckmc_cert_s and next is null.
void ckmc_cert_list_free (ckmc_cert_list_s *first)
 Destroys the ckmc_cert_list_s handle and releases resources of ckmc_cert_list_s from the provided first handle cascadingly.
void ckmc_cert_list_all_free (ckmc_cert_list_s *first)
 Destroys the ckmc_cert_list_s handle and releases all its resources from the provided first handle cascadingly.
int ckmc_param_list_new (ckmc_param_list_h *pparams)
 Creates new parameter list.
int ckmc_param_list_set_integer (ckmc_param_list_h params, ckmc_param_name_e name, uint64_t value)
 Sets integer parameter to the list.
int ckmc_param_list_set_buffer (ckmc_param_list_h params, ckmc_param_name_e name, const ckmc_raw_buffer_s *buffer)
 Sets buffer parameter to the list.
int ckmc_param_list_get_integer (ckmc_param_list_h params, ckmc_param_name_e name, uint64_t *pvalue)
 Gets integer parameter from the list.
int ckmc_param_list_get_buffer (ckmc_param_list_h params, ckmc_param_name_e name, ckmc_raw_buffer_s **ppbuffer)
 Gets buffer parameter from the list.
void ckmc_param_list_free (ckmc_param_list_h params)
 Frees previously allocated list of algorithm params.
int ckmc_generate_new_params (ckmc_algo_type_e type, ckmc_param_list_h *pparams)
 Generates algorithm parameters for a given algorithm type and set them to the list.

Typedefs

typedef enum __ckmc_key_type ckmc_key_type_e
 Enumeration for key types of key manager.
typedef enum __ckmc_data_format ckmc_data_format_e
 Enumeration for data format.
typedef enum __ckmc_ec_type ckmc_ec_type_e
 Enumeration for elliptic curve.
typedef enum __ckmc_hash_algo ckmc_hash_algo_e
 Enumeration for hash algorithm.
typedef enum
__ckmc_rsa_padding_algo 
ckmc_rsa_padding_algo_e
 Enumeration for RSA padding algorithm.
typedef enum __ckmc_access_right ckmc_access_right_e
 Enumeration for database access rights.
typedef enum __ckmc_permission ckmc_permission_e
 Enumeration for permissions to access/modify alias.
typedef struct __ckmc_raw_buff ckmc_raw_buffer_s
 The structure for binary buffer used in key manager CAPI.
typedef struct __ckmc_policy ckmc_policy_s
 The structure for a policy for storing key/certificate/binary data.
typedef struct __ckmc_key ckmc_key_s
 The structure for key used in key manager CAPI.
typedef struct __ckmc_cert ckmc_cert_s
 The structure for certificate used in key manager CAPI.
typedef struct __ckmc_alias_list ckmc_alias_list_s
 The structure for linked list of alias.
typedef struct ckmc_alias_info_s ckmc_alias_info_s
 The structure of alias and additional information about it.
typedef struct
__ckmc_alias_info_list_s 
ckmc_alias_info_list_s
 The structure for linked list of alias with additional information.
typedef struct __ckmc_cert_list ckmc_cert_list_s
 The structure for linked list of ckmc_cert_s.
typedef enum __ckmc_ocsp_status ckmc_ocsp_status_e
 Enumeration for OCSP status.
typedef struct __ckmc_pkcs12 ckmc_pkcs12_s
 The structure for PKCS12 used in key manager CAPI.
typedef enum __ckmc_param_name ckmc_param_name_e
 Enumeration for crypto algorithm parameters.
typedef struct __ckmc_param_list * ckmc_param_list_h
 Algorithm parameter list handle.
typedef enum __ckmc_algo_type ckmc_algo_type_e
 Enumeration for crypto algorithm types.

Typedef Documentation

Enumeration for database access rights.

Deprecated:
Deprecated since 2.4.[Use ckmc_permission_e() instead]
Since :
2.3

Enumeration for crypto algorithm types.

Since :
3.0
See also:
ckmc_param_name_e

The structure for linked list of alias with additional information.

Since :
5.5

The structure of alias and additional information about it.

Since :
5.5

The structure for linked list of alias.

Since :
2.3

The structure for linked list of ckmc_cert_s.

Since :
2.3
typedef struct __ckmc_cert ckmc_cert_s

The structure for certificate used in key manager CAPI.

Since :
2.3

Enumeration for data format.

Since :
2.3

Enumeration for elliptic curve.

Since :
2.3

Enumeration for hash algorithm.

Since :
2.3
typedef struct __ckmc_key ckmc_key_s

The structure for key used in key manager CAPI.

Since :
2.3

Enumeration for key types of key manager.

Since :
2.3

Enumeration for OCSP status.

Since :
2.4
typedef struct __ckmc_param_list* ckmc_param_list_h

Algorithm parameter list handle.

Since :
3.0
Remarks:
Each parameter list must have at least one CKMC_PARAM_ALGO_TYPE parameter that identifies the algorithm. See ckmc_algo_type_e for available algorithms and additional parameters they support.
See also:
ckmc_generate_new_params()
ckmc_param_list_new()
ckmc_param_list_set_integer()
ckmc_param_list_set_buffer()
ckmc_param_list_get_integer()
ckmc_param_list_get_buffer()
ckmc_param_list_free()
ckmc_algo_type_e
ckmc_param_name_e

Enumeration for crypto algorithm parameters.

Since :
3.0
See also:
ckmc_algo_type_e

Enumeration for permissions to access/modify alias.

Since :
2.4
typedef struct __ckmc_pkcs12 ckmc_pkcs12_s

The structure for PKCS12 used in key manager CAPI.

Since :
2.4
typedef struct __ckmc_policy ckmc_policy_s

The structure for a policy for storing key/certificate/binary data.

Since :
2.3

The structure for binary buffer used in key manager CAPI.

Since :
2.3

Enumeration for RSA padding algorithm.

Since :
2.3

Enumeration Type Documentation

Enumeration for database access rights.

Deprecated:
Deprecated since 2.4.[Use ckmc_permission_e() instead]
Since :
2.3
Enumerator:
CKMC_AR_READ 

Access right for read

CKMC_AR_READ_REMOVE 

Access right for read and remove

Enumeration for crypto algorithm types.

Since :
3.0
See also:
ckmc_param_name_e
Enumerator:
CKMC_ALGO_AES_CTR 

AES-CTR algorithm Supported parameters:

  • CKMC_PARAM_ALGO_TYPE = CKMC_ALGO_AES_CTR(mandatory),
  • CKMC_PARAM_ED_IV = 16-byte initialization vector(mandatory)
  • CKMC_PARAM_ED_CTR_LEN = length of counter block in bits (optional, only 128b is supported at the moment)
CKMC_ALGO_AES_CBC 

AES-CBC algorithm Supported parameters:

  • CKMC_PARAM_ALGO_TYPE = CKMC_ALGO_AES_CBC(mandatory),
  • CKMC_PARAM_ED_IV = 16-byte initialization vector(mandatory)
CKMC_ALGO_AES_GCM 

AES-GCM algorithm Supported parameters:

  • CKMC_PARAM_ALGO_TYPE = CKMC_ALGO_AES_GCM(mandatory),
  • CKMC_PARAM_ED_IV = initialization vector(mandatory)
  • CKMC_PARAM_ED_TAG_LEN = GCM tag length in bits. One of {32, 64, 96, 104, 112, 120, 128} (optional, if not present, the length 128 is used; since Tizen 5.0, if TrustZone backend is used, 32 and 64 lengths are not supported)
  • CKMC_PARAM_ED_AAD = additional authentication data(optional)
CKMC_ALGO_AES_CFB 

AES-CFB algorithm Supported parameters:

  • CKMC_PARAM_ALGO_TYPE = CKMC_ALGO_AES_CFB(mandatory),
  • CKMC_PARAM_ED_IV = 16-byte initialization vector(mandatory)
CKMC_ALGO_RSA_OAEP 

RSA-OAEP algorithm Supported parameters:

  • CKMC_PARAM_ALGO_TYPE = CKMC_ALGO_RSA_OAEP(required),
  • CKMC_PARAM_ED_LABEL = label to be associated with the message (optional, not supported at the moment)

Enumeration for data format.

Since :
2.3
Enumerator:
CKMC_FORM_DER_BASE64 

DER format base64 encoded data

CKMC_FORM_DER 

DER encoded data

CKMC_FORM_PEM 

PEM encoded data. It consists of the DER format base64 encoded with additional header and footer lines.

Enumeration for elliptic curve.

Since :
2.3
Enumerator:
CKMC_EC_PRIME192V1 

Elliptic curve domain "secp192r1" listed in "SEC 2" recommended elliptic curve domain

CKMC_EC_PRIME256V1 

"SEC 2" recommended elliptic curve domain - secp256r1

CKMC_EC_SECP384R1 

NIST curve P-384(covers "secp384r1", the elliptic curve domain listed in See SEC 2

Enumeration for hash algorithm.

Since :
2.3
Enumerator:
CKMC_HASH_NONE 

No Hash Algorithm

CKMC_HASH_SHA1 

Hash Algorithm SHA1

CKMC_HASH_SHA256 

Hash Algorithm SHA256

CKMC_HASH_SHA384 

Hash Algorithm SHA384

CKMC_HASH_SHA512 

Hash Algorithm SHA512

Enumeration for key types of key manager.

Since :
2.3
Enumerator:
CKMC_KEY_NONE 

Key type not specified

CKMC_KEY_RSA_PUBLIC 

RSA public key

CKMC_KEY_RSA_PRIVATE 

RSA private key

CKMC_KEY_ECDSA_PUBLIC 

ECDSA public key

CKMC_KEY_ECDSA_PRIVATE 

ECDSA private key

CKMC_KEY_DSA_PUBLIC 

DSA public key

CKMC_KEY_DSA_PRIVATE 

DSA private key

CKMC_KEY_AES 

AES key

Enumeration for OCSP status.

Since :
2.4
Enumerator:
CKMC_OCSP_STATUS_GOOD 

OCSP status is good

CKMC_OCSP_STATUS_REVOKED 

The certificate is revoked

CKMC_OCSP_STATUS_UNKNOWN 

Unknown error

CKMC_OCSP_ERROR_UNSUPPORTED 

The certificate does not provide OCSP extension

CKMC_OCSP_ERROR_INVALID_URL 

The invalid URL in certificate OCSP extension

CKMC_OCSP_ERROR_INVALID_RESPONSE 

The invalid response from OCSP server

CKMC_OCSP_ERROR_REMOTE 

OCSP remote server error

CKMC_OCSP_ERROR_NET 

Network connection error

CKMC_OCSP_ERROR_INTERNAL 

OpenSSL API error

Enumeration for crypto algorithm parameters.

Since :
3.0
See also:
ckmc_algo_type_e
Enumerator:
CKMC_PARAM_ED_IV 

16B buffer (up to 2^64-1 bytes long in case of AES GCM)

CKMC_PARAM_ED_CTR_LEN 

integer - ctr length in bits

CKMC_PARAM_ED_AAD 

buffer

CKMC_PARAM_ED_TAG_LEN 

integer - tag length in bits

CKMC_PARAM_ED_LABEL 

buffer

Enumeration for permissions to access/modify alias.

Since :
2.4
Enumerator:
CKMC_PERMISSION_NONE 

Clear permissions

CKMC_PERMISSION_READ 

Read allowed

CKMC_PERMISSION_REMOVE 

Remove allowed

Enumeration for RSA padding algorithm.

Since :
2.3
Enumerator:
CKMC_NONE_PADDING 

No Padding

CKMC_PKCS1_PADDING 

PKCS#1 Padding

CKMC_X931_PADDING 

X9.31 padding

Enumeration for Key Manager Errors.

Since :
2.3
Enumerator:
CKMC_ERROR_NONE 

Successful

CKMC_ERROR_INVALID_PARAMETER 

Invalid function parameter

CKMC_ERROR_OUT_OF_MEMORY 

Out of memory

CKMC_ERROR_PERMISSION_DENIED 

Permission denied

CKMC_ERROR_NOT_SUPPORTED 

Device needed to run API is not supported

CKMC_ERROR_SOCKET 

Socket error between client and Central Key Manager

CKMC_ERROR_BAD_REQUEST 

Invalid request from client

CKMC_ERROR_BAD_RESPONSE 

Invalid response from Central Key Manager

CKMC_ERROR_SEND_FAILED 

Transmitting request failed

CKMC_ERROR_RECV_FAILED 

Receiving response failed

CKMC_ERROR_AUTHENTICATION_FAILED 

Optional password which used when saving is incorrect

CKMC_ERROR_BUFFER_TOO_SMALL 

The output buffer size which is passed as parameter is too small

CKMC_ERROR_SERVER_ERROR 

Central Key Manager has been failed for some reason

CKMC_ERROR_DB_LOCKED 

The database was not unlocked - user did not login

CKMC_ERROR_DB_ERROR 

An internal error inside the database

CKMC_ERROR_DB_ALIAS_EXISTS 

Provided alias already exists in the database

CKMC_ERROR_DB_ALIAS_UNKNOWN 

No data for given alias

CKMC_ERROR_VERIFICATION_FAILED 

CA certificate(s) were unknown and chain could not be created

CKMC_ERROR_INVALID_FORMAT 

A provided file or binary has not a valid format

CKMC_ERROR_FILE_ACCESS_DENIED 

A provided file doesn't exist or cannot be accessed in the file system

CKMC_ERROR_NOT_EXPORTABLE 

The data is saved as unexportable so it cannot be leaked

CKMC_ERROR_FILE_SYSTEM 

Save key/certificate/pkcs12 failed because of file system error

CKMC_ERROR_UNKNOWN 

The error with unknown reason


Function Documentation

int ckmc_alias_info_get_alias ( const ckmc_alias_info_s info,
char **  alias 
)

Gets the alias from ckmc_alias_info_s structure.

Since :
5.5
Remarks:
The alias should not be released. The alias can be used until ckmc_alias_info_s is released.
Parameters:
[in]infoThe pointer to the ckmc_alias_info_s structure
[out]aliasThe pointer to the alias
Returns:
CKMC_ERROR_NONE on success, othervise a negative error value
Return values:
CKMC_ERROR_NONESuccessful
CKMC_ERROR_INVALID_PARAMETERInput parameter is invalid
See also:
ckmc_alias_info_s
int ckmc_alias_info_is_password_protected ( const ckmc_alias_info_s info,
bool *  is_password_protected 
)

Gets the password protection status from ckmc_alias_info_s structure.

Since :
5.5
Parameters:
[in]infoThe pointer to the ckmc_alias_info_s structure
[out]is_password_protectedThe pointer to the password protection flag
Returns:
CKMC_ERROR_NONE on success, othervise a negative error value
Return values:
CKMC_ERROR_NONESuccessful
CKMC_ERROR_INVALID_PARAMETERInput parameter is invalid
See also:
ckmc_alias_info_s

Destroys the ckmc_alias_info_list_s handle and releases resources of ckmc_alias_info_list_s from the provided first handle cascadingly.

Since :
5.5
Parameters:
[in]firstThe first ckmc_alias_info_list_s handle to destroy
See also:
ckmc_alias_info_list_s
int ckmc_alias_list_add ( ckmc_alias_list_s previous,
char *  alias,
ckmc_alias_list_s **  pplast 
)

Creates a new ckmc_alias_list_s handle, adds it to a previous ckmc_alias_list_s and returns it. The alias pointer in the returned ckmc_alias_list_s handle points to the provided characters and next is null.

Since :
2.4
Parameters:
[in]previousThe last ckmc_alias_list_s handle to which a newly created ckmc_alias_list_s is added
[in]aliasThe item to be set in the newly created ckmc_alias_list_s
[out]pplastThe pointer to a newly created and added ckmc_alias_list_s handle
Returns:
CKMC_ERROR_NONE on success, otherwise a negative error value
Return values:
CKMC_ERROR_NONESuccessful
CKMC_ERROR_INVALID_PARAMETERInput parameter is invalid
CKMC_ERROR_OUT_OF_MEMORYNot enough memory
See also:
ckmc_alias_list_all_free()
ckmc_alias_list_s

Destroys the ckmc_alias_list_s handle and releases all its resources from the provided first handle cascadingly.

Since :
2.4
Remarks:
It also destroys the alias in ckmc_alias_list_s.
Parameters:
[in]firstThe first ckmc_alias_list_s handle to destroy
See also:
ckmc_alias_list_s

Destroys the ckmc_alias_list_s handle and releases resources of ckmc_alias_list_s from the provided first handle cascadingly.

Since :
2.4
Remarks:
It does not destroy an alias itself in ckmc_alias_list_s.
Parameters:
[in]firstThe first ckmc_alias_list_s handle to destroy
See also:
ckmc_alias_list_all_free()
ckmc_alias_list_s
int ckmc_alias_list_new ( char *  alias,
ckmc_alias_list_s **  ppalias_list 
)

Creates a new ckmc_alias_list_s handle and returns it. The alias pointer in the returned ckmc_alias_list_s handle points to the provided characters and next is null.

Since :
2.4
Remarks:
You must destroy the newly created ckmc_alias_list_s by calling ckmc_alias_list_free() or ckmc_alias_list_all_free() if it is no longer needed.
Parameters:
[in]aliasThe first item to be set in the newly created ckmc_alias_list_s
[out]ppalias_listThe pointer to a newly created ckmc_alias_list_s handle
Returns:
CKMC_ERROR_NONE on success, otherwise a negative error value
Return values:
CKMC_ERROR_NONESuccessful
CKMC_ERROR_INVALID_PARAMETERInput parameter is invalid
CKMC_ERROR_OUT_OF_MEMORYNot enough memory
See also:
ckmc_alias_list_all_free()
ckmc_alias_list_s
int ckmc_alias_new ( const char *  owner_id,
const char *  alias,
char **  full_alias 
)

Creates a new full alias which is a concatenation of owner_id and alias.

Since :
3.0
Remarks:
full_alias should be freed with free() after use.
Returns CKMC_ERROR_INVALID_PARAMETER if any of parameter is NULL.
Returns CKMC_ERROR_INVALID_PARAMETER if owner_id is empty.
Parameters:
[in]owner_idData owner's id. This should be package id if data owner is application. If you want to access data stored by system services, it should be ckmc_owner_id_system
[in]aliasData alias
[out]full_aliasThe newly created alias which is a concatenation of owner_id, ckmc_owner_id_separator and alias. Destroy by free() after use
Returns:
CKMC_ERROR_NONE on success, otherwise a negative error value
Return values:
CKMC_ERROR_NONESuccessful
CKMC_ERROR_INVALID_PARAMETERInput parameter is invalid
CKMC_ERROR_OUT_OF_MEMORYNot enough memory
See also:
ckmc_owner_id_separator
ckmc_owner_id_system
void ckmc_buffer_free ( ckmc_raw_buffer_s buffer)

Destroys the ckmc_raw_buffer_s handle and releases all its resources.

Since :
2.3
Parameters:
[in]bufferThe ckmc_raw_buffer_s structure to destroy
int ckmc_buffer_new ( unsigned char *  data,
size_t  size,
ckmc_raw_buffer_s **  ppbuffer 
)

Creates a new ckmc_raw_buffer_s handle and returns it.

Since :
2.4
Remarks:
You must destroy the newly created ckmc_raw_buffer_s by calling ckmc_buffer_free() if it is no longer needed.
Parameters:
[in]dataThe byte array of buffer
[in]sizeThe byte size of buffer
[out]ppbufferThe pointer to a newly created ckmc_raw_buffer_s handle
Returns:
CKMC_ERROR_NONE on success, otherwise a negative error value
Return values:
CKMC_ERROR_NONESuccessful
CKMC_ERROR_INVALID_PARAMETERInput parameter is invalid
CKMC_ERROR_OUT_OF_MEMORYNot enough memory
See also:
ckmc_buffer_free()
ckmc_raw_buffer_s
void ckmc_cert_free ( ckmc_cert_s cert)

Destroys the ckmc_cert_s handle and releases all its resources.

Since :
2.3
Parameters:
[in]certThe ckmc_cert_s handle to destroy
See also:
ckmc_load_cert_from_file()
int ckmc_cert_list_add ( ckmc_cert_list_s previous,
ckmc_cert_s cert,
ckmc_cert_list_s **  pplast 
)

Creates a new ckmc_cert_list_s handle, adds it to a previous ckmc_cert_list_s and returns it. The cert pointer in the returned ckmc_alias_list_s handle points to the provided ckmc_cert_s and next is null.

Since :
2.4
Parameters:
[in]previousThe last ckmc_cert_list_s handle to which a newly created ckmc_cert_list_s is added
[in]certThe item to be set in the newly created ckmc_cert_list_s
[out]pplastThe pointer to a newly created and added ckmc_alias_list_s handle
Returns:
CKMC_ERROR_NONE on success, otherwise a negative error value
Return values:
CKMC_ERROR_NONESuccessful
CKMC_ERROR_INVALID_PARAMETERInput parameter is invalid
CKMC_ERROR_OUT_OF_MEMORYNot enough memory
See also:
ckmc_cert_list_all_free()
ckmc_cert_list_s

Destroys the ckmc_cert_list_s handle and releases all its resources from the provided first handle cascadingly.

Since :
2.3
Remarks:
It also destroys ckmc_cert_s in ckmc_cert_list_s.
Parameters:
[in]firstThe first ckmc_cert_list_s handle to destroy
See also:
ckmc_cert_list_s

Destroys the ckmc_cert_list_s handle and releases resources of ckmc_cert_list_s from the provided first handle cascadingly.

Since :
2.4
Remarks:
It does not destroy ckmc_cert_s itself in ckmc_cert_list_s.
Parameters:
[in]firstThe first ckmc_cert_list_s handle to destroy
See also:
ckmc_cert_list_all_free()
ckmc_cert_list_s
int ckmc_cert_list_new ( ckmc_cert_s cert,
ckmc_cert_list_s **  ppalias_list 
)

Creates a new ckmc_cert_list_s handle and returns it. The cert pointer in the returned ckmc_cert_list_s handle points to the provided ckmc_cert_s and next is null.

Since :
2.4
Remarks:
You must destroy the newly created ckmc_cert_list_s by calling ckmc_cert_list_free() or ckmc_cert_list_all_free() if it is no longer needed.
Parameters:
[in]certThe first item to be set in the newly created ckmc_cert_list_s
[out]ppalias_listThe pointer to a newly created ckmc_alias_list_s handle
Returns:
CKMC_ERROR_NONE on success, otherwise a negative error value
Return values:
CKMC_ERROR_NONESuccessful
CKMC_ERROR_INVALID_PARAMETERInput parameter is invalid
CKMC_ERROR_OUT_OF_MEMORYNot enough memory
See also:
ckmc_cert_list_all_free()
ckmc_cert_list_s
int ckmc_cert_new ( unsigned char *  raw_cert,
size_t  cert_size,
ckmc_data_format_e  data_format,
ckmc_cert_s **  ppcert 
)

Creates a new ckmc_cert_s handle and returns it.

Since :
2.4
Remarks:
You must destroy the newly created ckmc_cert_s by calling ckmc_cert_free() if it is no longer needed.
Parameters:
[in]raw_certThe byte array of certificate
[in]cert_sizeThe byte size of raw_cert
[in]data_formatThe encoding format of raw_cert
[out]ppcertThe pointer to a newly created ckmc_cert_s handle
Returns:
CKMC_ERROR_NONE on success, otherwise a negative error value
Return values:
CKMC_ERROR_NONESuccessful
CKMC_ERROR_INVALID_PARAMETERInput parameter is invalid
CKMC_ERROR_OUT_OF_MEMORYNot enough memory
See also:
ckmc_cert_free()
ckmc_load_cert_from_file()
ckmc_cert_s

Generates algorithm parameters for a given algorithm type and set them to the list.

Since :
3.0
Remarks:
Caller is responsible for ckmc_param_list_h destruction.
Algorithm parameters are set to default values. Optional fields are left empty. Initialization vectors are left empty (they have to be set manually). Caller is responsible for freeing the list with ckmc_param_list_free().
If the function returns error, provided param list may contain some of default parameters.
Parameters:
[in]typeType of the algorithm
[out]pparamsNewly generated handle of param list which should be freed by caller after use
Returns:
CKMC_ERROR_NONE on success, otherwise a negative error value
Return values:
CKMC_ERROR_NONESuccessful
CKMC_ERROR_INVALID_PARAMETERInput parameter is invalid
See also:
ckmc_param_list_new()
ckmc_param_list_set_integer()
ckmc_param_list_set_buffer()
ckmc_param_list_get_integer()
ckmc_param_list_get_buffer()
ckmc_param_list_free()
ckmc_param_list_h
ckmc_param_name_e
ckmc_algo_type_e
void ckmc_key_free ( ckmc_key_s key)

Destroys the ckmc_key_s handle and releases all its resources.

Since :
2.3
Parameters:
[in]keyThe ckmc_key_s handle to destroy
int ckmc_key_new ( unsigned char *  raw_key,
size_t  key_size,
ckmc_key_type_e  key_type,
char *  password,
ckmc_key_s **  ppkey 
)

Creates a new ckmc_key_s handle and returns it.

Since :
2.4
Remarks:
You must destroy the newly created ckmc_key_s by calling ckmc_key_free() if it is no longer needed.
Parameters:
[in]raw_keyThe byte array of key
raw_key may be encrypted with password
[in]key_sizeThe byte size of raw_key
[in]key_typeThe raw_key's type
[in]passwordThe byte array used to decrypt raw_key inside key manager
If raw_key is not encrypted, password can be null
[out]ppkeyThe pointer to a newly created ckmc_key_s handle
Returns:
CKMC_ERROR_NONE on success, otherwise a negative error value
Return values:
CKMC_ERROR_NONESuccessful
CKMC_ERROR_INVALID_PARAMETERInput parameter is invalid
CKMC_ERROR_OUT_OF_MEMORYNot enough memory
See also:
ckmc_key_free()
ckmc_key_s
int ckmc_load_cert_from_file ( const char *  file_path,
ckmc_cert_s **  cert 
)

Creates a new ckmc_cert_s handle from a given file and returns it.

Since :
2.3
Remarks:
You must destroy the newly created ckmc_cert_s by calling ckmc_cert_free() if it is no longer needed.
Parameters:
[in]file_pathThe path of certificate file to be loaded
The only DER or PEM encoded certificate file is supported
[out]certThe pointer of newly created ckmc_cert_s handle
Returns:
CKMC_ERROR_NONE on success, otherwise a negative error value
Return values:
CKMC_ERROR_NONESuccessful
CKMC_ERROR_OUT_OF_MEMORYNot enough memory space
CKMC_ERROR_INVALID_FORMATInvalid certificate file format
CKMC_ERROR_FILE_ACCESS_DENIEDProvided file does not exist or cannot be accessed
See also:
ckmc_cert_free()
ckmc_cert_s
int ckmc_load_from_pkcs12_file ( const char *  file_path,
const char *  passphrase,
ckmc_key_s **  private_key,
ckmc_cert_s **  cert,
ckmc_cert_list_s **  ca_cert_list 
)

Creates a new ckmc_key_s (private_key), ckmc_cert_s (cert), and ckmc_cert_list_s (ca_cert_list) handle from a given PKCS#12 file and returns them.

Deprecated:
Deprecated since 2.4.[Use ckmc_pkcs12_load() instead]
Since :
2.3
Remarks:
You must destroy the newly created ckmc_key_s, ckmc_cert_s, and ckmc_cert_list_s by calling ckmc_key_free(), ckmc_cert_free(), and ckmc_cert_list_all_free() if they are no longer needed.
Parameters:
[in]file_pathThe path of PKCS12 file to be loaded
[in]passphraseThe passphrase used to decrypt the PCKS12 file
If PKCS12 file is not encrypted, passphrase can be null
[out]private_keyThe pointer of newly created ckmc_key_s handle for a private key
[out]certThe pointer of newly created ckmc_cert_s handle for a certificate
It is null if the PKCS12 file does not contain a certificate
[out]ca_cert_listThe pointer of newly created ckmc_cert_list_s handle for CA certificates
It is null if the PKCS12 file does not contain CA certificates
Returns:
CKMC_ERROR_NONE on success, otherwise a negative error value
Return values:
CKMC_ERROR_NONESuccessful
CKMC_ERROR_OUT_OF_MEMORYNot enough memory space
CKMC_ERROR_INVALID_FORMATInvalid PKCS12 file format
CKMC_ERROR_FILE_ACCESS_DENIEDProvided file does not exist or cannot be accessed
See also:
ckmc_pkcs12_new()
ckmc_pkcs12_load()
ckmc_key_free()
ckmc_cert_free()
ckmc_cert_list_all_free()
ckmc_key_s
ckmc_cert_s
ckmc_cert_list_s

Gets buffer parameter from the list.

Since :
3.0
Remarks:
Caller is responsible for ckmc_param_list_h creation.
Parameters:
[in]paramsAlgorithm param list handle created with ckmc_param_list_new() or ckmc_generate_new_params() which contains param with name
[in]nameName of parameter to get
[out]ppbufferValue of the parameter in form of a buffer
Caller is responsible for creating and freeing the buffer
Returns:
CKMC_ERROR_NONE on success, otherwise a negative error value
Return values:
CKMC_ERROR_NONESuccessful
CKMC_ERROR_INVALID_PARAMETERInput parameter is invalid
See also:
ckmc_param_list_new()
ckmc_param_list_set_integer()
ckmc_param_list_set_buffer()
ckmc_param_list_get_integer()
ckmc_param_list_free()
ckmc_generate_new_params()
ckmc_buffer_free()
ckmc_param_list_h
ckmc_param_name_e
ckmc_algo_type_e
int ckmc_param_list_get_integer ( ckmc_param_list_h  params,
ckmc_param_name_e  name,
uint64_t *  pvalue 
)

Gets integer parameter from the list.

Since :
3.0
Remarks:
Caller is responsible for ckmc_param_list_h creation.
Parameters:
[in]paramsAlgorithm param list handle created with ckmc_param_list_new() or ckmc_generate_new_params() which contains param with name
[in]nameName of parameter to get
[out]pvalueValue of the parameter in form of a integer
Returns:
CKMC_ERROR_NONE on success, otherwise a negative error value
Return values:
CKMC_ERROR_NONESuccessful
CKMC_ERROR_INVALID_PARAMETERInput parameter is invalid
See also:
ckmc_param_list_new()
ckmc_param_list_set_integer()
ckmc_param_list_set_buffer()
ckmc_param_list_get_buffer()
ckmc_param_list_free()
ckmc_generate_new_params()
ckmc_param_list_h
ckmc_param_name_e
ckmc_algo_type_e

Creates new parameter list.

Since :
3.0
Remarks:
Caller is responsible for freeing it with ckmc_param_list_free().
Parameters:
[in]pparamsDouble pointer to the handle of param list to which the newly created algorithm param list will be assigned
Returns:
CKMC_ERROR_NONE on success, otherwise a negative error value
Return values:
CKMC_ERROR_NONESuccessful
CKMC_ERROR_INVALID_PARAMETERInput parameter is invalid
See also:
ckmc_param_list_set_integer()
ckmc_param_list_set_buffer()
ckmc_param_list_free()
ckmc_generate_new_params()
ckmc_param_list_h
ckmc_param_name_e
ckmc_algo_type_e

Sets buffer parameter to the list.

Since :
3.0
Remarks:
Caller is responsible for ckmc_param_list_h creation.
Parameters:
[in]paramsAlgorithm param list handle created with ckmc_param_list_new() or ckmc_generate_new_params() New param with name and buffer will be set here
[in]nameName of parameter to set
Existing parameter will be overwritten
Passing invalid parameter name will result in an error
[in]bufferValue of the parameter in form of a buffer
Caller is responsible for creating and freeing the buffer
Returns:
CKMC_ERROR_NONE on success, otherwise a negative error value
Return values:
CKMC_ERROR_NONESuccessful
CKMC_ERROR_INVALID_PARAMETERInput parameter is invalid
See also:
ckmc_param_list_new()
ckmc_param_list_set_integer()
ckmc_param_list_get_integer()
ckmc_param_list_get_buffer()
ckmc_param_list_free()
ckmc_generate_new_params()
ckmc_param_list_h
ckmc_param_name_e
ckmc_algo_type_e
int ckmc_param_list_set_integer ( ckmc_param_list_h  params,
ckmc_param_name_e  name,
uint64_t  value 
)

Sets integer parameter to the list.

Since :
3.0
Remarks:
Caller is responsible for ckmc_param_list_h creation.
Parameters:
[in]paramsAlgorithm param list handle created with ckmc_param_list_new() or ckmc_generate_new_params()
New param with name and value will be set here
[in]nameName of parameter to set
Existing parameter will be overwritten
Passing invalid parameter name will result in an error
[in]valueValue of the parameter in form of a integer
Returns:
CKMC_ERROR_NONE on success, otherwise a negative error value
Return values:
CKMC_ERROR_NONESuccessful
CKMC_ERROR_INVALID_PARAMETERInput parameter is invalid
See also:
ckmc_param_list_new()
ckmc_param_list_set_buffer()
ckmc_param_list_get_integer()
ckmc_param_list_get_buffer()
ckmc_param_list_free()
ckmc_generate_new_params()
ckmc_param_list_h
ckmc_param_name_e
ckmc_algo_type_e
void ckmc_pkcs12_free ( ckmc_pkcs12_s pkcs12)

Destroys the ckmc_pkcs12_s handle and releases all its resources.

Since :
2.4
Parameters:
[in]pkcs12The ckmc_pkcs12_s handle to destroy
See also:
ckmc_pkcs12_new()
ckmc_pkcs12_load()
int ckmc_pkcs12_load ( const char *  file_path,
const char *  passphrase,
ckmc_pkcs12_s **  pkcs12_bundle 
)

Creates a new ckmc_pkcs12_s handle from a given PKCS#12 file and returns it.

Since :
2.4
Remarks:
You must destroy the newly created ckmc_pkcs12_s by calling ckmc_pkcs12_free() if they are no longer needed.
Parameters:
[in]file_pathThe path of PKCS12 file to be loaded
[in]passphraseThe passphrase used to decrypt the PCKS12 file
If PKCS12 file is not encrypted, passphrase can be null
[out]pkcs12_bundleThe pointer of newly created ckmc_cert_list_s handle for CA certificates
It is null if the PKCS12 file does not contain CA certificates
Returns:
CKMC_ERROR_NONE on success, otherwise a negative error value
Return values:
CKMC_ERROR_NONESuccessful
CKMC_ERROR_OUT_OF_MEMORYNot enough memory space
CKMC_ERROR_INVALID_FORMATInvalid PKCS12 file format
CKMC_ERROR_FILE_ACCESS_DENIEDProvided file does not exist or cannot be accessed
See also:
ckmc_pkcs12_free()
ckmc_pkcs12_s
int ckmc_pkcs12_new ( ckmc_key_s private_key,
ckmc_cert_s cert,
ckmc_cert_list_s ca_cert_list,
ckmc_pkcs12_s **  pkcs12_bundle 
)

Creates a new ckmc_pkcs12_s handle and returns it.

Since :
2.4
Remarks:
You must destroy the newly created ckmc_pkcs12_s by calling ckmc_pkcs12_free() if it is no longer needed.
On success, private_key, cert && ca_cert_list ownership is transferred into newly returned ckmc_pkcs12_s.
Parameters:
[in]private_keyckmc_key_s handle to the private key (optional)
[in]certckmc_cert_s handle to the certificate (optional)
[in]ca_cert_listckmc_cert_list_s list of chain certificate handles (optional)
[out]pkcs12_bundleThe pointer to a newly created ckmc_pkcs12_s handle
Returns:
CKMC_ERROR_NONE on success, otherwise a negative error value
Return values:
CKMC_ERROR_NONESuccessful
CKMC_ERROR_INVALID_PARAMETERInput parameter is invalid or private_key, cert and ca_cert_list all are null
CKMC_ERROR_OUT_OF_MEMORYNot enough memory
See also:
ckmc_pkcs12_free()
ckmc_pkcs12_load()
ckmc_key_s
ckmc_cert_s
ckmc_cert_list_s
ckmc_pkcs12_s

Variable Documentation

char const* const ckmc_label_name_separator

Separator between alias and label.

Deprecated:
Deprecated since 3.0. [Use ckmc_owner_id_separator instead]
Since :
2.3
Remarks:
Alias can be provided as an alias alone, or together with label - in this case, separator " " (space bar) is used to separate label and alias.
See also:
ckmc_owner_id_separator
char const* const ckmc_owner_id_separator

Separator between alias and owner id.

Since :
3.0
Remarks:
Alias can be provided as an alias alone, or together with owner id. In this case, separator " " (space bar) is used to separate id and alias.
See also:
ckmc_alias_new()
char const* const ckmc_owner_id_system

The owner of system database.

Since :
3.0
Remarks:
ckmc_owner_id_system contains id connected with all system applications that run with uid less than 5000. Client should use ckmc_owner_id_system to access data owned by system application and stored in system database. Client must have permission to access proper row.
See also:
ckmc_alias_new()