1 /* Dropping uid/gid privileges of the current process.
2 Copyright (C) 2009-2023 Free Software Foundation, Inc.
3
4 This program is free software: you can redistribute it and/or modify
5 it under the terms of the GNU General Public License as published by
6 the Free Software Foundation, either version 3 of the License, or
7 (at your option) any later version.
8
9 This program is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 GNU General Public License for more details.
13
14 You should have received a copy of the GNU General Public License
15 along with this program. If not, see <https://www.gnu.org/licenses/>. */
16
17 #ifndef _IDPRIV_H
18 #define _IDPRIV_H
19
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23
24 /* This module allows programs which are installed with setuid or setgid bit
25 (and which therefore initially run with an effective user id or group id
26 different from the one of the current user) to drop their uid or gid
27 privilege, either permanently or temporarily.
28
29 It is absolutely necessary to minimize the amount of code that is running
30 with escalated privileges (e.g. with effective uid = root). The reason is
31 that any bug or exploit in a part of a program that is running with
32 escalated privileges is a security vulnerability that - upon discovery -
33 puts the users in danger and requires immediate fixing. Then consider that
34 there's a bug every 10 or 20 lines of code on average...
35
36 For programs that temporarily drop privileges but have the ability to
37 restore them later, there are additionally the dangers that
38 - Any bug in the non-privileged part of the program may be used to
39 create invalid data structures that will trigger security
40 vulnerabilities in the privileged part of the program.
41 - Code execution exploits in the non-privileged part of the program may
42 be used to invoke the function that restores high privileges and then
43 execute additional arbitrary code.
44
45 1) The usual, and reasonably safe, way to minimize the amount of code
46 running with privileges is to create a separate executable, with setuid
47 or setgid bit, that contains only code for the tasks that require
48 privileges (and,of course, strict checking of the arguments, so that the
49 program cannot be abused). The main program is installed without setuid
50 or setgid bit.
51
52 2) A less safe way is to do some privileged tasks at the beginning of the
53 program's run, and drop privileges permanently as soon as possible.
54
55 Note: There may still be security issues if the privileged task puts
56 sensitive data into the process memory or opens communication channels
57 to restricted facilities.
58
59 3) The most unsafe way is to drop privileges temporarily for most of the
60 main program but to re-enable them for the duration of privileged tasks.
61
62 As explained above, this approach has uncontrollable dangers for
63 security.
64
65 This approach is normally not usable in multithreaded programs, because
66 you cannot know what kind of system calls the other threads could be
67 doing during the time the privileges are enabled.
68
69 With approach 1, you don't need gnulib modules.
70 With approach 2, you need the gnulib module 'idpriv-drop'.
71 With approach 3, you need the gnulib module 'idpriv-droptemp'. But really,
72 you should better stay away from this approach.
73 */
74
75 /* For more in-depth discussion of these topics, see the papers/articles
76 * Hao Chen, David Wagner, Drew Dean: Setuid Demystified
77 <https://www.usenix.org/legacy/publications/library/proceedings/sec02/full_papers/chen/chen.pdf>
78 * Dan Tsafrir, Dilma da Silva, David Wagner: The Murky Issue of Changing
79 Process Identity: Revising "Setuid Demystified"
80 <https://people.eecs.berkeley.edu/~daw/papers/setuid-login08b.pdf>
81 <https://code.google.com/archive/p/change-process-identity/>
82 * Dhruv Mohindra: Observe correct revocation order while relinquishing
83 privileges
84 <https://www.securecoding.cert.org/confluence/display/seccode/POS36-C.+Observe+correct+revocation+order+while+relinquishing+privileges>
85 */
86
87
88 /* For approach 2. */
89
90 /* Drop the uid and gid privileges of the current process.
91 Return 0 if successful, or -1 with errno set upon failure. The recommended
92 handling of failure is to terminate the process. */
93 extern int idpriv_drop (void);
94
95
96 /* For approach 3. */
97
98 /* Drop the uid and gid privileges of the current process in a way that allows
99 them to be restored later.
100 Return 0 if successful, or -1 with errno set upon failure. The recommended
101 handling of failure is to terminate the process. */
102 extern int idpriv_temp_drop (void);
103
104 /* Restore the uid and gid privileges of the current process.
105 Return 0 if successful, or -1 with errno set upon failure. The recommended
106 handling of failure is to not perform the actions that require the escalated
107 privileges. */
108 extern int idpriv_temp_restore (void);
109
110
111 #ifdef __cplusplus
112 }
113 #endif
114
115
116 #endif /* _IDPRIV_H */