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