Annotation of libwww/Library/src/HTAAUtil.html, revision 2.29
2.2 timbl 1: <HTML>
2.1 luotonen 2: <HEAD>
2.27 frystyk 3: <TITLE>W3C Reference Library libwww Authentication</TITLE>
2.29 ! frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 11-Mar-1996 -->
2.13 frystyk 5: </HEAD>
2.1 luotonen 6: <BODY>
2.13 frystyk 7:
2.25 frystyk 8: <H1>Authentication Manager</H1>
2.13 frystyk 9:
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>
16:
2.25 frystyk 17: This module handles the registration of multiple Access authentication
18: schemes with support for both clients and servers. The module allows
19: multiple authentication schemes to be registered at run time so that
20: the client and server easily can extend the set of authentication
21: schemes. The Library does already support two welknown schemes from
22: the HTTP specification: <B>basic</B> and <B>digest</B> but othes can
23: be added. <P>
24:
25: Authentication information is kept separate from the various
26: autehntication schemes so that the management of authentication
27: information such as challenges and credentials can be handed
28: independent of the scheme used. All information about authentication
29: information is stored in a <A HREF="#authbase">Authentication
30: Information base</A>.<P>
2.13 frystyk 31:
32: This module is implemented by <A HREF="HTAAUtil.c">HTAAUtil.c</A>, and
2.25 frystyk 33: it is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C
34: Reference Library</A>.
2.13 frystyk 35:
2.1 luotonen 36: <PRE>
37: #ifndef HTAAUTIL_H
38: #define HTAAUTIL_H
2.25 frystyk 39: #include "HTAssoc.h"
2.23 frystyk 40: #include "HTReq.h"
2.15 frystyk 41: </PRE>
2.1 luotonen 42:
2.15 frystyk 43: <H2>Default filenames</H2>
2.1 luotonen 44:
2.15 frystyk 45: <PRE>
46: #ifndef PASSWD_FILE
2.25 frystyk 47: #define PASSWD_FILE "/tmp/passwd"
2.1 luotonen 48: #endif
49:
50: #ifndef GROUP_FILE
2.25 frystyk 51: #define GROUP_FILE "/tmp/group"
2.1 luotonen 52: #endif
53:
54: #define ACL_FILE_NAME ".www_acl"
55:
56: /*
57: ** Numeric constants
58: */
59: #define MAX_USERNAME_LEN 16 /* @@ Longest allowed username */
2.5 luotonen 60: #define MAX_PASSWORD_LEN 4*13 /* @@ Longest allowed password */
61: /* (encrypted, so really only 4*8)*/
2.1 luotonen 62: #define MAX_METHODNAME_LEN 12 /* @@ Longest allowed method name */
63: #define MAX_FIELDNAME_LEN 16 /* @@ Longest field name in */
64: /* protection setup file */
65: #define MAX_PATHNAME_LEN 80 /* @@ Longest passwd/group file */
66: /* patname to allow */
2.23 frystyk 67: </PRE>
68:
69: We need to define the following structures as they are used in the
2.25 frystyk 70: HTRequest object.
2.23 frystyk 71:
72: <PRE>
2.1 luotonen 73: /*
2.6 luotonen 74: ** Access Authorization failure reasons
75: */
76: typedef enum {
77: HTAA_OK, /* 200 OK */
78: HTAA_OK_GATEWAY, /* 200 OK, acting as a gateway */
2.7 luotonen 79: HTAA_OK_REDIRECT, /* 302 OK, redirected */
2.6 luotonen 80: HTAA_NO_AUTH, /* 401 Unauthorized, not authenticated */
81: HTAA_NOT_MEMBER, /* 401 Unauthorized, not authorized */
82: HTAA_IP_MASK, /* 403 Forbidden by IP mask */
2.9 luotonen 83: HTAA_IP_MASK_PROXY, /* 403 Forbidden by IP mask on proxy */
2.6 luotonen 84: HTAA_BY_RULE, /* 403 Forbidden by rule */
85: HTAA_NO_ACL, /* 403 Forbidden, ACL non-existent */
86: HTAA_NO_ENTRY, /* 403 Forbidden, no ACL entry */
87: HTAA_SETUP_ERROR, /* 403 Forbidden, server setup error */
88: HTAA_DOTDOT, /* 403 Forbidden, URL with /../ illegal */
89: HTAA_HTBIN, /* 403 Forbidden, /htbin not enabled */
2.7 luotonen 90: HTAA_INVALID_REDIRECT,
91: /* 403 Forbidden, bad redirection setup */
2.10 luotonen 92: HTAA_INVALID_USER, /* 403 Forbidden, bad user directory */
2.7 luotonen 93: HTAA_NOT_ALLOWED, /* 403 Forbidden, dangerous method must */
94: /* be explicitly allowed */
2.8 luotonen 95: HTAA_NOT_FOUND, /* 404 Not found, or read protected */
96: HTAA_MULTI_FAILED /* 404 No suitable presentation found */
2.6 luotonen 97: } HTAAFailReason;
2.2 timbl 98: </PRE>
2.1 luotonen 99:
2.25 frystyk 100: <H2>Authentication Scheme Registration</H2>
101:
102: Registering an autentication scheme involes the following parts:
103:
104: <DL>
105: <DT><B>scheme</B>
106: <DD>The name of the scheme which is used to identify the scheme, for
107: example as the <CODE><scheme></CODE> part of the
108: <CODE>WWW-authenticate</CODE> HTTP header.
109:
110: <DT><B>parser</B>
111: <DD>Each scheme must have a <EM>parser</EM> callback function that can
112: parse and interpret either the challenge sent by a server application
113: or the credentials sent by the client to see whether they can be
114: fulfilled or not. In the case of a client, the parser is called each
115: time a request did not optain authorization to access the
116: resource. The parser should then parse the challenge and store it so
117: that we know what we must fulfill if a new request is issued. If the
118: app is a server then the parser should validate that the credentails
119: are sufficent for accessing the resource.
120:
121: <DT><B>generator</B>
122: <DD>A scheme must also have a <EM>generator</EM> callback function
123: that can be called to generate a valid challenge or credentials to be
124: sent to the other part. If a new request is issued and we have a
125: challenge for this request then the generator should make sure that we
126: get the right credentials. This can for example be by asking the user
127: for a user name a and password. In the case of a server, the generator
128: should generate a challenge that must be answered in order to access
129: the resource.
130:
131: <DT><B>garbage collection</B>
132: <DD>The authentication information base has to be able to delete
133: authentication information but as it doesn't know the format of the
134: scheme specific parts, you must register a garbage collector which
135: also is a callback function. The info base manager then calls this
136: function each time authentication information is either being deleted
137: or updated.
138:
139: </DL>
140:
141: The request object has two hooks for the access authentication
142: handler: <CODE>challenge</CODE> and <CODE>credentials.</CODE>. Both
143: are association lists but the format is completely for the
144: <CODE>parser</CODE> and the <CODE>generator</CODE> callback functions
145: to manage. By using callback functions for parsing and generating
146: valid authentication/authorization information, this module is
147: independent of each scheme and hence allows for highly different
148: schemes.
149:
150: <H3>Callback Functions</H3>
151:
152: The types for the parser and generator callback functions are
153: symmetric in that the parser expects an association list of unparsed
154: data and returns a scheme dependent data object to be added to the
155: authentication information base. The callback functions are made so
156: that they can be used both on client side and on server side. The
157: <CODE>scheme</CODE> parameter is to tell the current authentication
158: scheme. That way, the same callback functions can be for multiple
159: schemes if needed.
160:
161: <PRE>
162: typedef BOOL HTAuthParCallback (HTRequest * request,
2.26 frystyk 163: const char * scheme);
2.25 frystyk 164:
165: typedef BOOL HTAuthGenCallback (HTRequest * request,
2.26 frystyk 166: const char * scheme,
2.25 frystyk 167: char * realm,
168: void * data);
169:
2.26 frystyk 170: typedef BOOL HTAuthGcCallback (const char * scheme,
2.25 frystyk 171: void * data);
172: </PRE>
173:
174:
175: <H3>Add an Authentication Scheme</H3>
176:
177: You can add an authentication scheme by using the following
178: method. Each of the callback function must have the type as defined
179: below.
180:
181: <PRE>
2.26 frystyk 182: extern BOOL HTAuthCall_add (const char * scheme,
2.25 frystyk 183: HTAuthParCallback * parser,
184: HTAuthGenCallback * generator,
185: HTAuthGcCallback * gc);
186: </PRE>
187:
188: <H3>Delete an Authentication Scheme</H3>
189:
190: Likewise, you can delete an authentication scheme:
191:
192: <PRE>
2.26 frystyk 193: extern BOOL HTAuthCall_delete (const char * scheme);
2.25 frystyk 194: extern BOOL HTAuthCall_deleteAll (void);
195: </PRE>
196:
197: <H2>Generating Calls to callback functions</H2>
198:
199: <H3>Call An authentication Scheme Parser</H3>
200:
201: This function looks for a authentication scheme that matches what we
202: have in the request object and calls the parser callback function.
203: Case is not significant. Return YES or whatever callback returns
204:
2.1 luotonen 205: <PRE>
2.25 frystyk 206: extern BOOL HTAuth_parse (HTRequest * request);
207: </PRE>
208:
209: <H3>Call An authentication Scheme Generator</H3>
210:
211: This function looks for a any authentication scheme that protects this
212: resource and calls the generator callback in order to make a challenge
213: or credentials. Return YES or whatever callback returns
2.1 luotonen 214:
2.25 frystyk 215: <PRE>
216: extern BOOL HTAuth_generate (HTRequest * request);
217: </PRE>
2.1 luotonen 218:
2.25 frystyk 219: <H3>Call An authentication Scheme Garbage Collector</H3>
2.19 frystyk 220:
2.25 frystyk 221: This function looks for a authentication scheme that matches what we
222: have in the request object and calls the cleanup callback function.
223: Case is not significant. Return YES if callback found else NO
2.19 frystyk 224:
2.25 frystyk 225: <PRE>
2.26 frystyk 226: extern BOOL HTAuth_cleanup (const char * scheme, void * data);
2.25 frystyk 227: </PRE>
2.2 timbl 228:
2.25 frystyk 229: <A NAME="authbase"><H2>Authentication Information Databases</H2></A>
2.1 luotonen 230:
2.25 frystyk 231: The authentication information is stored in a database managed by this
232: module. In the current implementation, a database is a list of
233: sub-authentication databases, each uniquely identified by a hostname
234: and a port number. Each database contains a set of templates which
235: can be used to predict what information to use in a hierarchical
236: tree. All authentication dependent information is stored as opaque
237: data in a <CODE>node</CODE> referenced by a <EM>realm</EM> and a
238: <EM>URL template</EM>. <P>
239:
240: Normally applications would only keep one auth base but if it wants
241: different protection setup as a function of different interfaces then
242: it can have one auth base representing each interface. <P>
243:
244: Server applications can have different authentication setups for each
245: hostname and port number they control. For example, a server with
246: interfaces "www.foo.com" and "internal.foo.com" can have different
247: protection setups for each interface.
2.4 duns 248:
2.25 frystyk 249: <H3>Add information to the Database</H3>
250:
251: Add an access authentication information node to the database. If
252: the entry is already found then it is replaced with the new one.
253: The template must follow normal URI syntax but can include a wildcard
254: Return YES if added (or replaced), else NO
2.1 luotonen 255:
2.25 frystyk 256: <PRE>
2.29 ! frystyk 257: extern BOOL HTAuthInfo_add (const char * scheme, char * url,
! 258: char * realm, void * data);
2.28 eric 259: </PRE>
260:
261: <H3>Delete the Database</H3>
262:
263: <PRE>
264: extern BOOL HTAuthInfo_deleteAll (void);
2.1 luotonen 265: </PRE>
2.5 luotonen 266:
2.1 luotonen 267: <PRE>
268: #endif /* NOT HTAAUTIL_H */
2.25 frystyk 269: </PRE>
270:
271: End of file declaration
272: </BODY>
2.2 timbl 273: </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