It provides APIs that allow access to extended key manager functionality.

Required Header

#include <ckmc/ckmc-extended.h>

Overview

It provides APIs for extended functionality including concatenated data wrapping and unwrapping

Functions
int	ckmc_wrap_concatenated_data (const ckmc_param_list_h params, const char wrapping_key_alias, const char wrapping_key_password, const char alias, const char password, const ckmc_raw_buffer_s data, ckmc_key_s *ppwrapped_key)
	Wraps concatenated key and data (key\|data) with wrapping key and returns it to the client.
int	ckmc_unwrap_concatenated_data (const ckmc_param_list_h params, const char wrapping_key_alias, const char wrapping_key_password, const ckmc_key_s wrapped_key, const char alias, size_t size, const ckmc_policy_s policy, ckmc_raw_buffer_s **ppdata)
	Unwraps concatenated key and data (key\|data) with wrapping key. Splits to key (stored inside key manager) and data (returned to the client).
int	ckmc_create_key_pair_kem (const ckmc_kem_type_e kem_type, const char private_key_alias, const char public_key_alias, const ckmc_policy_s policy_private_key, const ckmc_policy_s policy_public_key)
	Creates private/public key pair based on Key-Encapsulation Mechanism (KEM) type and stores them inside key manager based on each policy.
int	ckmc_encapsulate_key (const ckmc_param_list_h params, const char public_key_alias, const char public_key_password, const char shared_secret_alias, const ckmc_policy_s shared_secret_policy, ckmc_raw_buffer_s *ppciphertext)
	Generates a random shared secret, encapsulates it using a public KEM key and produces a ciphertext. The ciphertext is returned and the shared secret is stored inside key manager using the shared secret alias and the policy provided.
int	ckmc_decapsulate_key (const ckmc_param_list_h params, const char private_key_alias, const char private_key_password, const char shared_secret_alias, const ckmc_policy_s shared_secret_policy, const ckmc_raw_buffer_s ciphertext)
	Decapsulates the shared secret from the ciphertext and KEM type private key. The shared secret is stored inside key manager using the shared secret alias and the policy provided.
int	ckmc_key_derive_hybrid (const ckmc_param_list_h params, const char first_secret_alias, const char first_secret_password, const char second_secret_alias, const char second_secret_password, const char *new_key_alias, const ckmc_policy_s new_key_policy)
	Derives a new key from another two concatenated keys/secrets (first\|second) with a given algorithm and stores it inside key manager using a new key alias and policy.

Function Documentation

int ckmc_create_key_pair_kem	(	const ckmc_kem_type_e	kem_type,
		const char *	private_key_alias,
		const char *	public_key_alias,
		const ckmc_policy_s	policy_private_key,
		const ckmc_policy_s	policy_public_key
	)

Creates private/public key pair based on Key-Encapsulation Mechanism (KEM) type and stores them inside key manager based on each policy.

Warning:: This is not for use by third-party applications.

Since :: 7.0

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/keymanager.extended

Remarks:: If password in policy_private_key or policy_public_key is provided, the stored key is additionally encrypted with it.; Currently supported KEM types are: CKMC_ML_KEM_768, CKMC_ML_KEM_1024.

Parameters:

[in]	kem_type	The type of KEM key to be created
[in]	private_key_alias	The name of private key to be stored
[in]	public_key_alias	The name of public key to be stored
[in]	policy_private_key	Private key storing policy
[in]	policy_public_key	Public key storing policy

Returns:: 0 on success, otherwise a negative error value

Return values:

CKMC_ERROR_NONE	Successful
CKMC_ERROR_PERMISSION_DENIED	Failed to access key manager
CKMC_ERROR_INVALID_PARAMETER	Input parameter is invalid (missing or invalid mandatory algorithm parameter, private_key_alias = NULL, public_key_alias = NULL)
CKMC_ERROR_DB_LOCKED	A user key is not loaded in memory (a user is not logged in)
CKMC_ERROR_DB_ALIAS_EXISTS	Alias already exists
CKMC_ERROR_DB_ERROR	Failed due to a database error
CKMC_ERROR_SERVER_ERROR	Unknown error

