summaryrefslogtreecommitdiff
path: root/src/include/app-runtime.h
blob: 82734031aa091f68c0b27c5eaaadffddf46c7404 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
/*
 * Copyright (c) 2016-2022 Samsung Electronics Co., Ltd. All rights reserved.
 *
 * This file is licensed under the terms of MIT License or the Apache License
 * Version 2.0 of your choice. See the LICENSE.MIT file for MIT license details.
 * See the LICENSE file or the notice below for Apache License Version 2.0
 * details.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#pragma once

#include "security-manager-types.h"

#include <sys/types.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Get package id of a given application
 *
 * On successful call pkg_id should be freed by the caller using free() function
 *
 * \param[out] pkg_id  Pointer to package identifier string
 * \param[in]  app_id  Application identifier
 * \return API return code or error code
 */
int security_manager_get_app_pkgid(char **pkg_id, const char *app_id);

/**
 * Compute smack label for given application id and set it for
 * currently running process
 *
 * \param[in] app_id  Application identifier
 * \return API return code or error code
 */
int security_manager_set_process_label_from_appid(const char *app_id);

/**
 * For given app_id and current user, calculate allowed privileges that give
 * direct access to file system resources. Then add current process to
 * supplementary groups that are assigned to these resources.
 *
 * In Tizen some sensitive resources are being accessed by applications directly.
 * The resources, being file system objects, are owned by dedicated GIDs and only
 * processes in those UNIX groups can access them. This function is used for
 * adding application process to all permitted groups that are assigned to such
 * privileges.
 *
 * \param[in] app_id  Application identifier
 * \return API return code or error code
 */
int security_manager_set_process_groups_from_appid(const char *app_id);

/**
 * The above launcher functions, manipulating process Smack label and group,
 * require elevated privileges. Since they will be called by launcher after fork,
 * in the process for the application, privileges should be dropped before
 * running an actual application. This function is a helper for that purpose -
 * it drops capabilities from the process.
 *
 * \return API return code or error code
 */
int security_manager_drop_process_privileges(void);

/**
 * A convenience function for launchers for preparing security context for an
 * application candidate process. It is aimed to cover these actions that
 * are generic to all kinds of applications and MUST be called
 * in single-threaded environment, after fork(), before the application launcher
 * calls exec() on app candidate process binary (custom app loader).
 *
 * On systems with configured mount namespaces for privilege access control
 * (non-empty file privilege-mount.list), this currently only sets up the new
 * mount namespace.
 *
 * On systems without mount namespaces-controlled privileges, this is currently
 * a no-op.
 *
 * \return API return code or error code
 */
int security_manager_prepare_app_candidate(void);

/**
 * A convenience function for launchers for preparing security context for an
 * application process. It should be called before running actual application code.
 *
 * This function has to be called in a process where security_manager_prepare_app_candidate() was
 * already called and all existing threads are already in the same namespaces.
 *
 * This function can be called in multithreaded environment.
 * However, threads must not be spawned or terminated while the function's running.
 *
 * \param[in] app_id  Application identifier
 * \return API return code or error code
 */
int security_manager_prepare_app(const char *app_id);

/**
 * A convenience function for launchers for preparing security context for an
 * application process. It should be called before running actual application code.
 *
 * This function has to be called in a process where security_manager_prepare_app_candidate() was
 * already called and all existing threads are already in the same namespaces.
 *
 * This function can be called in multithreaded environment.
 * However, threads must not be spawned or terminated while the function's running.
 *
 * \param[in] app_id         Application identifier
 * \param[in] subsession_id  Subsession identifier, NULL if default session
 * \return API return code or error code
 */
int security_manager_prepare_app2(const char *app_id, const char *subsession_id);

/**
 * This function is intended for launchers for cleaning security context for an
 * application process. It should be called after application termination.
 *
 * Required privileges:
 * - http://tizen.org/privilege/notexist
 *
 * \param[in] app_id  Application identifier
 * \param[in] uid  User identifier
 * \param[in] pid  Process identifier
 * \return API return code or error code
 */
int security_manager_cleanup_app(const char *app_id, uid_t uid, pid_t pid);

