Annotation of libwww/Library/src/HTAAUtil.html, revision 2.6
2.2 timbl 1: <HTML>
2.1 luotonen 2: <HEAD>
2.2 timbl 3: <TITLE>Utilities for the Authorization parts of libwww</TITLE></HEAD>
2.1 luotonen 4: <BODY>
2.2 timbl 5: <H1>Common Parts of Authorization Module
6: to Both Server And Browser</H1>This module is the interface to the
7: common parts of Access Authorization
8: (AA) package for both server and
9: browser. Important to know about
10: memory allocation:<P>
11: Routines in this module use dynamic
12: allocation, but free automatically
13: all the memory reserved by them.<P>
14: Therefore the caller never has to
15: (and never should) free() any object
16: returned by these functions.<P>
17: Therefore also all the strings returned
18: by this package are only valid until
19: the next call to the same function
20: is made. This approach is selected,
21: because of the nature of access authorization:
22: no string returned by the package
23: needs to be valid longer than until
24: the next call.<P>
25: This also makes it easy to plug the
26: AA package in: you don't have to
27: ponder whether to free() something
28: here or is it done somewhere else
29: (because it is always done somewhere
30: else).<P>
31: The strings that the package needs
32: to store are copied so the original
33: strings given as parameters to AA
34: functions may be freed or modified
35: with no side effects.<P>
36: Also note: The AA package does not
37: free() anything else than what it
38: has itself allocated.
2.1 luotonen 39: <PRE>
40: #ifndef HTAAUTIL_H
41: #define HTAAUTIL_H
42:
43: #include "HTUtils.h" /* BOOL, PARAMS, ARGS */
44: #include "HTList.h"
2.5 luotonen 45: #include "HTAtom.h"
2.2 timbl 46: #include "tcp.h"
2.1 luotonen 47:
48: #ifdef SHORT_NAMES
49: #define HTAASenu HTAAScheme_enum
50: #define HTAASnam HTAAScheme_name
2.5 luotonen 51: #define HTMeInLi HTMethod_inList
2.1 luotonen 52: #define HTAAteMa HTAA_templateMatch
53: #define HTAAmaPT HTAA_makeProtectionTemplate
54: #define HTAApALi HTAA_parseArgList
55: #endif /*SHORT_NAMES*/
56:
57:
2.2 timbl 58: </PRE>
59: <H2>Default filenames</H2>
60: <PRE>#ifndef PASSWD_FILE
2.1 luotonen 61: #define PASSWD_FILE "/home2/luotonen/passwd"
62: #endif
63:
64: #ifndef GROUP_FILE
65: #define GROUP_FILE "/home2/luotonen/group"
66: #endif
67:
68: #define ACL_FILE_NAME ".www_acl"
69:
70:
71: /*
72: ** Numeric constants
73: */
74: #define MAX_USERNAME_LEN 16 /* @@ Longest allowed username */
2.5 luotonen 75: #define MAX_PASSWORD_LEN 4*13 /* @@ Longest allowed password */
76: /* (encrypted, so really only 4*8)*/
2.1 luotonen 77: #define MAX_METHODNAME_LEN 12 /* @@ Longest allowed method name */
78: #define MAX_FIELDNAME_LEN 16 /* @@ Longest field name in */
79: /* protection setup file */
80: #define MAX_PATHNAME_LEN 80 /* @@ Longest passwd/group file */
81: /* patname to allow */
82:
83: /*
84: ** Helpful macros
85: */
86: #define FREE(x) if (x) {free(x); x=NULL;}
87:
2.6 ! luotonen 88:
! 89: /*
! 90: ** Access Authorization failure reasons
! 91: */
! 92: typedef enum {
! 93: HTAA_OK, /* 200 OK */
! 94: HTAA_OK_GATEWAY, /* 200 OK, acting as a gateway */
! 95: HTAA_NO_AUTH, /* 401 Unauthorized, not authenticated */
! 96: HTAA_NOT_MEMBER, /* 401 Unauthorized, not authorized */
! 97: HTAA_IP_MASK, /* 403 Forbidden by IP mask */
! 98: HTAA_BY_RULE, /* 403 Forbidden by rule */
! 99: HTAA_NO_ACL, /* 403 Forbidden, ACL non-existent */
! 100: HTAA_NO_ENTRY, /* 403 Forbidden, no ACL entry */
! 101: HTAA_SETUP_ERROR, /* 403 Forbidden, server setup error */
! 102: HTAA_DOTDOT, /* 403 Forbidden, URL with /../ illegal */
! 103: HTAA_HTBIN, /* 403 Forbidden, /htbin not enabled */
! 104: HTAA_NOT_FOUND /* 404 Not found, or read protected */
! 105: } HTAAFailReason;
! 106:
! 107:
2.1 luotonen 108: </PRE>
109: <H2>Datatype definitions</H2>
2.2 timbl 110: <H3>HTAAScheme</H3>The enumeration HTAAScheme represents
111: the possible authentication schemes
112: used by the WWW Access Authorization.
2.1 luotonen 113: <PRE>
114: typedef enum {
115: HTAA_UNKNOWN,
116: HTAA_NONE,
117: HTAA_BASIC,
118: HTAA_PUBKEY,
119: HTAA_KERBEROS_V4,
120: HTAA_KERBEROS_V5,
121: HTAA_MAX_SCHEMES /* THIS MUST ALWAYS BE LAST! Number of schemes */
122: } HTAAScheme;
123:
2.2 timbl 124: </PRE>
2.1 luotonen 125:
126: <H2>Authentication Schemes</H2>
127: <PRE>
128: /* PUBLIC HTAAScheme_enum()
129: ** TRANSLATE SCHEME NAME TO A SCHEME ENUMERATION
130: ** ON ENTRY:
131: ** name is a string representing the scheme name.
132: **
133: ** ON EXIT:
134: ** returns the enumerated constant for that scheme.
135: */
136: PUBLIC HTAAScheme HTAAScheme_enum PARAMS((CONST char* name));
137:
138:
139: /* PUBLIC HTAAScheme_name()
140: ** GET THE NAME OF A GIVEN SCHEME
141: ** ON ENTRY:
142: ** scheme is one of the scheme enum values:
143: ** HTAA_NONE, HTAA_BASIC, HTAA_PUBKEY, ...
144: **
145: ** ON EXIT:
146: ** returns the name of the scheme, i.e.
147: ** "none", "basic", "pubkey", ...
148: */
149: PUBLIC char *HTAAScheme_name PARAMS((HTAAScheme scheme));
2.2 timbl 150:
2.1 luotonen 151: </PRE>
152: <H2>Methods</H2>
2.5 luotonen 153: Methods are now represented as HTAtoms.
2.1 luotonen 154: <PRE>
2.5 luotonen 155: /* PUBLIC HTMethod_inList()
2.1 luotonen 156: ** IS A METHOD IN A LIST OF METHOD NAMES
157: ** ON ENTRY:
158: ** method is the method to look for.
159: ** list is a list of method names.
160: **
161: ** ON EXIT:
162: ** returns YES, if method was found.
163: ** NO, if not found.
164: */
2.5 luotonen 165: PUBLIC BOOL HTMethod_inList PARAMS((HTAtom * method,
166: HTList * list));
2.1 luotonen 167: </PRE>
168: <H2>Match Template Against Filename</H2>
169: <PRE>
170: /* PUBLIC HTAA_templateMatch()
171: ** STRING COMPARISON FUNCTION FOR FILE NAMES
172: ** WITH ONE WILDCARD * IN THE TEMPLATE
173: ** NOTE:
174: ** This is essentially the same code as in HTRules.c, but it
175: ** cannot be used because it is embedded in between other code.
176: ** (In fact, HTRules.c should use this routine, but then this
177: ** routine would have to be more sophisticated... why is life
178: ** sometimes so hard...)
179: **
180: ** ON ENTRY:
181: ** template is a template string to match the file name
182: ** agaist, may contain a single wildcard
183: ** character * which matches zero or more
184: ** arbitrary characters.
185: ** filename is the filename (or pathname) to be matched
186: ** agaist the template.
187: **
188: ** ON EXIT:
189: ** returns YES, if filename matches the template.
190: ** NO, otherwise.
191: */
192: PUBLIC BOOL HTAA_templateMatch PARAMS((CONST char * template,
193: CONST char * filename));
194:
195:
2.4 duns 196: /* PUBLIC HTAA_templateCaseMatch()
197: ** STRING COMPARISON FUNCTION FOR FILE NAMES
198: ** WITH ONE WILDCARD * IN THE TEMPLATE (Case Insensitive)
199: ** NOTE:
200: ** This is essentially the same code as in HTAA_templateMatch, but
201: ** it compares case insensitive (for VMS). Reason for this routine
202: ** is that HTAA_templateMatch gets called from several places, also
203: ** there where a case sensitive match is needed, so one cannot just
204: ** change the HTAA_templateMatch routine for VMS.
205: **
206: ** ON ENTRY:
207: ** template is a template string to match the file name
208: ** agaist, may contain a single wildcard
209: ** character * which matches zero or more
210: ** arbitrary characters.
211: ** filename is the filename (or pathname) to be matched
212: ** agaist the template.
213: **
214: ** ON EXIT:
215: ** returns YES, if filename matches the template.
216: ** NO, otherwise.
217: */
218: PUBLIC BOOL HTAA_templateCaseMatch PARAMS((CONST char * template,
219: CONST char * filename));
220:
221:
2.1 luotonen 222: /* PUBLIC HTAA_makeProtectionTemplate()
223: ** CREATE A PROTECTION TEMPLATE FOR THE FILES
224: ** IN THE SAME DIRECTORY AS THE GIVEN FILE
225: ** (Used by server if there is no fancier way for
226: ** it to tell the client, and by browser if server
227: ** didn't send WWW-ProtectionTemplate: field)
228: ** ON ENTRY:
229: ** docname is the document pathname (from URL).
230: **
231: ** ON EXIT:
232: ** returns a template matching docname, and other files
233: ** files in that directory.
234: **
235: ** E.g. /foo/bar/x.html => /foo/bar/ *
236: ** ^
237: ** Space only to prevent it from
238: ** being a comment marker here,
239: ** there really isn't any space.
240: */
241: PUBLIC char *HTAA_makeProtectionTemplate PARAMS((CONST char * docname));
242: </PRE>
243: <H2>MIME Argument List Parser</H2>
244: <PRE>
245:
246: /* PUBLIC HTAA_parseArgList()
247: ** PARSE AN ARGUMENT LIST GIVEN IN A HEADER FIELD
248: ** ON ENTRY:
249: ** str is a comma-separated list:
250: **
251: ** item, item, item
252: ** where
253: ** item ::= value
254: ** | name=value
255: ** | name="value"
256: **
257: ** Leading and trailing whitespace is ignored
258: ** everywhere except inside quotes, so the following
259: ** examples are equal:
260: **
261: ** name=value,foo=bar
262: ** name="value",foo="bar"
263: ** name = value , foo = bar
264: ** name = "value" , foo = "bar"
265: **
266: ** ON EXIT:
267: ** returns a list of name-value pairs (actually HTAssocList*).
268: ** For items with no name, just value, the name is
269: ** the number of order number of that item. E.g.
270: ** "1" for the first, etc.
271: */
272: PUBLIC HTList *HTAA_parseArgList PARAMS((char * str));
273:
274: </PRE>
2.5 luotonen 275:
2.1 luotonen 276: <PRE>
277: #endif /* NOT HTAAUTIL_H */
2.2 timbl 278: </PRE>End of file HTAAUtil.h.</BODY>
279: </HTML>
Webmaster