Annotation of libwww/Library/src/HTAABrow.html, revision 2.18
2.1 luotonen 1: <HEAD>
2.16 frystyk 2: <TITLE>Browser side Access Auth</TITLE>
2.18 ! frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 5-Sep-1995 -->
2.1 luotonen 4: </HEAD>
5: <BODY>
2.8 frystyk 6:
2.1 luotonen 7: <H1>Browser Side Access Authorization Module</H1>
8:
2.8 frystyk 9: <PRE>
10: /*
2.12 frystyk 11: ** (c) COPYRIGHT MIT 1995.
2.8 frystyk 12: ** Please first read the full copyright statement in the file COPYRIGH.
13: */
14: </PRE>
15:
2.1 luotonen 16: This module is the browser side interface to Access Authorization (AA)
17: package. It contains code only for browser.<P>
18:
19: <B>Important</B> to know about memory allocation:<P>
20:
2.8 frystyk 21: Routines in this module use dynamic allocation, but free automatically
22: all the memory reserved by them.<P>
23:
2.1 luotonen 24: Therefore the caller never has to (and never should)
2.8 frystyk 25: <CODE>free()</CODE> any object returned by these functions.<P>
26:
27: Therefore also all the strings returned by this package are only valid
28: until the next call to the same function is made. This approach is
29: selected, because of the nature of access authorization: no string
30: returned by the package needs to be valid longer than until the next
31: call.<P>
32:
33: This also makes it easy to plug the AA package in: you don't have to
34: ponder whether to <CODE>free()</CODE> something here or is it done
35: somewhere else (because it is always done somewhere else).<P>
36:
2.1 luotonen 37: The strings that the package needs to store are copied
38: so the original strings given as parameters to AA
2.8 frystyk 39: functions may be freed or modified with no side effects.<P>
40:
41: <B>Also note:</B> The AA package does not <CODE>free()</CODE> anything
42: else than what it has itself allocated. <P>
43:
44: This module is implemented by <A HREF="HTAABrow.c">HTAABrow.c</A>, and
45: it is a part of the <A
2.17 frystyk 46: HREF="http://www.w3.org/pub/WWW/Library/">
2.15 frystyk 47: W3C Reference Library</A>.
2.1 luotonen 48:
49: <PRE>
50: #ifndef HTAABROW_H
51: #define HTAABROW_H
2.18 ! frystyk 52: #include "HTAAUtil.h"
2.3 luotonen 53: #include "HTList.h"
54: #include "HTAssoc.h"
2.18 ! frystyk 55: #include "HTReq.h"
2.3 luotonen 56:
57: /*
58: ** Local datatype definitions
59: **
60: ** HTAAServer contains all the information about one server.
61: */
2.18 ! frystyk 62: typedef struct _HTAAServer {
2.3 luotonen 63:
64: char * hostname; /* Host's name */
65: int portnumber; /* Port number */
66: HTList * setups; /* List of protection setups */
67: /* on this server; i.e. valid */
68: /* authentication schemes and */
69: /* templates when to use them. */
70: /* This is actually a list of */
71: /* HTAASetup objects. */
72: HTList * realms; /* Information about passwords */
73: } HTAAServer;
74:
75:
76: /*
77: ** HTAASetup contains information about one server's one
78: ** protected tree of documents.
79: */
2.18 ! frystyk 80: typedef struct _HTAASetup {
2.3 luotonen 81: HTAAServer *server; /* Which server serves this tree */
2.5 frystyk 82: char * tmplate; /* Template for this tree */
2.3 luotonen 83: HTList * valid_schemes; /* Valid authentic.schemes */
84: HTAssocList**scheme_specifics;/* Scheme specific params */
85: BOOL reprompt; /* Failed last time -- reprompt (or whatever)*/
2.18 ! frystyk 86: } HTAASetup;
2.3 luotonen 87:
88:
89: /*
90: ** Information about usernames and passwords in
91: ** Basic and Pubkey authentication schemes;
92: */
2.18 ! frystyk 93: typedef struct _HTAARealm {
2.3 luotonen 94: char * realmname; /* Password domain name */
95: char * username; /* Username in that domain */
96: char * password; /* Corresponding password */
2.18 ! frystyk 97: } HTAARealm;
2.1 luotonen 98: </PRE>
99:
100: <H2>Routines for Browser Side Recording of AA Info</H2>
101:
102: Most of the browser-side AA is done by the following two functions
103: (which are called from file <CODE>HTTP.c</CODE> so the browsers using
104: <CODE>libwww</CODE> only need to be linked with the new library and not
105: be changed at all):
106: <UL>
107:
108: <LI><CODE>HTAA_composeAuth()</CODE> composes the
109: <CODE>Authorization:</CODE> line contents, if the AA package thinks
110: that the given document is protected. Otherwise this function returns
111: NULL. This function also calls the functions <CODE>HTPrompt(),</CODE>
112: <CODE>HTPromptPassword()</CODE> and <CODE>HTConfirm()</CODE> to get
113: the username, password and some confirmation from the user.
114:
115: <LI><CODE>HTAA_shouldRetryWithAuth()</CODE> determines whether to
116: retry the request with AA or with a new AA (in case username or
117: password was misspelled).
118:
119: </UL>
120: <PRE>
2.3 luotonen 121: /* BROWSER PUBLIC HTAA_composeAuth()
2.1 luotonen 122: **
2.3 luotonen 123: ** COMPOSE Authorization: HEADER LINE CONTENTS
124: ** IF WE ALREADY KNOW THAT THE HOST REQUIRES AUTHENTICATION
2.1 luotonen 125: **
126: ** ON ENTRY:
2.3 luotonen 127: ** req request, which contains
128: ** req->argument document, that we're trying to access.
129: ** req->setup protection setup info on browser.
130: ** req->scheme selected authentication scheme.
131: ** req->realm for Basic scheme the username and password.
2.1 luotonen 132: **
133: ** ON EXIT:
2.3 luotonen 134: ** returns NO, if no authorization seems to be needed, and
135: ** req->authorization is NULL.
136: ** YES, if it has composed Authorization field,
137: ** in which case the result is in req->authorization,
138: ** e.g.
2.1 luotonen 139: **
2.3 luotonen 140: ** "Basic AkRDIhEF8sdEgs72F73bfaS=="
2.1 luotonen 141: */
2.7 frystyk 142: extern BOOL HTAA_composeAuth PARAMS((HTRequest * req));
2.1 luotonen 143:
144:
2.3 luotonen 145: /* BROWSER PUBLIC HTAA_retryWithAuth()
2.1 luotonen 146: **
2.3 luotonen 147: ** RETRY THE SERVER WITH AUTHORIZATION (OR IF
148: ** ALREADY RETRIED, WITH A DIFFERENT USERNAME
149: ** AND/OR PASSWORD (IF MISSPELLED)) OR CANCEL
2.1 luotonen 150: ** ON ENTRY:
2.3 luotonen 151: ** req request.
152: ** req->valid_schemes
2.1 luotonen 153: ** This function should only be called when
154: ** server has replied with a 401 (Unauthorized)
2.3 luotonen 155: ** status code, and req structure has been filled
156: ** up according to server reply, especially the
157: ** req->valid_shemes list must have been set up
158: ** according to WWW-Authenticate: headers.
159: ** callback the function to call when username and
160: ** password have been entered (HTLoadHTTP()).
2.1 luotonen 161: ** ON EXIT:
2.3 luotonen 162: ** On GUI clients pops up a username/password dialog box
163: ** with "Ok" and "Cancel".
164: ** "Ok" button press should do a callback
165: **
166: ** HTLoadHTTP(req);
167: **
168: ** This actually done by function HTPasswordDialog(),
169: ** which GUI clients redefine.
170: **
171: ** returns YES, if dialog box was popped up.
172: ** NO, on failure.
2.1 luotonen 173: */
2.7 frystyk 174: extern BOOL HTAA_retryWithAuth PARAMS((HTRequest * req));
2.3 luotonen 175:
2.4 frystyk 176:
2.10 frystyk 177: /* PUPLIC HTAA_cleanup()
2.4 frystyk 178: **
179: ** Free the memory used by the entries concerning Access Authorization
180: ** in the request structure and put all pointers to NULL
181: ** Henrik 14/03-94.
182: **
183: ** ON ENTRY:
184: ** req the request structure
185: **
186: ** ON EXIT:
187: ** returns nothing.
188: */
2.7 frystyk 189: extern void HTAACleanup PARAMS((HTRequest *req));
2.1 luotonen 190: </PRE>
2.2 luotonen 191:
192: <H2>Enabling Gateway httpds to Forward Authorization</H2>
193: These functions should only be called from daemon code, and
194: <CODE>HTAAForwardAuth_reset()</CODE> must be called before the next
195: request is handled to make sure that authorization string
196: isn't cached in daemon so that other people can access private
197: files using somebody elses previous authorization information.
198: <PRE>
2.7 frystyk 199: extern void HTAAForwardAuth_set PARAMS((CONST char * scheme_name,
2.2 luotonen 200: CONST char * scheme_specifics));
2.7 frystyk 201: extern void HTAAForwardAuth_reset NOPARAMS;
2.2 luotonen 202: </PRE>
203:
2.1 luotonen 204: <PRE>
205: #endif /* NOT HTAABROW_H */
206: </PRE>
207: End of file HTAABrow.h.
208: </BODY>
Webmaster