Precondition:: User is already logged in and the user key is already loaded into memory in plain text form.

See also:: ckmc_encapsulate_key(); ckmc_decapsulate_key(); ckmc_kem_type_e; ckmc_policy_s

int ckmc_decapsulate_key	(	const ckmc_param_list_h	params,
		const char *	private_key_alias,
		const char *	private_key_password,
		const char *	shared_secret_alias,
		const ckmc_policy_s	shared_secret_policy,
		const ckmc_raw_buffer_s *	ciphertext
	)

Decapsulates the shared secret from the ciphertext and KEM type private key. The shared secret is stored inside key manager using the shared secret alias and the policy provided.

Warning:: This is not for use by third-party applications.

Since :: 7.0

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/keymanager.extended

Remarks:: The key used for decapsulation must be private KEM type key (CKMC_KEY_KEM_PRIVATE).; The KEM type used in key pair creation and encapsulation/decapsulation must be the same.; The supported format of the shared secret is a 32-byte CKMC_KEY_AES key.; If policy contains password when storing a private key, the same password should be provided.; If password in shared_secret_policy is provided, the stored key is additionally encrypted with it.

Parameters:

[in]	params	Algorithm parameter list handle. See ckmc_param_list_h and ckmc_algo_type_e for details. Supported algorithms: CKMC_ALGO_KEM
[in]	private_key_alias	Alias of the private KEM type key to be used for decapsulation
[in]	private_key_password	An optional password used in decrypting a key value
[in]	shared_secret_alias	Alias to store the shared secret
[in]	shared_secret_policy	Shared secret storing policy
[in]	ciphertext	Ciphertext

Returns:: 0 on success, otherwise a negative error value

Return values:

CKMC_ERROR_NONE	Successful
CKMC_ERROR_PERMISSION_DENIED	Insufficient permissions to access key manager
CKMC_ERROR_INVALID_PARAMETER	Input parameter is invalid (missing or invalid mandatory algorithm parameter, private_key_alias = NULL, shared_secret_alias = NULL, ciphertext = NULL)
CKMC_ERROR_DB_LOCKED	A user key is not loaded in memory (a user is not logged in)
CKMC_ERROR_DB_ERROR	Failed due to a database error
CKMC_ERROR_DB_ALIAS_UNKNOWN	private_key_alias does not exist
CKMC_ERROR_DB_ALIAS_EXISTS	shared_secret_alias already exist
CKMC_ERROR_AUTHENTICATION_FAILED	Private key decryption failed because private_key_password is incorrect
CKMC_ERROR_SERVER_ERROR	Unknown error

Precondition:: User is already logged in and the user key is already loaded into memory in plain text form.

See also:: ckmc_create_key_pair_kem(); ckmc_encapsulate_key(); ckmc_key_derive_hybrid(); ckmc_param_list_h; ckmc_policy_s; ckmc_raw_buffer_s

int ckmc_encapsulate_key	(	const ckmc_param_list_h	params,
		const char *	public_key_alias,
		const char *	public_key_password,
		const char *	shared_secret_alias,
		const ckmc_policy_s	shared_secret_policy,
		ckmc_raw_buffer_s **	ppciphertext
	)

Generates a random shared secret, encapsulates it using a public KEM key and produces a ciphertext. The ciphertext is returned and the shared secret is stored inside key manager using the shared secret alias and the policy provided.

Warning:: This is not for use by third-party applications.

Since :: 7.0

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/keymanager.extended

Remarks:: The key used for encapsulation must be public KEM type key (CKMC_KEY_KEM_PUBLIC).; The KEM type used in key pair creation and encapsulation/decapsulation must be the same.; The supported format of the shared secret is a 32-byte CKMC_KEY_AES key.; If policy contains password when storing a public key, the same password should be provided.; If password in shared_secret_policy is provided, the stored key is additionally encrypted with it.; The ppciphertext should be released using ckmc_buffer_free().

