"Fossies" - the Fresh Open Source Software Archive

Member "mod_auth_dce-3.4/README" (27 Jul 2001, 15187 Bytes) of package /linux/www/apache_httpd_modules/old/mod_auth_dce-3.4.tar.gz:

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 ------------
    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.
   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.
   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.
   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.
   34 Other features of mod_auth_dce include login context caching, and DCE
   35 authenticated CGI execution.
   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.
   43 Installation
   44 ------------
   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.
   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:
   52      cd /path/to/mod_auth_dce
   53      tar cf - auth_dce | (cd /path/to/apache/src/modules && tar xf -)
   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
   60      AddModule modules/auth_dce/mod_auth_dce.o
   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.
   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.
   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.
   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.
   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.
   91 Configuration Directives
   92 ------------------------
   94   Directive                  Context         Default Value
   95   -----------------------------------------------------------------
   96   AuthDCEUser                server          -none-
   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.
  104   Directive                  Context         Default Value
  105   -----------------------------------------------------------------
  106   AuthDCEKeytab              server          DCE default keytab
  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.
  112   Directive                  Context         Default Value
  113   -----------------------------------------------------------------
  114   AuthDCECertifyIdentify     server          Off
  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.
  123   Directive                  Context         Default Value
  124   -----------------------------------------------------------------
  125   AuthDCEAuthoritative       directory       On
  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.
  133   Directive                  Context         Default Value
  134   -----------------------------------------------------------------
  135   AuthDCEImpersonateBrowser  directory       On
  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.
  143   Directive                  Context         Default Value
  144   -----------------------------------------------------------------
  145   AuthDCE                    directory       Off
  147     When this directive is On, DCE authentication is enabled
  148     within the directory specified.
  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.
  157   Directive                  Context         Default Value
  158   -----------------------------------------------------------------
  159   AuthDCEDFSAuthorization    directory       Off
  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.
  169     When AuthDCEDFSAuthorization is enabled, your require
  170     directive should be set to "valid-user".
  172   Directive                  Context         Default Value
  173   -----------------------------------------------------------------
  174   AuthDCEIncludePW           directory       Off
  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.
  182   Directive                  Context         Default Value
  183   -----------------------------------------------------------------
  184   AuthDCEDirectoryIndex      directory       DirectoryIndex default
  186     This directive should be set to the same list of valid index
  187     files as the DirectoryIndex directive.
  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.
  196   Directive                  Context         Default Value
  197   -----------------------------------------------------------------
  198   AuthDCECacheBuckets        server          1000
  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.
  205   Directive                  Context         Default Value
  206   -----------------------------------------------------------------
  207   AuthDCECacheLifetime       server          21600 (6 hours)
  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.
  215   Directive                  Context         Default Value
  216   -----------------------------------------------------------------
  217   AuthDCECacheMaxIdle        server          14400 (4 hours)
  219     This directive controls how long a cached context can remain
  220     unused before being removed from the cache.
  222   Directive                  Context         Default Value
  223   -----------------------------------------------------------------
  224   AuthDCECacheGracePeriod    server          7200 (2 hours)
  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.
  231   Directive                  Context         Default Value
  232   -----------------------------------------------------------------
  233   AuthDCECacheSweepInterval  server          1800 (30 minutes)
  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.
  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.
  249 Configuration Guidelines
  250 ------------------------
  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.
  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).
  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).
  295 DCE Authenticated CGIs
  296 ----------------------
  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
  304      http://www.csupomona.edu/intranet/services/
  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.
  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.
  319 Feedback/Availability
  320 ---------------------
  322 Please report any bugs or feature requests to <henson@acm.org>.
  325 The latest version of mod_auth_dce is currently available at
  327 http://www.csupomona.edu/~henson/www/projects/mod_auth_dce/