]> git.ipfire.org Git - thirdparty/squid.git/commitdiff
cleaned up formatting of Authentication Framework section
authorwessels <>
Mon, 18 Jun 2001 22:02:55 +0000 (22:02 +0000)
committerwessels <>
Mon, 18 Jun 2001 22:02:55 +0000 (22:02 +0000)
doc/Programming-Guide/prog-guide.sgml

index 8c5f510560bf20ee6b91876b26b3d38b215bb437..060e03cae8173fc3d928359bed0fe86e1a1e753c 100644 (file)
@@ -2,7 +2,7 @@
 <article>
 <title>Squid Programmers Guide</title>
 <author>Duane Wessels, Squid Developers
-<date>$Id: prog-guide.sgml,v 1.40 2001/05/08 15:24:34 hno Exp $</date>
+<date>$Id: prog-guide.sgml,v 1.41 2001/06/18 16:02:55 wessels Exp $</date>
 
 <abstract>
 Squid is a WWW Cache application developed by the National Laboratory
@@ -156,10 +156,11 @@ Squid consists of the following major components
 <sect1>Authentication Framework
 
        <P>
-       These functions are responsible for handling HTTP authentication.
-       They follow a modular framework allow different authentication schemes
-       to be added at will. For information on working with the authentication schemes
-       See the chapter Authentication Framework.
+       These functions are responsible for handling HTTP
+       authentication.  They follow a modular framework allow
+       different authentication schemes to be added at will. For
+       information on working with the authentication schemes See
+       the chapter Authentication Framework.
 
 <sect1>Network Communication
 
@@ -2022,16 +2023,8 @@ coupling between the storage layer and the replacement policy.
 
 <!-- %%%% Chapter : Authentication Framework %%%% -->
 <sect>Authentication Framework
-
-       <P>
-        <enum>
-        <item>Definition of an auth scheme.
-        <item>Data types
-        <item>How to add a new auth scheme
-        <item>How to 'hook in' new functions to the API.</enum>
                
-       <P>
-       Definition of an auth scheme
+<sect1>Definition of an auth scheme
                
        <P>An auth scheme in squid is the collection of functions required to
         manage the authentication process for a given HTTP authentication
@@ -2049,158 +2042,177 @@ coupling between the storage layer and the replacement policy.
         squid will allow a auth scheme helper to return group information for a
         user, to allow Squid to more seamlessly implement access control.
                
-       <P>Data types
+<sect1>Data types
                
        <P>The data types are presented in C for the simple reason that squid is
         currently written exclusively in C.
                
-       <P>Function typedefs.
+       <sect2>Function typedefs.
        
        <P>Each function related to the general case of HTTP authentication has
         a matching typedef. There are some additional function types used to
         register/initialize, deregister/shutdown and provide stats on auth
         modules:
+
+       <descrip>
                
-       <P>typedef int   AUTHSACTIVE();
+       <tag/typedef int   AUTHSACTIVE();/
                
-       <P>The Active function is used by squid to determine whether the auth
-        module has successfully initialised itself with the current configuration.
+       <P>The Active function is used by squid to determine whether
+       the auth module has successfully initialised itself with
+       the current configuration.
 
-       <P>typedef int   AUTHSCONFIGURED();
+       <tag/typedef int   AUTHSCONFIGURED();/
 
-       <P>The configured function is used to see if the auth module has been given 
-       valid parameters and is able to handle authentication requests if initialised.
-       If configured returns 0 no other module functions except 
+       <P>The configured function is used to see if the auth module
+       has been given valid parameters and is able to handle
+       authentication requests if initialised.  If configured
+       returns 0 no other module functions except
        Shutdown/Dump/Parse/FreeConfig will be called by Squid.
 
