lib/ode/internal-encryption.h

   1 /*
   2  *  Copyright (c) 2015 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 #ifndef __CAPI_ODE_INTERNAL_ENCRYPTION_H__
  18 #define __CAPI_ODE_INTERNAL_ENCRYPTION_H__
  19
  20 #include <ode/common.h>
  21
  22 /**
  23  * @file internal-encryption.h
  24  * @brief This file provides APIs to manage the encryption of internal storage.
  25  */
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31 /**
  32  * @brief       Mount internal storage with encryption by given password.
  33  * @details     Administrator can use this API to mount encrypted internal
  34  *              storage.
  35  * @since_tizen 3.0
  36  * @param[in]   password The password to mount internal storage
  37  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
  38  * @retval      #ODE_ERROR_NONE Successful
  39  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
  40  * @retval      #ODE_ERROR_TIMED_OUT Time out
  41  * @retval      #ODE_ERROR_KEY_REJECTED Password doen't match
  42  * @retval      #ODE_ERROR_NO_SUCH_FILE No such file or directory
  43  * @retval      #ODE_ERROR_NOT_PERMITTED Operation not permitted
  44  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
  45  *              the privilege to call this API
  46  * @pre         The password must match with what is set by
  47  *              ode_internal_encryption_init_password().
  48  * @see         ode_internal_encryption_encrypt()
  49  * @see         ode_internal_encryption_umount()
  50  */
  51 ODE_API int ode_internal_encryption_mount(const char* password);
  52
  53 /**
  54  * @brief       Umount internal storage
  55  * @details     Administrator can use this API to unmount internal storage.
  56  * @since_tizen 3.0
  57  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
  58  * @retval      #ODE_ERROR_NONE Successful
  59  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
  60  * @retval      #ODE_ERROR_TIMED_OUT Time out
  61  * @retval      #ODE_ERROR_NO_SUCH_FILE No such file or directory
  62  * @retval      #ODE_ERROR_NOT_PERMITTED Operation not permitted
  63  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
  64  *              the privilege to call this API
  65  * @see         ode_internal_encryption_mount()
  66  */
  67 ODE_API int ode_internal_encryption_umount();
  68
  69 /**
  70  * @brief       Encrypt internal storage by given password.
  71  * @details     Administrator can use this API to encrypt internal storage.
  72  * @since_tizen 3.0
  73  * @param[in]   password The password to encrypt internal storage
  74  * @param[in]   options Encryption options
  75  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
  76  * @retval      #ODE_ERROR_NONE Successful
  77  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
  78  * @retval      #ODE_ERROR_TIMED_OUT Time out
  79  * @retval      #ODE_ERROR_KEY_REJECTED Password doen't match
  80  * @retval      #ODE_ERROR_NOT_PERMITTED Operation not permitted
  81  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
  82  * @retval      #ODE_ERROR_NOT_SUPPORTED Given options are not supported
  83  *              the privilege to call this API
  84  * @pre         The password must match with what is set by
  85  *              ode_internal_encryption_init_password().
  86  * @see         ode_internal_encryption_mount()
  87  * @see         ode_internal_encryption_decrypt()
  88  * @see         ode_internal_encryption_get_supported_options()
  89  */
  90 ODE_API int ode_internal_encryption_encrypt(const char* password, unsigned int options);
  91
  92 /**
  93  * @brief       Decrypt internal storage by given password.
  94  * @details     Administrator can use this API to decrypt internal storage.
  95  * @since_tizen 3.0
  96  * @param[in]   password The password to decrypt internal storage
  97  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
  98  * @retval      #ODE_ERROR_NONE Successful
  99  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 100  * @retval      #ODE_ERROR_TIMED_OUT Time out
 101  * @retval      #ODE_ERROR_KEY_REJECTED Password doen't match
 102  * @retval      #ODE_ERROR_NOT_PERMITTED Operation not permitted
 103  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 104  *              the privilege to call this API
 105  * @pre         The password must match with what is set by
 106  *              ode_internal_encryption_init_password().
 107  * @see         ode_internal_encryption_encrypt()
 108  */
 109 ODE_API int ode_internal_encryption_decrypt(const char* password);
 110
 111 /**
 112  * @brief       Checks whether the internal encryption password was created
 113  * @details     Administrator can use this API to check if the password that
 114                 will be used for internal storage encryption/decryption
 115                 exists.
 116  * @since_tizen 3.0
 117  * @param[out]  result Whether encryption password was created
 118  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 119  * @retval      #ODE_ERROR_NONE Successful
 120  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 121  * @retval      #ODE_ERROR_TIMED_OUT Time out
 122  * @retval      #ODE_ERROR_NOT_PERMITTED Operation not permitted
 123  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 124  *              the privilege to call this API
 125  * @see         ode_internal_encryption_init_password()
 126  * @see         ode_internal_encryption_clean_password()
 127  */
 128 ODE_API int ode_internal_encryption_is_password_initialized(bool* result);
 129
 130 /**
 131  * @brief       Initialize internal encryption password to given password
 132  * @details     Administrator can use this API to set new password that will be
 133                 used for internal storage encryption/decryption.
 134  * @since_tizen 3.0
 135  * @param[in]   password The password to set
 136  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 137  * @retval      #ODE_ERROR_NONE Successful
 138  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 139  * @retval      #ODE_ERROR_TIMED_OUT Time out
 140  * @retval      #ODE_ERROR_NOT_PERMITTED Operation not permitted
 141  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 142  *              the privilege to call this API
 143  * @see         ode_internal_encryption_change_password()
 144  * @see         ode_internal_encryption_clean_password()
 145  * @see         ode_internal_encryption_encrypt()
 146  * @see         ode_internal_encryption_decrypt()
 147  * @see         ode_internal_encryption_mount()
 148  */
 149 ODE_API int ode_internal_encryption_init_password(const char* password);
 150
 151 /**
 152  * @brief       Remove internal encryption password
 153  * @details     Administrator can use this API to delete password that was set
 154                 by ode_internal_encryption_init_password().
 155  * @since_tizen 3.0
 156  * @param[in]   password The password to delete
 157  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 158  * @retval      #ODE_ERROR_NONE Successful
 159  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 160  * @retval      #ODE_ERROR_TIMED_OUT Time out
 161  * @retval      #ODE_ERROR_KEY_REJECTED old_password doen't match
 162  * @retval      #ODE_ERROR_NOT_PERMITTED Operation not permitted
 163  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 164  *              the privilege to call this API
 165  * @pre         The password must match with what is set by
 166  *              ode_internal_encryption_init_password().
 167  * @see         ode_internal_encryption_init_password()
 168  */
 169 ODE_API int ode_internal_encryption_clean_password(const char* password);
 170
 171 /**
 172  * @brief       Change the password for internal storage.
 173  * @details     Administrator can use this API to change password for internal
 174  *              storage.
 175  * @since_tizen 3.0
 176  * @param[in]   old_password Current password of internal storage
 177  * @param[in]   new_password The password to use newly for internal storage
 178  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 179  * @retval      #ODE_ERROR_NONE Successful
 180  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 181  * @retval      #ODE_ERROR_TIMED_OUT Time out
 182  * @retval      #ODE_ERROR_KEY_REJECTED old_password doen't match
 183  * @retval      #ODE_ERROR_NOT_PERMITTED Operation not permitted
 184  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 185  *              the privilege to call this API
 186  * @pre         Old password must match with what is set by
 187  *              ode_internal_encryption_init_password().
 188  * @see         ode_internal_encryption_init_password()
 189  */
 190 ODE_API int ode_internal_encryption_change_password(const char* old_password,
 191                                                                                                         const char* new_password);
 192
 193 /**
 194  * @brief       Verify if given password is internal encryption password.
 195  * @details     Administrator can use this API to find if a password is used
 196                 by internal encryption
 197  * @since_tizen 3.0
 198  * @param[in]   password The password to be verified
 199  * @param[out]  result The result of verification
 200  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 201  * @retval      #ODE_ERROR_NONE Successful
 202  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 203  * @retval      #ODE_ERROR_TIMED_OUT Time out
 204  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 205  *              the privilege to call this API
 206  * @pre         The password must match with what is set by
 207  *              ode_internal_encryption_init_password().
 208  * @see         ode_internal_encryption_init_password()
 209  * @see         ode_internal_encryption_change_password()
 210  */
 211 ODE_API int ode_internal_encryption_verify_password(const char* password, bool* result);
 212
 213 /**
 214  * @brief       Get current encryption state of internal storage.
 215  * @details     Administrator can use this API to get current encryption state
 216  *              of internal storage.
 217  * @since_tizen 3.0
 218  * @param[out]  state The encryption state of internal storage
 219  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 220  * @retval      #ODE_ERROR_NONE Successful
 221  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 222  * @retval      #ODE_ERROR_TIMED_OUT Time out
 223  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 224  *              the privilege to call this API
 225  * @see         ode_internal_encryption_encrypt()
 226  * @see         ode_internal_encryption_decrypt()
 227  */
 228 ODE_API int ode_internal_encryption_get_state(int* state);
 229
 230 /*
 231  * @brief       Enumeration for internal encryption options
 232  * @since_tizen 3.0
 233  */
 234 typedef enum {
 235         ODE_OPTION_INTERNAL_INCLUDE_UNUSED_REGION  = 1 << 0, /**< Encrypt all include unused region  */
 236 } ode_options_internal_e;
 237
 238 /**
 239  * @brief       Get supported options for encryption of internal storage.
 240  * @details     Administrator can use this API to get which options are
 241                 supported for encryption of external storage.
 242  * @since_tizen 3.0
 243  * @param[out]  option The logical OR of supported options in internal storage
 244  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 245  * @retval      #ODE_ERROR_NONE Successful
 246  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 247  * @retval      #ODE_ERROR_TIMED_OUT Time out
 248  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 249  *              the privilege to call this API
 250  * @see         ode_internal_encryption_encrypt()
 251  */
 252 ODE_API int ode_internal_encryption_get_supported_options(unsigned int* options);
 253
 254 /*
 255  * @}
 256  */
 257
 258 #ifdef __cplusplus
 259 }
 260 #endif
 261
 262 #endif /* __CAPI_ODE_INTERNAL_ENCRYPTION_H__ */