| 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 */ |