/**
 * This function returns array of groups bound to privileges of file resources.
 *
 * Caller needs to free memory allocated for the list using free().
 *
 * @param[out] groups pointer to array of strings.
 * @param[out] groups_count number of strings in levels array.
 * @return API return code or error code.
 */
int security_manager_groups_get(gid_t **groups, size_t *groups_count);

/**
 * This function returns maximum array of groups bound to privileges that
 * the application run by particular user is able to get.
 *
 * Caller needs to free memory allocated for the list using free().
 *
 * @param[in] uid uid for user running the process
 * @param[out] groups pointer to array of group names
 * @param[out] groups_count number of strings in levels array
 * @return API return code or error code.
 */
int security_manager_groups_get_for_user(uid_t uid, gid_t **groups, size_t *groups_count);

/**
 * Get package and application id of an application with given socket descriptor
 *
 * On successful call pkg_id and app_id should be freed when caller is done with them.
 * Both pkg_id and app_id are allocated with malloc() so they should be freed with free() function.
 * Either app_id or pkg_id may be NULL. NULL-ed argument will be ignored.
 * If both app_id and pkg_id are NULL then SECURITY_MANAGER_ERROR_INPUT_PARAM will be returned.
 * When socket descriptor is incorrect or not related to any package, this function will
 * return SECURITY_MANAGER_ERROR_NO_SUCH_OBJECT.
 * If process on the other side is a nonhybrid application, no app_id will be available.
 *
 * \note For non hybrid applications only package id can be returned
 *
 * \param[in]   sockfd  Socket descriptor of wanted application
 * \param[out]  pkg_id  Package id of the application
 * \param[out]  app_id  Application id of the application
 * \return API return code or error code
 */
int security_manager_identify_app_from_socket(int sockfd, char **pkg_id, char **app_id);

/**
 * Get package and application id of an application with given process identifier
 *
 * On successful call pkg_id and app_id should be freed when caller is done with them.
 * Both pkg_id and app_id are allocated with malloc() so they should be freed with free() function.
 * Either app_id or pkg_id may be NULL. NULL-ed argument will be ignored.
 * If both app_id and pkg_id are NULL then SECURITY_MANAGER_ERROR_INPUT_PARAM will be returned.
 * When process identifier is incorrect or not related to any package, this function will
 * return SECURITY_MANAGER_ERROR_NO_SUCH_OBJECT.
 * If given process is a nonhybrid application, no app_id will be available.
 *
 * \note Caller must be able to access and read file /proc/PID/atrr/current where PID is the given
 * process identifier.
 *
 * \note For non hybrid applications only package id can be returned
 *
 * \param[in]   pid     Process identifier of wanted application
 * \param[out]  pkg_id  Package id of the application
 * \param[out]  app_id  Application id of the application
 * \return API return code or error code
 */
int security_manager_identify_app_from_pid(pid_t pid, char **pkg_id, char **app_id);

/**
 * Get package and application id of an application with given process Cynara client identifier
 *
 * On successful call pkg_id and app_id should be freed when caller is done with them.
 * Both pkg_id and app_id are allocated with malloc() so they should be freed with free() function.
 * Either app_id or pkg_id may be NULL. NULL-ed argument will be ignored.
 * If both app_id and pkg_id are NULL then SECURITY_MANAGER_ERROR_INPUT_PARAM will be returned.
 * When process identifier is incorrect or not related to any package, this function will
 * return SECURITY_MANAGER_ERROR_NO_SUCH_OBJECT.
 *
 * \note For non hybrid applications only package id can be returned
 *
 * \param[in]   client  Application Cynara client identifier
 * \param[out]  pkg_id  Package id of the application
 * \param[out]  app_id  Application id of the application
 * \return API return code or error code
 */
int security_manager_identify_app_from_cynara_client(const char *client, char **pkg_id,
                                                     char **app_id);
