"Fossies" - the Fresh Open Source Software Archive 
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1 Introduction
2 ------------
3
4 mod_auth_dce is an Apache module for DCE-based authentication. It allows
5 you to run the server with or without credentials, authenticate remote
6 browsers, and optionally serve requests with the credentials of the
7 browsing user. You can control access to files either via standard web
8 server configuration directives, or via DFS ACLs.
9
10 With mod_auth_dce, you can supply DCE users and DCE groups to the Apache
11 require directive, and restrict access to files or resources so only the
12 listed users or groups can access them. In this mode, mod_auth_dce will
13 request authentication from the browser on every request, verify the
14 identity of the browsing user, and optionally attach the user's
15 credentials to the process serving the request.
16
17 When used with DFS, mod_auth_dce can also use DFS ACLs for authorization.
18 In this mode, mod_auth_dce will check the DFS ACL for each request. If the
19 file requested is readable by the server, it will be served with no
20 authentication required. If the file is not readable by the server,
21 mod_auth_dce will require authentication from the browser and use it to
22 obtain DCE credentials for the browsing user. The request will be
23 reprocessed using the DCE identity of the browser, and if the file
24 requested is readable by that user, it will be served. Otherwise, the
25 request will be forbidden.
26
27 mod_auth_dce is most useful when combined with DFS. Once mod_auth_dce has
28 been installed, access to files can be controlled simply by setting DFS
29 ACLs, with no further web server configuration required. However, support
30 of standard web server configuration directives allows mod_auth_dce to be
31 useful at sites without DFS, and also for protecting resources that are
32 not files, such as Apache handlers.
33
34 Other features of mod_auth_dce include login context caching, and DCE
35 authenticated CGI execution.
36
37 mod_auth_dce currently uses standard Basic authentication to get the
38 username and password. With stock Apache, this means the password is
39 transmitted in cleartext. However, if SSL is used, the password can be
40 encrypted.
41
42
43 Installation
44 ------------
45
46 To operate correctly, mod_auth_dce needs some minor patches to the Apache
47 source code. Please see the file README.PATCHES and apply the patch file.
48
49 Move the auth_dce subdirectory of the mod_auth_dce distribution to the
50 apache/src/modules directory after applying the patch. For example:
51
52 cd /path/to/mod_auth_dce
53 tar cf - auth_dce | (cd /path/to/apache/src/modules && tar xf -)
54
55
56 If you are using the Apache Autoconf-style Interface (APACI), supply the
57 option '--activate-module=src/modules/auth_dce/mod_auth_dce.c' to
58 configure. Otherwise, edit the Configuration file and add the line
59
60 AddModule modules/auth_dce/mod_auth_dce.o
61
62 In either case, mod_auth_dce will attempt to set compilation options
63 appropriately during the configuration process. If mod_auth_dce doesn't
64 recognize your OS, it will give a message and fail to configure. If you
65 are willing to help test mod_auth_dce for your platform, please contact
66 me.
67
68 Starting with version 3.0, mod_auth_dce includes a shared memory context
69 cache implementation. This improves the cache hit rate over the previous
70 per-process cache implementation, significantly reducing security server
71 load and web server response time under heavy request patterns.
72
73 Context caching is currently only supported on Solaris. For other
74 platforms, mod_auth_dce will disable caching during configuration. To
75 support context caching, a platform requires a shared memory mechanism
76 with a method to synchronize access by multiple processes. If you are
77 interested in helping test context caching on your platform, please
78 contact me.
79
80 While most cache functionality can be controlled via run-time
81 configuration directives, statistics generation is configured at compile
82 time. By default, processes will log cache statistics every 500
83 authenticated accesses. To disable statistics generation or change its
84 frequency, edit the mod_auth_dce.h file.
85
86 If DFS is not running on your web server, you'll need to edit the
87 mod_auth_dce.h file and comment out the '#define WITH_DFS' line before
88 compiling.
89
90
91 Configuration Directives
92 ------------------------
93
94 Directive Context Default Value
95 -----------------------------------------------------------------
96 AuthDCEUser server -none-
97
98 To run the server with credentials, set AuthDCEUser to the
99 principal whose credentials are to be acquired by the server.
100 This principal must have a valid account in the cell and an
101 entry in either the DCE default keytab or the keytab specified
102 in the AuthDCEKeytab directive.
103
104 Directive Context Default Value
105 -----------------------------------------------------------------
106 AuthDCEKeytab server DCE default keytab
107
108 Set this directive to the full path of a keytab that contains
109 an entry for the principal specified by the AuthDCEUser
110 directive. If omitted, the DCE default keytab will be used.
111
112 Directive Context Default Value
113 -----------------------------------------------------------------
114 AuthDCECertifyIdentify server Off
115
116 This directive controls whether or not the login contexts
117 generated by mod_auth_dce are certified. Certification
118 verifies that the login context came from a valid security
119 server. Certification is not possible on slim DCE clients, and
120 may or may not be necessary depending on how contexts are
121 used.
122
123 Directive Context Default Value
124 -----------------------------------------------------------------
125 AuthDCEAuthoritative directory On
126
127 When this directive is On, mod_auth_dce will either approve or
128 deny a request. When the directive is Off and a request is not
129 approved (due to authentication failure or access
130 restriction), mod_auth_dce will decline to handle the request
131 and allow other lower level modules to attempt authentication.
132
133 Directive Context Default Value
134 -----------------------------------------------------------------
135 AuthDCEImpersonateBrowser directory On
136
137 When this directive is On, the credentials of the browsing
138 user will be attached to the server process for the duration
139 of any request requiring authentication. If set to Off,
140 requests will be processed using the identity and credentials
141 (if any) of the server.
142
143 Directive Context Default Value
144 -----------------------------------------------------------------
145 AuthDCE directory Off
146
147 When this directive is On, DCE authentication is enabled
148 within the directory specified.
149
150 You will also need valid AuthType, AuthName, and require
151 directives in the Directory container. Currently, the only
152 supported AuthType is "Basic". List the authorized
153 users/groups for this directory in the require directive, or
154 see below for correct require configuration if
155 AuthDCEDFSAuthorization is enabled.
156
157 Directive Context Default Value
158 -----------------------------------------------------------------
159 AuthDCEDFSAuthorization directory Off
160
161 When this directive is On, DFS ACL checking is enabled within
162 the directory specified and mod_auth_dce will only require
163 authentication if the request is for a file not readable by
164 the server. If the server is running without DCE credentials,
165 server readability is controlled by the "any_other" entry on
166 the DFS ACL. Otherwise, it is controlled by the entries that
167 apply to the DCE identity of the server.
168
169 When AuthDCEDFSAuthorization is enabled, your require
170 directive should be set to "valid-user".
171
172 Directive Context Default Value
173 -----------------------------------------------------------------
174 AuthDCEIncludePW directory Off
175
176 Setting this directive to On will enable passing the browser's
177 password to CGI programs via the environment variable DCEPW.
178 Only enable this directive on web servers that do not allow
179 interactive logins. Otherwise, users could use the ps command
180 to potentially acquire plaintext passwords.
181
182 Directive Context Default Value
183 -----------------------------------------------------------------
184 AuthDCEDirectoryIndex directory DirectoryIndex default
185
186 This directive should be set to the same list of valid index
187 files as the DirectoryIndex directive.
188
189 mod_auth_dce needs this information to correctly serve server
190 readable index files in non server readable directories when
191 AuthDCEDFSAuthorization is enabled. Unfortunately, the list
192 already specified with DirectoryIndex is not available to
193 mod_auth_dce, necessitating this seemingly redundant
194 directive.
195
196 Directive Context Default Value
197 -----------------------------------------------------------------
198 AuthDCECacheBuckets server 1000
199
200 This directive configures how many buckets are in the cached
201 context hash table. Increase this if messages reporting "no
202 empty slots found in bucket" appear frequently in the error
203 log.
204
205 Directive Context Default Value
206 -----------------------------------------------------------------
207 AuthDCECacheLifetime server 21600 (6 hours)
208
209 This directive, along with the following two, controls how
210 long a context remains in the cache. A context will be in the
211 cache no longer than the sum of AuthDCECacheLifetime +
212 AuthDCECacheGracePeriod, which should be at most the valid
213 ticket lifetime in your DCE cell.
214
215 Directive Context Default Value
216 -----------------------------------------------------------------
217 AuthDCECacheMaxIdle server 14400 (4 hours)
218
219 This directive controls how long a cached context can remain
220 unused before being removed from the cache.
221
222 Directive Context Default Value
223 -----------------------------------------------------------------
224 AuthDCECacheGracePeriod server 7200 (2 hours)
225
226 This directive controls the maximum amount of time a context
227 marked as in use is retained in the cache after its lifetime
228 expires. It should be at least the estimated maximum time an
229 authenticated request will take to process.
230
231 Directive Context Default Value
232 -----------------------------------------------------------------
233 AuthDCECacheSweepInterval server 1800 (30 minutes)
234
235 This directive controls how often the cache maintenance thread
236 sweeps looking for cached contexts that can be removed. If
237 cache statistics generation is enabled, utilization statistics
238 are reported on each sweep.
239
240
241 NOTE: Previous versions of the documentation recommended not checking
242 for symlinks. However, if your web server publishes user files, a
243 user can potentially use symlinks to read other users' DCE
244 credential files. Therefore, the current recommendation is either
245 to disable symlinks, or to only allow symlinks if the owner
246 matches.
247
248
249 Configuration Guidelines
250 ------------------------
251
252 Your first decision when configuring mod_auth_dce is whether or not to
253 start the server with DCE credentials. If you start the server with
254 credentials, then all requests, authenticated or not, are processed either
255 with the credentials of the server or the credentials of the browsing
256 user. If the server is not started with credentials, then
257 non-authenticated requests are processed with no credentials, while
258 authenticated requests may be processed with the credentials of the
259 authenticated browsing user. If you are serving files in DFS, and the
260 server has no credentials, then any file to be served without
261 authentication must by readable by any_other. On the other hand, if the
262 server has credentials, then files may be served from DFS that are
263 readable by the server principal, but not necessarily by anyone else.
264 This, for example, allows you to have CGIs that anyone can execute, but no
265 one can view. To run the server with credentials, you must specify a valid
266 DCE principal/account via the AuthDCEUser configuration directive. This
267 account must have a valid keytab on the system. To use a non-default
268 keytab, the AuthDCEKeytab directive can be used. Note that only the child
269 server processes run with web server credentials, while the parent runs
270 with the credentials it was started with, if any. Therefore, logs must be
271 writable by the Unix identity of the parent server, generally root, or for
272 logs in DFS, the DCE identity of the machine, generally
273 hosts/hostname/self.
274
275 Your next decision is which, if any, pieces of your web space you wish to
276 protect using DCE authentication. Once you have identified these pieces,
277 you need to create a Location or Directory container for each identified
278 piece and include an AuthDCE directive (set to On). Then, you must decide
279 whether to restrict access based on explicitly named users/groups, or via
280 DFS ACLs. To use explicitly named users/groups, provide require directives
281 listing the authorized users and/or groups. To use DFS ACLs for access
282 control, include the AuthDCEDFSAuthorization directive (set to On) and a
283 require directive (set to valid-user).
284
285 For authenticated requests, you must decide whether or not to attach the
286 credentials of the authenticated browser to the process serving the
287 request. This is the default behavior, and if you are using
288 AuthDCEDFSAuthorization, is required. If you started the server with
289 credentials, and wish to serve the request using the credentials of the
290 server rather than the credentials of the authenticated browser, you must
291 disable this behavior by including the AuthDCEImpersonateBrowser directive
292 (set to Off).
293
294
295 DCE Authenticated CGIs
296 ----------------------
297
298 If you use DCE authentication for your cgi-bin directory, you can not only
299 restrict access to them, but when they run, they can also have full DCE
300 credentials of the browsing user. This feature can be used to create easy
301 to use remote DCE administration CGIs. For an example of the potential of
302 this feature, please see
303
304 http://www.csupomona.edu/intranet/services/
305
306
307 The identity of the browser is available to the CGI via the standard
308 REMOTE_USER environment variable. If AuthDCEIncludePW is set, then the
309 browser's DCE password is also available to the CGI via the DCEPW
310 environment variable. Do not set AuthDCEIncludePW on a web server that
311 also allows user logins, or the ps command could potentially be used to
312 compromise passwords.
313
314 You shouldn't allow untrusted users to place CGIs in a DCE authenticated
315 location, as they could then have their CGI run with a browser's
316 credentials.
317
318
319 Feedback/Availability
320 ---------------------
321
322 Please report any bugs or feature requests to <henson@acm.org>.
323
324
325 The latest version of mod_auth_dce is currently available at
326
327 http://www.csupomona.edu/~henson/www/projects/mod_auth_dce/