Release Notes for MacHTTP 2.0 (part 2) Version 1.3.1b16 additions ------------------------ + Fixed the Power Mac password dialog bug. + Fixed the conflict between caching servers (or clients) and password security checks. MacHTTP now demands a password for secure documents if a correct one isn't supplied with the request, even if the client or caching server already has the current copy of the document. Version 1.3.1b15 additions ------------------------ + Check memory allocation at start-up. MacHTTP now estimates how much memory you will need as it starts up, based on your config file settings. It will complain if you don't give it enough memory, but will launch and run as long as the barest minimums are available (32k). If memory requirements change during runtime (i.e. the upcoming AppleEvents for adjusting MAX_USERS, etc.), you will be responsible for ensuring that MacHTTP already has enough memory to accomodate the change. + Support for caching proxy servers. MacHTTP now works properly with caching proxy servers that send the "If-Modified-Since" tag in the request. If the modification date of the requested file has not changed, MacHTTP returns a "304 Not Modified" header, rather than sending the complete file. Note that MacHTTP logs zero bytes transfered in this case. This is NOT a bug. + Authentication by folder, multiple realms, username & password support. This is the BIG change for b15, so read the following carefully!!! MacHTTP now FULLY supports the Basic authentication scheme for all files it serves. This means that you may control access down to individual files and assign usernames and passwords. How authentication works: The Basic authentication scheme is built into most WWW clients (older versions of MacWeb and Mosaic do not support authentication). Authentication is OPTIONAL and you may choose not to activate any password-based security on your server. When a file or folder is restricted to access by certain users, MacHTTP returns a result to WWW clients that forces them to prompt the user for a username and password to access the file. Assuming the username and password sent to MacHTTP from the client are valid, the requested file is returned. Future requests for files requiring the same permissions will cause the WWW client to send the username and password automatically. Normally, this means a user will only have to enter a password once for convenience purposes. How MacHTTP implements authentication: MacHTTP allows you to divide your files and folders into multiple security "realms." Files and folders are placed in a realm, based on the text of the URL to the specific file. For example, suppose you want to configure your server so that you have some files available to everyone, some files availalble to co-workers, and some files available to customers. The MacHTTP.config file adds a new command, "REALM", which allows you to do this. The syntax of the REALM command is: REALM where match_string represents some substring of a URL that will be unique to all files in that realm and descriptive_name is text (no spaces!) that describes the realm in human readable terms. The arguments to REALM are case insensitive. Back to the example, assume your config file contains the following lines: REALM work Co-Workers REALM cust Customers Files in the Co-Workers realm may have names like: http://your.host/working_draft.html http://your.host/work-info/staff_photo.gif http://your.host/personnel/workers_comp.html Customer files may look like: http://your.host/customer_data/price_list.html http://your.host/custom_designs.html Using the "Co-Worker" example, MacHTTP looks for the match_string "work" in a URL. If it sees it, it requires authentication from the WWW client before it will allow access to the file. Notice that the substring "work" can be part of the file name, or a folder containing the file. MacHTTP will find the substring anywhere in the URL, so you can control access to multiple files by placing them in a folder whose name contains a realm's match_string. Be careful not to have a single URL match two realms. If this happens, MacHTTP uses the first realm that matches, in the order that they are entered in the config file. Once it has found that a file requires authentication, MacHTTP sends the appropriate message to the WWW client and passes the descriptive_name (in this case "Co-Workers") to the client. The WWW client will show this string to the user when it prompts the user for a username and password. MacHTTP will use a combination of the username and the realm to look up the correct password from the new "MacHTTP Settings" file. If the password supplied by the user matches the password found in the settings file, the file will be returned to the user. The MacHTTP Settings file: This file is where username and password information is stored for all users authorized to access restricted files on your server. The information is stored as STRing resources, so there is no possibility that a remote user can download this information from your server. Ultimately, many of MacHTTP's settings and configuration information stored in the MacHTTP.config file will move to the new settings file. For the time being, there will be one more file to clutter up your MacHTTP folder. Creating Passwords: Assuming that there is at least one REALM statement in your MacHTTP.config file, you can use the new "Passwords..." menu command under the "Edit" menu to add or delete password entries from the MacHTTP Settings file. (Ultimately, there will be balloon help and AppleGuide info for this dialog.) To add a new username, enter the name in the "User Name" field, the password in the "Password" field, and use the "Realms" pop-up menu to select a security realm from those defined in the config file. Then, click the Add button. The new username will appear in the scrolling list, along with the realm it is assigned to. Note that a user name may be entered in multiple realms, allowing the user to be both a co-worker and a customer, for example. Each username/realm combination must be unique within the settings file. To view a username's password or to delete a username, select one of the names from the scrolling list. The information comprising the username entry will be displayed in the username and password fields and the realm pop-up. Press the Delete button to remove the username. Although you may modify the values in the fields at this point, if you press the Add button, the changes will be saved as a new username and will not modify the old entry. To modify an existing username, delete the old one and add a new one. Usernames are available immediately after adding them, so there is no need to stop or start the server. In addition, MacHTTP will continue to serve files while you are entering username info. This is a major new chunk of functionality and I am interested in any and all feedback regarding its behavior. Version 1.3.1b14 additions ------------------------ + added ACGI type for asynchronous CGI apps and scripts and returned CGI type to its old synchronous behavior. ACGI files will behave as CGI files did under b11-b13. CGI files will behave as they did under b10 and earlier. + increased POST arg size to 8k. + b14 is now a fat binary again, built with CodeWarrior. Version 1.3.1b13 additions ------------------------ + Fixed mystery crash from b11, b12. This should eliminate unexplained type 1 and type 2 errors. + Added Date: and Last-Modified: fields to headers returned by MacHTTP. This allows MacHTTP to work with caching servers. Note that the Date: and Last-Modified: fields are only returned for TEXT and BINARY documents. SCRIPT, APPL, and CGI applications are all responsible for generating these headers themselves, if necessary. (In most cases, these dates will always be the current date and time, since CGIs are generating new HTML each execution.) Version 1.3.1b12 additions ------------------------ + This version is essentially unchanged from b11, with the exception of a few more error checks that may help eliminate the random crashes some users experience. + Parse username and password from authentication field (completed) MacHTTP now correctly parses the username and password from a "user" type authentication message as sent by WWW clients using the "Basic" authentication scheme. The "Authorization:" tag is sent by clients in response to a HTTP "401" status code. A demonstration script is included that shows how to prompt the user for a password and use the results to grant access. Examine "password.cgi" for details. This feature works with current versions of Mac Mosaic ONLY. MacWeb support is coming soon, according to the author. Check the following URL for complete details on authentication: http://info.cern.ch/hypertext/WWW/AccessAuthorization/Overview.html Version 1.3.1b11 additions ------------------------ + asynch AppleEvents MacHTTP now sends AppleEvents to CGI applications immediately, without waiting for a reply. When the application completes and returns results to MacHTTP's event queue, the results are passed on to the WWW client. This allows multiple scripts to run at the same time without MacHTTP having to wait until each one completes. Clients requesting TEXT or BINARY files are no longer forced to wait for CGI requests to complete. IMPORTANT!!! You should NOT write applications that quit immediately after serving a single request. If you do, you run the risk of accidently discarding a pending AppleEvent that MacHTTP has placed in your event queue. Rather, you should only quit when there are no more pending AppleEvents (i.e., you've received an Idle event.) + Unlimited suffix mappings MacHTTP should now support an unlimited number of suffix mappings. Unfortunately, MacHTTP no longer provides default mappings if it cannot find a config file. + add args to SCRIPT files SCRIPT type files are now passed the same arguments as CGI files. Predefined variables include: path_args http_search_args post_args method client_address username password Note that the http_request variable is no longer available. + Parse username and password from authentication field MacHTTP now parses the username and password from a "user" type authentication message as sent by WWW clients. This feature has not been tested with current WWW clients. The "Authorization:" tag is sent by clients in response to a HTTP "401" status code. I've been unable to get a script to successfully bring up the authentication dialog on Mosaic or MacWeb. If anyone can demonstrate this feature in operation, please send me the script! Version 1.3.1b10 additions ------------------------ + Fixed the "defunct listens" bug introduced in b8. Version 1.3.1b9 additions ----------------------- + increased default stack space for 68000 Macs. This needs to be tested by a 68000 Mac user as I don't have access to one. It *should* allow MacHTTP to run on all Macs now. + completed work on POST method. POST arguments are now extracted from the client's query based on the size transmitted in the query, eliminating trailing CR/LFs from the post args passed to scripts. + fixed the "-1 connections" bug. + added Content-Length to the HTTP/1.0 header. This means that clients will now be able to display how much data is being sent from MacHTTP for TEXT and BINARY files. + fixed the order of "/" translations in URLs. MacHTTP now converts "/" to ":", translates %xx encodings, then converts "::" to ":". Steps 1 and 2 were previously reversed, making "/" illegal in file names. + added security by DNS name. As of version 1.3.1b9 you may also specify full or partial domain names for ALLOW and DENY statements. The domain names are matched from right to left, as opposed to the left to right matches done for IP address ALLOW and DENY statements. Also, the domain names you specify are case-sensitive and MUST end with a period (.). For example: ALLOW tmc.edu. DENY oac.hsc.uth.tmc.edu. would deny all hosts (implicit DENY *), allow any tmc.edu node, and deny the specific host, oac.hsc.uth.tmc.edu. Version 1.3.1b8 additions ----------------------- First, B8 is NOT a fat binary. B8 adds several new features, including the long awaited POST method. Please note that several aspects of the user interface are in the process of changing. For instance, the bar graph will probably replace the numeric connection information, a zoom box will be added, a server stats window will be added etc. + added check for A/UX and a possible fix for rapid phantom connections This *may* solve the problem that A/UX users have reported with repeated phantom connections. If you run A/UX, PLEASE try this version out and let me know how it works. + add POST method The POST method is now supported (where appropriate). CGI routines can receive their arguments via a POST method in addition to the GET method. This means forms can use the GET or POST method. Using the POST method: --------------------- Using the POST method is as simple as changing the method used by your HTML form documents from GET to POST. MacHTTP now passes two additional AppleEvent parameters to CGI scripts and applications. They are "post arguments" (keyword 'post') and the "method" (keyword 'meth'). The sample script that comes with this archive demonstrates the new syntax for these additional arguments. Normally, if POST arguments are passed, the search arguments and path arguments will probably be empty. However, you can create URLs for the "submit" button on forms that do pass path and/or search args. This could allow a single script to handle multiple forms, for example. Check the "method" parameter to determine whether or not the POST arguments are valid. They are only valid if the method is "POST" (duh.) MacHTTP does NOT translate special characters that may be embedded in post arguments (unlike search args passed by GET methods). Currently, POST arguments are limited to 2048 bytes. This limit will be removed in the final version, allowing post arguments of arbitrary size. I just want to make sure the logic works now before adding a bunch of dynamic memory allocation. + add additional CGI args to AppleEvents (method, request header, POST args, etc.) See above. Added 'post' and 'meth' AppleEvent keywords. Both are strings. + make main window resizeable Still need to add a zoom box and remember window positions, but resizing seems to work OK. + remove %xx translation from args sent to scripts See above. POST arguments are not translated. Search and Path args still have %xx encoded characters and '+' chars translated. Version 1.3.1b7 additions ----------------------- This version is unchanged from b6 with one IMPORTANT exception. MacHTTP 1.3.1b7 is NOT a fat binary. It is 680x0 code only. This is because there is a very HUGE bug in the ANSI libraries that ship with CodeWarrior. Until this bug is fixed, MacHTTP will be built using Think C only. In short, CodeWarrior's standard I/O routines cannot read (correctly) using two streams that access the same read-only file. Since this happens all the time with MacHTTP, it's unacceptable and would require a very large modification to MacHTTP's internal logic to avoid. Version 1.3.1b6 additions ----------------------- + added support for default file in each folder. IMPORTANT!!! You MUST change your config file entry for the INDEX file to remove any leading directory information before the file name (including even ":"). This config file entry is now the file that will be returned whenever a directory is requested as a URL, regardless of the directory. This allows you to put a "default.html" file in every directory that will be returned when clients request a directory instead of a file. Again, it should be a simple file name like "default.html", not a full or partial path name like ":default.html". Note that if a malformed directory URL (i.e., a URL without a trailing "/") is requested, MacHTTP considers this an error and returns the error file instead of the index file. This is to avoid confusing some clients that still don't deal with malformed directory requests. + fixed special file returns to include correct MIME types Requesting directories, non-existent files, etc. will no longer result in sending an "empty screen" to some clients. A MIME type is always returned. + fixed data overruns on path and search args This was probably the cause of many of the mysterious crashes. If path or search args were too long, they were overwriting data. MacHTTP now checks for args that are too long and simply truncates them. A warning is also written to the screen. + added start-up time stamp to screen and AppleEvent Status Report. + added MacHTTP version info to AppleEvent Status Report. Version 1.3.1b5 additions ----------------------- The "DNS Bug" has been fixed. The 68k portion of the fat binary was built using an incorrect version of the DNR.c source file, causing it to work improperly. The problem with Error.html being returned with the wrong MIME type has been fixed (sort of). As long as your ERROR file is a HTML file, the correct MIME type will be returned to the client, regardless of the type or name of the file the client was originally requesting. Previously, GIFs, etc. that weren't found resulted in the client receiving a HTML error message file that had a GIF MIME type. A minor modification was made to the way MacHTTP writes to the log file. Previous versions of MacHTTP flushed the output buffer for the log file after every message was written to the log. This causes a lot of unnecessary disk I/O and may be the root of the problem with large log files. The downside is that the log file *may* not yet contain the most recent few log entries if you try opening an active log file with another application. PLEASE let me know if this modification improves MacHTTP's behavior with large log files or if it causes problems because log entries are buffered. Version 1.3.1b4 additions ----------------------- This beta is a fat binary. It is built entirely with CodeWarrior DR/3. It *may* correct problems with large log files since it is using CodeWarrior libraries instead of Think C I/O routines. I would appreciate hearing any feedback on whether or not this problem "goes away". Version 1.3.1b4 adds support for improved DNS performance. A new config file directive, "NO_DNS", has been added. If you add a single line to the config file: NO_DNS MacHTTP will avoid accessing the domain name service, improving performance. The drawback is that MacHTTP will only log IP addresses rather than the host name. Use this option if you have a flakey DNS, lots of clients that don't support reverse look-ups, or other DNS problems. 1.3.1b4 also improves DNS caching if you leave DNS services enabled. MacHTTP will cache the last few name look-ups, minimizing the need for DNS look-ups but maintaining the host names while logging. Version 1.3.1b1 additions ----------------------- Version 1.3.1b1 of MacHTTP is unchanged from 1.3 with the exception of the introduction of a single new feature. This beta adds support for sending a new AppleEvent, called "Search Doc," to script applications or stand-alone programs. The "Search Doc" event is sent whenever a client requests a URL which has a suffix mapping of a new type, "CGI." The CGI suffix mapping and the Search Doc event give MacHTTP a superset of the capabilities available in Unix servers using the common gateway interface (CGI) standard for interfacing to external programs. In the final version of MacHTTP 1.3.1, CGI applications will be passed the following information whenever a client requests the application's URL: � path arguments: the "path arguments" portion of a URL, used to pass arguments to the CGI application in addition to the search arguments. � search arguments: this is the same data from "http_search_args" we've all come to know and love. � address: This is the domain name of the WWW client requesting the URL. � user name: The user name passed by the WWW client in the Authorization: tag of the HTTP request. (not passed by 1.3.1b1 yet) � password: The password passed by the WWW client in the Authorization: tag of the HTTP request. (not passed by 1.3.1b1 yet) The syntax for the CGI suffix mapping in the config file is identical to the other suffix mappings. See the config file for an example. The CGI file type behaves exactly the same as the APPL file type, with the exception of the additional parameters passed besides "search arguments." New URL Syntax -------------- This info is subject to change, but for now, the syntax of URLs understood by MacHTTP looks like: // []/ [$] [?] Notice that "$" has been added to the syntax to divide path arguments from the actual path to the searching application and the search arguments. This is legal syntax according to the URL standard, but using "$" to represent path arguments isn't explicitly part of the URL standard and isn't the way CGI URLs are specified for Unix servers. Therefore, the syntax MAY change in the future. An example of a URL using this syntax might be: http://your.host.edu/search.cgi$document_1.data?some+search+terms Semantically, this might be interpreted as follows. MacHTTP will launch the application "search.cgi." It will pass it everything after $ and before ? as path arguments. The text after ? is passed as search arguments. The path arguments can mean ANYTHING to the application. In this case, they may tell the application which document to search (i.e., document_1.data). As long as there are no spaces, you can put up to 512 bytes of path arguments after the $. The Search Example application available from the Examples page on the MacHTTP Home Page includes support for handling the new "Search Doc" event. AppleScripts should add handlers for the WWW�sdoc event (as opposed to the old WWW�srch event). A sample AppleScript for handling the "Search Doc" event is included in this archive. The AETE resource (AppleScript dictionary) entries for this new event look like: Search Doc: Search a specific document for keywords Search Doc 'char' -- Path Arguments for 'char' -- Search arguments [address 'char'] -- Client Address [user 'char'] -- User Name [password 'char'] -- Password Result: 'char' -- Search Results To test the new CGI/Search Doc functions, place a copy of the Search.exe application from the "Search Example" archive mentioned above in the MacHTTP folder. Rename it to "Search.cgi." Make a copy of the "search_me" data file and place it in the same folder as "Search.cgi". Access it using the URL: http://your.host.edu/Search.cgi$search_me?two