src/include/security-manager.h

   1 /*
   2  *  Copyright (c) 2000 - 2014 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  *  Contact: Rafal Krypa <r.krypa@samsung.com>
   5  *
   6  *  Licensed under the Apache License, Version 2.0 (the "License");
   7  *  you may not use this file except in compliance with the License.
   8  *  You may obtain a copy of the License at
   9  *
  10  *      http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  *  Unless required by applicable law or agreed to in writing, software
  13  *  distributed under the License is distributed on an "AS IS" BASIS,
  14  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  *  See the License for the specific language governing permissions and
  16  *  limitations under the License
  17  *
  18  *      Security Manager library header
  19  */
  20 /*
  21  * @file        security-manager.h
  22  * @author      Pawel Polawski (p.polawski@samsung.com)
  23  * @version     1.0
  24  * @brief       This file contains header of security-manager API
  25  */
  26
  27 #ifndef SECURITY_MANAGER_H_
  28 #define SECURITY_MANAGER_H_
  29
  30 #include <sys/types.h>
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /*! \brief return code of API functions */
  37 enum lib_retcode {
  38     SECURITY_MANAGER_SUCCESS,
  39     SECURITY_MANAGER_ERROR_UNKNOWN,
  40     SECURITY_MANAGER_ERROR_INPUT_PARAM,
  41     SECURITY_MANAGER_ERROR_MEMORY,
  42     SECURITY_MANAGER_ERROR_REQ_NOT_COMPLETE,
  43     SECURITY_MANAGER_ERROR_AUTHENTICATION_FAILED,
  44     SECURITY_MANAGER_ERROR_ACCESS_DENIED,
  45 };
  46
  47 /*! \brief accesses types for application installation paths*/
  48 enum app_install_path_type {
  49     //accessible read-write only for applications with same package id
  50     SECURITY_MANAGER_PATH_PRIVATE,
  51     //read-write access for all applications
  52     SECURITY_MANAGER_PATH_PUBLIC,
  53     //read only access for all applications
  54     SECURITY_MANAGER_PATH_PUBLIC_RO,
  55     //this is only for range limit
  56     SECURITY_MANAGER_ENUM_END
  57 };
  58
  59 /**
  60  * This enum has values equivalent to gumd user type.
  61  * The gum-utils help states that
  62  * "usertype can be system(1), admin(2), guest(3), normal(4)."
  63  */
  64 enum security_manager_user_type {
  65     SM_USER_TYPE_NONE   = 0,/*<-this should not be used, if it is used, there will be an error returned by SM*/
  66     SM_USER_TYPE_SYSTEM = 1,
  67     SM_USER_TYPE_ADMIN  = 2,
  68     SM_USER_TYPE_GUEST  = 3,
  69     SM_USER_TYPE_NORMAL = 4,
  70     SM_USER_TYPE_ANY = 5,/*<-this value may be used only for setting policies and not during user adding*/
  71     SM_USER_TYPE_END
  72 };
  73 typedef enum security_manager_user_type security_manager_user_type;
  74
  75 /*! \brief data structure responsible for handling informations
  76  * required to install / uninstall application */
  77 struct app_inst_req;
  78 typedef struct app_inst_req app_inst_req;
  79
  80 /*! \brief data structure responsible for handling informations
  81  * required to manage users */
  82 struct user_req;
  83 typedef struct user_req user_req;
  84
  85 /*! \brief data structure responsible for handling policy updates
  86  *  required to manage users' and applications' permissions */
  87 struct policy_update_req;
  88 typedef struct policy_update_req policy_update_req;
  89
  90 /*! \brief data structure responsible for handling single policy entry*/
  91 struct policy_entry;
  92 typedef struct policy_entry policy_entry;
  93
  94 /*! \brief wildcard to be used in requests to match all possible values of given field.
  95  *         Use it, for example when it is desired to list or apply policy change for all
  96  *         users or all apps for selected user.
  97  */
  98 #define SECURITY_MANAGER_ANY "#"
  99
 100 /*! \brief value denoting delete operation on specific policy. It can only be used
 101  *         in update policy operation, passed to either security_manager_policy_entry_admin_set_level
 102  *         or security_manager_policy_entry_set_level.
 103  */
 104 #define SECURITY_MANAGER_DELETE "DELETE"
 105
 106 /**
 107  * This function translates lib_retcode error codes to strings describing
 108  * errors.
 109  * @param[in] rc error code of lib_retcode type
 110  * @return string describing error for error code
 111  */
 112 const char *security_manager_strerror(enum lib_retcode rc);
 113
 114 /*
 115  * This function is responsible for initialize app_inst_req data structure
 116  * It uses dynamic allocation inside and user responsibility is to call
 117  * app_inst_req_free() for freeing allocated resources
 118  *
 119  * \param[in] Address of pointer for handle app_inst_req structure
 120  * \return API return code or error code
 121  */
 122 int security_manager_app_inst_req_new(app_inst_req **pp_req);
 123
 124 /*
 125  * This function is used to free resources allocated by calling app_inst_req_new()
 126  *  \param[in] Pointer handling allocated app_inst_req structure
 127  */
 128 void security_manager_app_inst_req_free(app_inst_req *p_req);
 129
 130 /*
 131  * This function is used to set up application identifier in app_inst_req structure
 132  *
 133  * \param[in] Pointer handling app_inst_req structure
 134  * \param[in] Application identifier
 135  * \return API return code or error code
 136  */
 137 int security_manager_app_inst_req_set_app_id(app_inst_req *p_req, const char *app_id);
 138
 139 /*
 140  * This function is used to set up package identifier in app_inst_req structure
 141  *
 142  * \param[in] Pointer handling app_inst_req structure
 143  * \param[in] Package identifier
 144  * \return API return code or error code
 145  */
 146 int security_manager_app_inst_req_set_pkg_id(app_inst_req *p_req, const char *pkg_id);
 147
 148 /*
 149  * This function is used to add privilege to app_inst_req structure,
 150  * it can be called multiple times
 151  *
 152  * \param[in] Pointer handling app_inst_req structure
 153  * \param[in] Application privilager
 154  * \return API return code or error code
 155  */
 156 int security_manager_app_inst_req_add_privilege(app_inst_req *p_req, const char *privilege);
 157
 158 /*
 159  * This function is used to add application path to app_inst_req structure,
 160  * it can be called multiple times
 161  *
 162  * \param[in] Pointer handling app_inst_req structure
 163  * \param[in] Application path
 164  * \param[in] Application path type
 165  * \return API return code or error code
 166  */
 167 int security_manager_app_inst_req_add_path(app_inst_req *p_req, const char *path, const int path_type);
 168
 169 /*
 170  * This function is used to set up user identifier in app_inst_req structure.
 171  * This field simplifies support for online and offline modes.
 172  *
 173  * \param[in] Pointer handling app_inst_req structure
 174  * \param[in] User identifier (UID)
 175  * \return API return code or error code
 176  */
 177 int security_manager_app_inst_req_set_uid(app_inst_req *p_req,
 178                                           const uid_t uid);
 179
 180 /*
 181  * This function is used to install application based on
 182  * using filled up app_inst_req data structure
 183  *
 184  * \param[in] Pointer handling app_inst_req structure
 185  * \return API return code or error code: it would be
 186  * - SECURITY_MANAGER_SUCCESS on success,
 187  * - SECURITY_MANAGER_ERROR_AUTHENTICATION_FAILED when user does not
 188  * have rights to install requested directories,
 189  * - SECURITY_MANAGER_ERROR_UNKNOWN on other errors.
 190  */
 191 int security_manager_app_install(const app_inst_req *p_req);
 192
 193 /*
 194  * This function is used to uninstall application based on
 195  * using filled up app_inst_req data structure
 196  *
 197  * \param[in] Pointer handling app_inst_req structure
 198  * \return API return code or error code
 199  */
 200 int security_manager_app_uninstall(const app_inst_req *p_req);
 201
 202 /**
 203  * Get package id of a given application
 204  *
 205  * On successful call pkg_id should be freed by the caller using free() function
 206  *
 207  * \param[out] Pointer to package identifier string
 208  * \param[in]  Application identifier
 209  * \return API return code or error code
 210  */
 211 int security_manager_get_app_pkgid(char **pkg_id, const char *app_id);
 212
 213 /**
 214  * Compute smack label for given application id and set it for
 215  * currently running process
 216  *
 217  * \param[in] Application identifier
 218  * \return API return code or error code
 219  */
 220 int security_manager_set_process_label_from_appid(const char *app_id);
 221
 222 /**
 223  * For given app_id and current user, calculate allowed privileges that give
 224  * direct access to file system resources. Then add current process to
 225  * supplementary groups that are assigned to these resources.
 226  *
 227  * In Tizen some sensitive resources are being accessed by applications directly.
 228  * The resources, being file system objects, are owned by dedicated GIDs and only
 229  * processes in those UNIX groups can access them. This function is used for
 230  * adding application process to all permitted groups that are assigned to such
 231  * privileges.
 232  *
 233  * \param[in] Application identifier
 234  * \return API return code or error code
 235  */
 236 int security_manager_set_process_groups_from_appid(const char *app_id);
 237
 238 /**
 239  * The above launcher functions, manipulating process Smack label and group,
 240  * require elevated privileges. Since they will be called by launcher after fork,
 241  * in the process for the application, privileges should be dropped before
 242  * running an actual application. This function is a helper for that purpose -
 243  * it drops capabilities from the process.
 244  *
 245  * \return API return code or error code
 246  */
 247 int security_manager_drop_process_privileges(void);
 248
 249 /**
 250  * A convenience function for launchers for preparing security context for an
 251  * application process. It should be called after fork in the new process, before
 252  * running the application in it.
 253  * It is aimed to cover most common cases and will internally call other, more
 254  * specialized security-manager functions for launchers.
 255  * Currently it just calls:
 256  * - security_manager_set_process_label_from_appid
 257  * - security_manager_set_process_groups_from_appid
 258  * - security_manager_drop_process_privileges
 259  *
 260  * \param[in] Application identifier
 261  * \return API return code or error code
 262  */
 263 int security_manager_prepare_app(const char *app_id);
 264
 265 /*
 266  * This function is responsible for initialization of user_req data structure.
 267  * It uses dynamic allocation inside and user responsibility is to call
 268  * security_manager_user_req_free() for freeing allocated resources.
 269  *
 270  * @param[in] Address of pointer for handle user_req structure
 271  * @return API return code or error code
 272  */
 273 int security_manager_user_req_new(user_req **pp_req);
 274
 275 /*
 276  * This function is used to free resources allocated by
 277  * security_manager_user_req_new()
 278  *
 279  * @param[in] Pointer handling allocated user_req structure
 280  */
 281 void security_manager_user_req_free(user_req *p_req);
 282
 283 /*
 284  * This function is used to set up user identifier in user_req structure.
 285  *
 286  * @param p_req Structure containing user data filled during this function call
 287  * @param uid User identifier to be set
 288  * @return API return code or error code
 289  */
 290 int security_manager_user_req_set_uid(user_req *p_req, uid_t uid);
 291
 292 /*
 293  * This function is used to set up user type in user_req structure.
 294  *
 295  * @param p_req Structure containing user data filled during this function call
 296  * @param utype User type to be set
 297  * @return API return code or error code
 298  */
 299 int security_manager_user_req_set_user_type(user_req *p_req, security_manager_user_type utype);
 300
 301 /*
 302  * This function should be called to inform security-manager about adding new user.
 303  * This function succeeds only when is called by privileged user.
 304  * Otherwise it just returns SECURITY_MANAGER_ERROR_AUTHENTICATION_FAILED and does nothing.
 305  *
 306  * It adds all required privileges to a newly created user.
 307  * User data are passed through  pointer 'p_req'.
 308  * @param p_req Structure containing user data filled before calling this
 309  * uid and user type needs to be filled in p_req structure,
 310  * otherwise SECURITY_MANAGER_ERROR_INPUT_PARAM will be returned.
 311  * @return API return code or error code.
 312  */
 313 int security_manager_user_add(const user_req *p_req);
 314
 315 /*
 316  * This function should be called to inform security-manager about removing a user.
 317  * This function succeeds only when is called by privileged user.
 318  * Otherwise it just returns SECURITY_MANAGER_ERROR_AUTHENTICATION_FAILED and does nothing.
 319  *
 320  * It removes all privileges granted to a user that has been granted previously by
 321  * security_manager_user_add.
 322  *
 323  * @param p_req Structure containing user data filled before calling this.
 324  * uid of user needs to be filled in p_req structure,
 325  * otherwise SECURITY_MANAGER_ERROR_INPUT_PARAM will be returned.
 326  * @return API return code or error code
 327  */
 328 int security_manager_user_delete(const user_req *p_req);
 329
 330 /**
 331  * \brief This function is responsible for initializing policy_update_req data structure.
 332  *
 333  * It uses dynamic allocation inside and user responsibility is to call
 334  * policy_update_req_free() for freeing allocated resources.
 335  *
 336  * \param[out] pp_req Address of pointer for handle policy_update_req structure
 337  * \return API return code or error code
 338  */
 339 int security_manager_policy_update_req_new(policy_update_req **pp_req);
 340
 341 /**
 342  * \brief This function is used to free resources allocated by calling policy_update_req_new().
 343  * \param[in] p_req Pointer handling allocated policy_update_req structure
 344  */
 345 void security_manager_policy_update_req_free(policy_update_req *p_req);
 346
 347 /**
 348  * \brief This function is responsible for initializing policy_entry data structure.
 349  *
 350  * It uses dynamic allocation inside and user responsibility is to call
 351  * policy_policy_entry_free() for freeing allocated resources.
 352  *
 353  * \note application and privilege fields default to SECURITY_MANAGER_ANY wildcard,
 354  *       user field defaults to calling user's UID, whereas the current and max level
 355  *       values, default to empty string "".
 356  *
 357  * \param[out] pp_entry Address of pointer for handle policy_entry structure
 358  * \return API return code or error code
 359  */
 360 int security_manager_policy_entry_new(policy_entry **pp_entry);
 361
 362 /**
 363  * \brief This function is used to free resources allocated by calling
 364  * policy_entry_req_new().
 365  * \param[in] p_entry Pointer handling allocated policy_entry structure
 366  */
 367 void security_manager_policy_entry_free(policy_entry *p_entry);
 368
 369 /**
 370  * This function is used to set up application identifier in p_entry structure
 371  *
 372  * \param[in] p_entry Pointer handling policy_entry structure
 373  * \param[in] app_id Application identifier to be set
 374  * \return API return code or error code
 375  */
 376 int security_manager_policy_entry_set_application(policy_entry *p_entry, const char *app_id);
 377
 378 /**
 379  * This function is used to set up user identifier in p_entry structure
 380  * Calling this function may be omitted if user wants to set policies for himself
 381  * \param[in] p_entry Pointer handling policy_entry structure
 382  * \param[in] user_id User identifier to be set
 383  * \return API return code or error code
 384  */
 385 int security_manager_policy_entry_set_user(policy_entry *p_entry, const char *user_id);
 386
 387 /**
 388  * This function is used to set up privilege in p_entry structure
 389  *
 390  * \param[in] p_entry Pointer handling policy_entry structure
 391  * \param[in] privilege Privilege to be set
 392  * \return API return code or error code
 393  */
 394 int security_manager_policy_entry_set_privilege(policy_entry *p_entry, const char *privilege);
 395
 396 /**
 397  * This function is used to set up privilege level in p_entry structure.
 398  * This api is intended to be used to decrease user's own level of privilege.
 399  *
 400  * \param[in] p_entry Pointer handling policy_entry structure
 401  * \param[in] policy_level Policy level to be set. The level of privilege may
 402  * be one of strings returned by @ref security_manager_policy_levels_get.
 403  * If it is not, then error code SECURITY_MANAGER_ERROR_INPUT_PARAM is returned.
 404  * Two predefined values are always valid here:
 405  *
 406  * "Allow", which means that user allows some app (setup by calling function
 407  * @ref security_manager_policy_entry_set_application) to run with some privilege
 408  * (setup by @ref security_manager_policy_entry_set_privilege).
 409  * Note, that this not necessarily mean, that this privilege will really be granted.
 410  * Final decision of granting privilege also depends on app's manifests,
 411  * predefined policy and administrator's or manufacturer's settings.
 412  * If all of those policy sources also allows granting privilege for that app,
 413  *  then (and only then) it will be granted.
 414  *
 415  * "Deny", which means that user disallows some app (setup by calling function
 416  * @ref security_manager_policy_entry_set_application) to run with some privilege
 417  * (setup by @ref security_manager_policy_entry_set_privilege).
 418  * Note, that this denies privilege irrespective of privilege levels granted
 419  * to app by other policy sources: app's manifests, predefined policy
 420  * and administrator's or manufacturer's settings.
 421  *
 422  * Other levels may be also valid, if returned by security_manager_policy_levels_get.
 423  * They represent other policy levels configured in system, which security-manager
 424  * does support. The other levels are always something between "Allow" and "Deny"
 425  * (like "Allow only once").
 426  *
 427  * Irrespective of a meaning of those values security-manager will always treat
 428  * policy set by security_manager_policy_entry_set_level as a mean to
 429  * decrease user's own rights. This will never increase overall policy.
 430  *
 431  * \return API return code or error code
 432  */
 433 int security_manager_policy_entry_set_level(policy_entry *p_entry, const char *policy_level);
 434
 435 /**
 436  * This function is used to set up privilege level for admin policy entries
 437  * in p_entry structure.
 438  *
 439  * This function is intended to be used by admin to change level of privilege.
 440  * If it is used by user that has no http://tizen.org/privilege/systemsettings.admin
 441  * privilege, then security_manager_policy_update_send will return error code.
 442  *
 443  * \param[in] p_entry Pointer handling policy_entry structure
 444  * \param[in] policy_level Policy level to be set. This may be one of strings
 445  * returned by @ref security_manager_policy_levels_get. If it is not, then error
 446  * code is returned (SECURITY_MANAGER_ERROR_INPUT_PARAM).
 447  * Two predefined values are always valid here:
 448  *
 449  * "Allow", which means that admin allows some user's app to
 450  * get privilege irrespective of predefined policy settings for that user.
 451  * Note, that this not necessarily mean, that this privilege will really be granted.
 452  * Final decision of granting privilege also depends on app's manifests,
 453  * user's own policy (set up by @ref security_manager_policy_entry_set_level)
 454  * or manufacturer's settings.
 455  * If all of those policy sources also allows granting privilege for that app,
 456  * then (and only then) it will be granted.
 457  *
 458  * "Deny", which means that admin disallows some user's app to get privilege
 459  * irrespective of predefined policy settings for that user.
 460  * Note, that this denies privilege app's manifests, user's own policy
 461  * (set up by @ref security_manager_policy_entry_set_level) or manufacturer's
 462  * settings.
 463  *
 464  * Other levels may be also valid, if returned by security_manager_policy_levels_get.
 465  * They represent other policy levels configured in system, which security-manager
 466  * does support. The other levels are always something between "Allow" and "Deny"
 467  * (like "Allow only once").
 468  *
 469  * Irrespective of a meaning of those values security-manager will always treat
 470  * policy set by security_manager_policy_entry_admin_set_level as a mean for admin
 471  * to change user's rights, but will not alter user's own privilege level set up
 472  * by @ref security_manager_policy_entry_set_level.
 473  *
 474  * \return API return code or error code
 475  */
 476 int security_manager_policy_entry_admin_set_level(policy_entry *p_entry, const char *policy_level);
 477
 478 /**
 479  * This function is used to add policy entry to policy update request.
 480  *
 481  * Note, that this function does not make a copy of object pointed to by p_entry
 482  * and does not change owner of this handler.
 483  * User is responsible to keep p_entry untouched until @ref security_manager_policy_update_send
 484  * is called on p_req. After that p_entry still needs to be freed.
 485  * (see examples in documentation of @ref security_manager_policy_update_send)
 486  *
 487  * \param[in] p_req Pointer handling allocated policy_update_req structure
 488  * \param[in] p_entry Pointer handling policy_entry structure
 489  * \return API return code or error code
 490  */
 491 int security_manager_policy_update_req_add_entry(policy_update_req *p_req, const policy_entry *p_entry);
 492
 493 /**
 494  * This function is used to obtain user ID from p_entry structure
 495  *
 496  * \param[in] p_entry Pointer handling policy_entry structure
 497  * \attention Warning: memory pointed to by value written to policy_level needs to be freed
 498  *
 499  * \return user uid
 500  */
 501
 502 const char *security_manager_policy_entry_get_user(policy_entry *p_entry);
 503 /**
 504  * This function is used to obtain application name from p_entry structure
 505  *
 506  * \param[in] p_entry Pointer handling policy_entry structure
 507  * \attention Warning: memory pointed to by value written to policy_level needs to be freed
 508  *
 509  * \return application name
 510  */
 511
 512 const char *security_manager_policy_entry_get_application(policy_entry *p_entry);
 513 /**
 514  * This function is used to obtain privilege name from p_entry structure
 515  *
 516  * \param[in] p_entry Pointer handling policy_entry structure
 517  * \attention Warning: memory pointed to by value written to policy_level needs to be freed
 518  *
 519  * \return privilege name
 520  */
 521 const char *security_manager_policy_entry_get_privilege(policy_entry *p_entry);
 522 /**
 523  * This function is used to obtain current policy level from p_entry structure
 524  *
 525  * \param[in] p_entry Pointer handling policy_entry structure
 526  * \attention Warning: memory pointed to by value written to policy_level needs to be freed
 527  *
 528  * \return Current policy level
 529  */
 530 const char *security_manager_policy_entry_get_level(policy_entry *p_entry);
 531
 532 /**
 533  * This function is used to obtain maximal policy level from p_entry structure
 534  *
 535  * \param[in] p_entry Pointer handling policy_entry structure.
 536  * \attention Warning: memory pointed to by value written to policy_level needs to be freed
 537  *
 538  * \return Maximal policy level
 539  */
 540 const char *security_manager_policy_entry_get_max_level(policy_entry *p_entry);
 541
 542 /**
 543  * \brief This function is used to send the prepared policy update request using privacy manager
 544  *        entry point. The request should contain at least one policy update unit, otherwise
 545  *        the SECURITY_MANAGER_ERROR_INPUT_PARAM is returned.
 546  *
 547  * \note  1. If user field in policy_entry is empty, then uid of the calling user is assumed
 548  *        2. If privilege or app field in policy_entry is empty, then SECURITY_MANAGER_API_BAD_REQUEST
 549  *           is returned
 550  *        3. For user's personal policy: wildcards usage in application or privilege field of policy_entry
 551  *           is not allowed
 552  *
 553  * \param[in] p_req Pointer handling allocated policy_update_req structure
 554  * \return API return code or error code
 555  *
 556  * Example:
 557  * (warning: checking return codes are omitted in examples just for visibility reasons)
 558  *
 559  * - to update policy for user by himself:
 560  *   (Deny access from app MyApp1 to privilege http://tizen.org/privilege/systemsettings,
 561  *   deny access from app MyApp2 to privilege http://tizen.org/privilege/systemsettings,
 562  *   deny access from app MyApp3 to privilege http://tizen.org/privilege/notificationmanager)
 563  *
 564  *      policy_update_req *policy_update_request;
 565  *      policy_entry *entry1;
 566  *      policy_entry *entry2;
 567  *      policy_entry *entry3;
 568  *
 569  *      security_manager_policy_update_req_new(&policy_update_request);
 570  *      security_manager_policy_entry_new(&entry1);
 571  *      security_manager_policy_entry_new(&entry2);
 572  *      security_manager_policy_entry_new(&entry3);
 573  *
 574  *      security_manager_policy_entry_set_application(entry1, "MyApp1");
 575  *      security_manager_policy_entry_set_privilege(entry1, "http://tizen.org/privilege/systemsettings");
 576  *      security_manager_policy_entry_set_level(entry1, "Deny");
 577  *
 578  *      security_manager_policy_entry_set_application(entry2, "MyApp2");
 579  *      security_manager_policy_entry_set_privilege(entry2, "http://tizen.org/privilege/systemsettings");
 580  *      security_manager_policy_entry_set_level(entry2, "Deny");
 581  *
 582  *      security_manager_policy_entry_set_application(entry3, "MyApp3");
 583  *      security_manager_policy_entry_set_privilege(entry3, "http://tizen.org/privilege/notificationmanager");
 584  *      security_manager_policy_entry_set_level(entry3, "Deny");
 585  *
 586  *      security_manager_policy_update_req_add_entry(policy_update_request, entry1);
 587  *      security_manager_policy_update_req_add_entry(policy_update_request, entry2);
 588  *      security_manager_policy_update_req_add_entry(policy_update_request, entry3);
 589  *
 590  *      //do not change entry1, entry2 or entry3!
 591  *
 592  *      security_manager_policy_update_send(policy_update_request);
 593  *
 594  *      security_manager_policy_entry_free(entry1);
 595  *      security_manager_policy_entry_free(entry2);
 596  *      security_manager_policy_entry_free(entry3);
 597  *      security_manager_policy_update_free(policy_update_request);
 598  *
 599  * - to update policy by administrator for some user:
 600  *   (Deny access of user of uid 2001 from any app to privilege http://tizen.org/privilege/vibrator,
 601  *   (allow access of user of uid 2002 using app "App1" to privilege http://tizen.org/privilege/email.admin)
 602  *
 603  *      policy_update_req *policy_update_request;
 604  *
 605  *      security_manager_policy_update_req_new(&policy_update_request);
 606
 607  *      policy_entry *entry1;
 608  *      policy_entry *entry2;
 609  *      char *adminswife = "2001";
 610  *      char *adminsfriend = "2002";
 611  *
 612  *      security_manager_policy_entry_new(&entry1);
 613  *      security_manager_policy_entry_new(&entry2);
 614  *
 615  *      security_manager_policy_entry_set_user(entry1, adminswife);
 616  *      security_manager_policy_entry_set_application(entry1, SECURITY_MANAGER_ANY);
 617  *      security_manager_policy_entry_set_privilege(entry1, "http://tizen.org/privilege/vibrator");
 618  *      security_manager_policy_entry_admin_set_level(entry1, "Deny");
 619  *
 620  *      security_manager_policy_entry_set_user(entry2, adminsfriend);
 621  *      security_manager_policy_entry_set_application(entry2, "App1");
 622  *      security_manager_policy_entry_set_privilege(entry2, "http://tizen.org/privilege/email.admin");
 623  *      security_manager_policy_entry_admin_set_level(entry2, "Allow");
 624  *
 625  *      security_manager_policy_update_req_add_entry(policy_update_request, entry1);
 626  *      security_manager_policy_update_req_add_entry(policy_update_request, entry2);
 627  *
 628  *      //do not change entry1 or entry2!
 629  *
 630  *      security_manager_policy_update_send(policy_update_request);
 631  *
 632  *      security_manager_policy_entry_free(entry1);
 633  *      security_manager_policy_entry_free(entry2);
 634  *      security_manager_policy_update_free(policy_update_request);
 635  *
 636  */
 637 int security_manager_policy_update_send(policy_update_req *p_req);
 638
 639 /**
 640  * \brief Function fetches all privileges enforced by admin user.
 641  *        The result is stored in the policy_entry structures array.
 642  *
 643  * \note It should be called by user with http://tizen.org/privilege/systemsettings.admin privilege.
 644  *       Normal users may list their personal policy entries using
 645  *       security_manager_get_configured_policy_for_self() API function.
 646  *
 647  * \attention Developer is responsible for calling security_manager_policy_entries_free()
 648  *            for freeing allocated resources.
 649  *
 650  * \param[in]  p_filter        Pointer to filter struct
 651  * \param[out] ppp_privs_policy Pointer handling allocated policy_entry structures array
 652  * \param[out] p_size          Pointer where the size of allocated array will be stored
 653  * \return API return code or error code
 654  */
 655 int security_manager_get_configured_policy_for_admin(
 656         policy_entry *p_filter,
 657         policy_entry ***ppp_privs_policy,
 658         size_t *p_size);
 659
 660 /**
 661  * \brief Function fetches all privileges that are configured by user in his/her
 662  *        privacy manager. The result is stored in the policy_entry structures array.
 663  *        User may only fetch privileges for his/her own UID.
 664  *
 665  * \attention Developer is responsible for calling security_manager_policy_entries_free()
 666  *            for freeing allocated resources.
 667  *
 668  * \param[in]  p_filter        Pointer to filter struct
 669  * \param[out] ppp_privs_policy Pointer handling allocated policy_entry structures array
 670  * \param[out] p_size          Pointer where the size of allocated array will be stored
 671  * \return API return code or error code
 672  */
 673 int security_manager_get_configured_policy_for_self(
 674         policy_entry *p_filter,
 675         policy_entry ***ppp_privs_policy,
 676         size_t *p_size);
 677
 678 /**
 679  * \brief Function gets the whole policy for all users, their applications and privileges
 680  *        based on the provided filter. The result is stored in the policy_entry array.
 681  *
 682  * \note If this call is performed by user with http://tizen.org/privilege/systemsettings.admin
 683  *       privilege, then it's possible to list policies for all users.
 684  *       Normal users may only list privileges for their own UID.
 685  *
 686  * \attention Developer is responsible for calling security_manager_policy_entries_free()
 687  *            for freeing allocated resources.
 688  *
 689  * \param[in]  p_filter        Pointer to filter struct
 690  * \param[out] ppp_privs_policy Pointer handling allocated policy_entry structures array
 691  * \param[out] p_size          Pointer where the size of allocated array will be stored
 692  * \return API return code or error code
 693  */
 694 int security_manager_get_policy(
 695         policy_entry *p_filter,
 696         policy_entry ***ppp_privs_policy,
 697         size_t *p_size);
 698
 699 /**
 700  *  \brief This function is used to free resources allocated in policy_entry structures array.
 701  *  \param[in] p_entries Pointer handling allocated policy status array
 702  *  \param[in] size      Size of the array
 703  */
 704 void security_manager_policy_entries_free(policy_entry *p_entries, const size_t size);
 705
 706 /**
 707  * This function returns array of available policy levels in form of simple
 708  * text descriptions. List is sorted using internal policy level value,
 709  * from highest value to lowest and starts with "Allow".
 710  *
 711  * Caller needs to free memory allocated for the list using
 712  * security_manager_policy_levels_free().
 713  *
 714  * @param levels pointer to array of strings.
 715  * @param levels_count number of strings in levels array.
 716  * @return API return code or error code.
 717  */
 718 int security_manager_policy_levels_get(char ***levels, size_t *levels_count);
 719
 720 /**
 721  * This function free memory allocated by security_manager_policy_levels_get()
 722  * function.
 723  *
 724  * @param levels array of strings returned by
 725  * security_manager_policy_levels_get() function.
 726  * @return API return code or error code.
 727  */
 728 void security_manager_policy_levels_free(char **levels, size_t levels_count);
 729
 730 #ifdef __cplusplus
 731 }
 732 #endif
 733
 734 #endif /* SECURITY_MANAGER_H_ */