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       Mount external storage with encryption by given password.
  34  * @details     Administrator can use this API to mount encrypted external
  35  *              storage.
  36  * @since_tizen 3.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_TIMED_OUT Time out
  42  * @retval      #ODE_ERROR_KEY_REJECTED Password doen't match
  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_external_encryption_init_password().
  48  * @see         ode_external_encryption_encrypt()
  49  * @see         ode_external_encryption_umount()
  50  */
  51 ODE_API int ode_external_encryption_mount(const char* password);
  52
  53 /**
  54  * @brief       Umount external storage
  55  * @details     Administrator can use this API to unmount external 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_NOT_PERMITTED Operation not permitted
  62  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
  63  *              the privilege to call this API
  64  * @see         ode_external_encryption_mount()
  65  */
  66 ODE_API int ode_external_encryption_umount();
  67
  68 /**
  69  * @brief       Encrypt external storage by given password.
  70  * @details     Administrator can use this API to encrypt external storage.
  71  * @since_tizen 3.0
  72  * @param[in]   password The password to encrypt external storage
  73  * @param[in]   options Encryption options
  74  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
  75  * @retval      #ODE_ERROR_NONE Successful
  76  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
  77  * @retval      #ODE_ERROR_TIMED_OUT Time out
  78  * @retval      #ODE_ERROR_KEY_REJECTED Password doen't match
  79  * @retval      #ODE_ERROR_NOT_PERMITTED Operation not permitted
  80  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
  81  * @retval      #ODE_ERROR_NOT_SUPPORTED Given options are not supported
  82  *              the privilege to call this API
  83  * @see         ode_external_encryption_mount()
  84  * @see         ode_external_encryption_decrypt()
  85  * @see         ode_external_encryption_get_supported_options()
  86  */
  87 ODE_API int ode_external_encryption_encrypt(const char* password, unsigned int options);
  88
  89 /**
  90  * @brief       Decrypt external storage by given password.
  91  * @details     Administrator can use this API to decrypt external storage.
  92  * @since_tizen 3.0
  93  * @param[in]   password The password to decrypt external storage
  94  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
  95  * @retval      #ODE_ERROR_NONE Successful
  96  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
  97  * @retval      #ODE_ERROR_TIMED_OUT Time out
  98  * @retval      #ODE_ERROR_KEY_REJECTED Password doen't match
  99  * @retval      #ODE_ERROR_NOT_PERMITTED Operation not permitted
 100  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 101  *              the privilege to call this API
 102  * @pre         The password must match with what is set by
 103  *              ode_external_encryption_init_password().
 104  * @see         ode_external_encryption_encrypt()
 105  */
 106 ODE_API int ode_external_encryption_decrypt(const char* password);
 107
 108 /**
 109  * @brief       Recovery external encryption when there is something wrong.
 110  * @details     Administrator can use this API to recovery encrypted external
 111  *              storage when the password is missing or the encryption is
 112  *              corrupted. Note that this API will be erase all the contents
 113  *              in external storage.
 114  * @since_tizen 3.0
 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_TIMED_OUT Time out
 119  * @retval      #ODE_ERROR_NOT_PERMITTED Operation not permitted
 120  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 121  *              the privilege to call this API
 122  * @see         ode_external_encryption_encrypt()
 123  */
 124 ODE_API int ode_external_encryption_recovery();
 125
 126 /**
 127  * @brief       Checks whether the external encryption password was created
 128  * @details     Administrator can use this API to check if the password that
 129                 will be used for external storage encryption/decryption
 130                 exists.
 131  * @since_tizen 3.0
 132  * @param[out]  result Whether encryption password was created
 133  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 134  * @retval      #ODE_ERROR_NONE Successful
 135  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 136  * @retval      #ODE_ERROR_TIMED_OUT Time out
 137  * @retval      #ODE_ERROR_NOT_PERMITTED Operation not permitted
 138  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 139  *              the privilege to call this API
 140  * @see         ode_external_encryption_init_password()
 141  * @see         ode_external_encryption_clean_password()
 142  */
 143 ODE_API int ode_external_encryption_is_password_initialized(bool* result);
 144
 145 /**
 146  * @brief       Initialize external encryption password to given password
 147  * @details     Administrator can use this API to set new password that will be
 148                 used for external storage encryption/decryption.
 149  * @since_tizen 3.0
 150  * @param[in]   password The password to set
 151  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 152  * @retval      #ODE_ERROR_NONE Successful
 153  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 154  * @retval      #ODE_ERROR_TIMED_OUT Time out
 155  * @retval      #ODE_ERROR_NOT_PERMITTED Operation not permitted
 156  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 157  *              the privilege to call this API
 158  * @see         ode_external_encryption_change_password()
 159  * @see         ode_external_encryption_clean_password()
 160  * @see         ode_external_encryption_encrypt()
 161  * @see         ode_external_encryption_decrypt()
 162  * @see         ode_external_encryption_mount()
 163  */
 164 ODE_API int ode_external_encryption_init_password(const char* password);
 165
 166 /**
 167  * @brief       Remove external encryption password
 168  * @details     Administrator can use this API to delete password that was set
 169                 by ode_external_encryption_init_password().
 170  * @since_tizen 3.0
 171  * @param[in]   password The password to delete
 172  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 173  * @retval      #ODE_ERROR_NONE Successful
 174  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 175  * @retval      #ODE_ERROR_TIMED_OUT Time out
 176  * @retval      #ODE_ERROR_KEY_REJECTED old_password doen't match
 177  * @retval      #ODE_ERROR_NOT_PERMITTED Operation not permitted
 178  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 179  *              the privilege to call this API
 180  * @pre         The password must match with what is set by
 181  *              ode_external_encryption_init_password().
 182  * @see         ode_external_encryption_init_password()
 183  */
 184 ODE_API int ode_external_encryption_clean_password(const char* password);
 185
 186 /**
 187  * @brief       Change the password for external storage.
 188  * @details     Administrator can use this API to change password for external
 189  *              storage.
 190  * @since_tizen 3.0
 191  * @param[in]   old_password Current password of external storage
 192  * @param[in]   new_password The password to use newly for external storage
 193  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 194  * @retval      #ODE_ERROR_NONE Successful
 195  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 196  * @retval      #ODE_ERROR_TIMED_OUT Time out
 197  * @retval      #ODE_ERROR_KEY_REJECTED old_password doen't match
 198  * @retval      #ODE_ERROR_NOT_PERMITTED Operation not permitted
 199  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 200  *              the privilege to call this API
 201  * @pre         The password must match with what is set by
 202  *              ode_external_encryption_init_password().
 203  * @see         ode_external_encryption_encrypt()
 204  */
 205 ODE_API int ode_external_encryption_change_password(const char* old_password,
 206                                                                                                         const char* new_password);
 207
 208 /**
 209  * @brief       Verify if given password is external encryption password.
 210  * @details     Administrator can use this API to find if a password is used
 211                 by external encryption
 212  * @since_tizen 3.0
 213  * @param[int]  password The password to be verified
 214  * @param[out]  result The result of verification
 215  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 216  * @retval      #ODE_ERROR_NONE Successful
 217  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 218  * @retval      #ODE_ERROR_TIMED_OUT Time out
 219  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 220  *              the privilege to call this API
 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_verify_password(const char* password, bool* result);
 226
 227 /**
 228  * @brief       Get current encryption state of external storage.
 229  * @details     Administrator can use this API to get current encryption state
 230  *              of external storage.
 231  * @since_tizen 3.0
 232  * @param[out]  state The encryption state of external storage
 233  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 234  * @retval      #ODE_ERROR_NONE Successful
 235  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 236  * @retval      #ODE_ERROR_TIMED_OUT Time out
 237  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 238  *              the privilege to call this API
 239  * @see         ode_external_encryption_encrypt()
 240  * @see         ode_external_encryption_decrypt()
 241  */
 242 ODE_API int ode_external_encryption_get_state(int* state);
 243
 244 /*
 245  * @brief       Enumeration for external encryption options
 246  * @since_tizen 3.0
 247  */
 248 typedef enum {
 249     ODE_OPTION_EXTERNAL_ONLY_NEW_FILE  = 1 << 0, /**< Encrypt new files only  */
 250     ODE_OPTION_EXTERNAL_EXCEPT_FOR_MEDIA_FILE  = 1 << 1, /**< Encrypt non-media files only */
 251 } ode_options_external_e;
 252
 253 /**
 254  * @brief       Get supported options for encryption of external storage.
 255  * @details     Administrator can use this API to get which options are
 256                                 supported for encryption of external storage.
 257  * @since_tizen 3.0
 258  * @param[out]  option The logical OR of supported options in external storage
 259  * @return      #ODE_ERROR_NONE on success, otherwise a negative value
 260  * @retval      #ODE_ERROR_NONE Successful
 261  * @retval      #ODE_ERROR_INVALID_PARAMETER Invalid parameter
 262  * @retval      #ODE_ERROR_TIMED_OUT Time out
 263  * @retval      #ODE_ERROR_PERMISSION_DENIED The application does not have
 264  *              the privilege to call this API
 265  * @see         ode_external_encryption_encrypt()
 266  */
 267 ODE_API int ode_external_encryption_get_supported_options(unsigned int* options);
 268
 269 /**
 270  * @}
 271  */
 272
 273 #ifdef __cplusplus
 274 }
 275 #endif
 276
 277 #endif /* __CAPI_ODE_EXTERNAL_ENCRYPTION_H__ */