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 /**
  85  * This function translates lib_retcode error codes to strings describing
  86  * errors.
  87  * @param[in] rc error code of lib_retcode type
  88  * @return string describing error for error code
  89  */
  90 const char *security_manager_strerror(enum lib_retcode rc);
  91
  92 /*
  93  * This function is responsible for initialize app_inst_req data structure
  94  * It uses dynamic allocation inside and user responsibility is to call
  95  * app_inst_req_free() for freeing allocated resources
  96  *
  97  * \param[in] Address of pointer for handle app_inst_req structure
  98  * \return API return code or error code
  99  */
 100 int security_manager_app_inst_req_new(app_inst_req **pp_req);
 101
 102 /*
 103  * This function is used to free resources allocated by calling app_inst_req_new()
 104  *  \param[in] Pointer handling allocated app_inst_req structure
 105  */
 106 void security_manager_app_inst_req_free(app_inst_req *p_req);
 107
 108 /*
 109  * This function is used to set up application identifier in app_inst_req structure
 110  *
 111  * \param[in] Pointer handling app_inst_req structure
 112  * \param[in] Application identifier
 113  * \return API return code or error code
 114  */
 115 int security_manager_app_inst_req_set_app_id(app_inst_req *p_req, const char *app_id);
 116
 117 /*
 118  * This function is used to set up package identifier in app_inst_req structure
 119  *
 120  * \param[in] Pointer handling app_inst_req structure
 121  * \param[in] Package identifier
 122  * \return API return code or error code
 123  */
 124 int security_manager_app_inst_req_set_pkg_id(app_inst_req *p_req, const char *pkg_id);
 125
 126 /*
 127  * This function is used to add privilege to app_inst_req structure,
 128  * it can be called multiple times
 129  *
 130  * \param[in] Pointer handling app_inst_req structure
 131  * \param[in] Application privilager
 132  * \return API return code or error code
 133  */
 134 int security_manager_app_inst_req_add_privilege(app_inst_req *p_req, const char *privilege);
 135
 136 /*
 137  * This function is used to add application path to app_inst_req structure,
 138  * it can be called multiple times
 139  *
 140  * \param[in] Pointer handling app_inst_req structure
 141  * \param[in] Application path
 142  * \param[in] Application path type
 143  * \return API return code or error code
 144  */
 145 int security_manager_app_inst_req_add_path(app_inst_req *p_req, const char *path, const int path_type);
 146
 147 /*
 148  * This function is used to set up user identifier in app_inst_req structure.
 149  * This field simplifies support for online and offline modes.
 150  *
 151  * \param[in] Pointer handling app_inst_req structure
 152  * \param[in] User identifier (UID)
 153  * \return API return code or error code
 154  */
 155 int security_manager_app_inst_req_set_uid(app_inst_req *p_req,
 156                                           const uid_t uid);
 157
 158 /*
 159  * This function is used to install application based on
 160  * using filled up app_inst_req data structure
 161  *
 162  * \param[in] Pointer handling app_inst_req structure
 163  * \return API return code or error code: it would be
 164  * - SECURITY_MANAGER_SUCCESS on success,
 165  * - SECURITY_MANAGER_ERROR_AUTHENTICATION_FAILED when user does not
 166  * have rights to install requested directories,
 167  * - SECURITY_MANAGER_ERROR_UNKNOWN on other errors.
 168  */
 169 int security_manager_app_install(const app_inst_req *p_req);
 170
 171 /*
 172  * This function is used to uninstall application based on
 173  * using filled up app_inst_req data structure
 174  *
 175  * \param[in] Pointer handling app_inst_req structure
 176  * \return API return code or error code
 177  */
 178 int security_manager_app_uninstall(const app_inst_req *p_req);
 179
 180 /**
 181  * Get package id of a given application
 182  *
 183  * On successful call pkg_id should be freed by the caller using free() function
 184  *
 185  * \param[out] Pointer to package identifier string
 186  * \param[in]  Application identifier
 187  * \return API return code or error code
 188  */
 189 int security_manager_get_app_pkgid(char **pkg_id, const char *app_id);
 190
 191 /**
 192  * Compute smack label for given application id and set it for
 193  * currently running process
 194  *
 195  * \param[in] Application identifier
 196  * \return API return code or error code
 197  */
 198 int security_manager_set_process_label_from_appid(const char *app_id);
 199
 200 /**
 201  * For given app_id and current user, calculate allowed privileges that give
 202  * direct access to file system resources. Then add current process to
 203  * supplementary groups that are assigned to these resources.
 204  *
 205  * In Tizen some sensitive resources are being accessed by applications directly.
 206  * The resources, being file system objects, are owned by dedicated GIDs and only
 207  * processes in those UNIX groups can access them. This function is used for
 208  * adding application process to all permitted groups that are assigned to such
 209  * privileges.
 210  *
 211  * \param[in] Application identifier
 212  * \return API return code or error code
 213  */
 214 int security_manager_set_process_groups_from_appid(const char *app_id);
 215
 216 /**
 217  * The above launcher functions, manipulating process Smack label and group,
 218  * require elevated privileges. Since they will be called by launcher after fork,
 219  * in the process for the application, privileges should be dropped before
 220  * running an actual application. This function is a helper for that purpose -
 221  * it drops capabilities from the process.
 222  *
 223  * \return API return code or error code
 224  */
 225 int security_manager_drop_process_privileges(void);
 226
 227 /**
 228  * A convenience function for launchers for preparing security context for an
 229  * application process. It should be called after fork in the new process, before
 230  * running the application in it.
 231  * It is aimed to cover most common cases and will internally call other, more
 232  * specialized security-manager functions for launchers.
 233  * Currently it just calls:
 234  * - security_manager_set_process_label_from_appid
 235  * - security_manager_set_process_groups_from_appid
 236  * - security_manager_drop_process_privileges
 237  *
 238  * \param[in] Application identifier
 239  * \return API return code or error code
 240  */
 241 int security_manager_prepare_app(const char *app_id);
 242
 243 /*
 244  * This function is responsible for initialization of user_req data structure.
 245  * It uses dynamic allocation inside and user responsibility is to call
 246  * security_manager_user_req_free() for freeing allocated resources.
 247  *
 248  * @param[in] Address of pointer for handle user_req structure
 249  * @return API return code or error code
 250  */
 251 int security_manager_user_req_new(user_req **pp_req);
 252
 253 /*
 254  * This function is used to free resources allocated by
 255  * security_manager_user_req_new()
 256  *
 257  * @param[in] Pointer handling allocated user_req structure
 258  */
 259 void security_manager_user_req_free(user_req *p_req);
 260
 261 /*
 262  * This function is used to set up user identifier in user_req structure.
 263  *
 264  * @param p_req Structure containing user data filled during this function call
 265  * @param uid User identifier to be set
 266  * @return API return code or error code
 267  */
 268 int security_manager_user_req_set_uid(user_req *p_req, uid_t uid);
 269
 270 /*
 271  * This function is used to set up user type in user_req structure.
 272  *
 273  * @param p_req Structure containing user data filled during this function call
 274  * @param utype User type to be set
 275  * @return API return code or error code
 276  */
 277 int security_manager_user_req_set_user_type(user_req *p_req, security_manager_user_type utype);
 278
 279 /*
 280  * This function should be called to inform security-manager about adding new user.
 281  * This function succeeds only when is called by privileged user.
 282  * Otherwise it just returns SECURITY_MANAGER_ERROR_AUTHENTICATION_FAILED and does nothing.
 283  *
 284  * It adds all required privileges to a newly created user.
 285  * User data are passed through  pointer 'p_req'.
 286  * @param p_req Structure containing user data filled before calling this
 287  * uid and user type needs to be filled in p_req structure,
 288  * otherwise SECURITY_MANAGER_ERROR_INPUT_PARAM will be returned.
 289  * @return API return code or error code.
 290  */
 291 int security_manager_user_add(const user_req *p_req);
 292
 293 /*
 294  * This function should be called to inform security-manager about removing a user.
 295  * This function succeeds only when is called by privileged user.
 296  * Otherwise it just returns SECURITY_MANAGER_ERROR_AUTHENTICATION_FAILED and does nothing.
 297  *
 298  * It removes all privileges granted to a user that has been granted previously by
 299  * security_manager_user_add.
 300  *
 301  * @param p_req Structure containing user data filled before calling this.
 302  * uid of user 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_delete(const user_req *p_req);
 307
 308
 309 #ifdef __cplusplus
 310 }
 311 #endif
 312
 313 #endif /* SECURITY_MANAGER_H_ */