318 lines
11 KiB
C
318 lines
11 KiB
C
/*
|
|
* $LynxId: HTAAUtil.h,v 1.13 2010/10/27 00:09:52 tom Exp $
|
|
*
|
|
* Utilities for the Authorization parts of libwww
|
|
* COMMON PARTS OF AUTHORIZATION MODULE TO BOTH SERVER AND BROWSER
|
|
*
|
|
* This module is the interface to the common parts of Access Authorization (AA) package
|
|
* for both server and browser. Important to know about memory allocation:
|
|
*
|
|
* Routines in this module use dynamic allocation, but free automatically all the memory
|
|
* reserved by them.
|
|
*
|
|
* Therefore the caller never has to (and never should) free() any object returned by
|
|
* these functions.
|
|
*
|
|
* Therefore also all the strings returned by this package are only valid until the next
|
|
* call to the same function is made. This approach is selected, because of the nature of
|
|
* access authorization: no string returned by the package needs to be valid longer than
|
|
* until the next call.
|
|
*
|
|
* This also makes it easy to plug the AA package in: you don't have to ponder whether to
|
|
* free() something here or is it done somewhere else (because it is always done somewhere
|
|
* else).
|
|
*
|
|
* The strings that the package needs to store are copied so the original strings given as
|
|
* parameters to AA functions may be freed or modified with no side effects.
|
|
*
|
|
* Also note: The AA package does not free() anything else than what it has itself
|
|
* allocated.
|
|
*
|
|
*/
|
|
|
|
#ifndef HTAAUTIL_H
|
|
#define HTAAUTIL_H
|
|
|
|
#include <HTList.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
/*
|
|
* Numeric constants
|
|
*/
|
|
#define MAX_USERNAME_LEN 16 /* @@ Longest allowed username */
|
|
#define MAX_PASSWORD_LEN 3*13 /* @@ Longest allowed password */
|
|
/* (encrypted, so really only 3*8) */
|
|
#define MAX_METHODNAME_LEN 12 /* @@ Longest allowed method name */
|
|
#define MAX_FIELDNAME_LEN 16 /* @@ Longest field name in */
|
|
/* protection setup file */
|
|
#define MAX_PATHNAME_LEN 80 /* @@ Longest passwd/group file */
|
|
/* pathname to allow */
|
|
/*
|
|
|
|
Datatype definitions
|
|
|
|
HTAASCHEME
|
|
|
|
The enumeration HTAAScheme represents the possible authentication schemes used by the
|
|
WWW Access Authorization.
|
|
|
|
*/ typedef enum {
|
|
HTAA_UNKNOWN,
|
|
HTAA_NONE,
|
|
HTAA_BASIC,
|
|
HTAA_PUBKEY,
|
|
HTAA_KERBEROS_V4,
|
|
HTAA_KERBEROS_V5,
|
|
HTAA_MAX_SCHEMES /* THIS MUST ALWAYS BE LAST! Number of schemes */
|
|
} HTAAScheme;
|
|
|
|
/*
|
|
|
|
ENUMERATION TO REPRESENT HTTP METHODS
|
|
|
|
*/
|
|
|
|
typedef enum {
|
|
METHOD_UNKNOWN,
|
|
METHOD_GET,
|
|
METHOD_PUT
|
|
} HTAAMethod;
|
|
|
|
/*
|
|
|
|
Authentication Schemes
|
|
|
|
*/
|
|
|
|
/* PUBLIC HTAAScheme_enum()
|
|
* TRANSLATE SCHEME NAME TO A SCHEME ENUMERATION
|
|
* ON ENTRY:
|
|
* name is a string representing the scheme name.
|
|
*
|
|
* ON EXIT:
|
|
* returns the enumerated constant for that scheme.
|
|
*/
|
|
extern HTAAScheme HTAAScheme_enum(const char *name);
|
|
|
|
/* PUBLIC HTAAScheme_name()
|
|
* GET THE NAME OF A GIVEN SCHEME
|
|
* ON ENTRY:
|
|
* scheme is one of the scheme enum values:
|
|
* HTAA_NONE, HTAA_BASIC, HTAA_PUBKEY, ...
|
|
*
|
|
* ON EXIT:
|
|
* returns the name of the scheme, i.e.
|
|
* "none", "basic", "pubkey", ...
|
|
*/
|
|
extern const char *HTAAScheme_name(HTAAScheme scheme);
|
|
|
|
/*
|
|
|
|
Methods
|
|
|
|
*/
|
|
|
|
/* PUBLIC HTAAMethod_enum()
|
|
* TRANSLATE METHOD NAME INTO AN ENUMERATED VALUE
|
|
* ON ENTRY:
|
|
* name is the method name to translate.
|
|
*
|
|
* ON EXIT:
|
|
* returns HTAAMethod enumerated value corresponding
|
|
* to the given name.
|
|
*/
|
|
extern HTAAMethod HTAAMethod_enum(const char *name);
|
|
|
|
/* PUBLIC HTAAMethod_name()
|
|
* GET THE NAME OF A GIVEN METHOD
|
|
* ON ENTRY:
|
|
* method is one of the method enum values:
|
|
* METHOD_GET, METHOD_PUT, ...
|
|
*
|
|
* ON EXIT:
|
|
* returns the name of the scheme, i.e.
|
|
* "GET", "PUT", ...
|
|
*/
|
|
extern const char *HTAAMethod_name(HTAAMethod method);
|
|
|
|
/* PUBLIC HTAAMethod_inList()
|
|
* IS A METHOD IN A LIST OF METHOD NAMES
|
|
* ON ENTRY:
|
|
* method is the method to look for.
|
|
* list is a list of method names.
|
|
*
|
|
* ON EXIT:
|
|
* returns YES, if method was found.
|
|
* NO, if not found.
|
|
*/
|
|
extern BOOL HTAAMethod_inList(HTAAMethod method, HTList *list);
|
|
|
|
/*
|
|
|
|
Match Template Against Filename
|
|
|
|
*/
|
|
|
|
/* PUBLIC HTAA_templateMatch()
|
|
* STRING COMPARISON FUNCTION FOR FILE NAMES
|
|
* WITH ONE WILDCARD * IN THE TEMPLATE
|
|
* NOTE:
|
|
* This is essentially the same code as in HTRules.c, but it
|
|
* cannot be used because it is embedded in between other code.
|
|
* (In fact, HTRules.c should use this routine, but then this
|
|
* routine would have to be more sophisticated... why is life
|
|
* sometimes so hard...)
|
|
*
|
|
* ON ENTRY:
|
|
* ctemplate is a template string to match the file name
|
|
* against, may contain a single wildcard
|
|
* character * which matches zero or more
|
|
* arbitrary characters.
|
|
* filename is the filename (or pathname) to be matched
|
|
* against the template.
|
|
*
|
|
* ON EXIT:
|
|
* returns YES, if filename matches the template.
|
|
* NO, otherwise.
|
|
*/
|
|
extern BOOL HTAA_templateMatch(const char *ctemplate,
|
|
const char *filename);
|
|
|
|
/* PUBLIC HTAA_templateCaseMatch()
|
|
* STRING COMPARISON FUNCTION FOR FILE NAMES
|
|
* WITH ONE WILDCARD * IN THE TEMPLATE (Case Insensitive)
|
|
* NOTE:
|
|
* This is essentially the same code as in HTAA_templateMatch, but
|
|
* it compares case insensitive (for VMS). Reason for this routine
|
|
* is that HTAA_templateMatch gets called from several places, also
|
|
* there where a case sensitive match is needed, so one cannot just
|
|
* change the HTAA_templateMatch routine for VMS.
|
|
*
|
|
* ON ENTRY:
|
|
* ctemplate is a template string to match the file name
|
|
* against, may contain a single wildcard
|
|
* character * which matches zero or more
|
|
* arbitrary characters.
|
|
* filename is the filename (or pathname) to be matched
|
|
* against the template.
|
|
*
|
|
* ON EXIT:
|
|
* returns YES, if filename matches the template.
|
|
* NO, otherwise.
|
|
*/
|
|
extern BOOL HTAA_templateCaseMatch(const char *ctemplate,
|
|
const char *filename);
|
|
|
|
/* PUBLIC HTAA_makeProtectionTemplate()
|
|
* CREATE A PROTECTION TEMPLATE FOR THE FILES
|
|
* IN THE SAME DIRECTORY AS THE GIVEN FILE
|
|
* (Used by server if there is no fancier way for
|
|
* it to tell the client, and by browser if server
|
|
* didn't send WWW-ProtectionTemplate: field)
|
|
* ON ENTRY:
|
|
* docname is the document pathname (from URL).
|
|
*
|
|
* ON EXIT:
|
|
* returns a template matching docname, and other files
|
|
* files in that directory.
|
|
*
|
|
* E.g. /foo/bar/x.html => /foo/bar/ *
|
|
* ^
|
|
* Space only to prevent it from
|
|
* being a comment marker here,
|
|
* there really isn't any space.
|
|
*/
|
|
extern char *HTAA_makeProtectionTemplate(const char *docname);
|
|
|
|
/*
|
|
|
|
MIME Argument List Parser
|
|
|
|
*/
|
|
|
|
/* PUBLIC HTAA_parseArgList()
|
|
* PARSE AN ARGUMENT LIST GIVEN IN A HEADER FIELD
|
|
* ON ENTRY:
|
|
* str is a comma-separated list:
|
|
*
|
|
* item, item, item
|
|
* where
|
|
* item ::= value
|
|
* | name=value
|
|
* | name="value"
|
|
*
|
|
* Leading and trailing whitespace is ignored
|
|
* everywhere except inside quotes, so the following
|
|
* examples are equal:
|
|
*
|
|
* name=value,foo=bar
|
|
* name="value",foo="bar"
|
|
* name = value , foo = bar
|
|
* name = "value" , foo = "bar"
|
|
*
|
|
* ON EXIT:
|
|
* returns a list of name-value pairs (actually HTAssocList*).
|
|
* For items with no name, just value, the name is
|
|
* the number of order number of that item. E.g.
|
|
* "1" for the first, etc.
|
|
*/
|
|
extern HTList *HTAA_parseArgList(char *str);
|
|
|
|
/*
|
|
|
|
Header Line Reader
|
|
|
|
*/
|
|
|
|
/* PUBLIC HTAA_setupReader()
|
|
* SET UP HEADER LINE READER, i.e., give
|
|
* the already-read-but-not-yet-processed
|
|
* buffer of text to be read before more
|
|
* is read from the socket.
|
|
* ON ENTRY:
|
|
* start_of_headers is a pointer to a buffer containing
|
|
* the beginning of the header lines
|
|
* (rest will be read from a socket).
|
|
* length is the number of valid characters in
|
|
* 'start_of_headers' buffer.
|
|
* soc is the socket to use when start_of_headers
|
|
* buffer is used up.
|
|
* ON EXIT:
|
|
* returns nothing.
|
|
* Subsequent calls to HTAA_getUnfoldedLine()
|
|
* will use this buffer first and then
|
|
* proceed to read from socket.
|
|
*/
|
|
extern void HTAA_setupReader(char *start_of_headers,
|
|
size_t length,
|
|
int soc);
|
|
|
|
/* PUBLIC HTAA_getUnfoldedLine()
|
|
* READ AN UNFOLDED HEADER LINE FROM SOCKET
|
|
* ON ENTRY:
|
|
* HTAA_setupReader must absolutely be called before
|
|
* this function to set up internal buffer.
|
|
*
|
|
* ON EXIT:
|
|
* returns a newly-allocated character string representing
|
|
* the read line. The line is unfolded, i.e.
|
|
* lines that begin with whitespace are appended
|
|
* to current line. E.g.
|
|
*
|
|
* Field-Name: Blaa-Blaa
|
|
* This-Is-A-Continuation-Line
|
|
* Here-Is_Another
|
|
*
|
|
* is seen by the caller as:
|
|
*
|
|
* Field-Name: Blaa-Blaa This-Is-A-Continuation-Line Here-Is_Another
|
|
*
|
|
*/
|
|
extern char *HTAA_getUnfoldedLine(void);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
#endif /* NOT HTAAUTIL_H */
|