Parameters:

[in]	params	Algorithm parameter list handle. See ckmc_param_list_h and ckmc_algo_type_e for details. Supported algorithms: CKMC_ALGO_KEM
[in]	public_key_alias	Alias of the public KEM type key to be used for encapsulation
[in]	public_key_password	An optional password used in decrypting a key value
[in]	shared_secret_alias	Alias to store the shared secret
[in]	shared_secret_policy	Shared secret storing policy
[out]	ppciphertext	Ciphertext

Returns:: 0 on success, otherwise a negative error value

Return values:

CKMC_ERROR_NONE	Successful
CKMC_ERROR_PERMISSION_DENIED	Insufficient permissions to access key manager
CKMC_ERROR_INVALID_PARAMETER	Input parameter is invalid (missing or invalid mandatory algorithm parameter, public_key_alias = NULL, shared_secret_alias = NULL)
CKMC_ERROR_DB_LOCKED	A user key is not loaded in memory (a user is not logged in)
CKMC_ERROR_DB_ERROR	Failed due to a database error
CKMC_ERROR_DB_ALIAS_UNKNOWN	public_key_alias does not exist
CKMC_ERROR_DB_ALIAS_EXISTS	shared_secret_alias already exist
CKMC_ERROR_AUTHENTICATION_FAILED	Public key decryption failed because public_key_password is incorrect
CKMC_ERROR_SERVER_ERROR	Unknown error

Precondition:: User is already logged in and the user key is already loaded into memory in plain text form.

 ckmc_param_list_h params;               // Initialized elsewhere
 ckmc_policy_s shared_secret_policy;     // Initialized elsewhere
 ckmc_raw_buffer_s *ppciphertext;
 int ret = ckmc_encapsulate_key(params,
                                "public_key_alias",
                                "public_key_password",
                                "shared_secret_alias",
                                shared_secret_policy,
                                &ppciphertext);
  ...
 ckmc_buffer_free(ppciphertext);

See also:: ckmc_create_key_pair_kem(); ckmc_decapsulate_key(); ckmc_key_derive_hybrid(); ckmc_param_list_h; ckmc_policy_s; ckmc_raw_buffer_s

int ckmc_key_derive_hybrid	(	const ckmc_param_list_h	params,
		const char *	first_secret_alias,
		const char *	first_secret_password,
		const char *	second_secret_alias,
		const char *	second_secret_password,
		const char *	new_key_alias,
		const ckmc_policy_s	new_key_policy
	)

Derives a new key from another two concatenated keys/secrets (first|second) with a given algorithm and stores it inside key manager using a new key alias and policy.

Warning:: This is not for use by third-party applications.

Since :: 7.0

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/keymanager.extended

Remarks:: The key/secret, pointed to by first_secret_alias and second_secret_alias must be a binary data or a symmetric key (CKMC_KEY_AES).; The derived key pointed to by new_key_alias will be a symmetric one. It will be stored as a CKMC_KEY_AES.; In this method, AES-type keys can be hybridized with KEM-type secrets derived from encapsulation/decapsulation methods.; If policy contains password when storing a key/secret, the same password should be provided.; If password in new_key_policy is provided, the stored key is additionally encrypted with it.

Parameters:

[in]	params	Algorithm parameter list handle. See ckmc_param_list_h and ckmc_algo_type_e for details. Supported algorithms: CKMC_ALGO_KBKDF
[in]	first_secret_alias	Alias of the first key/secret to use as an input
[in]	first_secret_password	Optional password of the first key/secret used as an input
[in]	second_secret_alias	Alias of the second key/secret to use as an input
[in]	second_secret_password	Optional password of the second key/secret used as an input
[in]	new_key_alias	Alias to store the new derived key/secret
[in]	new_key_policy	Policy used to store the new derived key/secret

Returns:: 0 on success, otherwise a negative error value

Return values:

