Add luks API declaration

Extension encryption is supposed to become a wrapper over cryptsetup. New API
will do exactly that.

Change-Id: I97780fa3b1a59f405478d8bd1fb6eb6272416c33

diff --git a/lib/ode/common.h b/lib/ode/common.h
index 683b7ce..86ac626 100644 (file)
--- a/lib/ode/common.h
+++ b/lib/ode/common.h
@@ -61,7 +61,9 @@ typedef enum {
        ODE_ERROR_OUT_OF_MEMORY        = TIZEN_ERROR_OUT_OF_MEMORY,        /**< Out of memory */
        ODE_ERROR_NOT_PERMITTED        = TIZEN_ERROR_NOT_PERMITTED,        /**< Operation is not permitted */
        ODE_ERROR_KEY_REJECTED         = TIZEN_ERROR_KEY_REJECTED,         /**< Passwor is rejected */
-       ODE_ERROR_NO_DATA              = TIZEN_ERROR_NO_DATA               /**< No Data */
+       ODE_ERROR_NO_DATA              = TIZEN_ERROR_NO_DATA,              /**< No Data */
+       ODE_ERROR_RESOURCE_BUSY        = TIZEN_ERROR_RESOURCE_BUSY,        /**< Device or resource busy */
+       ODE_ERROR_UNKNOWN              = TIZEN_ERROR_UNKNOWN               /**< Unknown error */
 } ode_error_type_e;
 
 /*

diff --git a/lib/ode/luks.h b/lib/ode/luks.h
new file mode 100644 (file)
index 0000000..0db6ded
--- /dev/null
+++ b/lib/ode/luks.h
@@ -0,0 +1,210 @@
+/*
+ *  Copyright (c) 2017 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 __CAPI_ODE_LUKS_H__
+#define __CAPI_ODE_LUKS_H__
+
+#include <ode/common.h>
+
+/**
+ * @file luks.h
+ * @brief This file provides APIs to perform LUKS operations.
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * @brief       Enumeration for luks operation types
+ *
+ * @since_tizen 4.0
+ *
+ * @see ode_luks_format()
+ * @see ode_luks_open()
+ * @see ode_luks_close()
+ */
+typedef enum {
+    ODE_LUKS_FORMAT = 1, /**< Format operation */
+    ODE_LUKS_OPEN   = 2, /**< Open operation */
+    ODE_LUKS_CLOSE  = 3  /**< Close operation */
+} ode_luks_operation_e;
+
+/**
+ * @brief       Called when luks operation is finished
+ *
+ * @since_tizen 4.0
+ *
+ * @param[in]   operation  Type of operation that was finished
+ * @param[in]   result     The result of the operation
+ * @param[in]   user_data  The user data passed from ode_luks_set_event_cb()
+ *
+ * @see         ode_luks_set_event_cb()
+ * @see         ode_luks_unset_event_cb()
+ */
+typedef void(*ode_luks_event_cb)(ode_luks_operation_e operation,
+                                                                int result,
+                                                                void* user_data);
+
+/**
+ * @brief       Formats given device as LUKS using given password.
+ *
+ * @details     The device will be formatted as LUKS but the password will be
+ *              stored in internal storage. This function is asynchronous. If a
+ *              callback was registered using ode_luks_set_event_cb() then it
+ *              will be invoked when the operation is finished.
+ *
+ * @since_tizen 4.0
+ *
+ * @param[in]   device    The device to be formatted
+ * @param[in]   password  The password used for formatting
+ *
+ * @return      #ODE_ERROR_NONE on success, otherwise a negative value. In case
+ *              of success additional return value will be passed to the
+ *              asynchronous callback
+ * @retval      #ODE_ERROR_NONE Successful
+ * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval      #ODE_ERROR_CONNECTION_REFUSED Connection to the server failed
+ * @retval      #ODE_ERROR_OUT_OF_MEMORY Out of memory
+ * @retval      #ODE_ERROR_NO_SUCH_FILE Wrong device
+ * @retval      #ODE_ERROR_RESOURCE_BUSY Device is busy
+ * @retval      #ODE_ERROR_UNKNOWN Unknown error
+ *
+ * @pre         The @a device must be present and neither mapped nor mounted.
+ *
+ * @post        Formatted device can be later opened using ode_luks_open(). The
+ *              mapping will not contain a valid file system. It needs to be
+ *              formatted.
+ *
+ * @see         ode_luks_open()
+ * @see         ode_luks_set_event_cb()
+ */
+ODE_API int ode_luks_format(const char* device, const char* password);
+
+/**
+ * @brief       Creates a mapping with given name backed by a LUKS device.
+ *
+ * @details     This function is asynchronous. If a callback was registered
+ *              using ode_luks_set_event_cb() then it will be invoked when the
+ *              operation is finished.
+ *
+ * @since_tizen 4.0
+ *
+ * @param[in]   device    The device to be used
+ * @param[in]   password  The password used for mapping creation that was used
+ *                        for formatting.
+ * @param[in]   mapping   The desired name of the mapping
+ *
+ * @return      #ODE_ERROR_NONE on success, otherwise a negative value. In case
+ *              of success additional return value will be passed to the
+ *              asynchronous callback
+ * @retval      #ODE_ERROR_NONE Successful
+ * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval      #ODE_ERROR_CONNECTION_REFUSED Connection to the server failed
+ * @retval      #ODE_ERROR_KEY_REJECTED Wrong password
+ * @retval      #ODE_ERROR_OUT_OF_MEMORY Out of memory
+ * @retval      #ODE_ERROR_NO_SUCH_FILE Wrong device or mapping
+ * @retval      #ODE_ERROR_RESOURCE_BUSY Device is busy
+ * @retval      #ODE_ERROR_UNKNOWN Unknown error
+ *
+ * @pre         The @a device must be a LUKS device formatted with
+ *              ode_luks_format(). The mapping must not exist.
+ *
+ * @post        The created mapping can be later mounted to access the encrypted
+ *              storage.
+ * @post        To close the mapping call ode_luks_close()
+ *
+ * @see         ode_luks_format()
+ * @see         ode_luks_close()
+ * @see         ode_luks_set_event_cb()
+ */
+ODE_API int ode_luks_open(const char* device,
+                                                 const char* password,
+                                                 const char* mapping);
+
+/**
+ * @brief       Removes a mapping with given name backed by a LUKS device.
+ *
+ * @details     This function is asynchronous. If a callback was registered
+ *              using ode_luks_set_event_cb() then it will be invoked when the
+ *              operation is finished.
+ *
+ * @since_tizen 4.0
+ *
+ * @param[in]   mapping   The name of the mapping to be closed
+ *
+ * @return      #ODE_ERROR_NONE on success, otherwise a negative value. In case
+ *              of success additional return value will be passed to the
+ *              asynchronous callback
+ * @retval      #ODE_ERROR_NONE Successful
+ * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval      #ODE_ERROR_CONNECTION_REFUSED Connection to the server failed
+ * @retval      #ODE_ERROR_OUT_OF_MEMORY Out of memory
+ * @retval      #ODE_ERROR_NO_SUCH_FILE Wrong mapping
+ * @retval      #ODE_ERROR_RESOURCE_BUSY Device is busy
+ * @retval      #ODE_ERROR_UNKNOWN Unknown error
+ *
+ * @pre         The mapping must be created by a call to ode_luks_open().
+ *              The mapping must not be mounted.
+ *
+ * @see         ode_luks_format()
+ * @see         ode_luks_open()
+ * @see         ode_luks_set_event_cb()
+ */
+ODE_API int ode_luks_close(const char* mapping);
+
+/**
+ * @brief       Registers a callback that will be invoked when given luks
+ *              operation is finished.
+ *
+ * @since_tizen 4.0
+ *
+ * @param[in]   callback  The callback function
+ * @param[in]   user_data The user data passed to the callback function
+ * @return      #ODE_ERROR_NONE on success, otherwise a negative value
+ * @retval      #ODE_ERROR_NONE Successful
+ * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval      #ODE_ERROR_CONNECTION_REFUSED Connection to the server failed
+ *
+ * @post        If the callback is not needed ode_luks_unset_event_cb() must be
+ *              called.
+ *
+ * @see         ode_luks_format()
+ * @see         ode_luks_open()
+ * @see         ode_luks_close()
+ * @see         ode_luks_unset_event_cb()
+ */
+ODE_API int ode_luks_set_event_cb(ode_luks_event_cb callback, void *user_data);
+
+/**
+ * @brief       Unregisters a callback that is invoked when given luks operation
+ *              is finished
+ *
+ * @since_tizen 4.0
+ *
+ * @see         ode_luks_set_event_cb()
+ */
+ODE_API void ode_luks_unset_event_cb();
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __CAPI_ODE_LUKS_H__ */