lib/ode/external-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_EXTERNAL_ENCRYPTION_H__
  18 #define __CAPI_ODE_EXTERNAL_ENCRYPTION_H__
  19
  20 #include <ode/common.h>
  21
  22 /**
  23  * @file external-encryption.h
  24  * @brief This file provides APIs to manage the encryption of external storage
  25  *        such as SD card.
  26  */
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 /**
  33  * @brief       Set a password to be used by mount of encrypted external storage
  34  * @details     Administrator can use this API to set a password for external
  35  *              mount external storage with encryption.
  36  * @since_tizen 4.0
  37  * @param[in]   password The password to mount external storage
  38  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
  39  * @retval      #ODE_ERROR_NONE Successful
  40  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
  41  * @retval      #ODE_ERROR_KEY_REJECTED Password doesn't match
  42  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
  43  *              the privilege to call this API
  44  * @retval      #ODE_ERROR_CONNECTION_REFUSED Connection to the server failed
  45  * @retval      #ODE_ERROR_UNKNOWN Unknown error
  46  * @pre         The password must match with what is set by
  47  *              ode_external_encryption_init_password().
  48  * @see         ode_external_encryption_init_password()
  49  * @see         ode_external_encryption_mount()
  50  */
  51 ODE_API int ode_external_encryption_set_mount_password(const char* password);
  52
  53 /**
  54  * @brief       Mount external storage with encryption
  55  * @details     Administrator can use this API to mount encrypted external
  56  *              storage.
  57  * @since_tizen 4.0
  58  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
  59  * @retval      #ODE_ERROR_NONE Successful
  60  * @retval      #ODE_ERROR_NO_SUCH_DEVICE External storage is not encrypted
  61  * @retval      #ODE_ERROR_NO_DATA Password isn't set
  62  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
  63  *              the privilege to call this API
  64  * @retval      #ODE_ERROR_CONNECTION_REFUSED Connection to the server failed
  65  * @retval      #ODE_ERROR_UNKNOWN Unknown error
  66  * @pre         A password must be set by
  67  *              ode_external_encryption_set_mount_password() before every
  68  *              mount attempt.
  69  * @see         ode_external_encryption_set_mount_password()
  70  * @see         ode_external_encryption_umount()
  71  */
  72 ODE_API int ode_external_encryption_mount();
  73
  74 /**
  75  * @brief       Umount external storage
  76  * @details     Administrator can use this API to unmount external storage.
  77  * @since_tizen 4.0
  78  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
  79  * @retval      #ODE_ERROR_NONE Successful
  80  * @retval      #ODE_ERROR_NO_SUCH_DEVICE External storage is not encrypted
  81  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
  82  *              the privilege to call this API
  83  * @retval      #ODE_ERROR_CONNECTION_REFUSED Connection to the server failed
  84  * @retval      #ODE_ERROR_UNKNOWN Unknown error
  85  * @see         ode_external_encryption_mount()
  86  */
  87 ODE_API int ode_external_encryption_umount();
  88
  89 /**
  90  * @brief       Encrypt external storage by given password.
  91  * @details     Administrator can use this API to encrypt external storage.
  92  * @since_tizen 4.0
  93  * @param[in]   password The password to encrypt external storage
  94  * @param[in]   options Encryption options
  95  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
  96  * @retval      #ODE_ERROR_NONE Successful
  97  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
  98  * @retval      #ODE_ERROR_KEY_REJECTED Password doesn't match
  99  * @retval      #ODE_ERROR_NO_SUCH_DEVICE External storage is not decrypted
 100  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 101  *              the privilege to call this API
 102  * @retval      #ODE_ERROR_CONNECTION_REFUSED Connection to the server failed
 103  * @retval      #ODE_ERROR_UNKNOWN Unknown error
 104  * @see         ode_external_encryption_mount()
 105  * @see         ode_external_encryption_decrypt()
 106  * @see         ode_external_encryption_get_supported_options()
 107  */
 108 ODE_API int ode_external_encryption_encrypt(const char* password, unsigned int options);
 109
 110 /**
 111  * @brief       Decrypt external storage by given password.
 112  * @details     Administrator can use this API to decrypt external storage.
 113  * @since_tizen 4.0
 114  * @param[in]   password The password to decrypt external storage
 115  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 116  * @retval      #ODE_ERROR_NONE Successful
 117  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 118  * @retval      #ODE_ERROR_KEY_REJECTED Password doesn't match
 119  * @retval      #ODE_ERROR_NO_SUCH_DEVICE External storage is not encrypted
 120  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 121  *              the privilege to call this API
 122  * @retval      #ODE_ERROR_CONNECTION_REFUSED Connection to the server failed
 123  * @retval      #ODE_ERROR_UNKNOWN Unknown error
 124  * @pre         The password must match with what is set by
 125  *              ode_external_encryption_init_password().
 126  * @see         ode_external_encryption_encrypt()
 127  */
 128 ODE_API int ode_external_encryption_decrypt(const char* password);
 129
 130 /**
 131  * @brief       Recovery external encryption when there is something wrong.
 132  * @details     Administrator can use this API to recovery encrypted external
 133  *              storage when the password is missing or the encryption is
 134  *              corrupted. Note that this API will be erase all the contents
 135  *              in external storage.
 136  * @since_tizen 4.0
 137  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 138  * @retval      #ODE_ERROR_NONE Successful
 139  * @retval      #ODE_ERROR_NO_SUCH_DEVICE External storage is decrypted
 140  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 141  *              the privilege to call this API
 142  * @retval      #ODE_ERROR_CONNECTION_REFUSED Connection to the server failed
 143  * @retval      #ODE_ERROR_UNKNOWN Unknown error
 144  * @see         ode_external_encryption_encrypt()
 145  */
 146 ODE_API int ode_external_encryption_recovery();
 147
 148 /**
 149  * @brief       Checks whether the external encryption password was created
 150  * @details     Administrator can use this API to check if the password that
 151                 will be used for external storage encryption/decryption
 152                 exists.
 153  * @since_tizen 4.0
 154  * @param[out]  result Whether encryption password was created
 155  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 156  * @retval      #ODE_ERROR_NONE Successful
 157  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 158  * @retval      #ODE_ERROR_CONNECTION_REFUSED Connection to the server failed
 159  * @retval      #ODE_ERROR_UNKNOWN Unknown error
 160  * @see         ode_external_encryption_init_password()
 161  * @see         ode_external_encryption_clean_password()
 162  */
 163 ODE_API int ode_external_encryption_is_password_initialized(bool* result);
 164
 165 /**
 166  * @brief       Initialize external encryption password to given password
 167  * @details     Administrator can use this API to set new password that will be
 168                 used for external storage encryption/decryption.
 169  * @since_tizen 4.0
 170  * @param[in]   password The password to set
 171  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 172  * @retval      #ODE_ERROR_NONE Successful
 173  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 174  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 175  *              the privilege to call this API
 176  * @retval      #ODE_ERROR_CONNECTION_REFUSED Connection to the server failed
 177  * @retval      #ODE_ERROR_UNKNOWN Unknown error
 178  * @see         ode_external_encryption_change_password()
 179  * @see         ode_external_encryption_clean_password()
 180  * @see         ode_external_encryption_encrypt()
 181  * @see         ode_external_encryption_decrypt()
 182  * @see         ode_external_encryption_mount()
 183  */
 184 ODE_API int ode_external_encryption_init_password(const char* password);
 185
 186 /**
 187  * @brief       Remove external encryption password
 188  * @details     Administrator can use this API to delete password that was set
 189                 by ode_external_encryption_init_password().
 190  * @since_tizen 4.0
 191  * @param[in]   password The password to delete
 192  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 193  * @retval      #ODE_ERROR_NONE Successful
 194  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 195  * @retval      #ODE_ERROR_KEY_REJECTED Password doesn't match
 196  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 197  *              the privilege to call this API
 198  * @retval      #ODE_ERROR_CONNECTION_REFUSED Connection to the server failed
 199  * @retval      #ODE_ERROR_UNKNOWN Unknown error
 200  * @pre         The password must match with what is set by
 201  *              ode_external_encryption_init_password().
 202  * @see         ode_external_encryption_init_password()
 203  */
 204 ODE_API int ode_external_encryption_clean_password(const char* password);
 205
 206 /**
 207  * @brief       Change the password for external storage.
 208  * @details     Administrator can use this API to change password for external
 209  *              storage.
 210  * @since_tizen 4.0
 211  * @param[in]   old_password Current password of external storage
 212  * @param[in]   new_password The password to use newly for external storage
 213  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 214  * @retval      #ODE_ERROR_NONE Successful
 215  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 216  * @retval      #ODE_ERROR_KEY_REJECTED Old password doesn't match
 217  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 218  *              the privilege to call this API
 219  * @retval      #ODE_ERROR_CONNECTION_REFUSED Connection to the server failed
 220  * @retval      #ODE_ERROR_UNKNOWN Unknown error
 221  * @pre         The password must match with what is set by
 222  *              ode_external_encryption_init_password().
 223  * @see         ode_external_encryption_encrypt()
 224  */
 225 ODE_API int ode_external_encryption_change_password(const char* old_password,
 226                                                                                                         const char* new_password);
 227
 228 /**
 229  * @brief       Verify if given password is external encryption password.
 230  * @details     Administrator can use this API to find if a password is used
 231                 by external encryption
 232  * @since_tizen 4.0
 233  * @param[int]  password The password to be verified
 234  * @param[out]  result The result of verification
 235  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 236  * @retval      #ODE_ERROR_NONE Successful
 237  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 238  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 239  *              the privilege to call this API
 240  * @retval      #ODE_ERROR_CONNECTION_REFUSED Connection to the server failed
 241  * @retval      #ODE_ERROR_UNKNOWN Unknown error
 242  * @pre         The password must match with what is set by
 243  *              ode_external_encryption_init_password().
 244  * @see         ode_external_encryption_encrypt()
 245  */
 246 ODE_API int ode_external_encryption_verify_password(const char* password, bool* result);
 247
 248 /**
 249  * @brief       Get current encryption state of external storage.
 250  * @details     Administrator can use this API to get current encryption state
 251  *              of external storage.
 252  * @since_tizen 4.0
 253  * @param[out]  state The encryption state of external storage
 254  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 255  * @retval      #ODE_ERROR_NONE Successful
 256  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 257  * @retval      #ODE_ERROR_CONNECTION_REFUSED Connection to the server failed
 258  * @retval      #ODE_ERROR_UNKNOWN Unknown error
 259  * @see         ode_external_encryption_encrypt()
 260  * @see         ode_external_encryption_decrypt()
 261  */
 262 ODE_API int ode_external_encryption_get_state(int* state);
 263
 264 /*
 265  * @brief       Enumeration for external encryption options
 266  * @since_tizen 4.0
 267  */
 268 typedef enum {
 269     ODE_OPTION_EXTERNAL_ONLY_NEW_FILE  = 1 << 0, /**< Encrypt new files only  */
 270     ODE_OPTION_EXTERNAL_EXCEPT_FOR_MEDIA_FILE  = 1 << 1, /**< Encrypt non-media files only */
 271 } ode_options_external_e;
 272
 273 /**
 274  * @brief       Get supported options for encryption of external storage.
 275  * @details     Administrator can use this API to get which options are
 276                                 supported for encryption of external storage.
 277  * @since_tizen 4.0
 278  * @param[out]  option The logical OR of supported options in external storage
 279  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 280  * @retval      #ODE_ERROR_NONE Successful
 281  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 282  * @retval      #ODE_ERROR_CONNECTION_REFUSED Connection to the server failed
 283  * @retval      #ODE_ERROR_UNKNOWN Unknown error
 284  * @see         ode_external_encryption_encrypt()
 285  */
 286 ODE_API int ode_external_encryption_get_supported_options(unsigned int* options);
 287
 288 /**
 289  * @brief       Register a callback to get mount event of external storage
 290  * @details     Services can use this API to attach a callback to be called
 291  *              by mount event of external storage with encryption.
 292  * @since_tizen 4.0
 293  * @param[in]   callback The mount event callback function
 294  * @param[in]   user_data The user data passed to the callback function
 295  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 296  * @retval      #ODE_ERROR_NONE Successful
 297  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 298  * @retval      #ODE_ERROR_CONNECTION_REFUSED Connection to the server failed
 299  * @retval      #ODE_ERROR_UNKNOWN Unknown error
 300  * @post        If the callback is not needed,
 301  *              ode_external_encryption_unset_mount_event_cb() must be called.
 302  * @see         ode_external_encryption_mount()
 303  * @see         ode_external_encryption_unset_mount_event_cb()
 304  */
 305 ODE_API int ode_external_encryption_set_mount_event_cb(ode_mount_event_cb callback, void *user_data);
 306
 307 /**
 308  * @brief       Unregister a callback to get mount event of external storage
 309  * @details     Services can use this API to detach a callback to be called
 310  *              by mount event of external storage with encryption.
 311  * @since_tizen 4.0
 312  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 313  * @retval      #ODE_ERROR_NONE Successful
 314  * @see         ode_external_encryption_mount()
 315  * @see         ode_external_encryption_set_mount_event_cb()
 316  */
 317 ODE_API int ode_external_encryption_unset_mount_event_cb();
 318
 319 /**
 320  * @}
 321  */
 322
 323 #ifdef __cplusplus
 324 }
 325 #endif
 326
 327 #endif /* __CAPI_ODE_EXTERNAL_ENCRYPTION_H__ */