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 kumpf 1.5     /** Open the given file with the given mode.  The file permissions are
119                   governed by Executor policy (if the Executor is called) or by the
120                   process umask setting.

121 kumpf 1.2         @param path the path of the file.
122                   @param mode 'r'=read, 'w'=write, and 'a'=append.
123                   @return the file stream or NULL on failure.
124               */
125               static FILE* openFile(
126                   const char* path,
127                   int mode);
128           
129               /** Rename the given file.
130                   @param oldPath the path of the old file.
131                   @param newPath the path of the new file.
132                   @return 0=success, -1=failure
133               */
134               static int renameFile(
135                   const char* oldPath,
136                   const char* newPath);
137           
138               /** Remove the given file.
139                   @path the path of the file that will be reoved.
140                   @return 0=success, -1=failure
141               */
142 kumpf 1.2     static int removeFile(
143                   const char* path);
144           
145               /** Start a provider agent as the given user. The provider agent will
146                   load the given provider module.
147           
148                   @param module name of provider module to be loaded.
149                   @param pegasusHome the Pegasus home directory to use to find the
150                       cimprovagt executable.

151 kumpf 1.3         @param userName the user name to run the provider agent as.

152 kumpf 1.2         @param pid the PID of the new process (to be eventually passed to
153                       reapProviderAgent()).
154                   @param readPipe pipe used to read data from provider agent.
155                   @param writePipe pipe used to write data from provider agent.
156                   @return 0=success, -1=failure
157               */
158               static int startProviderAgent(
159                   const char* module,
160                   const String& pegasusHome,
161                   const String& userName,
162                   int& pid,
163                   AnonymousPipe*& readPipe,
164                   AnonymousPipe*& writePipe);
165           
166               /** Cause the executor to daemonize itself.
167                   @return 0=success, -1=failure
168               */
169               static int daemonizeExecutor();
170           
171               /** Wait for the provider agent to exit.
172                   @param pid the process id obtained with startProviderAgent().
173 kumpf 1.2         @return 0=success, -1=failure
174               */
175               static int reapProviderAgent(
176                   int pid);
177           
178               /** Check whether the password is correct for the given user, using an
179                   underyling authentication mechanism (either PAM or cimserver.passwd
180                   file).
181                   @param username the name of a valid system user.
182                   @param password the clear text password for the given user.
183                   @return 0=success, -1=failure
184               */
185               static int authenticatePassword(
186                   const char* username,
187                   const char* password);
188           
189               /** Check whether the given user is valid for the underlying authentcation
190                   mechanism.
191                   @param username the name of the user.
192                   @return 0=success, -1=failure
193               */
194 kumpf 1.2     static int validateUser(
195                   const char* username);
196           
197               /** Begin authenticating the given *user* using the "local authentication"
198                   algorithm. A file containing a secret token is created on the local
199                   file system. The file is only readable by the given user. The caller
200                   should pass the path of this file to the client, who will attempt to
201                   read the secret token from the file and return it to the server. This
202                   token and the file path generated by this function should then be
203                   passed to authenticateLocal().
204                   @param username name of user to be challenged.
205                   @param challenge The challenge file path to be forwared by the caller
206                       to the client.
207                   @return 0=success, -1=failure
208               */
209               static int challengeLocal(
210                   const char* username,
211                   char challengeFilePath[EXECUTOR_BUFFER_SIZE]);
212           
213               /** Authenticate the given *user* using the "local authentication"
214                   algorithm. The secret token is read from the file created by
215 kumpf 1.2         challengeLocal(). If it matches the *response* argument,
216                   then the authentication is successful (returns zero).
217                   @param challengeFilePath The file path that was sent to the client
218                       to challenge for the secret token, generated by challengeLocal().
219                   @param response The challenge response obtained from the
220                       authenticating user. This is the response to the challenge
221                       obtained from challengeLocal().
222                   @return 0=success, -1=failure
223               */
224               static int authenticateLocal(
225                   const char* challengeFilePath,
226                   const char* response);
227           

228 kumpf 1.4     /** Update the log level used by the Executor process.
229                   @param logLevel the new log level to use in the Executor.
230                   @return 0=success, -1=failure
231               */
232               static int updateLogLevel(
233                   const char* logLevel);
234           

235 kumpf 1.2 private:
236               // Private to prevent instantiation.
237               Executor();
238           };
239           
240           PEGASUS_NAMESPACE_END
241           
242           #endif /* _Pegasus_Common_Executor_h */