Annotation of libwww/Library/src/HTAAUtil.html, revision 2.31
2.2 timbl 1: <HTML>
2.1 luotonen 2: <HEAD>
2.31 ! frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 7-Jul-1996 -->
! 4: <TITLE>W3C Reference Library libwww Access Authentication</TITLE>
2.13 frystyk 5: </HEAD>
2.1 luotonen 6: <BODY>
2.31 ! frystyk 7: <H1>
! 8: Access Authentication Manager
! 9: </H1>
2.13 frystyk 10: <PRE>
11: /*
2.18 frystyk 12: ** (c) COPYRIGHT MIT 1995.
2.13 frystyk 13: ** Please first read the full copyright statement in the file COPYRIGH.
14: */
15: </PRE>
2.31 ! frystyk 16: <P>
! 17: The <I>Authentication Manager</I> is a registry for <I>Authentication
! 18: Schemes</I> that follow the generic syntax defined by the
! 19: <A HREF="../../Protocols/">HTTP</A> <CODE>WWW-authenticate</CODE> and
! 20: <CODE>Authorization</CODE> headers. Currently, the only scheme defined is
! 21: <I>Basic Authentication</I>, but <I>Digest Authentication </I>will soon follow.
! 22: All <I>Authentication Schemes</I> are registered at run-time in form of an
! 23: <I>Authentication Module</I>. An <I>Authentication Module</I> consists of
! 24: the following:
! 25: <DL>
! 26: <DT>
! 27: <B>scheme</B>
! 28: <DD>
! 29: The name which is used to identify the scheme. This is equivalent to the
! 30: <CODE><scheme></CODE> part of the <CODE>WWW-authenticate</CODE> HTTP
! 31: header, for example "basic"
! 32: <DT>
! 33: <B>BEFORE Filter</B>
! 34: <DD>
! 35: When a new request is issued, the <I>Authentication Manage</I>r looks in
! 36: the URL tree to see if we have any access authentication information for
! 37: this particular request. The search is based on the realm (if known) in which
! 38: the request belongs and the URL itself. If a record is found then the
! 39: <I>Authentication Manager</I> calls the <I>Authentication Module</I> in order
! 40: to generate the credentials.
! 41: <DT>
! 42: <B>AFTER Filter</B>
! 43: <DD>
! 44: After a request has terminated and the result was lack of credentials, the
! 45: request should normally be repeated with a new set of credentials. The AFTER
! 46: filter is responsible for extracting the challenge from the HTTP response
! 47: and store it in the URL tree, so that we next time we request the same URL
! 48: we know that it is protected and we can ask the user for the appropriate
! 49: credentials (user name and password, for example).
! 50: <DT>
! 51: <B>garbage collection</B>
! 52: <DD>
! 53: The authentication information is stored in a <A HREF="HTUTree.html">URL
! 54: Tree</A> but as it doesn't know the format of the scheme specific parts,
! 55: you must register a garbage collector (gc). The gc is called when node is
! 56: deleted in the tree.
! 57: </DL>
! 58: <P>
! 59: <B>Note: </B>The <I>Authentication Manager</I> itself consists of
! 60: <B>BEFORE</B> and an <B>AFTER</B> <A HREF="HTFilter.html">filter</A> - just
! 61: like the <I>Authentication Modules</I>. This means that any <I>Authentication
! 62: Module</I> also can be registered directly as a <B>BEFORE</B> and
! 63: <B>AFTER</B> <A HREF="HTFilter.html">filter</A> by the <A HREF="HTNet.html">Net
! 64: Manager</A>. The reason for having the two layer model is that the
! 65: <I>Authentication Manager</I> maintains a single <A HREF="HTUTree.html">URL
! 66: tree</A> for storing access information for all <I>Authentication Schemes</I>.
! 67: <P>
! 68: An <I>Authentication Module</I> has three resources, it can use when creating
! 69: challenges or credentials:
! 70: <UL>
! 71: <LI>
! 72: Handle the <I>credentials</I> which is a part of the
! 73: <A HREF="HTReq.html#Access">Request obejct</A>. The credentials are often
! 74: generated by asking the user for a user name ansd a password.
! 75: <LI>
! 76: Handle the <I>challenges</I> which is a part of the
! 77: <A HREF="HTReq.html#Access">Request object</A>. The <A HREF="HTMIME.html">MIME
! 78: parser</A> will normally find the credentials as we parse the HTTP response.
! 79: <LI>
! 80: Add information to the <A HREF="HTUTree.html">URL Tree</A>
! 81: </UL>
! 82: <P>
! 83: This module is implemented by <A HREF="HTAAUtil.c">HTAAUtil.c</A>, and it
! 84: is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C Reference
! 85: Library</A>.
2.1 luotonen 86: <PRE>
87: #ifndef HTAAUTIL_H
88: #define HTAAUTIL_H
2.23 frystyk 89: #include "HTReq.h"
2.31 ! frystyk 90: #include "HTNet.h"
! 91: #include "HTUTree.h"
2.15 frystyk 92: </PRE>
2.31 ! frystyk 93: <H2>
! 94: Authentication Scheme Registration
! 95: </H2>
! 96: <P>
! 97: An <I>Authentication Scheme</I> is registered by registering an
! 98: <I>Authentication Module</I> to in the <I>Authentication Manager</I>.
! 99: <H3>
! 100: Add an Authentication Module
! 101: </H3>
! 102: <P>
! 103: You can add an authentication scheme by using the following method. Each
! 104: of the callback function must have the type as defined below.
! 105: <PRE>
! 106: typedef struct _HTAAModule HTAAModule;
! 107:
! 108: extern HTAAModule * HTAA_newModule (const char * scheme,
! 109: HTNetCallback * before,
! 110: HTNetCallback * after,
! 111: HTUTree_gc * gc);
! 112: </PRE>
! 113: <H3>
! 114: Find an Authentication Module
! 115: </H3>
! 116: <PRE>extern HTAAModule * HTAA_findModule (const char * scheme);
! 117: </PRE>
! 118: <H3>
! 119: Delete an Authentication Module
! 120: </H3>
! 121: <PRE>extern BOOL HTAA_deleteModule (const char * scheme);
! 122: </PRE>
! 123: <H3>
! 124: Delete ALL Authentication modules
! 125: </H3>
! 126: <PRE>extern BOOL HTAA_deleteAllModules (void);
! 127: </PRE>
! 128: <H2>
! 129: Handling the URL Tree
! 130: </H2>
! 131: <P>
! 132: The authentication information is stored as <A HREF="HTUTree.html">URL
! 133: Trees</A>. The root of a URL Tree is identified by a <I>hostname</I>
! 134: and a <I>port number</I>. Each URL Tree contains a set of templates and realms
! 135: which can be used to predict what information to use in a hierarchical tree.
! 136: <P>
! 137: The URL trees are automatically collected after some time so the application
! 138: does not have to worry about freeing the trees. When a node in a tree is
! 139: freed, the gc registered as part of the Authentication Module is called.
! 140: <P>
! 141: Server applications can have different authentication setups for each hostname
! 142: and port number, they control. For example, a server with interfaces
! 143: "<CODE>www.foo.com</CODE>" and "<CODE>internal.foo.com</CODE>" can have different
2.25 frystyk 144: protection setups for each interface.
2.31 ! frystyk 145: <H3>
! 146: Add information to the Database
! 147: </H3>
! 148: <P>
! 149: Add an access authentication information node to the database. If the entry
! 150: is already found then it is replaced with the new one. The template must
! 151: follow normal URI syntax but can include a wildcard Return YES if added (or
! 152: replaced), else NO
! 153: <PRE>
! 154: extern BOOL HTAA_addNode (const char * scheme,
! 155: const char * realm, const char * url,
! 156: void * context);
! 157: </PRE>
! 158: <H2>
! 159: The Authentication Manager Filters
! 160: </H2>
! 161: <P>
! 162: As mentioned, the <I>Access Authentication Manager</I> is itself a set of
! 163: <A HREF="HTFilter.html">filters</A> that can be registered by the
! 164: <A HREF="HTNet.html">Net manager</A>.
2.25 frystyk 165: <PRE>
2.31 ! frystyk 166: extern int HTAA_beforeFilter (HTRequest * request, void * param, int status);
2.28 eric 167: </PRE>
168: <PRE>
2.31 ! frystyk 169: extern BOOL HTAA_afterFilter (HTRequest * request, void * param, int status);
2.1 luotonen 170: </PRE>
171: <PRE>
172: #endif /* NOT HTAAUTIL_H */
2.25 frystyk 173: </PRE>
2.31 ! frystyk 174: <P>
! 175: <HR>
2.30 frystyk 176: <ADDRESS>
2.31 ! frystyk 177: @(#) $Id: HTAAUtil.html,v 2.30 1996/04/12 17:45:29 frystyk Exp $
2.30 frystyk 178: </ADDRESS>
2.31 ! frystyk 179: </BODY></HTML>
Webmaster