| 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 */ |