From 3c8372681116185075ccdda39f09007df34b4192 Mon Sep 17 00:00:00 2001
From: Filip Skrzeczkowski <f.skrzeczkow@samsung.com>
Date: Fri, 14 Jun 2024 16:56:01 +0200
Subject: [PATCH] Documentation improvement for Escrow Vault 2.0 support

The following changes in the CAPI documentation were made according
to requests made during the ACR approval process:
 - CAPI_KEY_MANAGER_CLIENT_EXTENDED_MODULE description
 - concatenated data (un)wrapping: code examples of memory handling
 - 3072 bit RSA clarification: minimum Tizen release

Change-Id: I095c088534e56d032041e46a263791877f1176e9
---
 doc/key-manager_doc.h            |  4 ++++
 src/include/ckmc/ckmc-extended.h | 34 +++++++++++++++++++++++++++++++++-
 src/include/ckmc/ckmc-manager.h  |  4 ++--
 3 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/doc/key-manager_doc.h b/doc/key-manager_doc.h
index 62b5fce..97d2935 100644
--- a/doc/key-manager_doc.h
+++ b/doc/key-manager_doc.h
@@ -36,6 +36,10 @@
  *     <td> @ref CAPI_KEY_MANAGER_TYPES_MODULE</td>
  *     <td> Defines data types used in these APIs and provides utility methods handling them.</td>
  *   </tr>
+ *   <tr>
+ *     <td> @ref CAPI_KEY_MANAGER_CLIENT_EXTENDED_MODULE</td>
+ *     <td> Provides APIs for extended functionality including concatenated data (un)wrapping.</td>
+ *   </tr>
  * </table>
  * It provides a secure repository for keys, certificates, and sensitive data of users and/or their APPs which are protected by Tizen platform.
  * Additionally, it provides secure cryptographic operations for non-exportable keys without revealing key values to clients.
diff --git a/src/include/ckmc/ckmc-extended.h b/src/include/ckmc/ckmc-extended.h
index 2154cd1..a96d2ea 100644
--- a/src/include/ckmc/ckmc-extended.h
+++ b/src/include/ckmc/ckmc-extended.h
@@ -57,6 +57,21 @@ extern "C" {
  *          @c 1024 bits.
  * @remarks The @a ppwrapped_key should be released using ckmc_key_free().
  *
+ * @code
+ * 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);
+ * @endcode
+ *
  * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e
  *                   for details. Supported algorithms:
  *                   - #CKMC_ALGO_RSA_OAEP
@@ -118,12 +133,29 @@ int ckmc_wrap_concatenated_data(const ckmc_param_list_h params,
  *          wrapped form.
  * @remarks The @a ppdata should be released using ckmc_buffer_free().
  *
+ * @code
+ * 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);
+ * @endcode
+ *
  * @param[in] params Algorithm parameter list handle. See #ckmc_param_list_h and #ckmc_algo_type_e
  *                   for details. Supported algorithms:
  *                   - #CKMC_ALGO_RSA_OAEP
  * @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] wrapped_key The wrapped key to be unwrapped, splitted and stored
+ * @param[in] wrapped_key The wrapped key to be unwrapped, split and stored
  * @param[in] alias The name of a key to be stored
  * @param[in] size The size in bits of the key to be stored. @c 128, @c 192 and @c 256 are supported
  * @param[in] policy The policy about how to store a key securely
diff --git a/src/include/ckmc/ckmc-manager.h b/src/include/ckmc/ckmc-manager.h
index a78d37a..0b3ee77 100644
--- a/src/include/ckmc/ckmc-manager.h
+++ b/src/include/ckmc/ckmc-manager.h
@@ -570,8 +570,8 @@ int ckmc_create_key_pair_rsa(const size_t size,
  *          use this function since 3.0.
  * @remarks If password in the policy is provided, the key is additionally encrypted with the
  *          password in the policy.
- * @param[in] size The size of key strength to be created. @c 1024, @c 2048, @c 3072 and @c 4096 are
- *                 supported
+ * @param[in] size The size of key strength to be created. @c 1024, @c 2048, @c 3072 (Since 7.0)
+ *                 and @c 4096 are supported
  * @param[in] private_key_alias The name of private key to be stored
  * @param[in] public_key_alias The name of public key to be stored
  * @param[in] policy_private_key The policy about how to store a private key securely
-- 
2.7.4