src/include/ckmc/ckmc-control.h

   1 /*
   2  *  Copyright (c) 2000 - 2014 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  * @file        ckmc-control.h
  18  * @version     1.0
  19  * @brief       Provides control functions for the key manager.
  20  */
  21
  22 #ifndef __TIZEN_CORE_CKMC_CONTROL_H
  23 #define __TIZEN_CORE_CKMC_CONTROL_H
  24
  25
  26 #include <sys/types.h>
  27 #include <ckmc/ckmc-error.h>
  28 #include <ckmc/ckmc-type.h>
  29
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /**
  36  * @addtogroup CAPI_KEY_MANAGER_CONTROL_MODULE
  37  * @{
  38  */
  39
  40 /**
  41  * @brief Decrypts a user key(DKEK) with password.
  42  *        A decrypted user key exists only on memory. If this API is called for the first time, a
  43  *        user key will be generated internally.
  44  *
  45  * @since_tizen 2.3
  46  * @privlevel platform
  47  * @privilege %http://tizen.org/privilege/keymanager.admin
  48  *
  49  * @remarks The user key is a randomly generated key used in encrypting user data. And the user key
  50  *          is protected by a user's password.
  51  *
  52  * @param[in] user      The user ID of a user whose key is decrypted
  53  * @param[in] password  The password used in decrypting a user key
  54  *
  55  * @return @c 0 on success,
  56  *         otherwise a negative error value
  57  *
  58  * @retval #CKMC_ERROR_NONE                   Successful
  59  * @retval #CKMC_ERROR_SERVER_ERROR           Failed to unlock user key
  60  * @retval #CKMC_ERROR_INVALID_PARAMETER      Invalid input parameter
  61  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED  Not correct password
  62  * @retval #CKMC_ERROR_PERMISSION_DENIED      Failed to access key manager
  63  *
  64  * @see ckmc_lock_user_key()
  65  * @see ckmc_remove_user_data()
  66  * @see ckmc_change_user_password()
  67  * @see ckmc_reset_user_password()
  68  */
  69 int ckmc_unlock_user_key(uid_t user, const char *password);
  70
  71 /**
  72  * @brief Removes a decrypted user key(DKEK) from memory
  73  *
  74  * @since_tizen 2.3
  75  * @privlevel platform
  76  * @privilege %http://tizen.org/privilege/keymanager.admin
  77  *
  78  * @param[in] user The user ID of a user whose key is removed from memory
  79  *
  80  * @return @c 0 on success,
  81  *         otherwise a negative error value
  82  *
  83  * @retval #CKMC_ERROR_NONE               Successful
  84  * @retval #CKMC_ERROR_INVALID_PARAMETER  Invalid input parameter
  85  * @retval #CKMC_ERROR_PERMISSION_DENIED  Failed to access key manager
  86  *
  87  * @see ckmc_unlock_user_key()
  88  * @see ckmc_remove_user_data()
  89  * @see ckmc_change_user_password()
  90  * @see ckmc_reset_user_password()
  91  */
  92 int ckmc_lock_user_key(uid_t user);
  93
  94 /**
  95  * @brief Removes user data from Store and erases a user key(DKEK) used for encryption.
  96  *
  97  * @since_tizen 2.3
  98  * @privlevel platform
  99  * @privilege %http://tizen.org/privilege/keymanager.admin
 100  *
 101  * @param[in] user The user ID of a user whose data and key are removed
 102  *
 103  * @return @c 0 on success,
 104  *         otherwise a negative error value
 105  *
 106  * @retval #CKMC_ERROR_NONE               Successful
 107  * @retval #CKMC_ERROR_INVALID_PARAMETER  Invalid input parameter
 108  * @retval #CKMC_ERROR_PERMISSION_DENIED  Failed to access key manager
 109  *
 110  * @see ckmc_unlock_user_key()
 111  * @see ckmc_lock_user_key()
 112  * @see ckmc_change_user_password()
 113  * @see ckmc_reset_user_password()
 114  */
 115 int ckmc_remove_user_data(uid_t user);
 116
 117 /**
 118  * @brief Changes a password for a user.
 119  *        The key manager decrypts a user key (DKEK) with old password and re-encrypts a user key
 120  *        with new password.
 121  *
 122  * @since_tizen 2.3
 123  * @privlevel platform
 124  * @privilege %http://tizen.org/privilege/keymanager.admin
 125  *
 126  * @param[in] user          The user ID of a user whose user key is re-encrypted
 127  * @param[in] old_password  The password used in decrypting a user key
 128  * @param[in] new_password  The password used in re-encrypting a user key
 129  *
 130  * @return @c 0 on success,
 131  *         otherwise a negative error value
 132  *
 133  * @retval #CKMC_ERROR_NONE                   Successful
 134  * @retval #CKMC_ERROR_INVALID_PARAMETER      Invalid input parameter
 135  * @retval #CKMC_ERROR_AUTHENTICATION_FAILED  Not correct password
 136  * @retval #CKMC_ERROR_BAD_REQUEST            No information about old password
 137  * @retval #CKMC_ERROR_PERMISSION_DENIED      Failed to access key manager
 138  *
 139  * @see ckmc_unlock_user_key()
 140  * @see ckmc_lock_user_key()
 141  * @see ckmc_remove_user_data()
 142  * @see ckmc_reset_user_password()
 143  */
 144 int ckmc_change_user_password(uid_t user, const char *old_password, const char *new_password);
 145
 146 /**
 147  * @brief Changes a password for a user without old password.
 148  *
 149  * @since_tizen 2.3
 150  * @privlevel platform
 151  * @privilege %http://tizen.org/privilege/keymanager.admin
 152  *
 153  * @param[in] user          The user ID of a user whose user key is re-encrypted
 154  * @param[in] new_password  The password used in re-encrypting a user key
 155  *
 156  * @return @c 0 on success,
 157  *         otherwise a negative error value
 158  *
 159  * @retval #CKMC_ERROR_NONE               Successful
 160  * @retval #CKMC_ERROR_INVALID_PARAMETER  Invalid input parameter
 161  * @retval #CKMC_ERROR_BAD_REQUEST        A user key is not unlocked
 162  * @retval #CKMC_ERROR_PERMISSION_DENIED  Failed to access key manager
 163  *
 164  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 165  *
 166  * @see ckmc_unlock_user_key()
 167  * @see ckmc_lock_user_key()
 168  * @see ckmc_remove_user_data()
 169  * @see ckmc_change_user_password()
 170  *
 171  */
 172 int ckmc_reset_user_password(uid_t user, const char *new_password);
 173
 174 /**
 175  * @deprecated, see ckmc_set_permission_by_adm()
 176  * @brief Allows another application to access client's application data
 177  *
 178  * @since_tizen 2.3
 179  * @privlevel platform
 180  * @privilege %http://tizen.org/privilege/keymanager.admin
 181  *
 182  * @remarks Data identified by @a alias should exist
 183  *
 184  * @param[in] user        User ID of a user whose data will be affected
 185  * @param[in] owner       Package id of the data owner
 186  * @param[in] alias       Data alias for which access will be granted
 187  * @param[in] accessor    Package id of the application that will gain access rights
 188  * @param[in] granted     Rights granted for @a accessor application
 189  *
 190  * @return @c 0 on success, otherwise a negative error value
 191  *
 192  * @retval #CKMC_ERROR_NONE                 Successful
 193  * @retval #CKMC_ERROR_INVALID_PARAMETER    Input parameter is invalid
 194  * @retval #CKMC_ERROR_DB_LOCKED            A user key is not loaded in memory (a user is not logged
 195  *                                          in)
 196  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN     Alias does not exist
 197  * @retval #CKMC_ERROR_PERMISSION_DENIED    Failed to access key manager
 198  *
 199  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 200  *
 201  * @see ckmc_set_permission_by_adm()
 202  * @see ckmc_set_permission()
 203  */
 204 int ckmc_allow_access_by_adm(uid_t user,
 205                              const char *owner,
 206                              const char *alias,
 207                              const char *accessor,
 208                              ckmc_access_right_e granted);
 209
 210 /**
 211  * @brief Allows another application to access client's application data
 212  *
 213  * @since_tizen 3.0
 214  * @privlevel platform
 215  * @privilege %http://tizen.org/privilege/keymanager.admin
 216  *
 217  * @remarks Data identified by @a alias should exist
 218  * @remarks @a alias must contain owner label (<owner label><ckmc_label_name_separator><name>)
 219  *
 220  * @param[in] user        User ID of a user whose data will be affected
 221  * @param[in] alias       Data alias for which access will be granted
 222  * @param[in] accessor    Package id of the application that will gain access rights
 223  * @param[in] permissions Mask of permissions granted for @a accessor application
 224  *                        (@a ckmc_permission_e)
 225  *                        (previous permission mask will be replaced with the new mask value)
 226  *
 227  * @return @c 0 on success, otherwise a negative error value
 228  *
 229  * @retval #CKMC_ERROR_NONE                 Successful
 230  * @retval #CKMC_ERROR_INVALID_PARAMETER    Input parameter is invalid
 231  * @retval #CKMC_ERROR_DB_LOCKED            A user key is not loaded in memory (a user is not logged
 232  *                                          in)
 233  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN     Alias does not exist
 234  * @retval #CKMC_ERROR_PERMISSION_DENIED    Failed to access key manager
 235  *
 236  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 237  *
 238  * @see ckmc_set_permission()
 239  */
 240 int ckmc_set_permission_by_adm(uid_t user, const char *alias, const char *accessor, int mask);
 241
 242
 243 /**
 244  * @deprecated, see ckmc_set_permission_by_adm()
 245  * @brief Revokes another application's access to client's application data
 246  *
 247  * @since_tizen 2.3
 248  * @privlevel platform
 249  * @privilege %http://tizen.org/privilege/keymanager.admin
 250  *
 251  * @remarks Data identified by @a alias should exist
 252  * @remarks Only access previously granted with ckmc_allow_access can be revoked.
 253  *
 254  * @param[in] user        User ID of a user whose data will be affected
 255  * @param[in] owner       Package id of the data owner
 256  * @param[in] alias       Data alias for which access will be revoked
 257  * @param[in] accessor    Package id of the application that will lose access rights
 258  *
 259  * @return @c 0 on success, otherwise a negative error value
 260  *
 261  * @retval #CKMC_ERROR_NONE                 Successful
 262  * @retval #CKMC_ERROR_INVALID_PARAMETER    Input parameter is invalid or the @a accessor doesn't
 263  *                                          have access to @a alias
 264  * @retval #CKMC_ERROR_DB_LOCKED            A user key is not loaded in memory (a user is not logged
 265  *                                          in)
 266  * @retval #CKMC_ERROR_DB_ALIAS_UNKNOWN     Alias does not exist
 267  * @retval #CKMC_ERROR_PERMISSION_DENIED    Failed to access key manager
 268  *
 269  * @pre User is already logged in and the user key is already loaded into memory in plain text form.
 270  *
 271  * @see ckmc_set_permission()
 272  * @see ckmc_set_permission_by_adm()
 273  */
 274 int ckmc_deny_access_by_adm(uid_t user, const char *owner, const char *alias, const char *accessor);
 275
 276 /**
 277  * @}
 278  */
 279
 280 #ifdef __cplusplus
 281 }
 282 #endif
 283
 284
 285 #endif /* __TIZEN_CORE_CKMC_CONTROL_H */