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