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