--------------------- PatchSet 5170 Date: 2007/08/06 08:34:09 Author: amosjeffries Branch: docs Tag: (none) Log: Migrate more Authentication Framework coments into the code. Members: doc/Programming-Guide/AuthenticationFramework.dox:1.1.2.4->1.1.2.5 src/AuthConfig.h:1.3->1.3.2.1 src/AuthUserRequest.h:1.8.2.2->1.8.2.3 Index: squid3/doc/Programming-Guide/AuthenticationFramework.dox =================================================================== RCS file: /cvsroot/squid-sf//squid3/doc/Programming-Guide/Attic/AuthenticationFramework.dox,v retrieving revision 1.1.2.4 retrieving revision 1.1.2.5 diff -u -r1.1.2.4 -r1.1.2.5 --- squid3/doc/Programming-Guide/AuthenticationFramework.dox 6 Aug 2007 07:58:06 -0000 1.1.2.4 +++ squid3/doc/Programming-Guide/AuthenticationFramework.dox 6 Aug 2007 08:34:09 -0000 1.1.2.5 @@ -58,18 +58,6 @@ register/initialize, deregister/shutdown and provide stats on auth modules: -\par typedef int AUTHSACTIVE(); - The Active function is used by squid to determine whether - the auth module has successfully initialised itself with - the current configuration. - -\par typedef int AUTHSCONFIGURED(); - 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. - \par typedef void AUTHSSETUP(authscheme_entry_t *); functions of type AUTHSSETUP are used to register an auth module with squid. The registration function MUST be @@ -144,20 +132,6 @@ the scheme_data pointer to NULL. Failure to unlink the scheme data will result in squid dying. -\par typedef char *AUTHSUSERNAME(auth_user_t *); - 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. - -\par typedef int AUTHSAUTHED(auth_user_request_t *); - 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. - \par The next set of functions perform the actual authentication. The functions are used by squid for both @@ -181,11 +155,6 @@ based authentication scheme, so the AuthUserRequest struct gets referenced from the ConnStateData. -\par typedef void AUTHSDECODE(auth_user_request_t *, const char *); - 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. - \par typedef void AUTHSFIXERR(auth_user_request_t *, HttpReply *, http_hdr_type, request_t *); Functions of type AUTHSFIXERR are used by squid to add scheme specific challenges when returning a 401 or 407 error code. On requests Index: squid3/src/AuthConfig.h =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/AuthConfig.h,v retrieving revision 1.3 retrieving revision 1.3.2.1 diff -u -r1.3 -r1.3.2.1 --- squid3/src/AuthConfig.h 9 May 2007 07:50:40 -0000 1.3 +++ squid3/src/AuthConfig.h 6 Aug 2007 08:34:10 -0000 1.3.2.1 @@ -1,6 +1,6 @@ /* - * $Id: AuthConfig.h,v 1.3 2007/05/09 07:50:40 squidadm Exp $ + * $Id: AuthConfig.h,v 1.3.2.1 2007/08/06 08:34:10 amosjeffries Exp $ * * * SQUID Web Proxy Cache http://www.squid-cache.org/ @@ -46,6 +46,8 @@ */ class AuthUserRequest; + +/// \ingroup AuthAPI class AuthConfig { @@ -57,18 +59,44 @@ virtual ~AuthConfig(){} - /* Is this configuration active? (helpers running etc etc */ + /** + * Used by squid to determine whether the auth module has successfully initialised itself with the current configuration. + * + * \retval true Authentication Module loaded and running. + * \retval false No Authentication Module loaded. + */ virtual bool active() const = 0; + /* new decode API: virtual factory pattern */ + /** + * Responsible for decoding the passed authentication header, creating or + * linking to a AuthUser object and for storing any needed details to complete + * authentication in AuthUserRequest::authenticate(). + * + * \param proxy_auth Login Pattern to parse. + * \retval * Details needed to authenticate. + */ virtual AuthUserRequest *decode(char const *proxy_auth) = 0; - /* squid is finished with this config, release any unneeded resources. + + /** + * squid is finished with this config, release any unneeded resources. * If a singleton, delete will not occur. if not a singleton (future), * delete will occur when no references are held. * TODO: we need a 'done for reconfigure' and a 'done permanently' concept. */ virtual void done() = 0; + /* is this config complete enough to run */ + /** + * 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. + * + * \retval true Authentication Module configured ready for use. + * \retval false Not configured or Configuration Error. + * No other module functions except Shutdown/Dump/Parse/FreeConfig will be called by Squid. + */ virtual bool configured() const = 0; + /* output the parameters */ virtual void dump(StoreEntry *, const char *, AuthConfig *) = 0; /* add headers as needed when challenging for auth */ Index: squid3/src/AuthUserRequest.h =================================================================== RCS file: /cvsroot/squid-sf//squid3/src/AuthUserRequest.h,v retrieving revision 1.8.2.2 retrieving revision 1.8.2.3 diff -u -r1.8.2.2 -r1.8.2.3 --- squid3/src/AuthUserRequest.h 6 Aug 2007 07:58:06 -0000 1.8.2.2 +++ squid3/src/AuthUserRequest.h 6 Aug 2007 08:34:10 -0000 1.8.2.3 @@ -1,6 +1,6 @@ /* - * $Id: AuthUserRequest.h,v 1.8.2.2 2007/08/06 07:58:06 amosjeffries Exp $ + * $Id: AuthUserRequest.h,v 1.8.2.3 2007/08/06 08:34:10 amosjeffries Exp $ * * DO NOT MODIFY NEXT 2 LINES: * arch-tag: 674533af-8b21-4641-b71a-74c4639072a0 @@ -80,7 +80,14 @@ */ int direction(); + /** + * Used by squid to determine whether the auth scheme has successfully authenticated the user request. + * + * \retval true User has successfully been authenticated. + * \retval false Timeouts on cached credentials have occurred or for any reason the credentials are not valid. + */ virtual int authenticated() const = 0; + virtual void authenticate(HttpRequest * request, ConnStateData::Pointer conn, http_hdr_type type) = 0; /* template method */ virtual int module_direction() = 0; @@ -114,6 +121,14 @@ void _lock (); // please use AUTHUSERREQUESTLOCK() void _unlock (); // please use AUTHUSERREQUESTUNLOCK() + /** + * 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. + * The string should NOT be allocated each time this function is called. + * + * \retval NULL No username/usercode is known. + * \retval * Null-terminated username string. + */ char const *username() const; AuthScheme *scheme() const; @@ -158,6 +173,7 @@ extern int authenticateDirection(AuthUserRequest *); /// \ingroup AuthAPI +/// See AuthUserRequest::authenticated() extern int authenticateUserAuthenticated(AuthUserRequest *); /// \ingroup AuthAPI extern int authenticateValidateUser(AuthUserRequest *);