<HTML>
<HEAD>
<TITLE>W3C Sample Code Library libwww Access Authentication</TITLE>
</HEAD>
<BODY>
<H1>
Access Authentication Manager
</H1>
<PRE>
/*
** (c) COPYRIGHT MIT 1995.
** Please first read the full copyright statement in the file COPYRIGH.
*/
</PRE>
<P>
The <I>Authentication Manager</I> is a registry for <I>Authentication
Schemes</I> that follow the generic syntax defined by the
<A HREF="../../Protocols/">HTTP</A> <CODE>WWW-authenticate</CODE> and
<CODE>Authorization</CODE> headers. Currently, the only scheme defined is
<I>Basic Authentication</I>, but <I>Digest Authentication </I>will soon follow.
All <I>Authentication Schemes</I> are registered at run-time in form of an
<I>Authentication Module</I>. An <I>Authentication Module</I> consists of
the following:
<DL>
<DT>
<B>scheme</B>
<DD>
The name which is used to identify the scheme. This is equivalent to the
<CODE><scheme></CODE> part of the <CODE>WWW-authenticate</CODE> HTTP
header, for example "basic"
<DT>
<B>BEFORE Filter</B>
<DD>
When a new request is issued, the <I>Authentication Manage</I>r looks in
the URL tree to see if we have any access authentication information for
this particular request. The search is based on the realm (if known) in which
the request belongs and the URL itself. If a record is found then the
<I>Authentication Manager</I> calls the <I>Authentication Module</I> in order
to generate the credentials.
<DT>
<B>AFTER Filter</B>
<DD>
After a request has terminated and the result was lack of credentials, the
request should normally be repeated with a new set of credentials. The AFTER
filter is responsible for extracting the challenge from the HTTP response
and store it in the URL tree, so that we next time we request the same URL
we know that it is protected and we can ask the user for the appropriate
credentials (user name and password, for example).
<DT>
<B>garbage collection</B>
<DD>
The authentication information is stored in a <A HREF="HTUTree.html">URL
Tree</A> but as it doesn't know the format of the scheme specific parts,
you must register a garbage collector (gc). The gc is called when node is
deleted in the tree.
</DL>
<P>
<B>Note: </B>The <I>Authentication Manager</I> itself consists of
<B>BEFORE</B> and an <B>AFTER</B> <A HREF="HTFilter.html">filter</A> - just
like the <I>Authentication Modules</I>. This means that any <I>Authentication
Module</I> also can be registered directly as a <B>BEFORE</B> and
<B>AFTER</B> <A HREF="HTFilter.html">filter</A> by the <A HREF="HTNet.html">Net
Manager</A>. The reason for having the two layer model is that the
<I>Authentication Manager</I> maintains a single <A HREF="HTUTree.html">URL
tree</A> for storing access information for all <I>Authentication Schemes</I>.
<P>
An <I>Authentication Module</I> has three resources, it can use when creating
challenges or credentials:
<UL>
<LI>
Handle the <I>credentials</I> which is a part of the
<A HREF="HTReq.html#Access">Request obejct</A>. The credentials are often
generated by asking the user for a user name ansd a password.
<LI>
Handle the <I>challenges</I> which is a part of the
<A HREF="HTReq.html#Access">Request object</A>. The <A HREF="HTMIME.html">MIME
parser</A> will normally find the credentials as we parse the HTTP response.
<LI>
Add information to the <A HREF="HTUTree.html">URL Tree</A>
</UL>
<P>
This module is implemented by <A HREF="HTAAUtil.c">HTAAUtil.c</A>, and it
is a part of the <A HREF="http://www.w3.org/Library/"> W3C Sample Code
Library</A>.
<PRE>
#ifndef HTAAUTIL_H
#define HTAAUTIL_H
#include "HTReq.h"
#include "HTNet.h"
#include "HTUTree.h"
</PRE>
<H2>
Authentication Scheme Registration
</H2>
<P>
An <I>Authentication Scheme</I> is registered by registering an
<I>Authentication Module</I> to in the <I>Authentication Manager</I>.
<H3>
Add an Authentication Module
</H3>
<P>
You can add an authentication scheme by using the following method. Each
of the callback function must have the type as defined below.
<PRE>
typedef struct _HTAAModule HTAAModule;
extern HTAAModule * HTAA_newModule (const char * scheme,
HTNetBefore * before,
HTNetAfter * after,
HTUTree_gc * gc);
</PRE>
<H3>
Find an Authentication Module
</H3>
<PRE>extern HTAAModule * HTAA_findModule (const char * scheme);
</PRE>
<H3>
Delete an Authentication Module
</H3>
<PRE>extern BOOL HTAA_deleteModule (const char * scheme);
</PRE>
<H3>
Delete ALL Authentication modules
</H3>
<PRE>extern BOOL HTAA_deleteAllModules (void);
</PRE>
<H2>
Handling the URL Tree
</H2>
<P>
The authentication information is stored as <A HREF="HTUTree.html">URL
Trees</A>. The root of a URL Tree is identified by a <I>hostname</I>
and a <I>port number</I>. Each URL Tree contains a set of templates and realms
which can be used to predict what information to use in a hierarchical tree.
<P>
The URL trees are automatically collected after some time so the application
does not have to worry about freeing the trees. When a node in a tree is
freed, the gc registered as part of the Authentication Module is called.
<P>
Server applications can have different authentication setups for each hostname
and port number, they control. For example, a server with interfaces
"<CODE>www.foo.com</CODE>" and "<CODE>internal.foo.com</CODE>" can have different
protection setups for each interface.
<H3>
Add new or Update a Note in the UTree
</H3>
<P>
Add an access authentication information node to the database or update an
existing one. If the entry is already found then it is replaced with the
new one. The template must follow normal URI syntax but can include a wildcard
Return YES if added (or replaced), else NO
<PRE>extern void * HTAA_updateNode (BOOL proxy,
char const * scheme,
const char * realm, const char * url,
void * context);
</PRE>
<H3>
Delete a Node from the UTree
</H3>
<P>
This is called if an already entered node has to be deleted, for example
if it is not used (the user cancelled entering a username and password),
or for some reason has expired.
<PRE>extern BOOL HTAA_deleteNode (BOOL proxy_access, char const * scheme,
const char * realm, const char * url);
</PRE>
<H2>
The Authentication Manager Filters
</H2>
<P>
As mentioned, the <I>Access Authentication Manager</I> is itself a set of
<A HREF="HTFilter.html">filters</A> that can be registered by the
<A HREF="HTNet.html">Net manager</A>.
<H3>
Before Filter
</H3>
<P>
Make a lookup in the URL tree to find any context for this node, If no context
is found then we assume that we don't know anything about this URL and hence
we don't call any <I>BEFORE</I> filters at all.
<PRE>
HTNetBefore HTAA_beforeFilter;
</PRE>
<H3>
After Filter
</H3>
<P>
Call the <I>AFTER</I> filter that knows how to handle this scheme.
<PRE>
HTNetAfter HTAA_afterFilter;
</PRE>
<H3>
Proxy Authentication Filter
</H3>
<P>
Just as for normal authentication we have a filter for proxy authentication.
The proxy authentication uses exactly the same code as normal authentication
but it stores the information in a separate proxy authentication
<A HREF="HTUTree.html">URL tree</A>. That way, we don't get any clashes between
a server acting as a proxy and a normal server at the same time on the same
port. The difference is that we only have a ingoing filter (a before filter)
as the out going filter is identical to the normal authentication filter.
The filter requires to be called after a proxy filter as we otherwise don't
know whether we are using a proxy or not.
<PRE>
HTNetBefore HTAA_proxyBeforeFilter;
</PRE>
<PRE>
#endif /* NOT HTAAUTIL_H */
</PRE>
<P>
<HR>
<ADDRESS>
@(#) $Id: HTAAUtil.html,v 2.37 1998/09/10 03:18:40 frystyk Exp $
</ADDRESS>
</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