ode-key-storage-plugin/ode-key-storage-plugin.h

   1 /*
   2  *  Copyright (c) 2017 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   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
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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
  15  */
  16
  17 /**
  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.
  21  */
  22
  23 #ifndef __CAPI_ODE_KEY_STORAGE_PLUGIN_H__
  24 #define __CAPI_ODE_KEY_STORAGE_PLUGIN_H__
  25
  26 #include <stddef.h>
  27 #include <tizen.h>
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 #ifndef ODE_KSP_API
  34 #define ODE_KSP_API __attribute__((visibility("default")))
  35 #endif
  36
  37 /**
  38  * @brief       Enumeration of key storage plugin API errors
  39  * @since_tizen 4.0
  40  */
  41 typedef enum {
  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;
  47
  48
  49 /**
  50  * @brief      Store the master encryption key
  51  *
  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.
  55  *
  56  * @since_tizen 4.0
  57  *
  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
  63  *
  64  * @return     #ODE_KSP_ERROR_NONE on success, otherwise a negative value
  65  *
  66  * @retval     #ODE_KSP_ERROR_NONE Successful
  67  * @retval     #ODE_KSP_ERROR_INVALID_PARAMETER Invalid parameter
  68  * @retval     #ODE_KSP_ERROR_UNKNOWN Unknown error
  69  *
  70  * @see        ode_ksp_load()
  71  * @see        ode_ksp_remove()
  72  */
  73 ODE_KSP_API int ode_ksp_store(const unsigned char* key, size_t key_len,
  74                                                           unsigned char** token, size_t* token_len);
  75
  76 /**
  77  * @brief      Load the master encryption key
  78  *
  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.
  82  *
  83  * @since_tizen 4.0
  84  *
  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
  88  *                        it with free()
  89  * @param[out] key_len    Length of the @a key
  90  *
  91  * @return     #ODE_KSP_ERROR_NONE on success, otherwise a negative value
  92  *
  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
  97  *
  98  * @see        ode_ksp_store()
  99  * @see        ode_ksp_remove()
 100  */
 101 ODE_KSP_API int ode_ksp_load(const unsigned char* token, size_t token_len,
 102                                                          unsigned char** key, size_t* key_len);
 103
 104 /**
 105  * @brief      Remove master key data
 106  *
 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.
 110  *
 111  * @since_tizen 4.0
 112  *
 113  * @param[in]  token      Token returned by ode_ksp_store()
 114  * @param[in]  token_len  Length of the token
 115  *
 116  * @return     #ODE_KSP_ERROR_NONE on success, otherwise a negative value
 117  *
 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
 122  *
 123  * @see        ode_ksp_store()
 124  */
 125 ODE_KSP_API int ode_ksp_remove(const unsigned char* token, size_t token_len);
 126
 127 /**
 128  * @}
 129  */
 130
 131 #ifdef __cplusplus
 132 }
 133 #endif
 134
 135 #endif /* __CAPI_ODE_KEY_STORAGE_PLUGIN_H__ */