CKMC_ERROR_NONE	Successful
CKMC_ERROR_PERMISSION_DENIED	Insufficient permissions to access key manager
CKMC_ERROR_INVALID_PARAMETER	Input parameter is invalid (missing or invalid mandatory algorithm parameter, first_secret_alias = NULL, second_secret_alias = NULL, new_key_alias = NULL)
CKMC_ERROR_DB_LOCKED	A user key is not loaded in memory (a user is not logged in)
CKMC_ERROR_DB_ERROR	Failed due to a database error
CKMC_ERROR_DB_ALIAS_UNKNOWN	first_secret_alias or second_secret_alias does not exist
CKMC_ERROR_DB_ALIAS_EXISTS	new_key_alias already exist
CKMC_ERROR_AUTHENTICATION_FAILED	Key decryption failed because first_secret_password or second_secret_password is incorrect
CKMC_ERROR_SERVER_ERROR	Unknown error

Precondition:: User is already logged in and the user key is already loaded into memory in plain text form.

See also:: ckmc_create_key_pair_kem(); ckmc_encapsulate_key(); ckmc_decapsulate_key(); ckmc_param_list_h; ckmc_policy_s

int ckmc_unwrap_concatenated_data	(	const ckmc_param_list_h	params,
		const char *	wrapping_key_alias,
		const char *	wrapping_key_password,
		const ckmc_key_s *	wrapped_key,
		const char *	alias,
		size_t	size,
		const ckmc_policy_s	policy,
		ckmc_raw_buffer_s **	ppdata
	)

Unwraps concatenated key and data (key|data) with wrapping key. Splits to key (stored inside key manager) and data (returned to the client).

Warning:: This is not for use by third-party applications.

Since :: 7.0

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/keymanager.extended

Remarks:: The wrapping key must be private RSA (CKMC_KEY_RSA_PRIVATE).; key_type in wrapped_key can only be CKMC_KEY_AES.; password in wrapped_key must be set to NULL. There's no need to additionally encrypt a wrapped key.; The key denoted by alias can only be CKMC_KEY_AES.; If password in policy is provided, the stored key is additionally encrypted with it.; If extractable in policy is set to false, the stored key may still be exported in a wrapped form.; The supported size for the key to be stored is 128, 192 and 256 bits.; The ppdata should be released using ckmc_buffer_free().

Parameters:

[in]	params	Algorithm parameter list handle. See ckmc_param_list_h and ckmc_algo_type_e for details. Supported algorithms: CKMC_ALGO_RSA_OAEP
[in]	wrapping_key_alias	The name of the wrapping key
[in]	wrapping_key_password	An optional password of the wrapping key
[in]	wrapped_key	The wrapped key to be unwrapped, split and stored
[in]	alias	The name of a key to be stored
[in]	size	The size in bits of the key to be stored
[in]	policy	The policy about how to store a key securely
[out]	ppdata	The unwrapped data.

Returns:: 0 on success, otherwise a negative error value

Return values:

CKMC_ERROR_NONE	Successful
CKMC_ERROR_PERMISSION_DENIED	Insufficient permissions to access key manager, the wrapping key or to create the unwrapped key
CKMC_ERROR_INVALID_PARAMETER	Input parameter is invalid (missing or invalid mandatory algorithm parameter or invalid key size, wrapping_key_alias = NULL, wrapped_key = NULL, alias = NULL, ppdata = NULL)
CKMC_ERROR_DB_LOCKED	A user key is not loaded in memory (a user is not logged in)
CKMC_ERROR_DB_ALIAS_UNKNOWN	wrapping_key_alias does not exist
CKMC_ERROR_DB_ALIAS_EXISTS	alias already exists
CKMC_ERROR_INVALID_FORMAT	The format of wrapped_key is not valid
CKMC_ERROR_DB_ERROR	Failed due to a database error
CKMC_ERROR_AUTHENTICATION_FAILED	Wrapping key decryption failed because wrapping_key_password is incorrect
CKMC_ERROR_SERVER_ERROR	Unknown error

