Annotation of libwww/Library/src/HTAAUtil.html, revision 2.4
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.2 timbl 45: #include "tcp.h"
2.1 luotonen 46:
47: #ifdef SHORT_NAMES
48: #define HTAASenu HTAAScheme_enum
49: #define HTAASnam HTAAScheme_name
50: #define HTAAMenu HTAAMethod_enum
51: #define HTAAMnam HTAAMethod_name
52: #define HTAAMinL HTAAMethod_inList
53: #define HTAAteMa HTAA_templateMatch
54: #define HTAAmaPT HTAA_makeProtectionTemplate
55: #define HTAApALi HTAA_parseArgList
56: #define HTAAsuRe HTAA_setupReader
57: #define HTAAgUfL HTAA_getUnfoldedLine
58: #endif /*SHORT_NAMES*/
59:
60:
2.2 timbl 61: </PRE>
62: <H2>Default filenames</H2>
63: <PRE>#ifndef PASSWD_FILE
2.1 luotonen 64: #define PASSWD_FILE "/home2/luotonen/passwd"
65: #endif
66:
67: #ifndef GROUP_FILE
68: #define GROUP_FILE "/home2/luotonen/group"
69: #endif
70:
71: #define ACL_FILE_NAME ".www_acl"
72:
73:
74: /*
75: ** Numeric constants
76: */
77: #define MAX_USERNAME_LEN 16 /* @@ Longest allowed username */
78: #define MAX_PASSWORD_LEN 3*13 /* @@ Longest allowed password */
79: /* (encrypted, so really only 3*8)*/
80: #define MAX_METHODNAME_LEN 12 /* @@ Longest allowed method name */
81: #define MAX_FIELDNAME_LEN 16 /* @@ Longest field name in */
82: /* protection setup file */
83: #define MAX_PATHNAME_LEN 80 /* @@ Longest passwd/group file */
84: /* patname to allow */
85:
86: /*
87: ** Helpful macros
88: */
89: #define FREE(x) if (x) {free(x); x=NULL;}
90:
91: </PRE>
92: <H2>Datatype definitions</H2>
2.2 timbl 93: <H3>HTAAScheme</H3>The enumeration HTAAScheme represents
94: the possible authentication schemes
95: used by the WWW Access Authorization.
2.1 luotonen 96: <PRE>
97: typedef enum {
98: HTAA_UNKNOWN,
99: HTAA_NONE,
100: HTAA_BASIC,
101: HTAA_PUBKEY,
102: HTAA_KERBEROS_V4,
103: HTAA_KERBEROS_V5,
104: HTAA_MAX_SCHEMES /* THIS MUST ALWAYS BE LAST! Number of schemes */
105: } HTAAScheme;
106:
2.2 timbl 107: </PRE>
2.1 luotonen 108: <H3>Enumeration to Represent HTTP Methods</H3>
109: <PRE>
110: typedef enum {
111: METHOD_UNKNOWN,
112: METHOD_GET,
113: METHOD_PUT
114: } HTAAMethod;
115:
2.2 timbl 116: </PRE>
2.1 luotonen 117: <H2>Authentication Schemes</H2>
118: <PRE>
119: /* PUBLIC HTAAScheme_enum()
120: ** TRANSLATE SCHEME NAME TO A SCHEME ENUMERATION
121: ** ON ENTRY:
122: ** name is a string representing the scheme name.
123: **
124: ** ON EXIT:
125: ** returns the enumerated constant for that scheme.
126: */
127: PUBLIC HTAAScheme HTAAScheme_enum PARAMS((CONST char* name));
128:
129:
130: /* PUBLIC HTAAScheme_name()
131: ** GET THE NAME OF A GIVEN SCHEME
132: ** ON ENTRY:
133: ** scheme is one of the scheme enum values:
134: ** HTAA_NONE, HTAA_BASIC, HTAA_PUBKEY, ...
135: **
136: ** ON EXIT:
137: ** returns the name of the scheme, i.e.
138: ** "none", "basic", "pubkey", ...
139: */
140: PUBLIC char *HTAAScheme_name PARAMS((HTAAScheme scheme));
2.2 timbl 141:
2.1 luotonen 142: </PRE>
143: <H2>Methods</H2>
144: <PRE>
145: /* PUBLIC HTAAMethod_enum()
146: ** TRANSLATE METHOD NAME INTO AN ENUMERATED VALUE
147: ** ON ENTRY:
148: ** name is the method name to translate.
149: **
150: ** ON EXIT:
151: ** returns HTAAMethod enumerated value corresponding
152: ** to the given name.
153: */
154: PUBLIC HTAAMethod HTAAMethod_enum PARAMS((CONST char * name));
155:
156:
157: /* PUBLIC HTAAMethod_name()
158: ** GET THE NAME OF A GIVEN METHOD
159: ** ON ENTRY:
160: ** method is one of the method enum values:
161: ** METHOD_GET, METHOD_PUT, ...
162: **
163: ** ON EXIT:
164: ** returns the name of the scheme, i.e.
165: ** "GET", "PUT", ...
166: */
167: PUBLIC char *HTAAMethod_name PARAMS((HTAAMethod method));
168:
169:
170: /* PUBLIC HTAAMethod_inList()
171: ** IS A METHOD IN A LIST OF METHOD NAMES
172: ** ON ENTRY:
173: ** method is the method to look for.
174: ** list is a list of method names.
175: **
176: ** ON EXIT:
177: ** returns YES, if method was found.
178: ** NO, if not found.
179: */
180: PUBLIC BOOL HTAAMethod_inList PARAMS((HTAAMethod method,
181: HTList * list));
182: </PRE>
183: <H2>Match Template Against Filename</H2>
184: <PRE>
185: /* PUBLIC HTAA_templateMatch()
186: ** STRING COMPARISON FUNCTION FOR FILE NAMES
187: ** WITH ONE WILDCARD * IN THE TEMPLATE
188: ** NOTE:
189: ** This is essentially the same code as in HTRules.c, but it
190: ** cannot be used because it is embedded in between other code.
191: ** (In fact, HTRules.c should use this routine, but then this
192: ** routine would have to be more sophisticated... why is life
193: ** sometimes so hard...)
194: **
195: ** ON ENTRY:
196: ** template is a template string to match the file name
197: ** agaist, may contain a single wildcard
198: ** character * which matches zero or more
199: ** arbitrary characters.
200: ** filename is the filename (or pathname) to be matched
201: ** agaist the template.
202: **
203: ** ON EXIT:
204: ** returns YES, if filename matches the template.
205: ** NO, otherwise.
206: */
207: PUBLIC BOOL HTAA_templateMatch PARAMS((CONST char * template,
208: CONST char * filename));
209:
210:
2.4 ! duns 211: /* PUBLIC HTAA_templateCaseMatch()
! 212: ** STRING COMPARISON FUNCTION FOR FILE NAMES
! 213: ** WITH ONE WILDCARD * IN THE TEMPLATE (Case Insensitive)
! 214: ** NOTE:
! 215: ** This is essentially the same code as in HTAA_templateMatch, but
! 216: ** it compares case insensitive (for VMS). Reason for this routine
! 217: ** is that HTAA_templateMatch gets called from several places, also
! 218: ** there where a case sensitive match is needed, so one cannot just
! 219: ** change the HTAA_templateMatch routine for VMS.
! 220: **
! 221: ** ON ENTRY:
! 222: ** template is a template string to match the file name
! 223: ** agaist, may contain a single wildcard
! 224: ** character * which matches zero or more
! 225: ** arbitrary characters.
! 226: ** filename is the filename (or pathname) to be matched
! 227: ** agaist the template.
! 228: **
! 229: ** ON EXIT:
! 230: ** returns YES, if filename matches the template.
! 231: ** NO, otherwise.
! 232: */
! 233: PUBLIC BOOL HTAA_templateCaseMatch PARAMS((CONST char * template,
! 234: CONST char * filename));
! 235:
! 236:
2.1 luotonen 237: /* PUBLIC HTAA_makeProtectionTemplate()
238: ** CREATE A PROTECTION TEMPLATE FOR THE FILES
239: ** IN THE SAME DIRECTORY AS THE GIVEN FILE
240: ** (Used by server if there is no fancier way for
241: ** it to tell the client, and by browser if server
242: ** didn't send WWW-ProtectionTemplate: field)
243: ** ON ENTRY:
244: ** docname is the document pathname (from URL).
245: **
246: ** ON EXIT:
247: ** returns a template matching docname, and other files
248: ** files in that directory.
249: **
250: ** E.g. /foo/bar/x.html => /foo/bar/ *
251: ** ^
252: ** Space only to prevent it from
253: ** being a comment marker here,
254: ** there really isn't any space.
255: */
256: PUBLIC char *HTAA_makeProtectionTemplate PARAMS((CONST char * docname));
257: </PRE>
258: <H2>MIME Argument List Parser</H2>
259: <PRE>
260:
261: /* PUBLIC HTAA_parseArgList()
262: ** PARSE AN ARGUMENT LIST GIVEN IN A HEADER FIELD
263: ** ON ENTRY:
264: ** str is a comma-separated list:
265: **
266: ** item, item, item
267: ** where
268: ** item ::= value
269: ** | name=value
270: ** | name="value"
271: **
272: ** Leading and trailing whitespace is ignored
273: ** everywhere except inside quotes, so the following
274: ** examples are equal:
275: **
276: ** name=value,foo=bar
277: ** name="value",foo="bar"
278: ** name = value , foo = bar
279: ** name = "value" , foo = "bar"
280: **
281: ** ON EXIT:
282: ** returns a list of name-value pairs (actually HTAssocList*).
283: ** For items with no name, just value, the name is
284: ** the number of order number of that item. E.g.
285: ** "1" for the first, etc.
286: */
287: PUBLIC HTList *HTAA_parseArgList PARAMS((char * str));
288:
289: </PRE>
290: <H2>Header Line Reader</H2>
291: <PRE>
292: /* PUBLIC HTAA_setupReader()
293: ** SET UP HEADER LINE READER, i.e. give
294: ** the already-read-but-not-yet-processed
295: ** buffer of text to be read before more
296: ** is read from the socket.
297: ** ON ENTRY:
298: ** start_of_headers is a pointer to a buffer containing
299: ** the beginning of the header lines
300: ** (rest will be read from a socket).
301: ** length is the number of valid characters in
302: ** 'start_of_headers' buffer.
303: ** soc is the socket to use when start_of_headers
304: ** buffer is used up.
305: ** ON EXIT:
306: ** returns nothing.
307: ** Subsequent calls to HTAA_getUnfoldedLine()
308: ** will use this buffer first and then
309: ** proceed to read from socket.
310: */
311: PUBLIC void HTAA_setupReader PARAMS((char * start_of_headers,
312: int length,
313: int soc));
314:
315:
316: /* PUBLIC HTAA_getUnfoldedLine()
317: ** READ AN UNFOLDED HEADER LINE FROM SOCKET
318: ** ON ENTRY:
319: ** HTAA_setupReader must absolutely be called before
320: ** this function to set up internal buffer.
321: **
322: ** ON EXIT:
323: ** returns a newly-allocated character string representing
324: ** the read line. The line is unfolded, i.e.
325: ** lines that begin with whitespace are appended
326: ** to current line. E.g.
327: **
328: ** Field-Name: Blaa-Blaa
329: ** This-Is-A-Continuation-Line
330: ** Here-Is_Another
331: **
332: ** is seen by the caller as:
333: **
334: ** Field-Name: Blaa-Blaa This-Is-A-Continuation-Line Here-Is_Another
335: **
336: */
337: PUBLIC char *HTAA_getUnfoldedLine NOPARAMS;
338:
339: #endif /* NOT HTAAUTIL_H */
2.2 timbl 340: </PRE>End of file HTAAUtil.h.</BODY>
341: </HTML>
Webmaster