Annotation of libwww/Library/src/HTAAUtil.html, revision 2.12
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 HTAAteMa HTAA_templateMatch
51: #define HTAAmaPT HTAA_makeProtectionTemplate
52: #define HTAApALi HTAA_parseArgList
53: #endif /*SHORT_NAMES*/
54:
55:
2.2 timbl 56: </PRE>
57: <H2>Default filenames</H2>
58: <PRE>#ifndef PASSWD_FILE
2.1 luotonen 59: #define PASSWD_FILE "/home2/luotonen/passwd"
60: #endif
61:
62: #ifndef GROUP_FILE
63: #define GROUP_FILE "/home2/luotonen/group"
64: #endif
65:
66: #define ACL_FILE_NAME ".www_acl"
67:
68:
69: /*
70: ** Numeric constants
71: */
72: #define MAX_USERNAME_LEN 16 /* @@ Longest allowed username */
2.5 luotonen 73: #define MAX_PASSWORD_LEN 4*13 /* @@ Longest allowed password */
74: /* (encrypted, so really only 4*8)*/
2.1 luotonen 75: #define MAX_METHODNAME_LEN 12 /* @@ Longest allowed method name */
76: #define MAX_FIELDNAME_LEN 16 /* @@ Longest field name in */
77: /* protection setup file */
78: #define MAX_PATHNAME_LEN 80 /* @@ Longest passwd/group file */
79: /* patname to allow */
80:
81: /*
82: ** Helpful macros
83: */
84: #define FREE(x) if (x) {free(x); x=NULL;}
85:
2.6 luotonen 86:
87: /*
88: ** Access Authorization failure reasons
89: */
90: typedef enum {
91: HTAA_OK, /* 200 OK */
92: HTAA_OK_GATEWAY, /* 200 OK, acting as a gateway */
2.7 luotonen 93: HTAA_OK_REDIRECT, /* 302 OK, redirected */
2.6 luotonen 94: HTAA_NO_AUTH, /* 401 Unauthorized, not authenticated */
95: HTAA_NOT_MEMBER, /* 401 Unauthorized, not authorized */
96: HTAA_IP_MASK, /* 403 Forbidden by IP mask */
2.9 luotonen 97: HTAA_IP_MASK_PROXY, /* 403 Forbidden by IP mask on proxy */
2.6 luotonen 98: HTAA_BY_RULE, /* 403 Forbidden by rule */
99: HTAA_NO_ACL, /* 403 Forbidden, ACL non-existent */
100: HTAA_NO_ENTRY, /* 403 Forbidden, no ACL entry */
101: HTAA_SETUP_ERROR, /* 403 Forbidden, server setup error */
102: HTAA_DOTDOT, /* 403 Forbidden, URL with /../ illegal */
103: HTAA_HTBIN, /* 403 Forbidden, /htbin not enabled */
2.7 luotonen 104: HTAA_INVALID_REDIRECT,
105: /* 403 Forbidden, bad redirection setup */
2.10 luotonen 106: HTAA_INVALID_USER, /* 403 Forbidden, bad user directory */
2.7 luotonen 107: HTAA_NOT_ALLOWED, /* 403 Forbidden, dangerous method must */
108: /* be explicitly allowed */
2.8 luotonen 109: HTAA_NOT_FOUND, /* 404 Not found, or read protected */
110: HTAA_MULTI_FAILED /* 404 No suitable presentation found */
2.6 luotonen 111: } HTAAFailReason;
112:
113:
2.1 luotonen 114: </PRE>
115: <H2>Datatype definitions</H2>
2.2 timbl 116: <H3>HTAAScheme</H3>The enumeration HTAAScheme represents
117: the possible authentication schemes
118: used by the WWW Access Authorization.
2.1 luotonen 119: <PRE>
120: typedef enum {
121: HTAA_UNKNOWN,
122: HTAA_NONE,
123: HTAA_BASIC,
124: HTAA_PUBKEY,
125: HTAA_KERBEROS_V4,
126: HTAA_KERBEROS_V5,
127: HTAA_MAX_SCHEMES /* THIS MUST ALWAYS BE LAST! Number of schemes */
128: } HTAAScheme;
129:
2.2 timbl 130: </PRE>
2.1 luotonen 131:
132: <H2>Authentication Schemes</H2>
133: <PRE>
134: /* PUBLIC HTAAScheme_enum()
135: ** TRANSLATE SCHEME NAME TO A SCHEME ENUMERATION
136: ** ON ENTRY:
137: ** name is a string representing the scheme name.
138: **
139: ** ON EXIT:
140: ** returns the enumerated constant for that scheme.
141: */
2.12 ! frystyk 142: extern HTAAScheme HTAAScheme_enum PARAMS((CONST char* name));
2.1 luotonen 143:
144:
145: /* PUBLIC HTAAScheme_name()
146: ** GET THE NAME OF A GIVEN SCHEME
147: ** ON ENTRY:
148: ** scheme is one of the scheme enum values:
149: ** HTAA_NONE, HTAA_BASIC, HTAA_PUBKEY, ...
150: **
151: ** ON EXIT:
152: ** returns the name of the scheme, i.e.
153: ** "none", "basic", "pubkey", ...
154: */
2.12 ! frystyk 155: extern char *HTAAScheme_name PARAMS((HTAAScheme scheme));
2.2 timbl 156:
2.1 luotonen 157:
2.7 luotonen 158: /* PUBLIC HTAA_templateCaseMatch()
2.4 duns 159: ** STRING COMPARISON FUNCTION FOR FILE NAMES
160: ** WITH ONE WILDCARD * IN THE TEMPLATE (Case Insensitive)
161: ** NOTE:
162: ** This is essentially the same code as in HTAA_templateMatch, but
163: ** it compares case insensitive (for VMS). Reason for this routine
164: ** is that HTAA_templateMatch gets called from several places, also
165: ** there where a case sensitive match is needed, so one cannot just
166: ** change the HTAA_templateMatch routine for VMS.
167: **
168: ** ON ENTRY:
169: ** template is a template string to match the file name
170: ** agaist, 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: ** agaist the template.
175: **
176: ** ON EXIT:
177: ** returns YES, if filename matches the template.
178: ** NO, otherwise.
179: */
2.12 ! frystyk 180: extern BOOL HTAA_templateCaseMatch PARAMS((CONST char * tmplate,
2.7 luotonen 181: CONST char * filename));
2.4 duns 182:
183:
2.1 luotonen 184: /* PUBLIC HTAA_makeProtectionTemplate()
185: ** CREATE A PROTECTION TEMPLATE FOR THE FILES
186: ** IN THE SAME DIRECTORY AS THE GIVEN FILE
187: ** (Used by server if there is no fancier way for
188: ** it to tell the client, and by browser if server
189: ** didn't send WWW-ProtectionTemplate: field)
190: ** ON ENTRY:
191: ** docname is the document pathname (from URL).
192: **
193: ** ON EXIT:
194: ** returns a template matching docname, and other files
195: ** files in that directory.
196: **
197: ** E.g. /foo/bar/x.html => /foo/bar/ *
198: ** ^
199: ** Space only to prevent it from
200: ** being a comment marker here,
201: ** there really isn't any space.
202: */
2.12 ! frystyk 203: extern char *HTAA_makeProtectionTemplate PARAMS((CONST char * docname));
2.1 luotonen 204: </PRE>
205: <H2>MIME Argument List Parser</H2>
206: <PRE>
207:
208: /* PUBLIC HTAA_parseArgList()
209: ** PARSE AN ARGUMENT LIST GIVEN IN A HEADER FIELD
210: ** ON ENTRY:
211: ** str is a comma-separated list:
212: **
213: ** item, item, item
214: ** where
215: ** item ::= value
216: ** | name=value
217: ** | name="value"
218: **
219: ** Leading and trailing whitespace is ignored
220: ** everywhere except inside quotes, so the following
221: ** examples are equal:
222: **
223: ** name=value,foo=bar
224: ** name="value",foo="bar"
225: ** name = value , foo = bar
226: ** name = "value" , foo = "bar"
227: **
228: ** ON EXIT:
229: ** returns a list of name-value pairs (actually HTAssocList*).
230: ** For items with no name, just value, the name is
231: ** the number of order number of that item. E.g.
232: ** "1" for the first, etc.
233: */
2.12 ! frystyk 234: extern HTList *HTAA_parseArgList PARAMS((char * str));
2.1 luotonen 235:
236: </PRE>
2.5 luotonen 237:
2.1 luotonen 238: <PRE>
239: #endif /* NOT HTAAUTIL_H */
2.2 timbl 240: </PRE>End of file HTAAUtil.h.</BODY>
241: </HTML>
Webmaster