1 krisbash 1.1 /*
  2              **==============================================================================
  3              **
  4              ** Open Management Infrastructure (OMI)
  5              **
  6              ** Copyright (c) Microsoft Corporation
  7              ** 
  8              ** Licensed under the Apache License, Version 2.0 (the "License"); you may not 
  9              ** use this file except in compliance with the License. You may obtain a copy 
 10              ** of the License at 
 11              **
 12              **     http://www.apache.org/licenses/LICENSE-2.0 
 13              **
 14              ** THIS CODE IS PROVIDED *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 15              ** KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED 
 16              ** WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE, 
 17              ** MERCHANTABLITY OR NON-INFRINGEMENT. 
 18              **
 19              ** See the Apache 2 License for the specific language governing permissions 
 20              ** and limitations under the License.
 21              **
 22 krisbash 1.1 **==============================================================================
 23              */
 24              
 25              /*
 26              **==============================================================================
 27              **
 28              ** preexec.h:
 29              **
 30              **     The pre-exec feature allows a user-defined program to be executed
 31              **     immediately before invoking an out-of-process provider. Providers may
 32              **     use this feature by adding the following line in their provdier
 33              **     registration file:
 34              **
 35              **         PREEXEC=<PROGRAMNAME>
 36              **
 37              **     When a request for this provider is received, the program given by
 38              **     <PROGRAMNAME> is executed once per each unique UID-GID pair. For
 39              **     example, suppose the following requests are received for this provider:
 40              **
 41              **         Request-1: UID=101, GUID=101
 42              **         Request-2: UID=101, GUID=101
 43 krisbash 1.1 **         Request-3: UID=102, GUID=102
 44              **         Request-4: UID=102, GUID=102
 45              **         Request-5: UID=101, GUID=500
 46              **
 47              **     The program will be executed three times as shown below (since there
 48              **     are three unique UID-GID pairs):
 49              **
 50              **         Request-1: UID=101, GUID=101 (executed)
 51              **         Request-2: UID=101, GUID=101
 52              **         Request-3: UID=102, GUID=102 (executed)
 53              **         Request-4: UID=102, GUID=102
 54              **         Request-5: UID=101, GUID=500 (executed)
 55              **
 56              **     The pre-exec module caches this information to avoid invoking the
 57              **     same program more than once for the same UID-GID pair. The key for
 58              **     this cache is formed as follows:
 59              **
 60              **         <PROGRAMNAME>+<UID>+<GID>
 61              **
 62              **     For a program named 'DogPreExec' the keys are determined as follows:
 63              **
 64 krisbash 1.1 **         Request-1: UID=101, GUID=101 (DogPreExec+101+101)
 65              **         Request-2: UID=101, GUID=101 (DogPreExec+101+101)
 66              **         Request-3: UID=102, GUID=102 (DogPreExec+102+102)
 67              **         Request-4: UID=102, GUID=102 (DogPreExec+102+102)
 68              **         Request-5: UID=101, GUID=500 (DogPreExec+101+500)
 69              **
 70              **     The server determines whether to execute a pre-exec program with
 71              **     the following logic:
 72              **
 73              **         (1) The dispatcher receives a request for a given provider.
 74              **         (2) Checks whether the registration defines a PREEXEC line.
 75              **         (3) If so it invokes PreExec_Exec().
 76              **         (4) Checks whether PROGRAMNAME-UID-GID is in the cache.
 77              **         (6) Adds PROGRAMNAME-UID-GUID to the cache.
 78              **         (5) If not initially in the cache, invokes the program.
 79              **
 80              **     The pre-exec program is executed with the following parameters:
 81              **
 82              **         argc=3
 83              **         argv[0]=<FULLPROGRAMPATH>
 84              **         argv[1]=<UID>
 85 krisbash 1.1 **         argv[2]=<GID>
 86              **
 87              **     This feature is not built by default. To include this feature, OMI
 88              **     must be configured with the --enable-preexec option.
 89              **
 90              **     Notes:
 91              **
 92              **         (1) PREEXEC must refer to program that resides in the OMI
 93              **             binary directory (otherwise it would allow any program
 94              **             anywhere to be executed as root).
 95              **
 96              **         (2) It is the administrators responsibility to be certain that
 97              **             the OMI directory tree is secure. For example, the binary
 98              **             and registration directories shoujld only be writable by root.
 99              **
100              **         (3) Execution of pre-exec programs is as secure as loading of
101              **             providers as root. The security is determined by correct
102              **             permissions on the binary, registration, and provider
103              **             directories.
104              **
105              **         (4) If two provider registration files define the same PREEXEC
106 krisbash 1.1 **             line, the same program will still only be executed at most
107              **
108              **             once for each UID-GID pair.
109              **         (5) This feature is not available on Windows since it goes against
110              **             the Windows authentication policies. On Windows, one should use
111              **             root providers in conjunction with impersonation.
112              **
113              **         (6) During program execution, this module blocks SIGCHLD signals
114              **             which are usually handled by a global signal handler (see
115              **             server/server.c). It does this so that waidpid() will work
116              **             correctly (as it waits on the completion code of the pre-exec
117              **             program). Otherwise obth the global SIGCHLD handler and this
118              **             module would both call waitpid() and one or the other would
119              **             not respond.
120              **
121              **==============================================================================
122              */
123              
124              #ifndef _disp_preexec_h
125              #define _disp_preexec_h
126              
127 krisbash 1.1 #include <common.h>
128              #include <pal/hashmap.h>
129              
130              typedef struct _PreExec
131              {
132                  /* Key=PREEXECPATH+UID+GID */
133                  HashMap cache;
134              }
135              PreExec;
136              
137              int PreExec_Construct(
138                  PreExec* self);
139              
140              void PreExec_Destruct(
141                  PreExec* self);
142              
143              int PreExec_Exec(
144                  PreExec* self,
145                  const char* programPath,
146                  uid_t uid,
147                  uid_t gid);
148 krisbash 1.1 
149              #endif /* _disp_preexec_h */