version 1.1, 2007/01/02 06:17:19
|
version 1.1.2.14, 2007/01/18 01:41:56
|
|
|
|
//%2006//////////////////////////////////////////////////////////////////////// |
|
// |
|
// Copyright (c) 2000, 2001, 2002 BMC Software; Hewlett-Packard Development |
|
// Company, L.P.; IBM Corp.; The Open Group; Tivoli Systems. |
|
// Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company, L.P.; |
|
// IBM Corp.; EMC Corporation, The Open Group. |
|
// Copyright (c) 2004 BMC Software; Hewlett-Packard Development Company, L.P.; |
|
// IBM Corp.; EMC Corporation; VERITAS Software Corporation; The Open Group. |
|
// Copyright (c) 2005 Hewlett-Packard Development Company, L.P.; IBM Corp.; |
|
// EMC Corporation; VERITAS Software Corporation; The Open Group. |
|
// Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.; |
|
// EMC Corporation; Symantec Corporation; The Open Group. |
|
// |
|
// Permission is hereby granted, free of charge, to any person obtaining a copy |
|
// of this software and associated documentation files (the "Software"), to |
|
// deal in the Software without restriction, including without limitation the |
|
// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or |
|
// sell copies of the Software, and to permit persons to whom the Software is |
|
// furnished to do so, subject to the following conditions: |
|
// |
|
// THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN |
|
// ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED |
|
// "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT |
|
// LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR |
|
// PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT |
|
// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN |
|
// ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION |
|
// WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
|
// |
|
//============================================================================== |
|
// |
|
//%///////////////////////////////////////////////////////////////////////////// |
|
|
|
#ifndef _Pegasus_Common_Executor_h |
|
#define _Pegasus_Common_Executor_h |
|
|
|
#include <Pegasus/Common/Config.h> |
|
#include <Pegasus/Common/MessageLoader.h> |
|
#include <Pegasus/Common/AnonymousPipe.h> |
|
#include <Pegasus/Common/Linkage.h> |
|
#include <Pegasus/Common/SessionKey.h> |
|
#include <Executor/Defines.h> |
|
#include <cstdio> |
|
|
|
PEGASUS_NAMESPACE_BEGIN |
|
|
|
/** The Executor class is used to perform various privileged operations. When |
|
Pegasus is built with privilege separation, the methods of this class are |
|
used to submit requests to a privileged process called and "executor". The |
|
current process communicates with the executor over an anonymous local |
|
domain socket. But, when Pegasus is built without privilege separation, |
|
the methods are implemented in the same process (within Executor.cpp). |
|
|
|
<br> |
|
When configured for privilege separation, the Pegasus server runs as two |
|
processes. |
|
|
|
<ul> |
|
<li>the executor (the cimserver program). |
|
<li>the server (the cimservermain program). |
|
</ul> |
|
|
|
The "executor" is the parent process. When it starts the server it passes |
|
the -x option with a socket number. The server checks for this option. It |
|
if finds it, is assumes it is running in privilege separation mode, in |
|
which case is calls Executor::setSock() with this socket number. |
|
|
|
<br> |
|
The Executor::detectExecutor() method is used in various places to see if |
|
the executor is present. For example. |
|
|
|
<pre> |
|
if (Executor::detectExecutor() == 0) |
|
{ |
|
// Executor is present. |
|
} |
|
</pre> |
|
|
|
The remaining methods provide an interface for submitting requests to the |
|
executor over the given socket, if present. Otherwise, the methods are |
|
handled directly by this class (see Executor.cpp). Here is a typical |
|
exampe of its usage. |
|
|
|
<pre> |
|
if (Executor::removeFile(path) == 0) |
|
{ |
|
// File successfully removed. |
|
} |
|
</pre> |
|
|
|
This example removes the given file. But be aware that the executor defines |
|
a policy that identifies which files it may removed (or manipulated by the |
|
other methods). In order to remove a file, the file must be added to the |
|
executor policy (located in pegasus/src/Executor/Policy.c). |
|
*/ |
|
class PEGASUS_COMMON_LINKAGE Executor |
|
{ |
|
public: |
|
|
|
/** Sets the local socket used to communicate with the executor. |
|
Warning: this method must be called before any other method or |
|
not at all. |
|
@sock the socket |
|
*/ |
|
static void setSock(int sock); |
|
|
|
/** Return zero if the executor is the parent of the current process. |
|
If so, the methods below are handled by the executor. Otherwise, |
|
they are handled by alternative in-process "loopback" methods. |
|
@return 0=success, -1=failure |
|
*/ |
|
static int detectExecutor(); |
|
|
|
/** Ping the executor to see if it is responsive. |
|
@return 0=success, -1=failure |
|
*/ |
|
static int ping(); |
|
|
|
/** Open the given file with the given mode. |
|
@param path the path of the file. |
|
@param mode 'r'=read, 'w'=write, and 'a'=append. |
|
@return the file stream or NULL on failure. |
|
*/ |
|
static FILE* openFile( |
|
const char* path, |
|
int mode); |
|
|
|
/** Rename the given file. |
|
@param oldPath the path of the old file. |
|
@param newPath the path of the new file. |
|
@return 0=success, -1=failure |
|
*/ |
|
static int renameFile( |
|
const char* oldPath, |
|
const char* newPath); |
|
|
|
/** Remove the given file. |
|
@path the path of the file that will be reoved. |
|
@return 0=success, -1=failure |
|
*/ |
|
static int removeFile( |
|
const char* path); |
|
|
|
/** Start a provider agent as the given user. The provider agent will |
|
load the given provider module. |
|
|
|
@param sessionKey a valid session key. |
|
@param module name of provider module to be loaded. |
|
@param uid the UID to run the provider agent as. |
|
@param gid the GID to run the provider agent as. |
|
@param pid the PID of the new process (to be eventually passed to |
|
reapProviderAgent()). |
|
@param providerAgentSessionKey a newly generated providerAgentSessionKey |
|
(to be eventually passed to reapProviderAgent()). |
|
@param readPipe pipe used to read data from provider agent. |
|
@param writePipe pipe used to write data from provider agent. |
|
@return 0=success, -1=failure |
|
*/ |
|
static int startProviderAgent( |
|
const SessionKey& sessionKey, |
|
const char* module, |
|
int uid, |
|
int gid, |
|
int& pid, |
|
SessionKey& providerAgentSessionKey, |
|
AnonymousPipe*& readPipe, |
|
AnonymousPipe*& writePipe); |
|
|
|
/** Cause the executor to daemonize itself. |
|
@return 0=success, -1=failure |
|
*/ |
|
static int daemonizeExecutor(); |
|
|
|
/** Wait for the provider agent to exit. |
|
@param sessionKey the sessionKey obtained with startProviderAgent(). |
|
@param pid the process id obtained with startProviderAgent(). |
|
@return 0=success, -1=failure |
|
*/ |
|
static int reapProviderAgent( |
|
const SessionKey& sessionKey, |
|
int pid); |
|
|
|
/** Check whether the password is correct for the given user, using an |
|
underyling authentication mechanism (either PAM or cimserver.passwd |
|
file). |
|
@param username the name of a valid system user. |
|
@param password the clear text password for the given user. |
|
@param sessionKey a new session key that may be passed to |
|
startProviderAgent() and other methods. |
|
@return 0=success, -1=failure |
|
*/ |
|
static int authenticatePassword( |
|
const char* username, |
|
const char* password, |
|
SessionKey& sessionKey); |
|
|
|
/** Check whether the given user is valid for the underlying authentcation |
|
mechanism. |
|
@param username the name of the user. |
|
@return 0=success, -1=failure |
|
*/ |
|
static int validateUser( |
|
const char* username); |
|
|
|
/** Begin authenticating the given *user* using the "local authentication" |
|
algorithm. A file containing a secret token is created on the local |
|
file system. The file is only reabable by the given user. The caller |
|
should pass the path of this file to the client, who will attempt to |
|
read the secret token from the file and return it to the server. This |
|
token and the session key generated by this function should then be |
|
passed to authenticateLocal(). |
|
@param username name of user to be challenged. |
|
@param challenged the challenge to be forwared by the caller to the |
|
client (this is the path name of the secrets file mentioned above). |
|
@param sessionKey a new session key that may be passed to the |
|
startProviderAgent() and other methods. |
|
@return 0=success, -1=failure |
|
*/ |
|
static int challengeLocal( |
|
const char* username, |
|
char challenge[EXECUTOR_BUFFER_SIZE], |
|
SessionKey& sessionKey); |
|
|
|
/** Authenticate the given *user* using the "local authentication" |
|
algorithm. The secret token is read from the file created by |
|
challengeLocal(). If it matches the *challengeResponse* argument, |
|
then the authentication is successful (returns zero). |
|
@param sessionKey a session key obtained from challengeLocal(). |
|
@param challengeResponse the challenge response obtained from the |
|
authenticating user. This is the response to the challenge |
|
obtained from challengeLocal(). |
|
@return 0=success, -1=failure |
|
*/ |
|
static int authenticateLocal( |
|
const SessionKey& sessionKey, |
|
const char* challengeResponse); |
|
|
|
/** Generate a new sesion key for the given user. This method will be |
|
limited as soon as the SSL certificate authentication scheme is |
|
moved into the executor (it will cease to generate session keys |
|
upon the very first client connection). |
|
@param username user for whom to create a session key. |
|
@param sessionKey new session key that may be passed to |
|
startProviderAgent() and other methods. |
|
@return 0=success, -1=failure |
|
*/ |
|
static int newSessionKey( |
|
const char username[EXECUTOR_BUFFER_SIZE], |
|
SessionKey& sessionKey); |
|
|
|
/** Delete an existing session key. |
|
@param sessionKey the session key that will be deleted. |
|
@return 0=success, -1=failure |
|
*/ |
|
static int deleteSessionKey( |
|
const SessionKey& sessionKey); |
|
|
|
private: |
|
// Private to prevent instantiation. |
|
Executor(); |
|
}; |
|
|
|
PEGASUS_NAMESPACE_END |
|
|
|
#endif /* _Pegasus_Common_Executor_h */ |