From: wessels <> Date: Mon, 18 Jun 2001 22:32:35 +0000 (+0000) Subject: Continued fuzting with Authentication Framework section. I added some X-Git-Tag: SQUID_3_0_PRE1~1490 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=bb49003ab3576cb0431bc8c4f8c07ea27dd47cd5;p=thirdparty%2Fsquid.git Continued fuzting with Authentication Framework section. I added some description of the auth module (external process) interface for Basic Auth. --- diff --git a/doc/Programming-Guide/prog-guide.sgml b/doc/Programming-Guide/prog-guide.sgml index a2be275a84..7f2cf48a15 100644 --- a/doc/Programming-Guide/prog-guide.sgml +++ b/doc/Programming-Guide/prog-guide.sgml @@ -2,7 +2,7 @@
Squid Programmers Guide Duane Wessels, Squid Developers -$Id: prog-guide.sgml,v 1.42 2001/06/18 16:05:47 wessels Exp $ +$Id: prog-guide.sgml,v 1.43 2001/06/18 16:32:35 wessels Exp $ Squid is a WWW Cache application developed by the National Laboratory @@ -80,7 +80,7 @@ Squid consists of the following major components state information is held in a data structure called Server Side

@@ -118,7 +118,7 @@ Squid consists of the following major components this file number (sfilen) is converted to a disk pathname by a simple modulo of L2 and L1, but other storage drivers may map sfilen in other ways. A cache swap file consists - of two parts: the cache metadata, and the object data. + of two parts: the cache metadata, and the object data. Note the object data includes the full HTTP reply---headers and body. The HTTP reply headers are not the same as the cache metadata. @@ -209,7 +209,7 @@ Squid consists of the following major components This provides access to certain information needed by the cache administrator. A companion program, cache_object://hostname/operation @@ -228,7 +228,7 @@ Squid consists of the following major components Squid cache will know if it, or one if its neighbors, is closest to a given origin server. The actual measurements are made with the Autonomous System Numbers

- Squid supports Autonomous System (AS) numbers as another + Squid supports Autonomous System (AS) numbers as another access control element. The routines in Internet Cache Protocol

