Debian Codegraph @

WWW/Library/Implementation/HTAABrow.h

raw
1 /*
2 * $LynxId: HTAABrow.h,v 1.17 2016/11/24 23:32:22 tom Exp $
3 *
4 * BROWSER SIDE ACCESS AUTHORIZATION MODULE
5
6 This module is the browser side interface to Access Authorization (AA) package. It
7 contains code only for browser.
8
9 Important to know about memory allocation:
10
11 Routines in this module use dynamic allocation, but free automatically all the memory
12 reserved by them.
13
14 Therefore the caller never has to (and never should) free() any object returned by
15 these functions.
16
17 Therefore also all the strings returned by this package are only valid until the next
18 call to the same function is made. This approach is selected, because of the nature of
19 access authorization: no string returned by the package needs to be valid longer than
20 until the next call.
21
22 This also makes it easy to plug the AA package in: you don't have to ponder whether to
23 free()something here or is it done somewhere else (because it is always done somewhere
24 else).
25
26 The strings that the package needs to store are copied so the original strings given as
27 parameters to AA functions may be freed or modified with no side effects.
28
29 Also note:The AA package does not free() anything else than what it has itself
30 allocated.
31
32 */
33
34 #ifndef HTAABROW_H
35 #define HTAABROW_H
36
37 #include <HTAAUtil.h> /* Common parts of AA */
38
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42 /*
43 Routines for Browser Side Recording of AA Info
44
45 Most of the browser-side AA is done by the following two functions (which are called
46 from file HTTP.c so the browsers using libwww only need to be linked with the new
47 library and not be changed at all):
48
49 HTAA_composeAuth() composes the Authorization: line contents, if the AA package
50 thinks that the given document is protected. Otherwise this function returns NULL.
51 This function also calls the functions HTPrompt(),HTPromptPassword() and HTConfirm()
52 to get the username, password and some confirmation from the user.
53
54 HTAA_shouldRetryWithAuth() determines whether to retry the request with AA or with a
55 new AA (in case username or password was misspelled).
56
57 */
58 /* PUBLIC HTAA_composeAuth()
59 *
60 * COMPOSE THE ENTIRE AUTHORIZATION HEADER LINE IF WE
61 * ALREADY KNOW, THAT THE HOST MIGHT REQUIRE AUTHORIZATION
62 *
63 * ON ENTRY:
64 * hostname is the hostname of the server.
65 * portnumber is the portnumber in which the server runs.
66 * docname is the pathname of the document (as in URL)
67 *
68 * ON EXIT:
69 * returns NULL, if no authorization seems to be needed, or
70 * if it is the entire Authorization: line, e.g.
71 *
72 * "Authorization: basic username:password"
73 *
74 * As usual, this string is automatically freed.
75 */
76 extern char *HTAA_composeAuth(const char *hostname,
77 const int portnumber,
78 const char *docname,
79 int IsProxy);
80
81 /* BROWSER PUBLIC HTAA_shouldRetryWithAuth()
82 *
83 * DETERMINES IF WE SHOULD RETRY THE SERVER
84 * WITH AUTHORIZATION
85 * (OR IF ALREADY RETRIED, WITH A DIFFERENT
86 * USERNAME AND/OR PASSWORD (IF MISSPELLED))
87 * ON ENTRY:
88 * start_of_headers is the first block already read from socket,
89 * but status line skipped; i.e., points to the
90 * start of the header section.
91 * length is the remaining length of the first block.
92 * soc is the socket to read the rest of server reply.
93 *
94 * This function should only be called when
95 * server has replied with a 401 (Unauthorized)
96 * status code.
97 * ON EXIT:
98 * returns YES, if connection should be retried.
99 * The node containing all the necessary
100 * information is
101 * * either constructed if it does not exist
102 * * or password is reset to NULL to indicate
103 * that username and password should be
104 * reprompted when composing Authorization:
105 * field (in function HTAA_composeAuth()).
106 * NO, otherwise.
107 */
108 extern BOOL HTAA_shouldRetryWithAuth(char *start_of_headers,
109 size_t length,
110 int soc,
111 int IsProxy);
112
113 /*
114 * Function to allow clearing of all Authorization info
115 * via a browser command. - FM
116 */
117 extern void HTClearHTTPAuthInfo(void);
118
119 /*
120 * Check if a hostname-string contains user information.
121 */
122 extern BOOL HTAA_HaveUserinfo(const char *hostname);
123
124 /*
125
126 Enabling Gateway httpds to Forward Authorization
127
128 These functions should only be called from daemon code, and HTAAForwardAuth_reset()
129 must be called before the next request is handled to make sure that authorization
130 string isn't cached in daemon so that other people can access private files using
131 somebody else's previous authorization information.
132
133 */
134
135 extern void HTAAForwardAuth_set(const char *scheme_name,
136 const char *scheme_specifics);
137 extern void HTAAForwardAuth_reset(void);
138
139 #ifdef __cplusplus
140 }
141 #endif
142 #endif /* NOT HTAABROW_H */