/**
 * Check whether an application would have access to a privilege
 *
 * This enables queries for application's privileges when there is no application
 * process running. In such case the application label cannot be determined from
 * the process and the query for privilege must be based on app_id.
 *
 * The check result is placed in \b result:
 * - 0: access denied
 * - 1: access granted
 *
 * Required privileges:
 * for checking policy for the caller application process:
 * - none
 * for checking policy for other application process:
 * - http://tizen.org/privilege/notexist or http://tizen.org/privilege/permission.check
 *
 * \param[in]  app_id     Application identifier
 * \param[in]  privilege  Privilege name
 * \param[in]  uid        User identifier
 * \param[out] result     Placeholder for result
 * \return API return code or error code
 */
int security_manager_app_has_privilege(const char *app_id, const char *privilege,
                                       uid_t uid, int *result);

/**
 * This function creates descriptor that may be used as shared memory segment
 * with app_id application.
 *
 * \param[in]  name       This value is passed to shm_open as first parameter (man 3 shm_open for details)
 * \param[in]  oflag      This value is passed to shm_open as second parameter (man 3 shm_open for details)
 * \param[in]  mode       This value is passed to shm_open as third parameter (man 3 shm_open for details)
 * \param[in]  app_id     Identifier of application that will gain access to shared memory segment
 * \return file descriptor or -1 on error. If -1 is returned then errno will be set. Errno == ECONNABORTED
 *                        means that the security-manager server failed and did not return any information
 *                        about error.
 */
int security_manager_shm_open(const char *name, int oflag, mode_t mode, const char *app_id);

/**
 * Get package id and application id of an application which provides privilege.
 *
 * On successful call pkg_id and app_id should be freed when caller is done with them.
 * Both pkg_id and app_id are allocated with malloc() so they should be freed with free() function.
 * Either app_id or pkg_id may be NULL. NULL-ed argument will be ignored.
 * If both app_id and pkg_id are NULL then SECURITY_MANAGER_ERROR_INPUT_PARAM will be returned.
 * When privilege/uid is incorrect or not related to any package, this function will
 * return SECURITY_MANAGER_ERROR_NO_SUCH_OBJECT.
 *
 * \param[in]   privilege  Privilege name
 * \param[in]   uid        User identifier
 * \param[out]  pkg_id     Package id of the provider application
 * \param[out]  app_id     Application id of the provider application
 * \return API return code or error code
 */
int security_manager_get_app_defined_privilege_provider(const char *privilege,
                                                        uid_t uid,
                                                        char **pkg_id,
                                                        char **app_id);

/**
 * Get license of an application which provides privilege.
 *
 * On successful call license should be freed when caller is done with them.
 * license is allocated with malloc() so should be freed with free() function.
 * When privilege/uid is incorrect or not related to any license, this function will
 * return SECURITY_MANAGER_ERROR_NO_SUCH_OBJECT.
 *
 * \param[in]   privilege  Privilege name
 * \param[in]   uid        User identifier
 * \param[out]  license    Data used to verify if client may use this privilege.
 *                         If privilege type is SM_APP_DEFINED_PRIVILEGE_TYPE_UNTRUSTED this
 *                         value will be set to NULL.
 * \return API return code or error code
 */
int security_manager_get_app_defined_privilege_license(const char *privilege,
                                                       uid_t uid,
                                                       char **license);

/**
 * Extract license from application that requested access to privilege.
 *
 * On successful call license should be freed when caller is done with them.
 * license parameter will be allocated with malloc so it should be freed with free() function.
 * When privilege/pkg_id/app_id/uid is incorrect or not related to any license, this function
 * will return SECURITY_MANAGER_ERROR_NO_SUCH_OBJECT.
 *
 * \param[in]  privilege   Privilege name
 * \param[in]  pkg_id      Package Id of application that request of license.
 * \param[in]  app_id      Id of application that request access to privilege (null for
 *                         non-hybrid application).
 * \param[in]  uid         User identifier
 * \param[out] license     Data that will be used to verify access to privilege. If privilege
 *                         type is SM_APP_DEFINED_PRIVILEGE_TYPE_UNTRUSTED this value will be
 *                         set to NULL.
 * \return API return code or error code
 */
int security_manager_get_client_privilege_license(const char *privilege,
                                                  const char *pkg_id,
                                                  const char *app_id,
                                                  uid_t uid,
                                                  char **license);

#ifdef __cplusplus
}
#endif