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