-       <P>typedef void  AUTHSSETUP(authscheme_entry_t *);
+       <tag/typedef void  AUTHSSETUP(authscheme_entry_t *);/
+
+       <P>functions of type AUTHSSETUP are used to register an
+       auth module with squid. The registration function MUST be
+       named "authSchemeSetup_SCHEME" where SCHEME is the auth_scheme
+       as defined by RFC 2617. Only one auth scheme registered in
+       squid can provide functionality for a given auth_scheme.
+       (I.e. only one auth module can handle Basic, only one can
+       handle Digest and so forth). The Setup function is responsible
+       for registering the functions in the auth module into the
+       passed authscheme_entry_t. The authscheme_entry_t will
+       never be NULL. If it is NULL the auth module should log an
+       error and do nothing. The other functions can have any
+       desired name that does not collide with any statically
+       linked function name within Squid. It is recommended to
+       use names of the form "authe_SCHEME_FUNCTIONNAME" (for
+       example authenticate_NTLM_Active is the Active() function
+       for the NTLM auth module.
                
-       <P>functions of type AUTHSSETUP are used to register an auth module with
-        squid. The registration function MUST be named
-        "authSchemeSetup_SCHEME" where SCHEME is the auth_scheme as
-        defined by RFC 2617. Only one auth scheme registered in squid can
-        provide functionality for a given auth_scheme. (I.e. only one auth
-        module can handle Basic, only one can handle Digest and so forth). The
-        Setup function is responsible for registering the functions in the
-        auth module into the passed authscheme_entry_t. The authscheme_entry_t
-        will never be NULL. If it is NULL the auth module should log an error
-        and do nothing. The other functions can have any desired name that does
-        not collide with any statically linked function name within Squid. It is
-        recommended to use names of the form "authe_SCHEME_FUNCTIONNAME" (for example
-        authenticate_NTLM_Active is the Active() function for the NTLM auth
-        module.
-               
-       <P>typedef void  AUTHSSHUTDOWN(void);
-               
-       <P>Functions of type AUTHSSHUTDOWN are responsible for freeing any
-        resources used by the auth modules. The shutdown function will be called
-        before squid reconfigures, and before squid shuts down.
-               
-       <P>typedef void  AUTHSINIT(authScheme *);
-               
-       <P>Functions of type AUTHSINIT are responsible for allocating any
-        needed resources for the authentication module. AUTHSINIT functions are
-        called after each configuration takes place before any new requests are
-        made.
+       <tag/typedef void  AUTHSSHUTDOWN(void);/
+
+       <P>Functions of type AUTHSSHUTDOWN are responsible for
+       freeing any resources used by the auth modules. The shutdown
+       function will be called before squid reconfigures, and
+       before squid shuts down.
                
-       <P>typedef void  AUTHSPARSE(authScheme *, int, char *);
+       <tag/typedef void  AUTHSINIT(authScheme *);/
+
+       <P>Functions of type AUTHSINIT are responsible for allocating
+       any needed resources for the authentication module. AUTHSINIT
+       functions are called after each configuration takes place
+       before any new requests are made.
                
+       <tag/typedef void  AUTHSPARSE(authScheme *, int, char *);/
+
        <P>Functions of type AUTHSPARSE are responsible for parsing
-        authentication parameters. The function currently needs a scheme scope
-        data structure to store the configuration in. The passed scheme's
-        scheme_data pointer should point to the local data structure. Future
-        development will allow all authentication schemes direct access to their
-        configuration data without a locally scope structure. The parse function
-        is called by Squid's config file parser when a auth_param scheme_name
-        entry is encountered.
-               
-       <P>typedef void  AUTHSFREECONFIG(authScheme *);
+       authentication parameters. The function currently needs a
+       scheme scope data structure to store the configuration in.
+       The passed scheme's scheme_data pointer should point to
+       the local data structure. Future development will allow
+       all authentication schemes direct access to their configuration
+       data without a locally scope structure. The parse function
+       is called by Squid's config file parser when a auth_param
+       scheme_name entry is encountered.
                
-       <P>Functions of type AUTHSFREECONFIG are called by squid when freeing
-        configuration data. The auth scheme should free any memory allocated
-        that is related to parse data structures. The scheme MAY take advantage
-        of this call to remove scheme local configuration dependent data. (Ie
-        cached user details that are only relevant to a config setting).
+       <tag/typedef void  AUTHSFREECONFIG(authScheme *);/
+
+       <P>Functions of type AUTHSFREECONFIG are called by squid
+       when freeing configuration data. The auth scheme should
+       free any memory allocated that is related to parse data
+       structures. The scheme MAY take advantage of this call to
+       remove scheme local configuration dependent data. (Ie cached
+       user details that are only relevant to a config setting).
                
-       <P>typedef void  AUTHSDUMP(StoreEntry *, const char *, authScheme *);
-               
-       <P>Functions of type AUTHSDUMP are responsible for writing to the
-        StoreEntry the configuration parameters that a user would put in a
-        config file to recreate the running configuration.
+       <tag/typedef void  AUTHSDUMP(StoreEntry *, const char *, authScheme *);/
+
+       <P>Functions of type AUTHSDUMP are responsible for writing
+       to the StoreEntry the configuration parameters that a user
+       would put in a config file to recreate the running
+       configuration.
                
-       <P>typedef void  AUTHSSTATS(StoreEntry *);
-        <P>Functions of type AUTHSSTATS are called by the cachemgr to provide
-        statistics on the authmodule. Current modules simply provide the
-        statistics from the back end helpers (number of requests, state of the
-        helpers), but more detailed statistics are possible - for example unique
-        users seen or failed authentication requests.
-        <P>The next set of functions work on the data structures used by the
-        authentication schemes.
+       <tag/typedef void  AUTHSSTATS(StoreEntry *);/
+
+       <P>Functions of type AUTHSSTATS are called by the cachemgr
+       to provide statistics on the authmodule. Current modules
+       simply provide the statistics from the back end helpers
+       (number of requests, state of the helpers), but more detailed
+       statistics are possible - for example unique users seen or
+       failed authentication requests.  <P>The next set of functions
+       work on the data structures used by the authentication
+       schemes.
                
-       <P>typedef void  AUTHSREQFREE(auth_user_request_t *);
+       <tag/typedef void  AUTHSREQFREE(auth_user_request_t *);/
        
        <P>The AUTHSREQFREE function is called when a auth_user_request is being
         freed by the authentication framework, and scheme specific data was
         present. The function should free any scheme related data and MUST set
         the scheme_data pointer to NULL. Failure to unlink the scheme data will
         result in squid dying.
+
+       <tag/typedef char *AUTHSUSERNAME(auth_user_t *);/
+
+       <P>Squid does not make assumptions about where the username
+       is stored.  This function must return a pointer to a NULL
+       terminated string to be used in logging the request. Return
+       NULL if no username/usercode is known. The string should
+       NOT be allocated each time this function is called.
+
+       <tag/typedef int   AUTHSAUTHED(auth_user_request_t *);/
+
+       <P>The AUTHED function is used by squid to determine whether
+       the auth scheme has successfully authenticated the user
+       request. If timeouts on cached credentials have occurred
+       or for any reason the credentials are not valid, return
+       false.<P>The next set of functions perform the actual
+       authentication. The functions are used by squid for both
+       WWW- and Proxy- authentication. Therefore they MUST NOT
+       assume the authentication will be based on the Proxy-*
+       Headers.
                
-       <P>typedef char *AUTHSUSERNAME(auth_user_t *);
-               
-       <P>Squid does not make assumptions about where the username is stored.
-        This function must return a pointer to a NULL terminated string to be
-        used in logging the request. Return NULL if no username/usercode is
-        known. The string should NOT be allocated each time this function is
-        called.
-               
-       <P>typedef int   AUTHSAUTHED(auth_user_request_t *);
-       
-       <P>The AUTHED function is used by squid to determine whether the auth
-        scheme has successfully authenticated the user request. If timeouts on
-        cached credentials have occurred or for any reason the credentials are
-        not valid, return false.<P>The next set of
-        functions perform the actual authentication. The functions are used by
-        squid for both WWW- and Proxy- authentication. Therefore they MUST NOT
-        assume the authentication will be based on the Proxy-* Headers.
-               
-       <P>typedef void  AUTHSAUTHUSER(auth_user_request_t *, request_t *, ConnStateData *, http_hdr_type);
-        <P>Functions of type AUTHSAUTHUSER are called when Squid has a request
-        that needs authentication. If needed the auth scheme can alter the
-        auth_user pointer (usually to point to a previous instance of the user
-        whose name is discovered late in the auth process. For an example of
-        this see the NTLM scheme). These functions are responsible for
-        performing any in-squid routines for the authentication of the user. The
-        auth_user_request struct that is passed around is only persistent for
-        the current request. If the auth module requires access to the structure
-        in the future it MUST lock it, and implement some method for identifying
-        it in the future. For example the NTLM module implements a connection
-        based authentication scheme, so the auth_user_request struct gets
-        referenced from the ConnStateData.
+       <tag/typedef void  AUTHSAUTHUSER(auth_user_request_t *, request_t *, ConnStateData *, http_hdr_type);/
+
+       <P>Functions of type AUTHSAUTHUSER are called when Squid
+       has a request that needs authentication. If needed the auth
+       scheme can alter the auth_user pointer (usually to point
+       to a previous instance of the user whose name is discovered
+       late in the auth process. For an example of this see the
+       NTLM scheme). These functions are responsible for performing
+       any in-squid routines for the authentication of the user.
+       The auth_user_request struct that is passed around is only
+       persistent for the current request. If the auth module
+       requires access to the structure in the future it MUST lock
+       it, and implement some method for identifying it in the
+       future. For example the NTLM module implements a connection
+       based authentication scheme, so the auth_user_request struct
+       gets referenced from the ConnStateData.
                
-       <P>typedef void  AUTHSDECODE(auth_user_request_t *, const char *);
+       <tag/typedef void  AUTHSDECODE(auth_user_request_t *, const char *);/
                
        <P>Functions of type AUTHSDECODE are responsible for decoding the passed
         authentication header, creating or linking to a auth_user struct and for
         storing any needed details to complete authentication in AUTHSAUTHUSER.
                
-       <P>typedef int   AUTHSDIRECTION(auth_user_request_t *);
+       <tag/typedef int   AUTHSDIRECTION(auth_user_request_t *);/
                
        <P>Functions of type AUTHSDIRECTION are used by squid to determine what
         the next step in performing authentication for a given scheme is. The
         following are the return codes:
         
-        -2 = error in the auth module. Cannot determine request direction.
-        -1 = the auth module needs to send data to an external helper.
+       <itemize>
+        <item>-2 = error in the auth module. Cannot determine request direction.
+        <item>-1 = the auth module needs to send data to an external helper.
         Squid will prepare for a callback on the request and call the
          AUTHSSTART function.
-         0 = the auth module has all the information it needs to
+         <item>0 = the auth module has all the information it needs to
            perform the authentication and provide a succeed/fail result.
-         1 = the auth module needs to send a new challenge to the
+         <item>1 = the auth module needs to send a new challenge to the
          request originator. Squid will return the appropriate status code
          (401 or 407) and call the registered FixError function to allow the
          auth module to insert it's challenge.
+       </itemize>
                
-       <P>typedef void  AUTHSFIXERR(auth_user_request_t *, HttpReply *, http_hdr_type, request_t *);
+       <tag/typedef void  AUTHSFIXERR(auth_user_request_t *, HttpReply *, http_hdr_type, request_t *);/
                
        <P>Functions of type AUTHSFIXERR are used by squid to add scheme
         specific challenges when returning a 401 or 407 error code. On requests
@@ -2212,15 +2224,17 @@ coupling between the storage layer and the replacement policy.
         match the request, the authentication credentials in the request are
         ignored - and all auth modules are called.
 
-       <P>typedef void  AUTHSFREE(auth_user_t *);
+       <tag/typedef void  AUTHSFREE(auth_user_t *);/
                
        <P>These functions are responsible for freeing scheme specific data from
         the passed auth_user_t structure. This should only be called by squid
         when there are no outstanding requests linked to the auth user. This includes
        removing the user from any scheme specific memory caches.
                
-       <P>typedef void  AUTHSADDHEADER(auth_user_request_t *, HttpReply *, int);
-        typedef void  AUTHSADDTRAILER(auth_user_request_t *, HttpReply *, int);
+       <tag/typedef void  AUTHSADDHEADER(auth_user_request_t *, HttpReply *, int);/
+       <p>
+
+        <tag/typedef void  AUTHSADDTRAILER(auth_user_request_t *, HttpReply *, int);/
                
        <P>These functions are responsible for adding any authentication
         specific header(s) or trailer(s) OTHER THAN the WWW-Authenticate and
@@ -2231,32 +2245,36 @@ coupling between the storage layer and the replacement policy.
         auth_user_request exists in a request when the reply is constructed
         after the body is sent on chunked replies respectively.
                
-       <P>typedef void  AUTHSONCLOSEC(ConnStateData *);
+       <tag/typedef void  AUTHSONCLOSEC(ConnStateData *);/
                
        <P>This function type is called when a auth_user_request is
         linked into a ConnStateData struct, and the connection is closed. If any
         scheme specific activities related to the request or connection are in
         progress, this function MUST clear them.
                
-       <P>typedef void AUTHSSTART(auth_user_request_t * , RH * , void *);
+       <tag/typedef void AUTHSSTART(auth_user_request_t * , RH * , void *);/
                
        <P>This function type is called when squid is ready to put the request
         on hold and wait for a callback from the auth module when the auth
         module has performed it's external activities.
-               
-       <P>Structures
+
+       </descrip>
+
+       <sect2>Structures
                
        <P>This is used to link auth_users into the username cache. Because some
         schemes may link in aliases to a user, the link is not part of the
         auth_user structure itself.
                
-       <P>struct _auth_user_hash_pointer {
+       <verb>
+struct _auth_user_hash_pointer {
     /* first two items must be same as hash_link */
     char *key;
     auth_user_hash_pointer *next;
     auth_user_t *auth_user;
     dlink_node link; /* other hash entries that point to the same auth_user */
-        };
+};
+       </verb>
                
        <P>This is the main user related structure. It stores user-related data,
         and is persistent across requests. It can even persistent across
@@ -2264,7 +2282,8 @@ coupling between the storage layer and the replacement policy.
         structure is the cached ACL match results. This structure, is private to
         the authentication framework.
                
-       <P>struct _auth_user_t {
+<verb>
+struct _auth_user_t {
     /* extra fields for proxy_auth */
     /* this determines what scheme owns the user data. */
     auth_type_t auth_type;
@@ -2289,12 +2308,14 @@ coupling between the storage layer and the replacement policy.
     /* the auth_user_request structures that link to this. Yes it could be a splaytree
      * but how many requests will a single username have in parallel? */
     dlink_list requests;
-        };
+};
+</verb>
                
        <P>This is a short lived structure is the visible aspect of the
         authentication framework.
                
-       <P>struct _auth_user_request_t {
+<verb>
+struct _auth_user_request_t {
     /* this is the object passed around by client_side and acl functions */
     /* it has request specific data, and links to user specific data */
     /* the user */
@@ -2305,16 +2326,19 @@ coupling between the storage layer and the replacement policy.
     void *scheme_data;
     /* how many 'processes' are working on this data */
     size_t references;
-        };
+};
+</verb>
        
-        The authscheme_entry struct is used to store the runtime registered
-        functions that make up an auth scheme. An auth scheme module MUST implement
-        ALL functions except the
-        following functions: oncloseconnection, AddHeader, AddTrailer.. In
-        the future more optional functions may be added to this data type.
-               
-       <P>
-        struct _authscheme_entry {
+       <p>
+       The authscheme_entry struct is used to store the runtime
+       registered functions that make up an auth scheme. An auth
+       scheme module MUST implement ALL functions except the
+       following functions: oncloseconnection, AddHeader, AddTrailer..
+       In the future more optional functions may be added to this
+       data type.
+
+<verb>
+struct _authscheme_entry {
     char *typestr;
     AUTHSACTIVE   *Active;
     AUTHSADDHEADER *AddHeader;
@@ -2335,14 +2359,17 @@ coupling between the storage layer and the replacement policy.
     AUTHSSHUTDOWN *donefunc;
     AUTHSSTART    *authStart;
     AUTHSSTATS    *authStats;
-        };
-               
-       <P>For information on the requirements for each of the functions, see
-        the details under the typedefs above. For reference implementations, see
-        the squid source code, /src/auth/basic for a request based stateless auth module, and
-        /src/auth/ntlm for a connection based stateful auth module.
+};
+</verb>
+
+       <P>For information on the requirements for each of the
+       functions, see the details under the typedefs above. For
+       reference implementations, see the squid source code,
+       /src/auth/basic for a request based stateless auth module,
+       and /src/auth/ntlm for a connection based stateful auth
+       module.
        
-       <P>How to add a new auth scheme
+<sect1>How to add a new auth scheme
                
        <P>Copy the nearest existing auth scheme and modify to receive the
         appropriate scheme headers. Now step through the acl.c MatchAclProxyUser
@@ -2351,7 +2378,7 @@ coupling between the storage layer and the replacement policy.
         any backend existence it needs. Remember any blocking code must go in
         AUTHSSTART function(s) and _MUST_ use callbacks.
                
-       <P>How to 'hook in' new functions to the API.
+<sect1>How to ``hook in'' new functions to the API.
                
        <P>Start of by figuring the code path that will result in the function
         being called, and what data it will need. Then create a typedef for the