From 4f1cbaf2df3c1bb68741e531233ee551c6c5bf02 Mon Sep 17 00:00:00 2001
From: Jan Wojtkowski <j.wojtkowski@samsung.com>
Date: Tue, 11 Mar 2025 09:23:41 +0100
Subject: [PATCH] Add high level documentation to HAL API

Change-Id: Ie3d983493e7181ebf6aab8fe4dfc9ff9cf29ca56
---
 doc/hal_security_doc.h      |  4 +++
 doc/hal_security_keys_doc.h | 54 +++++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 doc/hal_security_keys_doc.h

diff --git a/doc/hal_security_doc.h b/doc/hal_security_doc.h
index 7041f2a..c47b0eb 100644
--- a/doc/hal_security_doc.h
+++ b/doc/hal_security_doc.h
@@ -38,6 +38,10 @@
  *    <td>Provides functions to handle device certificates and signing operations</td>
  * </tr>
  * <tr>
+ *    <td>@ref HALAPI_HAL_SECURITY_KEYS_MODULE</td>
+ *    <td>Provides functions to handle keys and data related operations</td>
+ * </tr>
+ * <tr>
  *    <td>@ref HALAPI_HAL_SECURITY_AUTH_MODULE</td>
  *    <td>Provides functions to handle the authentication per user</td>
  * </tr>
diff --git a/doc/hal_security_keys_doc.h b/doc/hal_security_keys_doc.h
new file mode 100644
index 0000000..dec7fb5
--- /dev/null
+++ b/doc/hal_security_keys_doc.h
@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) 2025 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.
+ */
+
+
+#ifndef __TIZEN_HAL_SECURITY_KEYS_DOC_H__
+#define __TIZEN_HAL_SECURITY_KEYS_DOC_H__
+
+
+/**
+ * @file hal_security_keys_doc.h
+ * @brief This file contains high level documentation of the HAL Security Keys module.
+ */
+
+/**
+ * @ingroup HALAPI_HAL_SECURITY
+ * @defgroup HALAPI_HAL_SECURITY_KEYS_MODULE Security Keys
+ * @brief The @ref HALAPI_HAL_SECURITY_KEYS_MODULE provides functions to handle keys and data related operations.
+ *
+ * @section HALAPI_HAL_SECURITY_KEYS_MODULE_HEADER Required Header
+ *   \#include <hal/hal-security-keys.h>
+ *
+ * @section HALAPI_HAL_SECURITY_KEYS_MODULE_OVERVIEW Overview
+ * The Security Keys provides functions to handle keys and data related operations
+ *
+ * The Security Keys functions provide methods to:
+ * - Create IV
+ * - Create/Destroy keys (AES, RSA, DSA, ECDSA, KEM)
+ * - Import/Export wrapped keys
+ * - Encapsulate/Decapsulate KEM keys
+ * - Import/Export data
+ * - Wrap/Unwrap concatenated data
+ * - Encrypt/Decrypt data
+ * - Initialize and perform cipher operations
+ * - Create and verify signatures
+ * - Derive keys (ECDH, KBKDF, KBKDF hybrid)
+ * - Get key chunk size
+ *
+ * For more information on the Security Keys features and the macros, see HAL Security programming guides and tutorials.
+ */
+
+#endif /* __TIZEN_HAL_SECURITY_KEYS_DOC_H__ */
-- 
2.34.1