1 martin 1.7 //%LICENSE////////////////////////////////////////////////////////////////

  2 martin 1.8 //

  3 martin 1.7 // Licensed to The Open Group (TOG) under one or more contributor license
  4            // agreements.  Refer to the OpenPegasusNOTICE.txt file distributed with
  5            // this work for additional information regarding copyright ownership.
  6            // Each contributor licenses this file to you under the OpenPegasus Open
  7            // Source License; you may not use this file except in compliance with the
  8            // License.

  9 martin 1.8 //

 10 martin 1.7 // Permission is hereby granted, free of charge, to any person obtaining a
 11            // copy of this software and associated documentation files (the "Software"),
 12            // to deal in the Software without restriction, including without limitation
 13            // the rights to use, copy, modify, merge, publish, distribute, sublicense,
 14            // and/or sell copies of the Software, and to permit persons to whom the
 15            // Software is furnished to do so, subject to the following conditions:

 16 martin 1.8 //

 17 martin 1.7 // The above copyright notice and this permission notice shall be included
 18            // in all copies or substantial portions of the Software.

 19 martin 1.8 //

 20 martin 1.7 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS

 21 martin 1.8 // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

 22 martin 1.7 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 23            // IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 24            // CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 25            // TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 26            // SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

 27 martin 1.8 //

 28 martin 1.7 //////////////////////////////////////////////////////////////////////////

 29 kumpf  1.2 //
 30            //%/////////////////////////////////////////////////////////////////////////////
 31            
 32            #ifndef _Pegasus_Common_Executor_h
 33            #define _Pegasus_Common_Executor_h
 34            
 35            #include <Pegasus/Common/Config.h>
 36            #include <Pegasus/Common/MessageLoader.h>
 37            #include <Pegasus/Common/AnonymousPipe.h>
 38            #include <Pegasus/Common/Linkage.h>
 39            #include <Executor/Defines.h>
 40            #include <cstdio>
 41            
 42            PEGASUS_NAMESPACE_BEGIN
 43            
 44            /** The Executor class is used to perform various privileged operations. When
 45                Pegasus is built with privilege separation, the methods of this class are
 46                used to submit requests to a privileged process called and "executor". The
 47                current process communicates with the executor over an anonymous local
 48                domain socket. But, when Pegasus is built without privilege separation,
 49                the methods are implemented in the same process (within Executor.cpp).
 50 kumpf  1.2 
 51                <br>
 52                When configured for privilege separation, the Pegasus server runs as two
 53                processes.
 54            
 55                <ul>
 56                    <li>the executor (the cimserver program).
 57                    <li>the server (the cimservermain program).
 58                </ul>
 59            
 60                The "executor" is the parent process. When it starts the server it passes
 61                the -x option with a socket number. The server checks for this option. It
 62                if finds it, is assumes it is running in privilege separation mode, in
 63                which case is calls Executor::setSock() with this socket number.
 64            
 65                <br>
 66                The Executor::detectExecutor() method is used in various places to see if
 67                the executor is present. For example.
 68            
 69                    <pre>
 70                    if (Executor::detectExecutor() == 0)
 71 kumpf  1.2         {
 72                        // Executor is present.
 73                    }
 74                    </pre>
 75            
 76                The remaining methods provide an interface for submitting requests to the
 77                executor over the given socket, if present. Otherwise, the methods are
 78                handled directly by this class (see Executor.cpp). Here is a typical
 79                exampe of its usage.
 80            
 81                    <pre>
 82                    if (Executor::removeFile(path) == 0)
 83                    {
 84                        // File successfully removed.
 85                    }
 86                    </pre>
 87            
 88                This example removes the given file. But be aware that the executor defines
 89                a policy that identifies which files it may removed (or manipulated by the
 90                other methods). In order to remove a file, the file must be added to the
 91                executor policy (located in pegasus/src/Executor/Policy.c).
 92 kumpf  1.2 */
 93            class PEGASUS_COMMON_LINKAGE Executor
 94            {
 95            public:
 96            
 97                /** Sets the local socket used to communicate with the executor.
 98                    Warning: this method must be called before any other method or
 99                    not at all.
100                    @sock the socket
101                */
102                static void setSock(int sock);
103            
104                /** Return zero if the executor is the parent of the current process.
105                    If so, the methods below are handled by the executor. Otherwise,
106                    they are handled by alternative in-process "loopback" methods.
107                    @return 0=success, -1=failure
108                */
109                static int detectExecutor();
110            
111                /** Ping the executor to see if it is responsive.
112                    @return 0=success, -1=failure
113 kumpf  1.2     */
114                static int ping();
115            

116 kumpf  1.5     /** Open the given file with the given mode.  The file permissions are
117                    governed by Executor policy (if the Executor is called) or by the
118                    process umask setting.

119 kumpf  1.2         @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                /** 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 kumpf  1.2     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                        cimprovagt executable.

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

150 kumpf  1.2         @param pid the PID of the new process (to be eventually passed to
151                        reapProviderAgent()).
152                    @param readPipe pipe used to read data from provider agent.
153                    @param writePipe pipe used to write data from provider agent.
154                    @return 0=success, -1=failure
155                */
156                static int startProviderAgent(
157                    const char* module,
158                    const String& pegasusHome,
159                    const String& userName,
160                    int& pid,
161                    AnonymousPipe*& readPipe,
162                    AnonymousPipe*& writePipe);
163            

164 kumpf  1.6     /** Cause the executor to complete its daemonization and the cimserver
165                    command to exit with success status.

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

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

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