+-------------------------------------+ | WASD HTTP SERVER - "NUTS AND BOLTS" | +-------------------------------------+ WASD VMS Web Services Copyright (C) 1996-2021 Mark G. Daniel. Revision: v12.0.0 (September 2021) Licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. Versions prior to v12.0.0 were distributed under a GPL licence. http://www.gnu.org/licenses/gpl.txt Thanks to BETA Testing Sites ---------------------------- WASD has become a large package and requests for additional functionality frequent enough that the relatively long development-testing-refinement- release cycle of the first few years is no longer possible. It is no longer feasable for the one author to code and exhaustively test all the functionality of each new release. The role of BETA testing has become indispensable. Thanks to all who participate in this part of the cycle, in particular (and in no significant order); Jeremy Begg VSM Software Services, Adelaide, South Australia Alex Daniels themail, United Kingdom DECUServe eisner.decus.org, MA, USA John Dite Compinia GmbH & Co. Victoriano Giralt University of Malaga, Spain Dr Klaus-Werner Gurgle Hamburg University, Germany Alexander Ivanov S&B Joint Stock Company, St Petersburg, Russia Ruslan Laishev Delta Telecom, St Petersburg, Russia Tom Linden Kednos Enterprises, California, USA Jean-Pierre Petit ESME-Sudria, Paris, France Jean-François Piéronne European WASD Advocate :^), Paris, France Geoff Roberts St Mark's College, Pt Pirie, South Australia There may be others but these are the ones who pester me with email. As the BETA test sites are also often the ones requesting additional functionality they should also be thanked for pushing along WASD's capability set. 2017 Confession Time: actually formal BETA testing now, and for some time, is seldom undertaken. The VMS community has shrunk to a point where there is an insufficient pool for a meaningful BETA test cycle. So, I do the best I can, and then release a ..0. The moral - beware any point-point-zero release as effectively it has become the field-test phase of the life-cycle! Brief Introduction to HTTPd Code -------------------------------- This document is designed to be only a broad overview of the basic workings of the HTTP server. It is derived from an original layed-up document, "Nut and Bolts", which was abandoned in favour of something requiring a little less up-keep (therefore increasing it's chances of being up-to-date :^) and that could be kept with the server code itself. This description only covers the server image itself, not the full suite of WASD VMS Web Services software. General Design -------------- (Almost) without apology the server is a large, monolithic, shall we be kind and say old-fashioned, piece of software. Lots of things would be done differently if it was being started over. Other things wouldn't be. The code is always attempting to do things faster or more efficiently (especially because it's VMS) and so it's a bit clunky in places. Other clunkiness is due entirely to the author ;^) Server Behaviour ---------------- The HTTPd executes permanently on the server host, listening for client connection requests on TCP/IP port 80 (by default). It provides concurrent services for a (technically) unlimitted number of clients (constrained only by the server resources). When a client connects the server performs the following tasks: 1. creates a thread for this request (this term does not denote the use of DECthreads or other specific thread library, just a thread of execution) 2. reads and analyzes the HTTP request sent ... o initiates transfer of the requested file, either from the file system or from the file cache o initiates processing of an SSI file o initiates directory listing o initiates processing of a clickable-image mapping file o initiates file/directory create/update o initiates server administration o initiates web file-system update o creates a (detached) process to execute a CGI(plus) script with: - SYS$COMMAND and SYS$OUTPUT assigned to intermediate mailboxes (essentially pipes) - SYS$INPUT logical name providing a mailbox allowing the script to read the raw request body (if any) - CGIPLUSIN logical name providing a mailbox allowing a CGIplus (persistent) script to read CGI variables - (for non-CGIplus) DCL symbols containing CGI-compilant variables - for the life of the script process HTTPd: * controls the essential behaviour via its SYS$COMMAND * receives data written to its SYS$OUTPUT, writing this to the client * supplies the body of a (POSTed) request via SYS$INPUT o creates a (detached) process to execute a WebSocket script with: - SYS$COMMAND assigned to intermediate mailbox (controls process) - SYS$OUTPUT assigned to mailbox until WebSocket established - CGIPLUSIN logical name providing a mailbox allowing the WebSocket (CGIplus, persistent) script to read CGI variables - WEBSOCKET_INPUT logical name providing a mailbox to read client data for the life of the request - WEBSOCKET_OUTPUT logical name providing a mailbox to write data to the client for the life of the request - for the life of the script process: * controls the essential behaviour via its SYS$COMMAND * disconnects the SYS$OUTPUT and CGIPLUSIN mailboxes once WebSocket is established and allows another WebSocket request to be accepted * manages multiple WEBSOCKET_INPUT and WEBSOCKET_OUTPUT mailboxes (i.e. multiple clients) connected to the process o creates a (detached) process to execute a "Raw"Socket script with: - RAWSOCKET_INPUT logical name providing a mailbox to read client data for the life of the request - RAWSOCKET_OUTPUT logical name providing a mailbox to write data to the client for the life of the request - other aspects substantially as per WebSocket scripting o creates a network process to execute a CGI or OSU script * controls the essential behaviour of a CGI script, providing the CGI-compilant variable and receiving CGI-compilant output * provides an emulation of the native OSU scripting environment 3. closes the connection to the client and disposes of the thread For I/O intensive activities like file transfer and directory listing, the AST-driven code provides an efficient, multi- threaded environment for the concurrent serving of multiple clients. Multi-Threaded -------------- The WASD HTTPd is written to exploit VMS operating system characteristics allowing the straight-forward implementation of event-driven, multi-threaded code. Asynchronous System Traps (ASTs), or software interrupts, at the conclusion of an I/O (or other) event allow functions to be activated to post- process the event. The event traps are automatically queued on a FIFO basis, allowing a series of events to be sequentially processed. When not responding to an event the process is quiescent, or otherwise occupied, effectively interleaving I/O and processing, and allowing a sophisticated client multi- threading. Multi-threaded code is inherently more complex than single-threaded code, and there are issues involved in the synchronization of some activities in such an environment. Fortunately VMS handles many of these issues internally. After connection acceptance, all of the processing done within the server is at USER mode AST delivery level, and for all intents and purposes the processing done therein is atomic, implicitly handling its own synchronization issues. The HTTPd is written to make longer duration activities, such as the transfer of a file's contents, event-driven. Other, shorter duration activites, such as accepting a client connection request, are handled synchronously. It is worth noting that with asynchronous, and AST-driven output, the data being written must be guaranteed to exist without modification for the duration of the write (indicated by completion AST delivery). This means data written must be static or in buffers that persist with the thread. Function-local (automatic) storage cannot be used. The server allocates dynamic storage for general (e.g. output buffering) or specific (e.g. response headers) uses. AST Behaviour ------------- With server functions having AST capability, in particular $QIO, the server is designed to rely on the AST routine to report any error, including both those that occur during the IO operation and any that occur when initiating the IO (which would normally prevent it being queued) even if that requires directly setting the IO status block with the offending status and explicitly declaring the AST. This eliminates any ambiguity about under what conditions ASTs are delivered ... ASTs are always delivered. If a call to a server function with AST capability does not supply an AST routine then it must check the return status to determine whether it can continue processing. If it supplies an AST routine address then it must not act on any error status returned, it must allow the AST routine to process according to the IO status block status. Server "Tasks" -------------- Each request can have one or more tasks executed sequentially to fullfil the request. This occurs most obviously with Server-Side Includes (SSI, the HTML pre-processor) but also, to a more limited extent, with directory listing and its read-me file inclusion. A task is more-or-less defined as one of: o transfer file from file-system or cache o directory listing o SSI interpretation o DCL execution or script processing o DECnet script processing o POST/PUT processing o WebDAV processing o WebSocket processing o proxy processing o update facility processing Each one of the associated modules executes relatively independently. Before commencing a task, a next-task pointer can be set to the function required to execute at the conclusion of that task. At that conclusion, the next- task functionality checks for a specified task to start or continue. If it has been specified control is passed to that next-task function via an AST. Some tasks can only be called once per request. Other tasks have the possibility of being called within other tasks or multiple times serially during a request. An example is the transfer file task (non-cache), which can be used within directory listings to insert read-me files, and when " HTTP/2 -~|~-+ | !detect HTTP/2 connection | | | +- NetRead()/SesolaNetRead() --+ | !read request header | | RequestParseHeader() | !request header to dictionary | | : : . . !both /2 and /1.n then ... : : | | RequestFields() | !tease out header field data | | RequestParseAndExecute() | !parse request line | | RequestExecute() | !begin to process request content | | MapUrl_Map() <--+ !apply mapping rules | +- RequestEnd() !if redirect from mapping | | | RequestRedirect() --> !redirect (possibly restart request) | | | RequestEnd() !301/302 response redirect | +- ProxyRequestBegin() !proxy request (HTTP) | : | ProxyRequestEnd() !after proxy processing | | | RequestEnd() !end of request | Authorize() --+ !authorize access to request path | | RequestExecutePostAuth1() !either direct or after AST | +- AdminBegin() !server administration | : | RequestEnd() !once complete | +- HtAdminBegin() !HTA database administration | : | RequestEnd() !once complete | +- other-internal !other internally handled | : | RequestEnd() !once complete | +- Authorize() ------+ !authorize access to script path | | | | RequestEnd() | !not authorized | | RequestExecutePostAuth2() !either direct of after AST | | | RequestEnd() !not authorized | +- ThrottleBegin() --+ !request subject to queuing | | RequestExecutePostThrottle() !none, or post queuing after AST | +- RequestScript() !script to process (incl. WebSocket) | | | +- internal !internally handled look-alikes | | : | | RequestEnd() !once complete | | | +- DclBegin() !sub/detached process CGI script | | : | | RequestEnd() !once complete | | | +- DECnetBegin() !network CGI or OSU script | : | RequestEnd() !once complete | +- FileBegin() !search cache, continue if not found | | | CacheSearch() ---------+ !if not found in cache | | | | CacheBegin() | !cache entry require revalidation? | | | | CacheAcpInfoAst() --+ !if cache entry is stale | | | | CacheNext() | !transfer from cache | : | | RequestEnd() | !once cache transfer complete | | RequestExecutePostCache() <--+ !cannot be supplied from cache | DavWebRequest() !if WebDAV-specific method | : !(some methods, e.g. PUT, can also | DavWebEnd() ! have WebDAV-specific behaviour) | PutBegin() !if a PUT, POST, or DELETE method | : | RequestEnd() !once PUT or POSTed | +- RequestHomePage() <--+ !search for a home page | | | | + ----------------+ !possible multiple names | | | RequestFile() !home page found, transfer | | : | | RequestEnd() !once transfered | | | DirBegin() --> !no home page, directory listing | : | RequestEnd() !once listed | +- RequestEnd() !auto-script | | | RequestRedirect() --> !redirect (possibly restart request) | | | RequestEnd() !301/302 response redirect | +- RequestEnd() !search keyword | | | RequestRedirect() --> !redirect (possibly restart request) | | | RequestEnd() !301/302 response redirect | RequestFile() !transfer file : RequestEnd() !once transfered | RequestRedirect() --> !redirect (possibly restart request) | RequestEnd() !301/302 response redirect HTTPd Modules ------------- The HTTPd server comprises several main modules, implementing the obvious functionality of the server, and other, smaller, support modules. Modules contain descriptive prologues. As these are usually up-to-date (usually more-so than discrete documentation such as this text anyway), it is strongly recommended that the source code modules be consulted for specific information on how each operates. This section is provided only to give a quick overview. All files are located in WASD_ROOT:[SRC.HTTPD] WASD.H This C header file contains many of the general data structures and macros required for the HTTPd. ENAMEL.H This header is used to work-around the issue of older versions of VMS and DECC not having a long NAM structure or definitions used to support ODS-5. For the same reason an extended FIB structure definition must be provided. For such environments this header file provides the necessary infrastructure, allowing extended file specification compliant code to be compiled and linked on pre-v7.2 systems. ADMIN.C Server administration is based in this module, although other modules provide their own functions for implementing menus, reports and actions. AUTH.C This module provides path-based authorization and authentica- tion. Uses the HTTPD$AUTH file as the source of configuration information. This module uses the other AUTHxxxxxx.C modules to provide particular required functionalities. AUTHACME.C Allows authentication and SYSUAF password changes using the ACME server via the $ACM system service. Provides both SYSUAF authentication and from other sources using other and third-party ACME agents. AUTHAGENT.C Provide authentication and authorization information from an external, CGIplus-based script. AUTHCACHE.C Provides the caching of authentication/authorization information so that the sources do not need to be accessed for every request. AUTHCONFIG.C Loads authorization configuration information from the HTTPD$CONFIG file into a data structure that the HTTPd then uses during authorization. AUTHHTA.C Accesses information stored in binary authentication databases (files). AUTHHTL.C Accesses information stored in plain-text authentication files. AUTHIDENT.C Provide authentication and authorization from an RFC1413 source ("ident" protocol). AUTHTOKEN.C Accesses authentication/authorization in one context and reflects that authorization to another using a short-lived token delivered as a cookie. AUTHVMS.C Accesses authentication and authorization information from the system's SYSUAF and RIGHTSLIST databases. BASE64.C Base-64 encoding/decoding (well, golllee!) BASIC.C Implmentation of the "BASIC" HTTP authentication scheme are implemented in this module. BODY.C Controls the transfer of the request body (for POST and PUT methods) from the client to the server and then on to a script, proxied server or internal HTTP module for processing. A script or a proxied HTTP server receives the "raw" data provided by the client. Internal modules or a proxied FTP server get data that has been processed by one of three functions that "filter" the data from a request body. The first just puts the entire body into a single buffer and is used internally. The others extract data from "application/x-www-form-urlencoded" or "multipart/form-data" content-types. CACHE.C This module implements a file data and revision time cache, designed to provided an efficient static document request (file transfer) mechanism. CGI.C The CGI module provides the CGI scripting support functions used by the DCL.C and DECNET.C modules. CLI.C Module to process (interpret) the HTTPD command-line. CONTROL.C This module implements the HTTPd command-line control functionality. At the command-line an administrator may enter HTTP/DO=command[/ALL]. This is written to the HTTPd via shared memory in a global sector, interpreted and the requested action taken or an error message sent back to the administrator. The Distributed Lock Manager (DLM) is used to alert a detached server process that a command is available for actions, and to distribute a command to all server cluster-wide when using the /ALL qualifier. CONFIG.C This module provides basic server and service configuration. Uses the HTTPD$CONFIG file as the source of configuration information. DICT.C A hash dictionary (associative array) of key-value pairs. In particular, used to store request and response header fields while interfacing between client and server. The implementation is a standard hash array with collision linked-list. An associated list allows iteration in order of insertion. DAVCOPY.C WebDAV copy a file or directory tree. DAVDELETE.C WebDAV delete a file or directory tree. DAVLOCK.C Manage a WebDAV lock on a resource (file or tree). Although WASD WebDAV uses VMS locks and the DLM for managing access within its processing this module deals exclusively with WebDAV locking. WASD WebDAV locks are stores in meta-data files managed by DAVMETA.C. DAVMETA.C WebDAV meta-data uses XML for its representation. WASD WebDAV meta-data is stored in a separate file along with the file it is the meta-data of (or directory file if a directory). This module manages the WASD-specific data stored in that (WebDAV locks) and independent client-supplied entities. DAVMOVE.C WebDAV move a file or directory tree. For efficiency renames the file or directory file if on the same volume, or if on another volume copies and deletes (much more expensive). DAVPROP.C Generates WebDAV "live" properties for files and directories. These are XML representations of such data as creation and modification timer, size, etc. DAVWEB.C This is the primary WebDAV processing module. All WebDAV-specific processing begins and ends with this. It also pr4ovides some common WebDAV processing functionality and the WebDAV report code. The prologue contains significant WASD Web-DAV comments. DCL.C The DCL execution functionality must interface and coordinate with an external subprocess. Supports CGI and CGIplus scripting and SSI DCL-processed directives. DCLMEMBUF.C Bulk data transfer from script to server using a (global section) memory buffer. Intended for transfers of multiple megabytes. DECNET.C The DECnet module provides scripting based on process management using DECnet. Both standard WASD CGI scripting and an emulation of OSU (DECthreads) scripting are supported. DESCR.C The Descr.c module generates a file description by searching HTML files for the first occurance of ... or ... tags, using the description provided there-in. It is primarily used by the directory listing module, but can also be used by the menu module. DIGEST.C This module provides authentication functionality for the DIGEST method. I do not know of any browser or user group that employs the mechanism. DIR.C This module implements the HTTPd directory listing (Index-of) functionality. ERROR.C Error generating and reporting functions. FAO.C Provides formatted write capability to storage and network buffer space. Functionality based on the VMS system service $FAO but contains all sorts of extensions to facilitate WASD objectives. It's versatility makes it an indispensable code module. FILE.C This module implements the static file transfer functionality. GRAPH.C This module generates the server activity graph. GZIP.C Provides ZLIB-enabled GZIP compression (gzip, deflate) for WASD. Dynamically maps required functions from a ZLIB shareable image. If the image is found and all required functions present the ZLIB compression/decompression of network streams in enabled for suitable requests/responses. If not it is just left disabled. Based on ZLIB port by Jean-François Piéronne. Requires this package to be installed and started on the runtime system for dynamic activation. HPACK.C HPACK is a compressor that reduces bandwidth requirements for HTTP/2 (RFC7540) request and response header fields. Defined by RFC7541. HTADMIN.C This module allows on-line administration of the HTTPd- specific authentication (.HTA) databases. HTTP2.C Initialises HTTP/2 functionality for the server. Handles some core HTTP/2 connection behaviours such as instantiation (initial connection), stream reset, go-away, ping, connection settings. HTTP2NET.C HTTP/2 network reads and writes. Reads are multiplexed onto the connection by the client and similarly multiplexed off at the server end. The frames read are then handed off to the appropriate processing function by frame type. Writes are serialised onto the connection using FIFO queuing. HTTP2REQUEST.C Conjure up a request structure, populate the dictionary with its request headers, supply it with a request body if required, execute the request, populate the (HTTP/2) response header with response header fields and then run-down the request. There are obviously life-cycle parallels to HTTP/1.1 processing. HTTP2WATCH.C Provide WATCHing of HTTP/2 processing. HTTPD.C This is the main() module of the server. It performs server startup and shutdown, along with other miscellaneous functionality. INSTANCE.C Contains functions used to setup, maintain and coordinate action between, multiple servers running on a single system, alone or in combination with multiple servers running across a cluster. An "instance" in this context refers to the (almost) completely autonomous server process. LOGGING.C The logging module provides an access log (server logs, including error messages are generated by the detached HTTPd process. The access log format can be that of the Web-standard, "common"-format, "common+server"-format or "combined"-format, along with user-definable formats, allowing processing by most log-analysis tools. MAPCON.C Used by the MAPURL.C module to process (the somewhat obsolesecent) mapping rule conditionals. MAPODS.C Used by the MAPURL.C module to support mapping of URL-style specifications to VMS file system specifications and back. Can process ODS-2, ODS-5 (EFS), SRI (MultiNet NFS), PATHWORKS (v4/5) and Advanced Server (PATHWORKS V6) / Samba encodings. MAPURL.C Main module supporting mapping of URLs to VMS file specifications and VMS specifications to URLs, setting specified characteristics agaionst paths, etc. Uses the HTTPD$MAP file as the source of configuration information. MAPUSER.C Used by the MAPURL.C module to support mapping /~ style requests (user home directory) using SYSUAF account data to map the username's home file specification. MD5.C Module providing MD5 digest code from RFC1321. This is used to generated "digests" (or unique fingerprints of sequences of bytes and strings) for use in authorization and the generation of file names in proxy caching. MSG.C The message database for the server is maintained by this module. Uses the HTTPD$MSG file as the source of configuration information. NET.C This module handles all non-SSL TCP/IP network activites, from creating the server socket and listening on the port, to reading and writing network I/O. It manages request initiation and rundown, and controls connection persistence. It is developed using, and based upon the behaviour of, both the Digital TCP/IP Services (UCX) BG driver. Any other package that supports this through emulation will support WASD. NETIO.C This module specialises in the low-level network data handling. ODS.C This module supports file system access for both ODS-2 and where appropriate (Alpha VMS v7.2ff) ODS-5. It does this by abstracting the NAM block so that either the standard or long formats may be used without other modules needing to be aware of the underlying structure. The VAX version does not need to know about long NAMs, or extended file specifications in general (excluded for code compactness and minor efficiency reasons using the ODS_EXTENDED macro). Alpha versions prior to 7.2 do not know about NAMLs and so for compilation in these environments a compatible NAML is provided (ENAMEL.H header file, see ENAMEL.H), allowing extended file specification compliant code to be compiled and linked on pre-v7.2 systems. Runtime decision structures based on the VMS version, device ACP type, etc., must be used if pre-v7.2 systems are to avoid using the NAML structure with RMS (which would of course result in runtime errors). In this way a single set of base- level Alpha object modules, built in either environment, will support both pre and post 7.2 environments. PERSONA.C For VMS V6.2 and later provides access to the $PERSONA services allowing the server to create scripting processes executing under user accounts other than itself (see DCL.C). For VMS versions not supporting the $PERSONA services (earlier than V6.2) it creates stubs allowing the module to be linked but just returning a status indicating it is not available. PROXY.C All data structures and general macros, etc., for proxy processing are located in the following header file. Provides the request and network functionality for proxy HTTP and HTTPS serving. PROXYCACHE.C Obsolete as of v12.0.0. PROXYFTP.C Provides FTP proxying for both GET (RETR) and POST/PUT (STOR) methods. Interprets directory listings (LIST) for DOS, Unix and VMS FTP servers (makes a feeble attempt for those it doesn't recognise). PROXYMAINT.C Since PROXYCACHE.C obsoleted above, a shadow of its former glory, performing a few reporting functions. PROXYNET.C This module provides the essential networking functionality for proxy processing. It also maintains the pool of persistent proxy->origin server connections. PROXYREWORK.C The proxy rework facility will modify a target string to a replacement string in the request header (e.g. Host:), the response header (e.g. set-cookie:), and in the response body. Rework will be applied to HTML and CSS responses. Probably needs a lot more (re)work(ing). PROXYSOCKS.C RFC 1928 SOCKS Version 5 proxy for TCP/IP. Supports only CONNECT TCP/IP and not BIND or UDP-associate. PROXYTUNNEL.C WASD supports the CONNECT method which effectively allows tunnelling of RAW octets through the proxy server. This facility is most commonly used to allow secure SSL connections to be established with hosts on the 'other side' of the proxy server. This basic mechanism is also used by WASD to provide an extended range of tunnelling services. PROXYVERIFY.C Implements a relatively simple, pragmatic mechanism that allows a proxy server to authorize a request locally, then convey that authorized username to a reverse-proxied server using a standard HTTP "Authorization: basic ..." request field, while keeping the original password private. It then provides an HTTP-based mechanism for the proxied-to server to verify that the request is indeed originating from the proxy server. PUT.C The PUT module allows files to be uploaded to, and stored by, the server. It also allows the deletion of files, and the creation and deletion of directories. This same module handles PUT, POST and DELETE methods appropriately. It requires authorization to be enabled on the server. REDIRECT.C Handle internal (an important and fundamental aspect of some WASD request processing) and external redirection. REGEX.C The GNU RX regular expression package REGEX.C and REGEX.H files, unmodified except for a small WASD macro introduced at the beginning of the former. REQUEST.C This module reads the request header from the client, parses this, and then calls the appropriate task function to execute the request (i.e. send a file, SSI an HTML file, generate a directory listing, execute a script, etc.) RESPONSE.C This module provides support for generating appropriate HTTP responses and response-related processing. It also deals specifically with National Character Set (NCS) configuration and conversions. SESOLA.C The SESOLA.. modules provide support for SEcure SOcket LAyer processing. This module provides the optional Transport Layer Security (TLS) (aka. Secure Sockets Layer (SSL)) encrypted communication link functionality for WASD and is named "SeSoLa" to avoid any confusion and/or conflict with OpenSSL package library routines. These modules are conditionally compiled into two sets of object modules, one for non-SSL servers, the other for those built against the optional OpenSSL toolkit. Also see the more general comments on TLS/SSL above. SESOLACACHE.C Implements the instance-shared SSL session cache. This allows multiple per-node instances to share session contexts. SESOLACGI.C Generates the SSL-specific CGI variables. Supports Purveyor and Apache environment sets of variables. SESOLACERT.C Parse X509 certificates, issuer and subject, plus extensions. SESOLACLIENT.C Handles processing specifically for the negotiation for and verification of peer (client) certificates. It also provide support for X.509 certificate authentication and authorization. SESOLAMKCERT.C For a TLS/SSL service that does not use the default or have a unique X509 server certificate, this module will dynamically create one during startup. The generation of a private key for the certificate can add significant time to overall server startup. SESOLANET.C This module provides the TLS/SSL network processing. It has functions supporting the encryption of plain data streams and the subsequent transmission to the remote SSL service, as well as the decryption back to original data of recei8ved SSL streams. It also supports the session acceptance (for SSL requests) and session establishment (connections, for SSL gatewaying). SESOLANETIO.C This module specialises in the low-level TLS/SSL network data handling. SHA1.C Provides SHA-1 digest hashing used during the WebSocket request handshake. SSI.C The Server Side Includes (HTML pre-processor) module provides this functionality as an integrated part of the server. STMLF.C The stmLF.c module converts VARIABLE format records to STREAM- LF. It is only called from the File.c module and only then when STREAM-LF conversion is enabled within the server configuration. STRDSC.C Particularly with the introduction of WebDAV and the associated XML processing required some more versatile method of string handling was required. This module uses a data structure allowing 32 bit sized strings (i.e. > 65365), linked-lists of buffers of these, and automatically uses dynamic memory associated with requests or server as appropriate. FAO.C and NET.C can use these structures. Data contained in them does not necessarily have to be ASCII/null-terminated of course. STRNG.C This code module contains functions related to string processing. In particular string wildcard and regular expression matching (see above). SUPPORT.C The support module provides a number of miscellaneous support functions for the HTTPd (well go-o-o-lee!). SYSPLUS.C Show essential system data without using a scripting process as does WatchShowSystem(). TCPIP.C With the introduction of IPv6 support some generic IP and TCP/IP functionality was move or placed into this module. It's header contains some structure definitions and macros used extensively in the support of QIO-based network I/O in WASD. The code module contains several support functions that tmake IPv4 and IPv6 supportable without recompilation. TCPIP6.C IPv6 address resolution functions only available with VMS V7.0 and later. IPv6 name/address resolution is a little problematic for WASD because there is (currently) no native asynchronous interface to it in the same way as there is with $QIO ACPCONTROL for IPv4. Fortunately IPv6 is somewhat of a niche environment! TCPIPALT.C Currently experimental. Alternate TCP/IP functions, lookup by name and by address. Both inline (synchronous) and by agent (DCL script, asynchronous). The agent can take on the role of a network agent and drop connections. This means that if using a lookup agent there is no need also to use a network agent. A drop connection is cached. THROTTLE.C Provides request throttling functions. This controls the number of concurrent processing requests against a specified path. Requests in excess of specified limits are FIFO queued. UPD.C Implements the on-line web directory administration and file editing and upload facility. It requires authorization to be enabled on the server. File and directory modification are still performed by the Put.c module. The Upd.c is an overly large body of code generating all of the dialogues and editing pages. It also provides additional functionality for the server administration, adding admin-specific portions of dialogues as required. VERSION.C The VERSION module merely provides a small, convenient place to generate some build information. VM.C The virtual memory management module provides dynamic memory allocation and deallocation functions. These functions use the VMS system library virtual memory routines. Also see general comments in section "Memory Management". WATCH.C The WATCH facility provides an online, real-time, in-browser-window view of request processing in the running server. It support functionality to allow a site administrator to intergate the processing server for resolving configuration and other run-time issues (the WATCH_CAT, or category functionality). It also contains extensive in-detail request processing functionality intended for server development and BETA debugging purposes (the WATCH_MOD, or module funtionality). WEBSOCK.C Essentially this module handles the setup and tear-down of mailbox "pipes" to persistent (CGIplus) processes managed by the DCL.C module. Each of these processes can handle multiple such WebSocket clients. Once established the mailbox "pipes" just transfer the raw network data to and from the client and scripting process. The WebSocket protocol must be implemented by the script (commonly using a library). Also provides WASD "Raw"Socket scripting using the WebSocket infrastructure and module but with no imposed protocol. +-----+ + END + +-----+