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