From 733f084dca9bafa67af48aa9e287e1f8d600bb2c Mon Sep 17 00:00:00 2001 From: Krzysztof Jackiewicz Date: Wed, 26 Apr 2023 12:17:14 +0200 Subject: [PATCH] Multi-stage encryption API Change-Id: If56a367a40f1ca3a6d4dcebfbb38543c7ec44fd5 --- src/include/ckmc/ckmc-manager.h | 114 +++++++++++++++++++++++++++++++++++++++- src/include/ckmc/ckmc-type.h | 10 ++++ 2 files changed, 123 insertions(+), 1 deletion(-) diff --git a/src/include/ckmc/ckmc-manager.h b/src/include/ckmc/ckmc-manager.h index 686d939..07d5305 100644 --- a/src/include/ckmc/ckmc-manager.h +++ b/src/include/ckmc/ckmc-manager.h @@ -1244,7 +1244,7 @@ int ckmc_export_wrapped_key(const ckmc_param_list_h params, * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a secret_alias does not exist * @retval #CKMC_ERROR_DB_ALIAS_EXISTS @a new_key_alias already exists * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error - * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Secret decryption failed because @a secret_password is + * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Secret decryption failed because @a secret_password is * incorrect * @retval #CKMC_ERROR_SERVER_ERROR Unknown error * @@ -1262,6 +1262,118 @@ int ckmc_key_derive(const ckmc_param_list_h params, const char *new_key_alias, ckmc_policy_s new_key_policy); +/** + * @brief Sets up a symmetric encryption or decryption context with given key and parameters. + * + * @since_tizen 6.5 + * + * @remarks The newly created @a context must be destroyed using ckmc_cipher_free() when it's no + * longer needed. + * @remarks To perform the encryption/decryption, one or more calls to ckmc_cipher_update() must be + * folowed by one call to ckmc_cipher_finalize(). + * + * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e + * for details. Supported algorithms: + * - #CKMC_ALGO_AES_GCM, + * @param[in] key_alias Alias of the key to be used for encryption/decryption + * @param[in] key_password Optional password of the key used for encryption/decryption + * @param[in] encrypt Encryption/decryption switch (true=encryption, false=decryption) + * @param[out] context Encryption/decryption context + * + * @return @c 0 on success, otherwise a negative error value + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_PERMISSION_DENIED Insufficient permissions to access key manager or the key + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (missing or invalid mandatory + * algorithm parameter, @a key_alias = NULL, + * @a context = NULL) + * @retval #CKMC_ERROR_DB_LOCKED A user key is not loaded in memory (a user is not logged in) + * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN @a key_alias does not exist + * @retval #CKMC_ERROR_DB_ERROR Failed due to a database error + * @retval #CKMC_ERROR_AUTHENTICATION_FAILED Key decryption failed because @a key_password is + * incorrect + * @retval #CKMC_ERROR_SERVER_ERROR Unknown error + * + * @pre User is already logged in and the user key is already loaded into memory in plain text form. + * + * @see #ckmc_cipher_ctx_h + * @see ckmc_cipher_update() + * @see ckmc_cipher_finalize() + * @see ckmc_cipher_free() + */ +int ckmc_cipher_initialize(ckmc_param_list_h params, + const char *key_alias, + const char *key_password, + bool encrypt, + ckmc_cipher_ctx_h *context); + +/** + * @brief Performs symmetric encryption or decryption of the input and places the result in the + * output. + * + * @since_tizen 6.5 + * + * @remarks The function may be called multiple times to encrypt succcessive blocks of data. + * @remarks The newly created @a ppout must be destroyed using ckmc_buffer_free() when it's no + * longer needed. + * + * @param[in] context Encryption/decryption context created with ckmc_cipher_initialize() + * @param[in] in Encryption/decryption input + * @param[out] ppout Encryption/decryption output + * + * @return @c 0 on success, otherwise a negative error value + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (@a context = NULL, + * @a ppout = NULL) + * @retval #CKMC_ERROR_SERVER_ERROR Unknown error + * + * @see #ckmc_cipher_ctx_h + * @see ckmc_cipher_initialize() + * @see ckmc_cipher_finalize() + * @see ckmc_cipher_free() + */ +int ckmc_cipher_update(ckmc_cipher_ctx_h context, + const ckmc_raw_buffer_s in, + ckmc_raw_buffer_s **ppout); + +/** + * @brief Finalizes symmetric encryption or decryption and returns remaining output if any. + * + * @since_tizen 6.5 + * + * @remarks After the call to this function the ckmc_cipher_update() can be called no more. + * @remarks The newly created @a ppout must be destroyed using ckmc_buffer_free() when it's no + * longer needed. + * + * @param[in] context Encryption/decryption context created with ckmc_cipher_initialize() + * @param[out] ppout Encryption/decryption output + * + * @return @c 0 on success, otherwise a negative error value + * @retval #CKMC_ERROR_NONE Successful + * @retval #CKMC_ERROR_INVALID_PARAMETER Input parameter is invalid (@a context = NULL, + * @a ppout = NULL) + * @retval #CKMC_ERROR_SERVER_ERROR Unknown error + * + * @see #ckmc_cipher_ctx_h + * @see ckmc_cipher_initialize() + * @see ckmc_cipher_update() + * @see ckmc_cipher_free() + */ +int ckmc_cipher_finalize(ckmc_cipher_ctx_h context, ckmc_raw_buffer_s **ppout); + +/** + * @brief Destroys the encryption/decryption context and releases all its resources. + * + * @since_tizen 6.5 + * + * @param[in] context Encryption/decryption context created with ckmc_cipher_initialize() + * + * @see #ckmc_cipher_ctx_h + * @see ckmc_cipher_initialize() + * @see ckmc_cipher_update() + * @see ckmc_cipher_finalize() + */ +void ckmc_cipher_free(ckmc_cipher_ctx_h context); + #ifdef __cplusplus } #endif diff --git a/src/include/ckmc/ckmc-type.h b/src/include/ckmc/ckmc-type.h index e568655..8897712 100644 --- a/src/include/ckmc/ckmc-type.h +++ b/src/include/ckmc/ckmc-type.h @@ -462,6 +462,16 @@ typedef enum __ckmc_algo_type { } ckmc_algo_type_e; /** + * @brief Encryption/decryption context handle. + * @since_tizen 6.5 + * @see ckmc_cipher_initialize() + * @see ckmc_cipher_update() + * @see ckmc_cipher_finalize() + * @see ckmc_cipher_free() + */ +typedef struct __ckmc_cipher_ctx *ckmc_cipher_ctx_h; + +/** * @brief Gets the alias from #ckmc_alias_info_s structure. * @since_tizen 5.5 * @remarks The @a alias should not be released. -- 2.7.4