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