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