root/maint/gnulib/lib/idpriv.h

/* */

INCLUDED FROM

   1 /* Dropping uid/gid privileges of the current process.
   2    Copyright (C) 2009-2021 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 */

/* */