2 * Copyright (c) 2017 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License
18 * @file ode-key-storage-plugin.h
19 * @brief This file provides APIs to be implemented by plugins responsible for
20 * master key storage for the purpose of system upgrade.
23 #ifndef __CAPI_ODE_KEY_STORAGE_PLUGIN_H__
24 #define __CAPI_ODE_KEY_STORAGE_PLUGIN_H__
34 #define ODE_KSP_API __attribute__((visibility("default")))
38 * @brief Enumeration of key storage plugin API errors
42 ODE_KSP_ERROR_NONE = TIZEN_ERROR_NONE, /**< The operation was successful */
43 ODE_KSP_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
44 ODE_KSP_ERROR_NO_SUCH_FILE = TIZEN_ERROR_NO_SUCH_FILE, /**< No such file or directory */
45 ODE_KSP_ERROR_UNKNOWN = TIZEN_ERROR_UNKNOWN /**< Unknown error */
46 } ode_ksp_error_type_e;
50 * @brief Store the master encryption key
52 * @details This plugin function will be called when the master key has to be
53 * stored for the purpose of system upgrade. The function should
54 * return data that is necessary to load the key.
58 * @param[in] key Master key to store
59 * @param[in] key_len Length of the master key
60 * @param[out] token Token returned by plugin needed to load the stored
61 * key. Caller is responsible for freeing it with free()
62 * @param[out] token_len Length of the @a token
64 * @return #ODE_KSP_ERROR_NONE on success, otherwise a negative value
66 * @retval #ODE_KSP_ERROR_NONE Successful
67 * @retval #ODE_KSP_ERROR_INVALID_PARAMETER Invalid parameter
68 * @retval #ODE_KSP_ERROR_UNKNOWN Unknown error
71 * @see ode_ksp_remove()
73 ODE_KSP_API int ode_ksp_store(const unsigned char* key, size_t key_len,
74 unsigned char** token, size_t* token_len);
77 * @brief Load the master encryption key
79 * @details This plugin function will be called during system upgrade to load
80 * the master key previously stored with ode_ksp_store(). The
81 * function should return the master key.
85 * @param[in] token Token returned by ode_ksp_store()
86 * @param[in] token_len Length of the token
87 * @param[out] key Loaded master key. Caller is responsible for freeing
89 * @param[out] key_len Length of the @a key
91 * @return #ODE_KSP_ERROR_NONE on success, otherwise a negative value
93 * @retval #ODE_KSP_ERROR_NONE Successful
94 * @retval #ODE_KSP_ERROR_INVALID_PARAMETER Invalid parameter
95 * @retval #ODE_KSP_ERROR_NO_SUCH_FILE No key matching the given token exists
96 * @retval #ODE_KSP_ERROR_UNKNOWN Unknown error
98 * @see ode_ksp_store()
99 * @see ode_ksp_remove()
101 ODE_KSP_API int ode_ksp_load(const unsigned char* token, size_t token_len,
102 unsigned char** key, size_t* key_len);
105 * @brief Remove master key data
107 * @details This plugin function will be called when the master key is not
108 * needed anymore. Plugin can erase all internal data associated
109 * with given token in this function.
113 * @param[in] token Token returned by ode_ksp_store()
114 * @param[in] token_len Length of the token
116 * @return #ODE_KSP_ERROR_NONE on success, otherwise a negative value
118 * @retval #ODE_KSP_ERROR_NONE Successful
119 * @retval #ODE_KSP_ERROR_INVALID_PARAMETER Invalid parameter
120 * @retval #ODE_KSP_ERROR_NO_SUCH_FILE No key matching the given token exists
121 * @retval #ODE_KSP_ERROR_UNKNOWN Unknown error
123 * @see ode_ksp_store()
125 ODE_KSP_API int ode_ksp_remove(const unsigned char* token, size_t token_len);
135 #endif /* __CAPI_ODE_KEY_STORAGE_PLUGIN_H__ */