Annotation of libwww/Library/src/HTAAUtil.html, revision 2.13
2.2 timbl 1: <HTML>
2.1 luotonen 2: <HEAD>
2.13 ! frystyk 3: <TITLE>Utilities for the Authorization parts of libwww</TITLE>
! 4: </HEAD>
2.1 luotonen 5: <BODY>
2.13 ! frystyk 6:
! 7: <H1>Common Parts of Authorization Module to Both Server And
! 8: Browser</H1>
! 9:
! 10: <PRE>
! 11: /*
! 12: ** (c) COPYRIGHT CERN 1994.
! 13: ** Please first read the full copyright statement in the file COPYRIGH.
! 14: */
! 15: </PRE>
! 16:
! 17: This module is the interface to the common parts of Access
! 18: Authorization (AA) package for both server and browser. Important to
! 19: know about memory allocation:<P>
! 20:
! 21: Routines in this module use dynamic allocation, but free automatically
! 22: all the memory reserved by them. Therefore the caller never has to
! 23: (and never should) free() any object returned by these functions.<P>
! 24:
! 25: Therefore also all the strings returned by this package are only valid
! 26: until the next call to the same function is made. This approach is
! 27: selected, because of the nature of access authorization: no string
! 28: returned by the package needs to be valid longer than until the next
! 29: call. This also makes it easy to plug the AA package in: you don't
! 30: have to ponder whether to free() something here or is it done
! 31: somewhere else (because it is always done somewhere else).<P>
! 32:
! 33: The strings that the package needs to store are copied so the original
! 34: strings given as parameters to AA functions may be freed or modified
2.2 timbl 35: with no side effects.<P>
2.13 ! frystyk 36:
! 37: Also note: The AA package does not free() anything else than what it
! 38: has itself allocated. <P>
! 39:
! 40: This module is implemented by <A HREF="HTAAUtil.c">HTAAUtil.c</A>, and
! 41: it is a part of the <A
! 42: HREF="http://info.cern.ch/hypertext/WWW/Library/User/Guide/Guide.html">
! 43: Library of Common Code</A>.
! 44:
2.1 luotonen 45: <PRE>
46: #ifndef HTAAUTIL_H
47: #define HTAAUTIL_H
48:
49: #include "HTUtils.h" /* BOOL, PARAMS, ARGS */
50: #include "HTList.h"
2.2 timbl 51: #include "tcp.h"
2.1 luotonen 52:
53: #ifdef SHORT_NAMES
54: #define HTAASenu HTAAScheme_enum
55: #define HTAASnam HTAAScheme_name
56: #define HTAAteMa HTAA_templateMatch
57: #define HTAAmaPT HTAA_makeProtectionTemplate
58: #define HTAApALi HTAA_parseArgList
59: #endif /*SHORT_NAMES*/
60:
61:
2.2 timbl 62: </PRE>
63: <H2>Default filenames</H2>
64: <PRE>#ifndef PASSWD_FILE
2.1 luotonen 65: #define PASSWD_FILE "/home2/luotonen/passwd"
66: #endif
67:
68: #ifndef GROUP_FILE
69: #define GROUP_FILE "/home2/luotonen/group"
70: #endif
71:
72: #define ACL_FILE_NAME ".www_acl"
73:
74:
75: /*
76: ** Numeric constants
77: */
78: #define MAX_USERNAME_LEN 16 /* @@ Longest allowed username */
2.5 luotonen 79: #define MAX_PASSWORD_LEN 4*13 /* @@ Longest allowed password */
80: /* (encrypted, so really only 4*8)*/
2.1 luotonen 81: #define MAX_METHODNAME_LEN 12 /* @@ Longest allowed method name */
82: #define MAX_FIELDNAME_LEN 16 /* @@ Longest field name in */
83: /* protection setup file */
84: #define MAX_PATHNAME_LEN 80 /* @@ Longest passwd/group file */
85: /* patname to allow */
86:
87: /*
88: ** Helpful macros
89: */
90: #define FREE(x) if (x) {free(x); x=NULL;}
91:
2.6 luotonen 92:
93: /*
94: ** Access Authorization failure reasons
95: */
96: typedef enum {
97: HTAA_OK, /* 200 OK */
98: HTAA_OK_GATEWAY, /* 200 OK, acting as a gateway */
2.7 luotonen 99: HTAA_OK_REDIRECT, /* 302 OK, redirected */
2.6 luotonen 100: HTAA_NO_AUTH, /* 401 Unauthorized, not authenticated */
101: HTAA_NOT_MEMBER, /* 401 Unauthorized, not authorized */
102: HTAA_IP_MASK, /* 403 Forbidden by IP mask */
2.9 luotonen 103: HTAA_IP_MASK_PROXY, /* 403 Forbidden by IP mask on proxy */
2.6 luotonen 104: HTAA_BY_RULE, /* 403 Forbidden by rule */
105: HTAA_NO_ACL, /* 403 Forbidden, ACL non-existent */
106: HTAA_NO_ENTRY, /* 403 Forbidden, no ACL entry */
107: HTAA_SETUP_ERROR, /* 403 Forbidden, server setup error */
108: HTAA_DOTDOT, /* 403 Forbidden, URL with /../ illegal */
109: HTAA_HTBIN, /* 403 Forbidden, /htbin not enabled */
2.7 luotonen 110: HTAA_INVALID_REDIRECT,
111: /* 403 Forbidden, bad redirection setup */
2.10 luotonen 112: HTAA_INVALID_USER, /* 403 Forbidden, bad user directory */
2.7 luotonen 113: HTAA_NOT_ALLOWED, /* 403 Forbidden, dangerous method must */
114: /* be explicitly allowed */
2.8 luotonen 115: HTAA_NOT_FOUND, /* 404 Not found, or read protected */
116: HTAA_MULTI_FAILED /* 404 No suitable presentation found */
2.6 luotonen 117: } HTAAFailReason;
118:
119:
2.1 luotonen 120: </PRE>
121: <H2>Datatype definitions</H2>
2.2 timbl 122: <H3>HTAAScheme</H3>The enumeration HTAAScheme represents
123: the possible authentication schemes
124: used by the WWW Access Authorization.
2.1 luotonen 125: <PRE>
126: typedef enum {
127: HTAA_UNKNOWN,
128: HTAA_NONE,
129: HTAA_BASIC,
130: HTAA_PUBKEY,
131: HTAA_KERBEROS_V4,
132: HTAA_KERBEROS_V5,
133: HTAA_MAX_SCHEMES /* THIS MUST ALWAYS BE LAST! Number of schemes */
134: } HTAAScheme;
135:
2.2 timbl 136: </PRE>
2.1 luotonen 137:
138: <H2>Authentication Schemes</H2>
139: <PRE>
140: /* PUBLIC HTAAScheme_enum()
141: ** TRANSLATE SCHEME NAME TO A SCHEME ENUMERATION
142: ** ON ENTRY:
143: ** name is a string representing the scheme name.
144: **
145: ** ON EXIT:
146: ** returns the enumerated constant for that scheme.
147: */
2.12 frystyk 148: extern HTAAScheme HTAAScheme_enum PARAMS((CONST char* name));
2.1 luotonen 149:
150:
151: /* PUBLIC HTAAScheme_name()
152: ** GET THE NAME OF A GIVEN SCHEME
153: ** ON ENTRY:
154: ** scheme is one of the scheme enum values:
155: ** HTAA_NONE, HTAA_BASIC, HTAA_PUBKEY, ...
156: **
157: ** ON EXIT:
158: ** returns the name of the scheme, i.e.
159: ** "none", "basic", "pubkey", ...
160: */
2.12 frystyk 161: extern char *HTAAScheme_name PARAMS((HTAAScheme scheme));
2.2 timbl 162:
2.1 luotonen 163:
2.7 luotonen 164: /* PUBLIC HTAA_templateCaseMatch()
2.4 duns 165: ** STRING COMPARISON FUNCTION FOR FILE NAMES
166: ** WITH ONE WILDCARD * IN THE TEMPLATE (Case Insensitive)
167: ** NOTE:
168: ** This is essentially the same code as in HTAA_templateMatch, but
169: ** it compares case insensitive (for VMS). Reason for this routine
170: ** is that HTAA_templateMatch gets called from several places, also
171: ** there where a case sensitive match is needed, so one cannot just
172: ** change the HTAA_templateMatch routine for VMS.
173: **
174: ** ON ENTRY:
175: ** template is a template string to match the file name
176: ** agaist, may contain a single wildcard
177: ** character * which matches zero or more
178: ** arbitrary characters.
179: ** filename is the filename (or pathname) to be matched
180: ** agaist the template.
181: **
182: ** ON EXIT:
183: ** returns YES, if filename matches the template.
184: ** NO, otherwise.
185: */
2.12 frystyk 186: extern BOOL HTAA_templateCaseMatch PARAMS((CONST char * tmplate,
2.7 luotonen 187: CONST char * filename));
2.4 duns 188:
189:
2.1 luotonen 190: /* PUBLIC HTAA_makeProtectionTemplate()
191: ** CREATE A PROTECTION TEMPLATE FOR THE FILES
192: ** IN THE SAME DIRECTORY AS THE GIVEN FILE
193: ** (Used by server if there is no fancier way for
194: ** it to tell the client, and by browser if server
195: ** didn't send WWW-ProtectionTemplate: field)
196: ** ON ENTRY:
197: ** docname is the document pathname (from URL).
198: **
199: ** ON EXIT:
200: ** returns a template matching docname, and other files
201: ** files in that directory.
202: **
203: ** E.g. /foo/bar/x.html => /foo/bar/ *
204: ** ^
205: ** Space only to prevent it from
206: ** being a comment marker here,
207: ** there really isn't any space.
208: */
2.12 frystyk 209: extern char *HTAA_makeProtectionTemplate PARAMS((CONST char * docname));
2.1 luotonen 210: </PRE>
211: <H2>MIME Argument List Parser</H2>
212: <PRE>
213:
214: /* PUBLIC HTAA_parseArgList()
215: ** PARSE AN ARGUMENT LIST GIVEN IN A HEADER FIELD
216: ** ON ENTRY:
217: ** str is a comma-separated list:
218: **
219: ** item, item, item
220: ** where
221: ** item ::= value
222: ** | name=value
223: ** | name="value"
224: **
225: ** Leading and trailing whitespace is ignored
226: ** everywhere except inside quotes, so the following
227: ** examples are equal:
228: **
229: ** name=value,foo=bar
230: ** name="value",foo="bar"
231: ** name = value , foo = bar
232: ** name = "value" , foo = "bar"
233: **
234: ** ON EXIT:
235: ** returns a list of name-value pairs (actually HTAssocList*).
236: ** For items with no name, just value, the name is
237: ** the number of order number of that item. E.g.
238: ** "1" for the first, etc.
239: */
2.12 frystyk 240: extern HTList *HTAA_parseArgList PARAMS((char * str));
2.1 luotonen 241:
242: </PRE>
2.5 luotonen 243:
2.1 luotonen 244: <PRE>
245: #endif /* NOT HTAAUTIL_H */
2.2 timbl 246: </PRE>End of file HTAAUtil.h.</BODY>
247: </HTML>
Webmaster