1 kumpf 1.2 //%2006////////////////////////////////////////////////////////////////////////
  2           //
  3           // Copyright (c) 2000, 2001, 2002 BMC Software; Hewlett-Packard Development
  4           // Company, L.P.; IBM Corp.; The Open Group; Tivoli Systems.
  5           // Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company, L.P.;
  6           // IBM Corp.; EMC Corporation, The Open Group.
  7           // Copyright (c) 2004 BMC Software; Hewlett-Packard Development Company, L.P.;
  8           // IBM Corp.; EMC Corporation; VERITAS Software Corporation; The Open Group.
  9           // Copyright (c) 2005 Hewlett-Packard Development Company, L.P.; IBM Corp.;
 10           // EMC Corporation; VERITAS Software Corporation; The Open Group.
 11           // Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.;
 12           // EMC Corporation; Symantec Corporation; The Open Group.
 13           //
 14           // Permission is hereby granted, free of charge, to any person obtaining a copy
 15           // of this software and associated documentation files (the "Software"), to
 16           // deal in the Software without restriction, including without limitation the
 17           // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 18           // sell copies of the Software, and to permit persons to whom the Software is
 19           // furnished to do so, subject to the following conditions:
 20           // 
 21           // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
 22 kumpf 1.2 // ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
 23           // "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
 24           // LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 25           // PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 26           // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 27           // ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 28           // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 29           //
 30           //==============================================================================
 31           //
 32           //%/////////////////////////////////////////////////////////////////////////////
 33           
 34           #ifndef _Pegasus_Common_Executor_h
 35           #define _Pegasus_Common_Executor_h
 36           
 37           #include <Pegasus/Common/Config.h>
 38           #include <Pegasus/Common/MessageLoader.h>
 39           #include <Pegasus/Common/AnonymousPipe.h>
 40           #include <Pegasus/Common/Linkage.h>
 41           #include <Executor/Defines.h>
 42           #include <cstdio>
 43 kumpf 1.2 
 44           PEGASUS_NAMESPACE_BEGIN
 45           
 46           /** The Executor class is used to perform various privileged operations. When
 47               Pegasus is built with privilege separation, the methods of this class are
 48               used to submit requests to a privileged process called and "executor". The
 49               current process communicates with the executor over an anonymous local
 50               domain socket. But, when Pegasus is built without privilege separation,
 51               the methods are implemented in the same process (within Executor.cpp).
 52           
 53               <br>
 54               When configured for privilege separation, the Pegasus server runs as two
 55               processes.
 56           
 57               <ul>
 58                   <li>the executor (the cimserver program).
 59                   <li>the server (the cimservermain program).
 60               </ul>
 61           
 62               The "executor" is the parent process. When it starts the server it passes
 63               the -x option with a socket number. The server checks for this option. It
 64 kumpf 1.2     if finds it, is assumes it is running in privilege separation mode, in
 65               which case is calls Executor::setSock() with this socket number.
 66           
 67               <br>
 68               The Executor::detectExecutor() method is used in various places to see if
 69               the executor is present. For example.
 70           
 71                   <pre>
 72                   if (Executor::detectExecutor() == 0)
 73                   {
 74                       // Executor is present.
 75                   }
 76                   </pre>
 77           
 78               The remaining methods provide an interface for submitting requests to the
 79               executor over the given socket, if present. Otherwise, the methods are
 80               handled directly by this class (see Executor.cpp). Here is a typical
 81               exampe of its usage.
 82           
 83                   <pre>
 84                   if (Executor::removeFile(path) == 0)
 85 kumpf 1.2         {
 86                       // File successfully removed.
 87                   }
 88                   </pre>
 89           
 90               This example removes the given file. But be aware that the executor defines
 91               a policy that identifies which files it may removed (or manipulated by the
 92               other methods). In order to remove a file, the file must be added to the
 93               executor policy (located in pegasus/src/Executor/Policy.c).
 94           */
 95           class PEGASUS_COMMON_LINKAGE Executor
 96           {
 97           public:
 98           
 99               /** Sets the local socket used to communicate with the executor.
100                   Warning: this method must be called before any other method or
101                   not at all.
102                   @sock the socket
103               */
104               static void setSock(int sock);
105           
106 kumpf 1.2     /** Return zero if the executor is the parent of the current process.
107                   If so, the methods below are handled by the executor. Otherwise,
108                   they are handled by alternative in-process "loopback" methods.
109                   @return 0=success, -1=failure
110               */
111               static int detectExecutor();
112           
113               /** Ping the executor to see if it is responsive.
114                   @return 0=success, -1=failure
115               */
116               static int ping();
117           
118               /** Open the given file with the given mode.
119                   @param path the path of the file.
120                   @param mode 'r'=read, 'w'=write, and 'a'=append.
121                   @return the file stream or NULL on failure.
122               */
123               static FILE* openFile(
124                   const char* path,
125                   int mode);
126           
127 kumpf 1.2     /** Rename the given file.
128                   @param oldPath the path of the old file.
129                   @param newPath the path of the new file.
130                   @return 0=success, -1=failure
131               */
132               static int renameFile(
133                   const char* oldPath,
134                   const char* newPath);
135           
136               /** Remove the given file.
137                   @path the path of the file that will be reoved.
138                   @return 0=success, -1=failure
139               */
140               static int removeFile(
141                   const char* path);
142           
143               /** Start a provider agent as the given user. The provider agent will
144                   load the given provider module.
145           
146                   @param module name of provider module to be loaded.
147                   @param pegasusHome the Pegasus home directory to use to find the
148 kumpf 1.2             cimprovagt executable.
149                   @param uid the UID to run the provider agent as.
150                   @param gid the GID to run the provider agent as.
151                   @param pid the PID of the new process (to be eventually passed to
152                       reapProviderAgent()).
153                   @param readPipe pipe used to read data from provider agent.
154                   @param writePipe pipe used to write data from provider agent.
155                   @return 0=success, -1=failure
156               */
157               static int startProviderAgent(
158                   const char* module,
159                   const String& pegasusHome,
160                   const String& userName,
161                   int uid,
162                   int gid,
163                   int& pid,
164                   AnonymousPipe*& readPipe,
165                   AnonymousPipe*& writePipe);
166           
167               /** Cause the executor to daemonize itself.
168                   @return 0=success, -1=failure
169 kumpf 1.2     */
170               static int daemonizeExecutor();
171           
172               /** Wait for the provider agent to exit.
173                   @param pid the process id obtained with startProviderAgent().
174                   @return 0=success, -1=failure
175               */
176               static int reapProviderAgent(
177                   int pid);
178           
179               /** Check whether the password is correct for the given user, using an
180                   underyling authentication mechanism (either PAM or cimserver.passwd
181                   file).
182                   @param username the name of a valid system user.
183                   @param password the clear text password for the given user.
184                   @return 0=success, -1=failure
185               */
186               static int authenticatePassword(
187                   const char* username,
188                   const char* password);
189           
190 kumpf 1.2     /** Check whether the given user is valid for the underlying authentcation
191                   mechanism.
192                   @param username the name of the user.
193                   @return 0=success, -1=failure
194               */
195               static int validateUser(
196                   const char* username);
197           
198               /** Begin authenticating the given *user* using the "local authentication"
199                   algorithm. A file containing a secret token is created on the local
200                   file system. The file is only readable by the given user. The caller
201                   should pass the path of this file to the client, who will attempt to
202                   read the secret token from the file and return it to the server. This
203                   token and the file path generated by this function should then be
204                   passed to authenticateLocal().
205                   @param username name of user to be challenged.
206                   @param challenge The challenge file path to be forwared by the caller
207                       to the client.
208                   @return 0=success, -1=failure
209               */
210               static int challengeLocal(
211 kumpf 1.2         const char* username,
212                   char challengeFilePath[EXECUTOR_BUFFER_SIZE]);
213           
214               /** Authenticate the given *user* using the "local authentication"
215                   algorithm. The secret token is read from the file created by
216                   challengeLocal(). If it matches the *response* argument,
217                   then the authentication is successful (returns zero).
218                   @param challengeFilePath The file path that was sent to the client
219                       to challenge for the secret token, generated by challengeLocal().
220                   @param response The challenge response obtained from the
221                       authenticating user. This is the response to the challenge
222                       obtained from challengeLocal().
223                   @return 0=success, -1=failure
224               */
225               static int authenticateLocal(
226                   const char* challengeFilePath,
227                   const char* response);
228           
229           private:
230               // Private to prevent instantiation.
231               Executor();
232 kumpf 1.2 };
233           
234           PEGASUS_NAMESPACE_END
235           
236           #endif /* _Pegasus_Common_Executor_h */