Debian Codegraph @

WWW/Library/Implementation/HTAAUtil.h

raw
1 /*
2 * $LynxId: HTAAUtil.h,v 1.13 2010/10/27 00:09:52 tom Exp $
3 *
4 * Utilities for the Authorization parts of libwww
5 * COMMON PARTS OF AUTHORIZATION MODULE TO BOTH SERVER AND BROWSER
6 *
7 * This module is the interface to the common parts of Access Authorization (AA) package
8 * for both server and browser. Important to know about memory allocation:
9 *
10 * Routines in this module use dynamic allocation, but free automatically all the memory
11 * reserved by them.
12 *
13 * Therefore the caller never has to (and never should) free() any object returned by
14 * these functions.
15 *
16 * Therefore also all the strings returned by this package are only valid until the next
17 * call to the same function is made. This approach is selected, because of the nature of
18 * access authorization: no string returned by the package needs to be valid longer than
19 * until the next call.
20 *
21 * This also makes it easy to plug the AA package in: you don't have to ponder whether to
22 * free() something here or is it done somewhere else (because it is always done somewhere
23 * else).
24 *
25 * The strings that the package needs to store are copied so the original strings given as
26 * parameters to AA functions may be freed or modified with no side effects.
27 *
28 * Also note: The AA package does not free() anything else than what it has itself
29 * allocated.
30 *
31 */
32
33 #ifndef HTAAUTIL_H
34 #define HTAAUTIL_H
35
36 #include <HTList.h>
37
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41 /*
42 * Numeric constants
43 */
44 #define MAX_USERNAME_LEN 16 /* @@ Longest allowed username */
45 #define MAX_PASSWORD_LEN 3*13 /* @@ Longest allowed password */
46 /* (encrypted, so really only 3*8) */
47 #define MAX_METHODNAME_LEN 12 /* @@ Longest allowed method name */
48 #define MAX_FIELDNAME_LEN 16 /* @@ Longest field name in */
49 /* protection setup file */
50 #define MAX_PATHNAME_LEN 80 /* @@ Longest passwd/group file */
51 /* pathname to allow */
52 /*
53
54 Datatype definitions
55
56 HTAASCHEME
57
58 The enumeration HTAAScheme represents the possible authentication schemes used by the
59 WWW Access Authorization.
60
61 */ typedef enum {
62 HTAA_UNKNOWN,
63 HTAA_NONE,
64 HTAA_BASIC,
65 HTAA_PUBKEY,
66 HTAA_KERBEROS_V4,
67 HTAA_KERBEROS_V5,
68 HTAA_MAX_SCHEMES /* THIS MUST ALWAYS BE LAST! Number of schemes */
69 } HTAAScheme;
70
71 /*
72
73 ENUMERATION TO REPRESENT HTTP METHODS
74
75 */
76
77 typedef enum {
78 METHOD_UNKNOWN,
79 METHOD_GET,
80 METHOD_PUT
81 } HTAAMethod;
82
83 /*
84
85 Authentication Schemes
86
87 */
88
89 /* PUBLIC HTAAScheme_enum()
90 * TRANSLATE SCHEME NAME TO A SCHEME ENUMERATION
91 * ON ENTRY:
92 * name is a string representing the scheme name.
93 *
94 * ON EXIT:
95 * returns the enumerated constant for that scheme.
96 */
97 extern HTAAScheme HTAAScheme_enum(const char *name);
98
99 /* PUBLIC HTAAScheme_name()
100 * GET THE NAME OF A GIVEN SCHEME
101 * ON ENTRY:
102 * scheme is one of the scheme enum values:
103 * HTAA_NONE, HTAA_BASIC, HTAA_PUBKEY, ...
104 *
105 * ON EXIT:
106 * returns the name of the scheme, i.e.
107 * "none", "basic", "pubkey", ...
108 */
109 extern const char *HTAAScheme_name(HTAAScheme scheme);
110
111 /*
112
113 Methods
114
115 */
116
117 /* PUBLIC HTAAMethod_enum()
118 * TRANSLATE METHOD NAME INTO AN ENUMERATED VALUE
119 * ON ENTRY:
120 * name is the method name to translate.
121 *
122 * ON EXIT:
123 * returns HTAAMethod enumerated value corresponding
124 * to the given name.
125 */
126 extern HTAAMethod HTAAMethod_enum(const char *name);
127
128 /* PUBLIC HTAAMethod_name()
129 * GET THE NAME OF A GIVEN METHOD
130 * ON ENTRY:
131 * method is one of the method enum values:
132 * METHOD_GET, METHOD_PUT, ...
133 *
134 * ON EXIT:
135 * returns the name of the scheme, i.e.
136 * "GET", "PUT", ...
137 */
138 extern const char *HTAAMethod_name(HTAAMethod method);
139
140 /* PUBLIC HTAAMethod_inList()
141 * IS A METHOD IN A LIST OF METHOD NAMES
142 * ON ENTRY:
143 * method is the method to look for.
144 * list is a list of method names.
145 *
146 * ON EXIT:
147 * returns YES, if method was found.
148 * NO, if not found.
149 */
150 extern BOOL HTAAMethod_inList(HTAAMethod method, HTList *list);
151
152 /*
153
154 Match Template Against Filename
155
156 */
157
158 /* PUBLIC HTAA_templateMatch()
159 * STRING COMPARISON FUNCTION FOR FILE NAMES
160 * WITH ONE WILDCARD * IN THE TEMPLATE
161 * NOTE:
162 * This is essentially the same code as in HTRules.c, but it
163 * cannot be used because it is embedded in between other code.
164 * (In fact, HTRules.c should use this routine, but then this
165 * routine would have to be more sophisticated... why is life
166 * sometimes so hard...)
167 *
168 * ON ENTRY:
169 * ctemplate is a template string to match the file name
170 * against, may contain a single wildcard
171 * character * which matches zero or more
172 * arbitrary characters.
173 * filename is the filename (or pathname) to be matched
174 * against the template.
175 *
176 * ON EXIT:
177 * returns YES, if filename matches the template.
178 * NO, otherwise.
179 */
180 extern BOOL HTAA_templateMatch(const char *ctemplate,
181 const char *filename);
182
183 /* PUBLIC HTAA_templateCaseMatch()
184 * STRING COMPARISON FUNCTION FOR FILE NAMES
185 * WITH ONE WILDCARD * IN THE TEMPLATE (Case Insensitive)
186 * NOTE:
187 * This is essentially the same code as in HTAA_templateMatch, but
188 * it compares case insensitive (for VMS). Reason for this routine
189 * is that HTAA_templateMatch gets called from several places, also
190 * there where a case sensitive match is needed, so one cannot just
191 * change the HTAA_templateMatch routine for VMS.
192 *
193 * ON ENTRY:
194 * ctemplate is a template string to match the file name
195 * against, may contain a single wildcard
196 * character * which matches zero or more
197 * arbitrary characters.
198 * filename is the filename (or pathname) to be matched
199 * against the template.
200 *
201 * ON EXIT:
202 * returns YES, if filename matches the template.
203 * NO, otherwise.
204 */
205 extern BOOL HTAA_templateCaseMatch(const char *ctemplate,
206 const char *filename);
207
208 /* PUBLIC HTAA_makeProtectionTemplate()
209 * CREATE A PROTECTION TEMPLATE FOR THE FILES
210 * IN THE SAME DIRECTORY AS THE GIVEN FILE
211 * (Used by server if there is no fancier way for
212 * it to tell the client, and by browser if server
213 * didn't send WWW-ProtectionTemplate: field)
214 * ON ENTRY:
215 * docname is the document pathname (from URL).
216 *
217 * ON EXIT:
218 * returns a template matching docname, and other files
219 * files in that directory.
220 *
221 * E.g. /foo/bar/x.html => /foo/bar/ *
222 * ^
223 * Space only to prevent it from
224 * being a comment marker here,
225 * there really isn't any space.
226 */
227 extern char *HTAA_makeProtectionTemplate(const char *docname);
228
229 /*
230
231 MIME Argument List Parser
232
233 */
234
235 /* PUBLIC HTAA_parseArgList()
236 * PARSE AN ARGUMENT LIST GIVEN IN A HEADER FIELD
237 * ON ENTRY:
238 * str is a comma-separated list:
239 *
240 * item, item, item
241 * where
242 * item ::= value
243 * | name=value
244 * | name="value"
245 *
246 * Leading and trailing whitespace is ignored
247 * everywhere except inside quotes, so the following
248 * examples are equal:
249 *
250 * name=value,foo=bar
251 * name="value",foo="bar"
252 * name = value , foo = bar
253 * name = "value" , foo = "bar"
254 *
255 * ON EXIT:
256 * returns a list of name-value pairs (actually HTAssocList*).
257 * For items with no name, just value, the name is
258 * the number of order number of that item. E.g.
259 * "1" for the first, etc.
260 */
261 extern HTList *HTAA_parseArgList(char *str);
262
263 /*
264
265 Header Line Reader
266
267 */
268
269 /* PUBLIC HTAA_setupReader()
270 * SET UP HEADER LINE READER, i.e., give
271 * the already-read-but-not-yet-processed
272 * buffer of text to be read before more
273 * is read from the socket.
274 * ON ENTRY:
275 * start_of_headers is a pointer to a buffer containing
276 * the beginning of the header lines
277 * (rest will be read from a socket).
278 * length is the number of valid characters in
279 * 'start_of_headers' buffer.
280 * soc is the socket to use when start_of_headers
281 * buffer is used up.
282 * ON EXIT:
283 * returns nothing.
284 * Subsequent calls to HTAA_getUnfoldedLine()
285 * will use this buffer first and then
286 * proceed to read from socket.
287 */
288 extern void HTAA_setupReader(char *start_of_headers,
289 size_t length,
290 int soc);
291
292 /* PUBLIC HTAA_getUnfoldedLine()
293 * READ AN UNFOLDED HEADER LINE FROM SOCKET
294 * ON ENTRY:
295 * HTAA_setupReader must absolutely be called before
296 * this function to set up internal buffer.
297 *
298 * ON EXIT:
299 * returns a newly-allocated character string representing
300 * the read line. The line is unfolded, i.e.
301 * lines that begin with whitespace are appended
302 * to current line. E.g.
303 *
304 * Field-Name: Blaa-Blaa
305 * This-Is-A-Continuation-Line
306 * Here-Is_Another
307 *
308 * is seen by the caller as:
309 *
310 * Field-Name: Blaa-Blaa This-Is-A-Continuation-Line Here-Is_Another
311 *
312 */
313 extern char *HTAA_getUnfoldedLine(void);
314
315 #ifdef __cplusplus
316 }
317 #endif
318 #endif /* NOT HTAAUTIL_H */