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 /*! \brief data structure responsible for handling informations
  59  * required to install / uninstall application */
  60 struct app_inst_req;
  61 typedef struct app_inst_req app_inst_req;
  62
  63 /**
  64  * This function translates lib_retcode error codes to strings describing
  65  * errors.
  66  * @param[in] rc error code of lib_retcode type
  67  * @return string describing error for error code
  68  */
  69 const char *security_manager_strerror(enum lib_retcode rc);
  70
  71 /*
  72  * This function is responsible for initialize app_inst_req data structure
  73  * It uses dynamic allocation inside and user responsibility is to call
  74  * app_inst_req_free() for freeing allocated resources
  75  *
  76  * \param[in] Address of pointer for handle app_inst_req structure
  77  * \return API return code or error code
  78  */
  79 int security_manager_app_inst_req_new(app_inst_req **pp_req);
  80
  81 /*
  82  * This function is used to free resources allocated by calling app_inst_req_new()
  83  *  \param[in] Pointer handling allocated app_inst_req structure
  84  */
  85 void security_manager_app_inst_req_free(app_inst_req *p_req);
  86
  87 /*
  88  * This function is used to set up application identifier in app_inst_req structure
  89  *
  90  * \param[in] Pointer handling app_inst_req structure
  91  * \param[in] Application identifier
  92  * \return API return code or error code
  93  */
  94 int security_manager_app_inst_req_set_app_id(app_inst_req *p_req, const char *app_id);
  95
  96 /*
  97  * This function is used to set up package identifier in app_inst_req structure
  98  *
  99  * \param[in] Pointer handling app_inst_req structure
 100  * \param[in] Package identifier
 101  * \return API return code or error code
 102  */
 103 int security_manager_app_inst_req_set_pkg_id(app_inst_req *p_req, const char *pkg_id);
 104
 105 /*
 106  * This function is used to add privilege to app_inst_req structure,
 107  * it can be called multiple times
 108  *
 109  * \param[in] Pointer handling app_inst_req structure
 110  * \param[in] Application privilager
 111  * \return API return code or error code
 112  */
 113 int security_manager_app_inst_req_add_privilege(app_inst_req *p_req, const char *privilege);
 114
 115 /*
 116  * This function is used to add application path to app_inst_req structure,
 117  * it can be called multiple times
 118  *
 119  * \param[in] Pointer handling app_inst_req structure
 120  * \param[in] Application path
 121  * \param[in] Application path type
 122  * \return API return code or error code
 123  */
 124 int security_manager_app_inst_req_add_path(app_inst_req *p_req, const char *path, const int path_type);
 125
 126 /*
 127  * This function is used to set up user identifier in app_inst_req structure.
 128  * This field simplifies support for online and offline modes.
 129  *
 130  * \param[in] Pointer handling app_inst_req structure
 131  * \param[in] User identifier (UID)
 132  * \return API return code or error code
 133  */
 134 int security_manager_app_inst_req_set_uid(app_inst_req *p_req,
 135                                           const uid_t uid);
 136
 137 /*
 138  * This function is used to install application based on
 139  * using filled up app_inst_req data structure
 140  *
 141  * \param[in] Pointer handling app_inst_req structure
 142  * \return API return code or error code: it would be
 143  * - SECURITY_MANAGER_SUCCESS on success,
 144  * - SECURITY_MANAGER_ERROR_AUTHENTICATION_FAILED when user does not
 145  * have rights to install requested directories,
 146  * - SECURITY_MANAGER_ERROR_UNKNOWN on other errors.
 147  */
 148 int security_manager_app_install(const app_inst_req *p_req);
 149
 150 /*
 151  * This function is used to uninstall application based on
 152  * using filled up app_inst_req data structure
 153  *
 154  * \param[in] Pointer handling app_inst_req structure
 155  * \return API return code or error code
 156  */
 157 int security_manager_app_uninstall(const app_inst_req *p_req);
 158
 159 /**
 160  * Get package id of a given application
 161  *
 162  * On successful call pkg_id should be freed by the caller using free() function
 163  *
 164  * \param[out] Pointer to package identifier string
 165  * \param[in]  Application identifier
 166  * \return API return code or error code
 167  */
 168 int security_manager_get_app_pkgid(char **pkg_id, const char *app_id);
 169
 170 /**
 171  * Compute smack label for given application id and set it for
 172  * currently running process
 173  *
 174  * \param[in] Application identifier
 175  * \return API return code or error code
 176  */
 177 int security_manager_set_process_label_from_appid(const char *app_id);
 178
 179 /**
 180  * For given app_id and current user, calculate allowed privileges that give
 181  * direct access to file system resources. Then add current process to
 182  * supplementary groups that are assigned to these resources.
 183  *
 184  * In Tizen some sensitive resources are being accessed by applications directly.
 185  * The resources, being file system objects, are owned by dedicated GIDs and only
 186  * processes in those UNIX groups can access them. This function is used for
 187  * adding application process to all permitted groups that are assigned to such
 188  * privileges.
 189  *
 190  * \param[in] Application identifier
 191  * \return API return code or error code
 192  */
 193 int security_manager_set_process_groups_from_appid(const char *app_id);
 194
 195 /**
 196  * The above launcher functions, manipulating process Smack label and group,
 197  * require elevated privileges. Since they will be called by launcher after fork,
 198  * in the process for the application, privileges should be dropped before
 199  * running an actual application. This function is a helper for that purpose -
 200  * it drops capabilities from the process.
 201  *
 202  * \return API return code or error code
 203  */
 204 int security_manager_drop_process_privileges(void);
 205
 206 /**
 207  * A convenience function for launchers for preparing security context for an
 208  * application process. It should be called after fork in the new process, before
 209  * running the application in it.
 210  * It is aimed to cover most common cases and will internally call other, more
 211  * specialized security-manager functions for launchers.
 212  * Currently it just calls:
 213  * - security_manager_set_process_label_from_appid
 214  * - security_manager_set_process_groups_from_appid
 215  * - security_manager_drop_process_privileges
 216  *
 217  * \param[in] Application identifier
 218  * \return API return code or error code
 219  */
 220 int security_manager_prepare_app(const char *app_id);
 221
 222
 223 #ifdef __cplusplus
 224 }
 225 #endif
 226
 227 #endif /* SECURITY_MANAGER_H_ */