Annotation of libwww/Library/src/HTAAUtil.html, revision 2.25
2.2 timbl 1: <HTML>
2.1 luotonen 2: <HEAD>
2.25 ! frystyk 3: <TITLE>Authentication Manager</TITLE>
! 4: <!-- Changed by: Henrik Frystyk Nielsen, 20-Feb-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,
! 163: CONST char * scheme);
! 164:
! 165: typedef BOOL HTAuthGenCallback (HTRequest * request,
! 166: CONST char * scheme,
! 167: char * realm,
! 168: void * data);
! 169:
! 170: typedef BOOL HTAuthGcCallback (CONST char * scheme,
! 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>
! 182: extern BOOL HTAuthCall_add (CONST char * scheme,
! 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>
! 193: extern BOOL HTAuthCall_delete (CONST char * scheme);
! 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>
! 226: extern BOOL HTAuth_cleanup (CONST char * scheme, void * data);
! 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>Initialize the Authentication database</H3>
2.4 duns 250:
2.25 ! frystyk 251: <PRE>
! 252: extern BOOL HTAuthInfo_init (void);
2.1 luotonen 253: </PRE>
2.25 ! frystyk 254:
! 255: <H3>Terminate the Database</H3>
! 256:
2.1 luotonen 257: <PRE>
2.25 ! frystyk 258: extern BOOL HTAuthInfo_terminate (void);
! 259: </PRE>
2.1 luotonen 260:
2.25 ! frystyk 261: <H3>Add information to the Database</H3>
! 262:
! 263: Add an access authentication information node to the database. If
! 264: the entry is already found then it is replaced with the new one.
! 265: The template must follow normal URI syntax but can include a wildcard
! 266: Return YES if added (or replaced), else NO
2.1 luotonen 267:
2.25 ! frystyk 268: <PRE>
! 269: extern BOOL HTAuthInfo_add (CONST char * scheme,
! 270: char * url,
! 271: char * realm,
! 272: void * data);
2.1 luotonen 273: </PRE>
2.5 luotonen 274:
2.1 luotonen 275: <PRE>
276: #endif /* NOT HTAAUTIL_H */
2.25 ! frystyk 277: </PRE>
! 278:
! 279: End of file declaration
! 280: </BODY>
2.2 timbl 281: </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