Precondition:: User is already logged in and the user key is already loaded into memory in plain text form.

 ckmc_param_list_h params;    // Initialized elsewhere
 ckmc_key_s *wrapped_key;     // Initialized elsewhere
 ckmc_policy_s policy;        // Initialized elsewhere
 ckmc_raw_buffer_s *ppdata;
 int ret = ckmc_unwrap_concatenated_data(params,
                                         "wrapping_key_alias",
                                         "wrapping_key_password",
                                         wrapped_key,
                                         "alias",
                                         192,
                                         policy,
                                         &ppdata);
  ...
 ckmc_buffer_free(ppdata);

See also:: ckmc_wrap_concatenated_data(); ckmc_param_list_h; ckmc_key_s; ckmc_policy_s; ckmc_raw_buffer_s

int ckmc_wrap_concatenated_data	(	const ckmc_param_list_h	params,
		const char *	wrapping_key_alias,
		const char *	wrapping_key_password,
		const char *	alias,
		const char *	password,
		const ckmc_raw_buffer_s *	data,
		ckmc_key_s **	ppwrapped_key
	)

Wraps concatenated key and data (key|data) with wrapping key and returns it to the client.

Warning:: This is not for use by third-party applications.

Since :: 7.0

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/keymanager.extended

Remarks:: The wrapping key must be public RSA (CKMC_KEY_RSA_PUBLIC).; The key denoted by alias can only be CKMC_KEY_AES.; The key and the wrapping key must be stored in the same backend.; The data size must be smaller or equal to: wrapping key size in bytes - key size in bytes - 2 * hash function output size in bytes - 2. Example: for 3072 RSA wrapping key, 256 AES key and hash SHA384 the maximum data size is: 3072/8 - 256/8 - 2*384/8 - 2 = 254 bytes.; Considering the data size limit it's recommended to use RSA key longer than 1024 bits.; The ppwrapped_key should be released using ckmc_key_free().

Parameters:

[in]	params	Algorithm parameter list handle. See ckmc_param_list_h and ckmc_algo_type_e for details. Supported algorithms: CKMC_ALGO_RSA_OAEP
[in]	wrapping_key_alias	The name of the wrapping key
[in]	wrapping_key_password	An optional password of the wrapping key
[in]	alias	The name of the key to be concatenated, wrapped and exported
[in]	password	An optional password used to decrypt the key pointed by alias
[in]	data	Data to be concatenated, wrapped and exported
[out]	ppwrapped_key	The wrapped key.

Returns:: 0 on success, otherwise a negative error value

Return values:

CKMC_ERROR_NONE	Successful
CKMC_ERROR_PERMISSION_DENIED	Insufficient permissions to access key manager, the wrapping key or the key being wrapped
CKMC_ERROR_INVALID_PARAMETER	Input parameter is invalid (missing or invalid mandatory algorithm parameter or data too long, wrapping_key_alias = NULL, alias = NULL, data = NULL, ppwrapped_key = NULL)
CKMC_ERROR_DB_LOCKED	A user key is not loaded in memory (a user is not logged in)
CKMC_ERROR_DB_ALIAS_UNKNOWN	wrapping_key_alias or alias does not exist
CKMC_ERROR_DB_ERROR	Failed due to a database error
CKMC_ERROR_AUTHENTICATION_FAILED	Wrapping key decryption failed because wrapping_key_password is incorrect
CKMC_ERROR_SERVER_ERROR	Unknown error

Precondition:: User is already logged in and the user key is already loaded into memory in plain text form.

 ckmc_param_list_h params;    // Initialized elsewhere
 ckmc_raw_buffer_s *data;     // Initialized elsewhere
 ckmc_key_s *ppwrapped_key;
 int ret = ckmc_wrap_concatenated_data(params,
                                       "wrapping_key_alias",
                                       "wrapping_key_password",
                                       "alias",
                                       "password",
                                       data,
                                       &ppwrapped_key);
  ...
 ckmc_key_free(ppwrapped_key);

See also:: ckmc_unwrap_concatenated_data(); ckmc_param_list_h; ckmc_raw_buffer_s; ckmc_key_s

Required Header

Overview

Functions

Function Documentation