E-MailRelay

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

groot.h
Go to the documentation of this file.
1 //
2 // Copyright (C) 2001-2018 Graeme Walker <graeme_walker@users.sourceforge.net>
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 <http://www.gnu.org/licenses/>.
16 // ===
17 ///
18 /// \file groot.h
19 ///
20
21 #ifndef G_ROOT_H
22 #define G_ROOT_H
23
24 #include "gdef.h"
25 #include "gidentity.h"
26
27 namespace G
28 {
29 class Root ;
30 }
31
32 /// \class G::Root
33 /// A class which acquires the process's special privileges on construction
34 /// and releases them on destruction. Despite the name of the class the special
35 /// privileges are not necessarily root privileges; they can be suid privileges.
36 ///
37 /// The class must be initialised by calling a static init() method. If instances
38 /// are nested then the inner instances have no effect.
39 ///
40 /// The effect of this class depends on whether the process's real-id is root
41 /// or not. If the real-id is root then the effective-id is switched to
42 /// some named 'ordinary' user's id at startup, and then back to what it
43 /// was (ie. root or the suid id) for the critical sections. Otherwise,
44 /// the effective-id is switched to the real-id at startup and switched back
45 /// to what it was for the critical sections.
46 ///
47 /// The implementation uses G::Process and G::Identity.
48 ///
49 class G::Root
50 {
51 public:
52 Root() ;
53 ///< Default constructor. Acquires special privileges by switching the user-id
54 ///< and possibly the group-id (see init()).
55 ///<
56 ///< Does nothing if the class has not been initialised by a call to init().
57 ///< Does nothing if there is another instance at an outer scope.
58 ///<
59 ///< The implementation uses G::Process::beSpecial().
60
61 explicit Root( bool change_group ) ;
62 ///< Constructor overload with explicit control over whether to change the
63 ///< group-id or not.
64
65 ~Root() ;
66 ///< Desctructor. Releases special privileges if this instance acquired them.
67 ///<
68 ///< The implementation uses G::Process::beOrdinary().
69
70 static void init( const std::string & non_root , bool default_change_group = true ) ;
71 ///< Initialises this class on process start-up by releasing root (or suid)
72 ///< privileges.
73 ///<
74 ///< The string parameter gives a non-privileged username which is used if the
75 ///< real user-id is root.
76 ///<
77 ///< The group-id behaviour of the default constructor is modified by the
78 ///< boolean parameter.
79
80 static Identity nobody() ;
81 ///< Returns the 'nobody' identity corresponding to the init() user name.
82 ///< Precondition: init() called
83
84 static Identity start( SignalSafe ) ;
85 ///< A signal-safe alternative to construction.
86
87 static void stop( SignalSafe , Identity ) ;
88 ///< A signal-safe alternative to destruction.
89
90 private:
91 Root( const Root & ) ;
92 void operator=( const Root & ) ;
93
94 private:
95 static Root * m_this ;
96 static bool m_initialised ;
97 static bool m_default_change_group ;
98 static Identity m_special ;
99 static Identity m_ordinary ;
100 bool m_change_group ;
101 } ;
102
103 #endif
G::SignalSafe
An empty structure that is used to indicate a signal-safe, reentrant implementation.
Definition: gsignalsafe.h:36
G::Root::nobody
static Identity nobody()
Returns the 'nobody' identity corresponding to the init() user name.
Definition: groot.cpp:102
gidentity.h
G::Identity
A combination of user-id and group-id, with a very low-level interface to the get/set/e/uid/gid funct...
Definition: gidentity.h:42
G::Root
A class which acquires the process's special privileges on construction and releases them on destruct...
Definition: groot.h:49
G::Root::start
static Identity start(SignalSafe)
A signal-safe alternative to construction.
Definition: groot.cpp:80
G::Root::init
static void init(const std::string &non_root, bool default_change_group=true)
Initialises this class on process start-up by releasing root (or suid) privileges.
Definition: groot.cpp:92
G::Root::stop
static void stop(SignalSafe, Identity)
A signal-safe alternative to destruction.
Definition: groot.cpp:86
G::Root::Root
Root()
Default constructor.
Definition: groot.cpp:34
G
Low-level classes.
Definition: garg.h:29
G::Root::~Root
~Root()
Desctructor.
Definition: groot.cpp:60