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