Multi-stage encryption API

Change-Id: If56a367a40f1ca3a6d4dcebfbb38543c7ec44fd5

diff --git a/src/include/ckmc/ckmc-manager.h b/src/include/ckmc/ckmc-manager.h
index 686d939..07d5305 100644 (file)
--- 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 (file)
--- 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.