Improve AAD and GCM tag handling in cipher API

* AAD may also be a subject of backend chunk size limitation. Allow
  calling ckmc_cipher_init multiple time do provide consecutive AAD
  portions.
* When encrypted data is split in to chunks there's no way to locate
  the trailing GCM tag part. Add optional buffer argument to
  ckmc_cipher_finalize() to allow passing the tag explicitly. This
  function will also return the tag in the output buffer during
  encryption.

Change-Id: Ic9ddb86e294f8180fb44327c1f4ac4f4650b3e4c

diff --git a/src/include/ckmc/ckmc-manager.h b/src/include/ckmc/ckmc-manager.h
index 6edbe51..7febfd7 100644 (file)
--- a/src/include/ckmc/ckmc-manager.h
+++ b/src/include/ckmc/ckmc-manager.h
@@ -1008,8 +1008,8 @@ int ckmc_remove_alias(const char *alias);
  *                      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.
- * @param[out] ppencrypted Encrypted data (some algorithms may return additional information
- *                         embedded in encrypted data. AES GCM is an example)
+ * @param[out] ppencrypted Encrypted data. In #CKMC_ALGO_AES_GCM mode it includes the GCM tag
+ *                         appended at the end.
  *
  * @return @c 0 on success, otherwise a negative error value
  * @retval #CKMC_ERROR_NONE Successful
@@ -1062,10 +1062,10 @@ int ckmc_encrypt_data(ckmc_param_list_h params,
  * @param[in] key_alias Alias of the key to be used for encryption
  * @param[in] password The password used in decrypting a key value. 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[in] encrypted Data to be decrypted. #CKMC_ALGO_AES_GCM mode requires GCM tag to be
+ *                      appended at the end. 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
  *
  * @return @c 0 on success, otherwise a negative error value
@@ -1126,7 +1126,8 @@ int ckmc_decrypt_data(ckmc_param_list_h params,
  * @param[in] wrapping_key_alias The name of the wrapping key.
  * @param[in] wrapping_key_password An optional password of the wrapping key
  * @param[in] alias The name of a key to be stored
- * @param[in] wrapped_key The wrapped key to be unwrapped and stored
+ * @param[in] wrapped_key The wrapped key to be unwrapped and stored. #CKMC_ALGO_AES_GCM mode
+ *                        requires GCM tag to be appended at the end of the @a wrapped_key.
  * @param[in] policy The policy about how to store a key securely
  *
  * @return @c 0 on success, otherwise a negative error value
@@ -1181,7 +1182,8 @@ int ckmc_import_wrapped_key(const ckmc_param_list_h params,
  * @param[in] wrapping_key_password An optional password of the wrapping key
  * @param[in] alias The name of the key to be wrapped and exported
  * @param[in] password An optional password used to decrypt the key pointed by @a alias
- * @param[out] ppwrapped_key The wrapped key
+ * @param[out] ppwrapped_key The wrapped key. In #CKMC_ALGO_AES_GCM mode it includes the GCM tag
+ *                           appended at the end.
  *
  * @return @c 0 on success, otherwise a negative error value
  * @retval #CKMC_ERROR_NONE Successful
@@ -1271,6 +1273,9 @@ int ckmc_key_derive(const ckmc_param_list_h params,
  *          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().
+ * @remarks To pass #CKMC_PARAM_ED_AAD in multiple chunks call the ckmc_cipher_initialize() multiple
+ *          times with consecutive portions of the AAD in the @a params and the @a context returned
+ *          from the first call. It must be done before the first call to ckmc_cipher_update().
  *
  * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e
  *                   for details. Supported algorithms:
@@ -1278,7 +1283,8 @@ int ckmc_key_derive(const ckmc_param_list_h params,
  * @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
+ * @param[out] context Encryption/decryption context. Must point to NULL if it's the first call.
+ *                     Otherwise, it must point to the previously returned context.
  *
  * @return @c 0 on success, otherwise a negative error value
  * @retval #CKMC_ERROR_NONE Successful
@@ -1343,8 +1349,12 @@ int ckmc_cipher_update(ckmc_cipher_ctx_h context,
  * @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.
+ * @remarks When using #CKMC_ALGO_AES_GCM decryption the GCM tag must be passed as @a in. In other
+ *          cases @a in should be set to NULL.
+ * @remarks When using #CKMC_ALGO_AES_GCM encryption the GCM tag will be returned in @a ppout.
  *
  * @param[in] context Encryption/decryption context created with ckmc_cipher_initialize()
+ * @param[in] in Optional additional decryption input required by some of the modes.
  * @param[out] ppout Encryption/decryption output
  *
  * @return @c 0 on success, otherwise a negative error value
@@ -1358,7 +1368,9 @@ int ckmc_cipher_update(ckmc_cipher_ctx_h context,
  * @see ckmc_cipher_update()
  * @see ckmc_cipher_free()
  */
-int ckmc_cipher_finalize(ckmc_cipher_ctx_h context, ckmc_raw_buffer_s **ppout);
+int ckmc_cipher_finalize(ckmc_cipher_ctx_h context,
+                         const ckmc_raw_buffer_s *in,
+                         ckmc_raw_buffer_s **ppout);
 
 /**
  * @brief Destroys the encryption/decryption context and releases all its resources.