src/afsweb/WebSecure_Design.txt

   1 Copyright 2000, International Business Machines Corporation and others.
   2 All Rights Reserved.
   3
   4 This software has been released under the terms of the IBM Public
   5 License.  For details, see the LICENSE file in the top-level source
   6 directory or online at http://www.openafs.org/dl/license10.html
   7
   8                         AFS WEB SECURE DESIGN DOCUMENT
   9
  10
  11 Functionality (common to both Servers)
  12
  13 Any URL beginning with /afs is handled by the plug-in. If a username and
  14 password accompanies the request then the plug-in attempts to authenticate
  15 the user with AFS and uses that token for serving the request.
  16 However in the absense of any Authentication header it attempts to serve
  17 the request as it normally would (without the plug-in). If the request
  18 returns an OK status, the document is served as is. If it returns HTTP
  19 status FORBIDDEN, then the plug-in responds with an AUTHENTICATION_REQUIRED
  20 response with a part of the URL giving the /afs/<cell_name> as the part of
  21 the WWW-Authenticate header.
  22
  23
  24 Netscape Enterprise Server Plug-in
  25
  26 The Netscape Server is multithreaded (each incoming HTTP request is
  27 handled by a thread). This design led to the requirement of per thread
  28 authentication credentials for AFS, (without which there would be one common
  29 token for all the threads handling requests for possibly different users).
  30 Since the AFS kernel cache manager only provides per process authentication
  31 credentials (using Process Authentication Groups or PAG's), the plug-in
  32 required a user-space cache manager. Within this user space cache manager
  33 a data structure stores the authentication credentials in a manner similar
  34 to PAG's (first two bits used). The user space cache manager provides the
  35 capability of per thread authentication required for the Netscape Server.
  36
  37
  38 The Netscape Server API provides an initialization routine using which the
  39 user space cache manager is started up. Unlike the Apache Server plug-in, the
  40 Netscape AFS Web Secure Server does not have to be on an AFS client machine.
  41 Configuration files permit the administrator to specify disk cache directories
  42 other than that used by any other cache managers. Therefore it is possible
  43 to have more than one user space cache manager running on the same machine
  44 along with a kernel cache manager.
  45
  46 The configuration allows the administrator to specify what URL it should
  47 look for files in AFS. Tokens for user credentials are obtained and cached
  48 in the user-space cache manager, which essentially is a port of the kernel
  49 cache manager into user-space.
  50
  51
  52
  53 Apache Server Module
  54
  55 The Apache Server software provides an API for adding modules to the web server
  56 and for creating handlers for requests. AFS Web Secure for Apache is built as
  57 a standard Apache module (mod_afs.c) along with a library (libapacheafs.a) and
  58 two binaries (weblog_starter and weblog).
  59
  60 The web server is not multithreaded but each request is served by child
  61 processes (the number of which is configurable). AFS Authentication requires
  62 each child process to communicate with the weblog process over a UNIX pipe
  63 (file locking is used to provide exclusive access to the pipe). The child
  64 processes send authentication credentials (username, password and cellname)
  65 to the weblog process which authenticates the user with AFS using the
  66 ka_AuthenticateUserGeneral system call (as in klog). Once an AFS token is
  67 obtained it gets the token fro the cache manager using the lpioctl system
  68 call and sends the token back to the child process that requested it.
  69 Note that since AFS permits one token per cell per PAG, it is essential for
  70 each of the child processes to be in a unique PAG. The lsetpag system call
  71 is used on startup to ensure each child process and the weblog process
  72 belong to a unique PAG. Once the child process obtains the token from the
  73 weblog process it sets it using the lpioctl system call to set a token. It
  74 can then access files in AFS with the appropriate ACL's.
  75
  76 Caching of tokens is done at two levels - the weblog process caches all tokens
  77 for all user credentials that it recieves from all Apache child processes.
  78 Each child process in turn caches the credentials it recieves. Token times
  79 are configurable using the SetAFSCacheExpiration directive. The kernel cache
  80 manager may cache tokens for the time specified using the SetAFSTokenExpiration
  81 directive. This is similar to using klog -lifetime <time>.
  82
  83 The sequence of events for AFS authentication is :
  84
  85 On startup the web-server creates two pipes and spawns the weblog_starter
  86 process (nanny process to watch over the weblog process and restart it or log
  87 an error in case it dies), which in turn starts up the weblog process with
  88 the pipes' file descriptors (inherited) as command line parameters.
  89
  90 Apache Server Process recieves request and hands it to a child process
  91
  92 Child process checks to see if request should be handled by Web Secure
  93 (using a configurable parameter set using the SetAFSLocation directive)
  94
  95 If Authentication credentials accompany the request, the child process checks
  96 its local cache for a matching (username, password, cellname, checksum) token.
  97 If one is found it sets the token using lpioctl and attempts to serve the
  98 request normally. If no token is found in the local cache, it sends a request
  99 to the weblog process over the pipe (again inherited) consisting of a username
 100 password and cellname after locking the pipe for exclusive access. The weblog
 101 process checks it's own cache or obtains a token after authentication if
 102 the cache lookup fails, and sends the token back to the child process which
 103 caches it and sets it (lpioctl).
 104
 105 The child process then serves the document normally.
 106
 107 All the web server-side communication and system calls are in the
 108 libapacheafs.a library, except for the "hook" to plug-in to the apache source
 109 which is in mod_afs.c for which the source code must be provided. The library
 110 libapacheafs.a consists of the following object files:
 111
 112 apache_afs_plugin.o - Initialization routines - interface to calls in
 113                       apache_afs_client.o. Lies in between mod_afs.o and
 114                       apache_afs_client.o.
 115
 116 apache_afs_client.o - Apache child process functionality for obtaining
 117                       the user credentials from the HTTP request, getting
 118                       and caching AFS tokens, communicating with the weblog
 119                       process.
 120
 121 apache_afs_utils.o  - wrapper around pioctl and setpag system calls and
 122                       debugging utilities common to both weblog and apache plug
 123                       in.
 124
 125 apache_afs_cache.o  - token caching routines common to weblog and apache
 126                       plug-in
 127
 128 In order to use the pioctl and setpag system calls the web server binary must
 129 link to libsys.a which is usually in /usr/afsws/lib/afs/ on AFS client machines
 130
 131
 132
 133
 134
 135
 136
 137
 138