Annotation of libwww/Library/src/HTAAUtil.html, revision 2.35
2.2 timbl 1: <HTML>
2.1 luotonen 2: <HEAD>
2.32 frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 14-Jul-1996 -->
2.35 ! frystyk 4: <TITLE>W3C Sample Code 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
2.35 ! frystyk 84: is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C Sample Code
2.31 frystyk 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,
2.34 frystyk 109: HTNetBefore * before,
110: HTNetAfter * after,
2.31 frystyk 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>
2.32 frystyk 146: Add new or Update Existng information to the Database
2.31 frystyk 147: </H3>
148: <P>
2.32 frystyk 149: Add an access authentication information node to the database or update an
150: existing one. If the entry is already found then it is replaced with the
151: new one. The template must follow normal URI syntax but can include a wildcard
152: Return YES if added (or replaced), else NO
2.33 frystyk 153: <PRE>extern void * HTAA_updateNode (BOOL proxy,
154: char const * scheme,
2.32 frystyk 155: const char * realm, const char * url,
156: void * context);
2.31 frystyk 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.32 frystyk 165: <H3>
166: Before Filter
167: </H3>
168: <P>
169: Make a lookup in the URL tree to find any context for this node, If no context
170: is found then we assume that we don't know anything about this URL and hence
171: we don't call any <I>BEFORE</I> filters at all.
2.34 frystyk 172: <PRE>
173: HTNetBefore HTAA_beforeFilter;
2.28 eric 174: </PRE>
2.32 frystyk 175: <H3>
176: After Filter
177: </H3>
178: <P>
179: Call the <I>AFTER</I> filter that knows how to handle this scheme.
2.34 frystyk 180: <PRE>
181: HTNetAfter HTAA_afterFilter;
2.1 luotonen 182: </PRE>
2.33 frystyk 183: <H3>
184: Proxy Authentication Filter
185: </H3>
186: <P>
187: Just as for normal authentication we have a filter for proxy authentication.
188: The proxy authentication uses exactly the same code as normal authentication
189: but it stores the information in a separate proxy authentication
190: <A HREF="HTUTree.html">URL tree</A>. That way, we don't get any clashes between
191: a server acting as a proxy and a normal server at the same time on the same
192: port. The difference is that we only have a ingoing filter (a before filter)
193: as the out going filter is identical to the normal authentication filter.
194: The filter requires to be called after a proxy filter as we otherwise don't
195: know whether we are using a proxy or not.
196: <PRE>
2.34 frystyk 197: HTNetBefore HTAA_proxyBeforeFilter;
2.33 frystyk 198: </PRE>
2.1 luotonen 199: <PRE>
200: #endif /* NOT HTAAUTIL_H */
2.25 frystyk 201: </PRE>
2.31 frystyk 202: <P>
203: <HR>
2.30 frystyk 204: <ADDRESS>
2.35 ! frystyk 205: @(#) $Id: HTAAUtil.html,v 2.34 1996/10/07 02:04:14 frystyk Exp $
2.30 frystyk 206: </ADDRESS>
2.31 frystyk 207: </BODY></HTML>
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTAAUtil.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src