- Here we implement the Internet Cache Protocol. This + Here we implement the Internet Cache Protocol. This protocol is documented in the RFC 2186 and RFC 2187. - The bulk of code is in the Currently, multicast is only used for ICP queries. The - routines in this file implement joining a UDP + routines in this file implement joining a UDP socket to a multicast group (or groups), and setting the multicast TTL value on outgoing packets. @@ -691,7 +691,7 @@ Squid consists of the following major components this file number (sfilen) is converted to a disk pathname by a simple modulo of L2 and L1, but other storage drivers may map sfilen in other ways. A cache swap file consists - of two parts: the cache metadata, and the object data. + of two parts: the cache metadata, and the object data. Note the object data includes the full HTTP reply---headers and body. The HTTP reply headers are not the same as the cache metadata. @@ -793,7 +793,7 @@ Squid consists of the following major components void storeFsSetup_ufs(storefs_entry_t *storefs) - { + { assert(!ufs_initialised); storefs->parsefunc = storeUfsDirParse; storefs->reconfigurefunc = storeUfsDirReconfigure; @@ -916,7 +916,7 @@ Squid consists of the following major components

Squid understands the concept of multiple diverse storage directories. Each storage directory provides a caching object store, with object - storage, retrieval, indexing and replacement. + storage, retrieval, indexing and replacement.

Each open object has associated with it a Called periodically to replace objects. The active replacement policy should be used to timeout unused objects in order to make room for - new objects. + new objects. callback @@ -1254,7 +1254,7 @@ Squid consists of the following major components

Data Structures + Data Structures

The data structure used for storing name-address mappings @@ -1955,7 +1955,7 @@ coupling between the storage layer and the replacement policy. - Internal Operation + Internal Operation

Internally, the execution flow is as follows: On a miss, @@ -2023,8 +2023,34 @@ coupling between the storage layer and the replacement policy. Authentication Framework - -Definition of an auth scheme + +

+ Squid's authentication system is responsible for reading + authentication credentials from HTTP requests and deciding + whether or not those credentials are valid. This functionality + resides in two separate components: Authentication Schemes + and Authentication Modules. + +

+ An Authentication Scheme describes how Squid gets the + credentials (i.e. username, password) from user requests. + Squid currently supports two authentication schemes: Basic + and NTLM. Basic authentication uses the + An Authentication Module takes the credentials received + from a client's request and tells Squid if they are + are valid. Authentication Modules are implemented + externally from Squid, as child helper processes. + Authentication Modules interface with various types + authentication databases, such as LDAP, PAM, NCSA-style + password files, and more. + +Authentication Scheme API + +Definition of an Authentication Scheme

An auth scheme in squid is the collection of functions required to manage the authentication process for a given HTTP authentication @@ -2042,11 +2068,6 @@ 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. -Data types - -

The data types are presented in C for the simple reason that squid is - currently written exclusively in C. - Function typedefs

Each function related to the general case of HTTP authentication has @@ -2198,7 +2219,7 @@ coupling between the storage layer and the replacement policy.

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. @@ -2260,11 +2281,11 @@ coupling between the storage layer and the replacement policy. - Structures + Data Structures -

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. +

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. struct _auth_user_hash_pointer { @@ -2328,7 +2349,7 @@ struct _auth_user_request_t { size_t references; }; - +

The authscheme_entry struct is used to store the runtime registered functions that make up an auth scheme. An auth @@ -2369,7 +2390,7 @@ struct _authscheme_entry { and /src/auth/ntlm for a connection based stateful auth module. -How to add a new auth scheme +How to add a new Authentication Scheme

Copy the nearest existing auth scheme and modify to receive the appropriate scheme headers. Now step through the acl.c MatchAclProxyUser @@ -2378,16 +2399,58 @@ struct _authscheme_entry { any backend existence it needs. Remember any blocking code must go in AUTHSSTART function(s) and _MUST_ use callbacks. -How to ``hook in'' new functions to the API - -

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 - function, add and entry to the authscheme_entry struct. Add a wrapper - function to authenticate.c (or if appropriate cf_cache.c) that called the - scheme specific function if it exists. Test it. Test it again. Now - port to all the existing auth schemes, or at least add a setting - of NULL for the function for each scheme. +How to ``hook in'' new functions to the API + +

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 function, add and entry to the + authscheme_entry struct. Add a wrapper function to + authenticate.c (or if appropriate cf_cache.c) that called + the scheme specific function if it exists. Test it. Test + it again. Now port to all the existing auth schemes, or at + least add a setting of NULL for the function for each + scheme. + +Authentication Module Interface +Basic Authentication Modules + +

+Basic authentication provides a username and password. These +are written to the authentication module processes on a single +line, separated by a space: + + + +

+The authentication module process reads username, password +pairs on stdin and returns either ``OK'' or ``ERR'' for +each line. + +

+The following simple perl script demonstrates how the +authentication module works. This script allows any +user named ``Dirk'' (without checking the password) +and allows any user that uses the password ``Sekrit'': + + +#!/usr/bin/perl -w +$|=1; +while (<>) { + chop; + ($u,$p) = split; + $ans = &check($u,$p); + print "$ans\n"; +} + +sub check { + local($u,$p) = @_; + return 'ERR' unless (defined $p && defined $u); + return 'OK' if ('Dirk' eq $u); + return 'OK' if ('Sekrit' eq $p); + return 'ERR'; +} + ICP @@ -2467,7 +2530,7 @@ struct _authscheme_entry { callback_func(callback_data, ....); cbdataUnlock(callback_data); - In this case, when

- To add new global data types one have to add them to the - cbdata_type enum in enums.h, and a corresponding + To add new global data types one have to add them to the + cbdata_type enum in enums.h, and a corresponding CREATE_CBDATA call in cbdata.c:cbdataInit(). Or alternatively add a CBDATA_GLOBAL_TYPE definition to globals.h and use CBDATA_INIT_TYPE as described above. @@ -2525,7 +2588,7 @@ struct _authscheme_entry { +

Life cycle -

+

/* declare */ HttpHeader hdr; - + /* initialize (as an HTTP Request header) */ httpHeaderInit(&hdr, hoRequest); @@ -2570,7 +2633,7 @@ struct _authscheme_entry { httpHeaderClean(&hdr); -

+

Prior to use, an Adding new header-field ids -

+

Adding new ids is simple. First add new HDR_ entry to the http_hdr_type enumeration in enums.h. Then describe a new header-field attributes in the HeadersAttrs array located @@ -2808,7 +2871,7 @@ struct _storeSwapLogData {