Add ECDH+KBKDF example

Add an ECDH+KBKDF example in form of a doxygen snippet. The code used in it is
compiled together with the project.

Disclaimer:
I don't know how to generate Tizen API documentation. Basing on other projects
I made an assumption that doxygen's EXAMPLE_PATH points to doc subdirectory.
With such assumption, vanilla doxygen generates the code snippet properly.

Change-Id: I7cdc98ff204238be0ad2440a8816ed53a61e7efc

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index ae81725..b5ad3aa 100644 (file)
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -17,3 +17,5 @@
 # @brief
 #
 INSTALL(FILES initial_values.xsd DESTINATION ${RO_DATA_DIR})
+
+ADD_SUBDIRECTORY(examples)
\ No newline at end of file

diff --git a/doc/examples/CMakeLists.txt b/doc/examples/CMakeLists.txt
new file mode 100644 (file)
index 0000000..dd2822f
--- /dev/null
+++ b/doc/examples/CMakeLists.txt
@@ -0,0 +1,11 @@
+SET(TARGET_EXAMPLES "examples")
+
+SET(EXAMPLE_SOURCES
+       ${CMAKE_CURRENT_SOURCE_DIR}/key_derive.cpp
+)
+
+ADD_LIBRARY(${TARGET_EXAMPLES} STATIC ${EXAMPLE_SOURCES})
+
+TARGET_INCLUDE_DIRECTORIES(${TARGET_EXAMPLES} PRIVATE
+       ${PROJECT_SOURCE_DIR}/src/include
+)

diff --git a/doc/examples/key_derive.cpp b/doc/examples/key_derive.cpp
new file mode 100644 (file)
index 0000000..79c6507
--- /dev/null
+++ b/doc/examples/key_derive.cpp
@@ -0,0 +1,124 @@
+/*
+ * Copyright (c) 2023 Samsung Electronics Co., Ltd All Rights Reserved
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License
+ */
+
+#include <cstring>
+
+#include <ckmc/ckmc-manager.h>
+
+//! [KEY_DERIVE example]
+int key_derive(const ckmc_raw_buffer_s* peers_public)
+{
+       int ret;
+
+       const char* const SECRET_ALIAS = "shared_secret";
+       const char* const KEY_ALIAS = "derived_key";
+       const char* const OURS_PRV_ALIAS = "ours_private";
+       const char* const OURS_PUB_ALIAS = "ours_public";
+
+       ckmc_policy_s unexportable { nullptr, false };
+       ckmc_policy_s exportable { nullptr, true };
+
+       // generate EC key pair
+       ret = ckmc_create_key_pair_ecdsa(CKMC_EC_PRIME256V1,
+                                        OURS_PRV_ALIAS,
+                                        OURS_PUB_ALIAS,
+                                        unexportable,
+                                        exportable);
+       if (ret != CKMC_ERROR_NONE)
+               return -1;
+
+       // set ECDH params
+       ckmc_param_list_h ecdh_params;
+       ret = ckmc_param_list_new(&ecdh_params);
+       if (ret != CKMC_ERROR_NONE)
+               return -1;
+
+       ret = ckmc_param_list_set_integer(ecdh_params, CKMC_PARAM_ALGO_TYPE, CKMC_ALGO_ECDH);
+       if (ret != CKMC_ERROR_NONE)
+               return -1;
+
+       ret = ckmc_param_list_set_buffer(ecdh_params, CKMC_PARAM_ECDH_PUBKEY, peers_public);
+       if (ret != CKMC_ERROR_NONE)
+               return -1;
+
+       // derive shared secret
+       ret = ckmc_key_derive(ecdh_params, OURS_PRV_ALIAS, nullptr, SECRET_ALIAS, unexportable);
+       if (ret != CKMC_ERROR_NONE)
+               return -1;
+
+       // set KBKDF params
+       ckmc_param_list_h kbkdf_params;
+       ret = ckmc_param_list_new(&kbkdf_params);
+       if (ret != CKMC_ERROR_NONE)
+               return -1;
+
+       ret = ckmc_param_list_set_integer(kbkdf_params, CKMC_PARAM_ALGO_TYPE, CKMC_ALGO_KBKDF);
+       if (ret != CKMC_ERROR_NONE)
+               return -1;
+
+       ret = ckmc_param_list_set_integer(kbkdf_params, CKMC_PARAM_KDF_PRF, CKMC_KDF_PRF_HMAC_SHA256);
+       if (ret != CKMC_ERROR_NONE)
+               return -1;
+
+       ret = ckmc_param_list_set_integer(kbkdf_params, CKMC_PARAM_KBKDF_MODE, CKMC_KBKDF_MODE_COUNTER);
+       if (ret != CKMC_ERROR_NONE)
+               return -1;
+
+       ret = ckmc_param_list_set_integer(kbkdf_params,
+                                         CKMC_PARAM_KBKDF_COUNTER_LOCATION,
+                                         CKMC_KBKDF_COUNTER_BEFORE_FIXED);
+       if (ret != CKMC_ERROR_NONE)
+               return -1;
+
+       char label[] = "label";
+       ckmc_raw_buffer_s* label_buf = nullptr;
+       ret = ckmc_buffer_new(reinterpret_cast<unsigned char*>(label), strlen(label), &label_buf);
+       if (ret != CKMC_ERROR_NONE)
+               return -1;
+
+       ret = ckmc_param_list_set_buffer(kbkdf_params, CKMC_PARAM_KBKDF_LABEL, label_buf);
+       ckmc_buffer_free(label_buf);
+       if (ret != CKMC_ERROR_NONE)
+               return -1;
+
+       char context[] = "context";
+       ckmc_raw_buffer_s* context_buf = nullptr;
+       ret = ckmc_buffer_new(reinterpret_cast<unsigned char*>(context), strlen(context), &context_buf);
+       if (ret != CKMC_ERROR_NONE)
+               return -1;
+
+       ret = ckmc_param_list_set_buffer(kbkdf_params, CKMC_PARAM_KBKDF_CONTEXT, context_buf);
+       ckmc_buffer_free(context_buf);
+       if (ret != CKMC_ERROR_NONE)
+               return -1;
+
+       ret = ckmc_param_list_set_integer(kbkdf_params, CKMC_PARAM_KDF_LEN, 32);
+       if (ret != CKMC_ERROR_NONE)
+               return -1;
+
+       // derive symmetric key
+       ret = ckmc_key_derive(kbkdf_params, SECRET_ALIAS, nullptr, KEY_ALIAS, unexportable);
+       if (ret != CKMC_ERROR_NONE)
+               return -1;
+
+       // remove shared secret
+       ret = ckmc_remove_key(SECRET_ALIAS);
+       if (ret != CKMC_ERROR_NONE)
+               return -1;
+
+       return 0;
+}
+//! [KEY_DERIVE example]

diff --git a/src/include/ckmc/ckmc-manager.h b/src/include/ckmc/ckmc-manager.h
index 0ae6af5..54c5ab5 100644 (file)
--- a/src/include/ckmc/ckmc-manager.h
+++ b/src/include/ckmc/ckmc-manager.h
@@ -1126,6 +1126,9 @@ int ckmc_export_wrapped_key(const ckmc_param_list_h params,
  *
  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
  *
+ * @par Example
+ * @snippet examples/key_derive.cpp KEY_DERIVE example
+ *
  * @see #ckmc_param_list_h
  * @see #ckmc_policy_s
  */