* @defgroup CAPI_KEY_MANAGER_MODULE Key Manager
* @brief The key manager provides a secure repository protected by Tizen platform for keys, certificates, and sensitive data of users and/or their APPs.
* Additionally, the key manager provides secure cryptographic operations for non-exportable keys without revealing key values to clients.
+ * Since Tizen 5.0 on chosen system images, module may use ARM TrustZone technology and may rely on particular TEE (Trusted Execution Environment) implementation.
* @section CAPI_KEY_MANAGER_MODULE_OVERVIEW Overview
* <table>
* <tr><th>API</th><th>Description</th></tr>
* - The client can specify only its own package id in the alias when storing a key, certificate, or data.
* - A client should specify the package id of the owner in the alias to retrieve a a key, certificate, or data shared by other applications.
* - Aliases are returned as the format of "package_id name" from the key-manager.
+ * Supported features
+ * Since Tizen 5.0 on chosen images, the realization of module functionality can be implemened using ARM TrustZone technology.
+ * Differences in standards governing TrustZone implementation and previous software-based implementation cause following differences in module operation:
+ * - When using TrustZone-based backend, GCM modes with 32 and 64 bit tag lengths are not supported.
+ * Global Platform TEE specification treats these configurations as unsafe and not supported.
+ * - When using TrustZone-based backend, passing big amounts of data (encryption/decryption) to the module has additional size restriction.
+ * Now it depends on the TEEC_CONFIG_SHAREDMEM_MAX_SIZE definition, specific for given TEE implementation, minus size of key-information needed to be passed to TEE.
+ * Minimum supported value for passing data to the module is at 500 kB.
*/
const Label &accessor,
PermissionMask permissionMask);
+ // This function will encrypt data.
+ // Since Tizen 5.0, on chosen images using TEE backend:
+ // * maximum size of data can be limited to TEE-specific value; minimum 500 kB is supported)
+ // * GCM modes with short tags (32 and 64 bits) are not supported
+ // In these cases, key-manager can return a CKM_API_ERROR_SERVER_ERROR
void encrypt(
const ObserverPtr &observer,
const CryptoAlgorithm &algo,
const Password &password,
const RawBuffer &plain);
+ // This function will decrypt data.
+ // Since Tizen 5.0, on chosen images using TEE backend:
+ // * maximum size of data can be limited to TEE-specific value; minimum 500 kB is supported)
+ // * GCM modes with short tags (32 and 64 bits) are not supported
+ // In these cases, key-manager can return a CKM_API_ERROR_SERVER_ERROR
void decrypt(
const ObserverPtr &observer,
const CryptoAlgorithm &algo,
int setPermission(const Alias &alias, const Label &accessor,
PermissionMask permissionMask);
+ // This function will encrypt data.
+ // Since Tizen 5.0, on chosen images using TEE backend:
+ // * maximum size of data can be limited to TEE-specific value; minimum 500 kB is supported)
+ // * GCM modes with short tags (32 and 64 bits) are not supported
+ // In these cases, key-manager can return a CKM_API_ERROR_SERVER_ERROR
int encrypt(const CryptoAlgorithm &algo,
const Alias &keyAlias,
const Password &password,
const RawBuffer &plain,
RawBuffer &encrypted);
+ // This function will decrypt data.
+ // Since Tizen 5.0, on chosen images using TEE backend:
+ // * maximum size of data can be limited to TEE-specific value; minimum 500 kB is supported)
+ // * GCM modes with short tags (32 and 64 bits) are not supported
+ // In these cases, key-manager can return a CKM_API_ERROR_SERVER_ERROR
int decrypt(const CryptoAlgorithm &algo,
const Alias &keyAlias,
const Password &password,
* @param[in] password The password used in decrypting a key value \n
* If password of the policy is provided in ckmc_save_key(), the same
* password should be provided
- * @param[in] decrypted Data to be encrypted. In case of AES algorithm there are no restrictions on the size of data.
+ * @param[in] decrypted Data to be encrypted. In case of AES algorithm there are no restrictions on the size of data,
+ * if S/W backend is used. If module uses TEE backend (since Tizen 5.0 on chosen images),
+ * maximum size of data is implementation-specific and at least 500 kB.
* For RSA the size must be smaller or equal to key size in bytes - 42.
- * Example: for 1024 RSA key the maximum data size is 1024/8 - 42 = 86
+ * Example: for 1024 RSA key the maximum data size is 1024/8 - 42 = 86.
* @param[out] ppencrypted Encrypted data (some algorithms may return additional information embedded in encrypted data.
* AES GCM is an example) \n
* The caller is responsible for freeing @a encrypted with ckmc_buffer_free()
* @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Key with given alias does not exist
* @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
* @retval #CKMC_ERROR_AUTHENTICATION_FAILED Key decryption failed because password is incorrect
+ * @retval #CKMC_ERROR_SERVER_ERROR Too big data size or unsupported GCM mode (32 and 64 bit tag lengths not supported on TEE backend) or internal error
* @pre User is already logged in and the user key is already loaded into memory in plain text form.
* @see ckmc_buffer_free()
* @see ckmc_param_list_new()
* @param[in] password The password used in decrypting a key value \n
* If password of the policy is provided in ckmc_save_key(), the same password should be provided
* @param[in] encrypted Data to be decrypted (some algorithms may require additional information embedded in encrypted data. AES GCM is an example)
+ * Since Tizen 5.0, on chosen images where module is using TEE backend, data size is limited to at least 500 kB
+ * (TEE implementation-specific).
* @param[out] ppdecrypted Decrypted data \n
* The caller is responsible for freeing @a decrypted with ckmc_buffer_free()
* @return @c 0 on success,
* @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN Key with given alias does not exist
* @retval #CKMC_ERROR_PERMISSION_DENIED Failed to access key manager
* @retval #CKMC_ERROR_AUTHENTICATION_FAILED Key decryption failed because password is incorrect
+ * @retval #CKMC_ERROR_SERVER_ERROR Too big data size or unsupported GCM mode (32 and 64 bit tag lengths not supported on TEE backend) or internal error
* @pre User is already logged in and the user key is already loaded into memory in plain text form.
* @see ckmc_buffer_free()
* @see ckmc_param_list_new()
- 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)
+ 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