include/privilege-control.h

   1 /*
   2  * libprivilege control
   3  *
   4  * Copyright (c) 2000 - 2012 Samsung Electronics Co., Ltd All Rights Reserved
   5  *
   6  * Contact: Kidong Kim <kd0228.kim@samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  *
  20  */
  21
  22 #include <stdbool.h>
  23 #include <sys/types.h>
  24
  25 #ifndef _PRIVILEGE_CONTROL_H_
  26 #define _PRIVILEGE_CONTROL_H_
  27
  28 /* Macros for converting preprocessor token to string */
  29 #define STRINGIFY(x) #x
  30 #define TOSTRING(x) STRINGIFY(x)
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif // __cplusplus
  35
  36 #ifndef API
  37 #define API __attribute__((visibility("default")))
  38 #endif // API
  39
  40 #define DEPRECATED __attribute__((deprecated))
  41 #define UNUSED __attribute__((unused))
  42
  43 /* error codes */
  44 #define PC_OPERATION_SUCCESS            ((int)0)
  45 #define PC_ERR_FILE_OPERATION           -1
  46 #define PC_ERR_MEM_OPERATION            -2
  47 #define PC_ERR_NOT_PERMITTED            -3
  48 #define PC_ERR_INVALID_PARAM            -4
  49 #define PC_ERR_INVALID_OPERATION        -5
  50 #define PC_ERR_DB_OPERATION             -6
  51
  52 /// Label is taken by another application
  53 #define PC_ERR_DB_LABEL_TAKEN           -7
  54
  55 /// Query fails during preparing a SQL statement
  56 #define PC_ERR_DB_QUERY_PREP            -8
  57
  58 /// Query fails during binding to a SQL statement
  59 #define PC_ERR_DB_QUERY_BIND            -9
  60
  61 /// Query fails during stepping a SQL statement
  62 #define PC_ERR_DB_QUERY_STEP            -10
  63
  64 /// Unable to establish a connection with the database
  65 #define PC_ERR_DB_CONNECTION            -11
  66
  67 /// There is no application with such app_id
  68 #define PC_ERR_DB_NO_SUCH_APP           -12
  69
  70 /// There already exists a permission with this name and type
  71 #define PC_ERR_DB_PERM_FORBIDDEN        -13
  72
  73
  74 typedef enum {
  75        APP_TYPE_WGT,
  76        APP_TYPE_OSP,
  77        APP_TYPE_EFL,
  78        APP_TYPE_OTHER,
  79 } app_type_t;
  80
  81 typedef enum {
  82         APP_PATH_PRIVATE,
  83         APP_PATH_GROUP_RW,
  84         APP_PATH_PUBLIC_RO,
  85         APP_PATH_SETTINGS_RW,
  86         APP_PATH_ANY_LABEL,
  87 } app_path_type_t;
  88
  89 /* APIs - used by applications */
  90 int control_privilege(void) DEPRECATED;
  91
  92 int set_privilege(const char* pkg_name) DEPRECATED;
  93
  94 /**
  95  * Set DAC and SMACK privileges for application.
  96  * This function is meant to be call by the application launcher just before
  97  * it launches an application. It will setup DAC and SMACK privileges based
  98  * on app type and accesses.
  99  * It must be called with root privileges, which will be dropped in the function.
 100  *
 101  * @param name package name
 102  * @param type application type (currently not used)
 103  * @param path file system path to the binary
 104  * @return PC_OPERATION_SUCCESS on success, PC_ERR_* on error
 105  */
 106 int perm_app_set_privilege(const char* name, const char* type, const char* path);
 107 int set_app_privilege(const char* name, const char* type, const char* path) DEPRECATED;
 108
 109 /**
 110  * For a UNIX socket endpoint determine the other side's pkg_id. Caller is
 111  * responsible for freeing the return widget id.
 112  *
 113  * @param  sockfd  socket file descriptor
 114  * @return         id of the connecting widget on success, NULL on failure.
 115  */
 116 char* perm_app_id_from_socket(int sockfd);
 117 char* app_id_from_socket(int sockfd) DEPRECATED;
 118
 119 /**
 120  * Adds an application to the database if it doesn't already exist. It is needed
 121  * for tracking lifetime of an application. It must be called by privileged
 122  * user, before using any other perm_app_* function regarding that application.
 123  * It must be called within database transaction started with perm_begin() and
 124  * finished with perm_end(). It may be called more than once during installation.
 125  *
 126  * @param  pkg_id  application identifier
 127  * @return         PC_OPERATION_SUCCESS on success, PC_ERR_* on error
 128  */
 129 int perm_app_install(const char* pkg_id);
 130 int app_install(const char* pkg_id) DEPRECATED;
 131
 132 /**
 133  * TODO: This function currently only validates input param. It will comply
 134  *       with its role when db is prepared for single "User" label for all apps.
 135  * Removes an application from the database with it's permissions, rules and
 136  * directories, enabling future installation of the application with the same
 137  * pkg_id. It is needed for tracking lifetime of an application. It must be
 138  * called by privileged user and within database transaction started with
 139  * perm_begin() and finished with perm_end().
 140  *
 141  * @param  pkg_id  application identifier
 142  * @return         PC_OPERATION_SUCCESS on success, PC_ERR_* on error
 143  */
 144 int perm_app_uninstall(const char* pkg_id);
 145 int app_uninstall(const char* pkg_id) DEPRECATED;
 146
 147 /**
 148  * Inform about installation of new Anti Virus application.
 149  * It is intended to be called during Anti Virus installation.
 150  * It will give this application SMACK rules to RWX access to all other apps
 151  * installed in system.
 152  * It must be called by privileged user.
 153  *
 154  * @param app_id application identifier
 155  * @return PC_OPERATION_SUCCESS on success, PC_ERR_* on error.
 156  */
 157 int app_register_av(const char* app_av_id) DEPRECATED;
 158
 159 /**
 160  * Grant SMACK permissions based on permissions list.
 161  * It is intended to be called during app installation.
 162  * It will construct SMACK rules based on permissions list, grant them
 163  * and store it in a file, so they will be automatically granted on
 164  * system boot.
 165  * It must be called by privileged user.
 166  * THIS FUNCTION IS NOW DEPRECATED. app_enable_permissions() SHOULD BE USED INSTEAD.
 167  *
 168  *
 169  * @param app_id application identifier
 170  * @param perm_list array of permission names, last element must be NULL
 171  * @return PC_OPERATION_SUCCESS on success, PC_ERR_* on error
 172  */
 173 int app_add_permissions(const char* app_id, const char** perm_list) DEPRECATED;
 174
 175 /**
 176  * Grant temporary SMACK permissions based on permissions list.
 177  * It will construct SMACK rules based on permissions list, grant them,
 178  * but not store it anywhere, so they won't be granted again on system boot.
 179  * It must be called by privileged user.
 180  * THIS FUNCTION IS NOW DEPRECATED. app_enable_permissions() SHOULD BE USED INSTEAD.
 181  *
 182  *
 183  * @param app_id application identifier
 184  * @param perm_list array of permission names, last element must be NULL
 185  * @return PC_OPERATION_SUCCESS on success, PC_ERR_* on error
 186  */
 187 int app_add_volatile_permissions(const char* app_id, const char** perm_list) DEPRECATED;
 188
 189 /**
 190  * Grant SMACK permissions based on permissions list.
 191  * It is intended to be called during app installation.
 192  * It will construct SMACK rules based on permissions list, grant them
 193  * and store it in a database, so they will be automatically granted on
 194  * system boot, when persistent mode is enabled.
 195  * It must be called by privileged user.
 196  *
 197  * @param  pkg_id      application identifier
 198  * @param  app_type    application type
 199  * @param  perm_list   array of permission names, last element must be NULL
 200  * @param  persistent  boolean for choosing between persistent and temporary rules
 201  * @return             PC_OPERATION_SUCCESS on success, PC_ERR_* on error
 202  */
 203 int perm_app_enable_permissions(const char* pkg_id, app_type_t app_type, const char** perm_list, bool persistent);
 204 int app_enable_permissions(const char* pkg_id, app_type_t app_type, const char** perm_list, bool persistent) DEPRECATED;
 205
 206 /**
 207  * Removes previously granted SMACK permissions based on permissions list.
 208  * It will remove given permissions from an application, leaving other granted
 209  * permissions untouched. Results will be persistent.
 210  * It must be called by privileged user.
 211  *
 212  * @param  pkg_id     application identifier
 213  * @param  app_type   application type
 214  * @param  perm_list  array of permission names, last element must be NULL
 215  * @return            PC_OPERATION_SUCCESS on success, PC_ERR_* on error
 216  */
 217 int perm_app_disable_permissions(const char* pkg_id, app_type_t app_type, const char** perm_list);
 218 int app_disable_permissions(const char* pkg_id, app_type_t app_type, const char** perm_list) DEPRECATED;
 219
 220 /**
 221  * TODO: This function currently only validates input param. It will comply
 222  *       with its role when db is prepared for single "User" label for all apps.
 223  * Removes all application's permissions, rules and directories registered in
 224  * the database. It must be called by privileged user.
 225  *
 226  * @param  pkg_id  application identifier
 227  * @return         PC_OPERATION_SUCCESS on success, PC_ERR_* on error
 228  */
 229 int perm_app_revoke_permissions(const char* pkg_id);
 230 int app_revoke_permissions(const char* pkg_id) DEPRECATED;
 231
 232 /**
 233  * Removes all application's permissions which are not persistent. It must be
 234  * called by privileged user.
 235  *
 236  * @param  pkg_id  application identifier
 237  * @return         PC_OPERATION_SUCCESS on success, PC_ERR_* on error
 238  */
 239 int perm_app_reset_permissions(const char* pkg_id);
 240 int app_reset_permissions(const char* pkg_id) DEPRECATED;
 241
 242 /**
 243  * Recursively set SMACK access labels for an application directory
 244  * and execute labels for executable files.
 245  * This function should be called once during app installation.
 246  * Results will be persistent on the file system.
 247  * It must be called by privileged user.
 248  * THIS FUNCTION IS NOW DEPRECATED. perm_app_setup_path() SHOULD BE USED INSTEAD.
 249  *
 250  * @param app_label label name
 251  * @param path directory path
 252  * @return PC_OPERATION_SUCCESS on success, PC_ERR_* on error
 253  */
 254 int app_label_dir(const char* app_label, const char* path) DEPRECATED;
 255
 256 /**
 257  * Recursively set SMACK access and transmute labels for an application
 258  * directory and add SMACK rule for application.
 259  * This function should be called once during app installation.
 260  * Results will be persistent on the file system.
 261  * It must be called by privileged user.
 262  * Labels app_label and shared_label should not be equal.
 263  * THIS FUNCTION IS NOW DEPRECATED. app_setup_path() SHOULD BE USED INSTEAD.
 264  *
 265  * @param app_label label name, used as subject for SMACK rule
 266  * @param shared_label, used as object for SMACK rule
 267  * @param path directory path
 268  * @return PC_OPERATION_SUCCESS on success, PC_ERR_* on error
 269  */
 270 int app_label_shared_dir(const char* app_label, const char* shared_label,
 271                                                  const char* path) DEPRECATED;
 272
 273 /**
 274  * Add SMACK rx rules for application identifiers to shared_label.
 275  * This function should be called during app installation.
 276  * It must be called by privileged user.
 277  * THIS FUNCTION IS NOW DEPRECATED. NO REPLACEMENT IS NEEDED.
 278  *
 279  * @param shared_label label of the shared resource
 280  * @param app_list list of application SMACK identifiers
 281  * @return PC_OPERATION_SUCCESS on success, PC_ERR_* on error
 282  */
 283 int add_shared_dir_readers(const char* shared_label, const char** app_list) DEPRECATED;
 284
 285 /**
 286  * Sets SMACK labels for an application directory (recursively) or for an executable/symlink
 287  * file. The exact behavior depends on app_path_type argument:
 288  *      - APP_PATH_PRIVATE: label with app's label, set access label on everything
 289  *    and execute label on executable files and symlinks to executable files
 290  *
 291  *      - APP_PATH_GROUP_RW: label with given shared_label, set access label on
 292  *        everything and enable transmute on directories. Also give pkg_id full access
 293  *        to the shared label.
 294  *
 295  *      - APP_PATH_PUBLIC_RO: label with autogenerated label, set access label on
 296  *        everything and enable transmute on directories. Give full access to the label to
 297  *        pkg_id and RX access to all other apps.
 298  *
 299  *      - APP_PATH_SETTINGS_RW: label with autogenerated label, set access label on
 300  *        everything and enable transmute on directories. Give full access to the label to
 301  *        pkg_id and RWX access to all appsetting apps.
 302  *
 303  * This function should be called during app installation.
 304  * Results will be persistent on the file system.
 305  * It must be called by privileged user.
 306  *
 307  * @param  pkg_id         application identifier
 308  * @param  path           file or directory path
 309  * @param  app_path_type  application path type
 310  * @param  shared_label   optional argument for APP_PATH_GROUP_RW and
 311  *                        APP_PATH_ANY_LABEL path type; type is const char*
 312  * @return                PC_OPERATION_SUCCESS on success, PC_ERR_* on error
 313  */
 314 int perm_app_setup_path(const char* pkg_id, const char* path, app_path_type_t app_path_type, ...);
 315 int app_setup_path(const char* pkg_id, const char* path, app_path_type_t app_path_type, ...) DEPRECATED;
 316
 317 /**
 318  * Make two applications "friends", by giving them both full permissions on
 319  * each other.
 320  * Results will be persistent on the file system. Must be called after
 321  * app_add_permissions() has been called for each application.
 322  * It must be called by privileged user.
 323  *
 324  * @param pkg_id1 first application identifier
 325  * @param pkg_id2 second application identifier
 326  * @return PC_OPERATION_SUCCESS on success, PC_ERR_* on error
 327  */
 328 int perm_app_add_friend(const char* pkg_id1, const char* pkg_id2);
 329 int app_add_friend(const char* pkg_id1, const char* pkg_id2) DEPRECATED;
 330
 331 /**
 332  * Modify SMACK rules to give access from (subject)customer_label to (object)
 333  * provider_label.
 334  * Note: This function will do nothing if subject has already rwxat access to
 335  * object. You can revoke this modyfication by calling app_rovoke_access.
 336  *
 337  * @param subject - label of client application
 338  * @param object  - label of provider application
 339  * @return PC_OPERATION_SUCCESS on success, PC_ERR_* on error
 340  */
 341 int app_give_access(const char* subject, const char* object, const char* permission);
 342
 343 /**
 344  * Revoke access granted by app_give_access. This function will not remove
 345  * accesses that were granted before app_give_access call.
 346  *
 347  * @param subject - label of client application
 348  * @param object  - label of provider application
 349  * @return PC_OPERATION_SUCCESS on success, PC_ERR_* on error
 350  */
 351 int app_revoke_access(const char* subject, const char* object);
 352
 353 /**
 354  * Adds new feature to the database. It must be called by privileged user and
 355  * within database transaction started with perm_begin() and finished with
 356  * perm_end().
 357  *
 358  * @param  app_type          application type
 359  * @param  api_feature_name  name of newly added feature
 360  * @param  smack_rule_set    set of rules required by the feature - NULL terminated
 361  *                           list of NULL terminated rules.
 362  * @param  list_of_db_gids   list of gids required to access databases controlled
 363  *                           by the feature
 364  * @return                   PC_OPERATION_SUCCESS on success, PC_ERR_* on error
 365  */
 366 int perm_add_api_feature(app_type_t app_type,
 367                          const char* api_feature_name,
 368                          const char** set_smack_rule_set,
 369                          const gid_t* list_of_db_gids,
 370                          size_t list_size);
 371
 372 int add_api_feature(app_type_t app_type,
 373                     const char* api_feature_name,
 374                     const char** set_smack_rule_set,
 375                     const gid_t* list_of_db_gids,
 376                     size_t list_size) DEPRECATED;
 377
 378 /**
 379  * Starts exclusive database transaction. Run before functions modifying
 380  * database.
 381  *
 382  * @return PC_OPERATION_SUCCESS on success, PC_ERR_* on error
 383  */
 384 int perm_begin(void);
 385
 386 /**
 387  * Ends exclusive database transaction. Run after functions modifying database.
 388  * If an error occurred during the transaction then all modifications will be
 389  * rolled back.
 390  *
 391  * @return PC_OPERATION_SUCCESS on success, PC_ERR_* on error
 392  */
 393 int perm_end(void);
 394
 395 /**
 396 * Run to rollback any privilege modification.
 397 *
 398 * @return PC_OPERATION_SUCCESS on success,
 399 *         PC_ERR_* on error
 400 */
 401 int perm_rollback(void);
 402
 403 /**
 404  * Get message connected to error code.
 405  *
 406  * @param errnum error code
 407  * @return string describing the error code
 408  */
 409 const char* perm_strerror(int errnum);
 410
 411 #ifdef __cplusplus
 412 }
 413 #endif // __cplusplus
 414
 415 #endif // _PRIVILEGE_CONTROL_H_