Obsolete Draft - February 15, 1998
Authors |
||
| Ian Kluft Cisco Systems San Jose, California, USA |
Ed Korthof Organic Online San Francisco, California, USA |
Stefano Mazzocchi Beta Version Productions Pavia, Italy |
This is a pre-implementation draft of the AJPv2 protocol specification, a subject under current discussion within the Java Apache Project. This is a work in progress subject to revision.
This specification is undergoing implementation experiments but performance tests will guide further changes to the specs. The implementations at the time will need to adjust to those changes.
This document describes an experimental design for a request protocol intended for but not restricted to use with the Apache JServ, which runs Java Servlets as defined by JavaSoft's Java Development Kit.
The original protocol that was built into Apache HTTPD's mod_jserv was purposely kept simple for the first implementations of the module. Usage and continuing development have led to experience indicating needs for significant new features.
The Apache JServ Protocol Version 2 (AJPv2) provides new features such as keepalive-like performance improvements and the ability for the Servlet Engine to make intermediate requests back to the HTTP for more information about its environment. The protocol is kept sufficiently generalized that the back-end process does not necessarily have to run Java. (The original JServ protocol had only modest dependencies on connecting to a Java back-end, though the mod_jserv module has strong dependencies on Java.) Although both the client and server must have prior agreement about which language is in use.
The Apache JServ Protocol Version 2 (AJPv2) is designed as a replacement for the original experimental protocol used by Apache HTTPD's mod_jserv module, which is used to communicate with a separate Java servlet engine. With experience using the original JServ protocol, the Java Apache Project is ready to develop a second-generation servlet engine protocol.
The original protocol, written by Alexei Kosut at Organic Online in July 1997, was deliberately kept simple according to the needs of the project at the time.
The protocol included a "startup" phase where the Apache HTTPD would start the Java Servlet Engine process and give it an initial setting for the authentication that will be used thereafter by all servlet requests. There was also a standalone "manual" mode for the servlet engine, where no authentication would be required. This is potentially dangerous if used without providing other protection against intruders.
Then for each request, the HTTPD process would connect to the Servlet Engine via a socket, and then send a series of ASCII text lines with request headers. The Servlet Engine would then respond with the entire response when it was done.
Usage of the JServ protocol has brought about more experience in this problem domain and the following needs:
One option for the multiple-requests-per-session (MRPS) goal was the W3C's MUX protocol. However, since the Apache HTTPD needs to keep open for some platforms which run single-threaded (and will continue well into the future on the more obscure ones), MUX was determined to have excessive overhead for this purpose because the support for arbitrary protocols introduces generalization not necessary in this environment.
The lifetime of an AJPv2 connection begins when the socket is established and may last for one or more sessions that each represent an HTTP request forwarded from the HTTP server to the Servlet Engine. For purposes of this specification, the HTTP server is the client in this exchange because it initiates the request and waits for results. Conversely, the Servlet Engine performs the server role in this context. The terms "client" and "server" will be used in this way.
Each session begins with the request environment, including information analogous to what is found in a CGI request's environment. During the course of processing the request, either the server or client may send some "function requests" to each other. These will be met with "function responses".
As the server completes parts of the primary request's result, it will send them as response packets. When the server completes its processing, it signals the end of the processing by closing the session.
At any point when there are no open sessions, it is the option of both the client and the server to close the connection for resource management, because file descriptors are assumed to be a finite resource on both sides.
| Note that this is unrelated to the use of "sessions" in the Java Development Kit's (JDK) 1.2 servlet classes, which track application-layer inter-request information that are outside the scope of this protocol. It is possible (and unfortunate) for terminology collisions such as this to occur at different layers of a protocol suite. But realizing they are at different layers allows them to be clearly differentiated. |
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
All data sent on the full duplex connection between the client and server MUST follow this structure:
The AJPv2 packet header can be represented by this diagram.
| Octet | 0 | 1 | 2 - 3 | 4 - 7 | 8 - <n+7> | |
|---|---|---|---|---|---|---|
| Contents | bits 0-4: Type | bits 5-7: Subtype | Flags | Session | Data Length | Data |
Session ID numbers MUST be unique within a connection. On connection-oriented packets, a Session ID MUST be ignored by the receiver and set to 0 by the originator. Session ID 0 is reserved for filler on connection-oriented packets and MUST NOT be used for an actual session.
Implementation note: When a server handles multiple connections at a time, it is only necessary to make ID's unique within each connection, not across all connections.
Packet types MUST have a corresponding subtype. Valid values are shown in the following table:
| Type # | Type Description | Context | Originator | Subtype # | Subtype Description |
|---|---|---|---|---|---|
| 0 | Challenge | Connection | Server | 0 | Server-initiated authentication challenge |
| 1 | Initialization | Connection | Client | 0 | Client authentication, response to challenge |
| 1 | Configuration commands in servlet native language | ||||
| 2 | Function Call | Session | Either | 0 | Function Request |
| 1 | Function Response | ||||
| 2 | "No-op" (process flags only) | ||||
| 3 | Request | Session | Client | 0 | Request Start |
| 1 | Request Entity | ||||
| 4 | Response | Session | Server | 0 | Response Header(s) (newline-delimited) |
| 1 | Response Entity | ||||
| 2 | Request log entries (newline-delimited) | ||||
| 3 | Warning (newline-delimited) | ||||
| 4 | Fatal error (newline-delimited) | ||||
| 5 | Asynchronous Event | Connection | Client | 0 | Restart (SIGHUP) |
| 1 | Shutdown (SIGTERM) | ||||
| 6 | Protocol Control | Connection | Either | 0 | Protocol Error |
Implementation note: Each Packet type has uniform settings across all subtypes for direction of travel and session/connection context. These may be determined using the type only, without regard to the subtype. Some further type divisions were made by groupings of related functions so that the type has additional semantic value than just these three attributes.
The tables fields are as follows.
The "Type #" contains the the numbers to be used in the packet type field of the AJPv2 header.
The "Type Description" contains a one-word description which will be used as a name for that type of packet in following sections.
The "Originator" field states whether combination of packet type and subtype may originate with the client, server or either one. A packet with that type and subtype combination MUST originate on the side(s) allows in the table.
The "Subtype #" contains the the numbers to be used in the packet subtype field of the AJPv2 header.
The "Subtype Description" contains a description of the meaning of a packet with that specific combination of type and subtype.
Any packet with packet type, subtype and origination not as shown in the table above constitutes a fatal protocol error.
A challenge packet contains a random-length array of random-value octets. This is the first packet sent by the server upon establishment of each connection. The length MUST be between 5 and 63 octets, inclusive. A new random challenge must be chosen for each connection. This challenge value MUST be saved by the server and associated with this connection for use in verifying the authentication of the client. See the section on the authentication algorithm for more details.
A Subtype 0 authentication packet is used as a response to the server's challenge. See the section on the authentication algorithm for more details.
A Subtype 1 initialization packet is used in cases when the client starts the server. It contains commands in the native language of the Servlet Engine. For the initial Apache JServ implementation, the language is Java. But any specific language is NOT REQUIRED for future uses of the protocol, and may be viewed as a higher-level protocol.
The Subtype 0 Function Request packet contains a request to be processed by the receiver, containing a request that will generate a Function Response packet. The AJPv2 protocol does not impose restrictions on the contents of these packets, which may be viewed as a higher-level protocol. Per-language function-call definitions will be maintained separately from this protocol and may be revised at different rates, but must be registered with the Java Apache Project and listed on the java.apache.org web site.
A Subtype 1 Function Response packet contains a response to a previous Function Request. The AJPv2 protocol does not impose restrictions on the contents of these packets, which may be viewed as a higher-level protocol. Per-language definitions will be maintained separately from this protocol and may be revised at different rates, but must be registered with the Java Apache Project and listed on the java.apache.org web site.
A Subtype 2 No-op packet has no activity associated with it specifically. It is reserved for any circumstances when the actions in the flag bits of the packet header are needed without actions of other packet types.
A Subtype 0 Request Start packet contains HTTP-style newline-delimited headers followed by a blank line and the beginning of the request entity. The headers in this request MUST included the same variables that are provided in the environment by the Common Gateway Interface. Receipt of this packet subtype MUST create a new session, and MUST NOT be sent more than once per session. Request Entity packets may follow to send additional portions of the request data.
A Subtype 1 request entity is a binary object. The type of the data will be provided in the environment variables if it is available. The handling of the type or any type errors is the responsibility of the servlet.
A Subtype 0 response packet contains one or more HTTP response headers. There MAY be more than one response header per packet, delimited by newlines. And there MAY be more than one response header packet sent from the server to the client within a session.
A Subtype 1 responses entity is a binary object. The type of the entity should have been provided in the response headers but is the responsibility of the servlet that generated it.
A Subtype 2 request log entry packet contains one or more log entry lines from the server to the client. This is intended as routine per-request logging. Warnings and errors should use the packets listed below specifically for those purposes. There MAY be more than one log entry per packet, delimited by newlines. And there MAY be more than one response header packet sent from the server to the client within a session.
A Subtype 3 warning packet contains a text message describing the warning condition. This intended for logging on the client. There MAY be more than one warning per packet, delimited by newlines.
A Subtype 4 fatal error packet contains a text message describing why a request failed. This intended for logging on the client and may be used to describe the error on any error messages forwarded to the user by the client. There MAY be more than one error line per packet, delimited by newlines.
A Subtype 0 restart signal packet indicates a Servlet Engine restart MUST take place if the session is properly authenticated. Any data placed in an asynchronous event packet is OPTIONAL but MAY be used for debugging purposes.
A Subtype 1 shutdown signal packet indicates the Servlet Engine MUST shut down if the session is properly authenticated. Any data placed in an asynchronous event packet is OPTIONAL but MAY be used for debugging purposes.
A Subtype 0 protocol error packet indicates a fatal failure due to a protocol error, indicating that the originating process is closing the connection. Any data placed in a protocol error packet is OPTIONAL but MAY be used for debugging purposes.
AJPv2 allows for multiple sessions within a connection so there is separate state information and state-transition rules for the connection and for each session. If authentication is configured to be enabled, the client side of the connection begins in the "Unauthenticated" state. Otherwise the initial state is "Open".
Due to the presence of flag bits, packets may contain more than one event applicable to the state tables. In such cases, the first event processed is based on the packet type and subtype. Then the flag bits are processed. A Close Connection flag supersedes and pre-empts the Session End Data and Session Close flags. A Session Close supersedes and pre-empts the Session End Data flag. Session Close and Session End Data flags MUST NOT be set on connection-oriented packets.
| Client Per-Connection State Transitions | |||
|---|---|---|---|
| State | Event | Action | New State |
| Unauthenticated | receive Challenge | Generate response (see authentication algorithm) | Open |
| receive Protocol Error | close connection | N/A | |
| receive other | return Protocol Error, close connection | N/A | |
| Open | receive any server-to-client per-session packet | pass to session handler | Open |
| flag set - Close Connection | terminate all sessions and connection | Open | |
| receive Protocol Error | close connection, terminate all sessions | N/A | |
| receive other | return Protocol Error, close connection | N/A | |
The client side of is where each session begins. The client creates a new session with a Request Start packet that contains an ID for a session which is not currently open. The new session is placed in the "Open-Data" state
| Client Per-Session State Transitions | |||
|---|---|---|---|
| State | Event | Action | New State |
| New | send Request Start to server | create session record | Open-Data |
| Open-Data | receive Function Request | parse message, dispatch requested function, send result to server | Open-Data |
| receive Response Header | pass header to upper layer | Open-Data | |
| receive Response Entity | pass entity to upper layer | Open-Data | |
| receive Log entry | pass log entry to upper layer | Open-Data | |
| flag set - Session Data End | complete response processing | Control-Only | |
| flag set - Session Close | close session | N/A | |
| receive Warning | pass warning (log w/ appropriate severity) to upper layer | Open-Data | |
| receive Error | pass error (log w/ appropriate severity) to upper layer | Open-Data | |
| receive other | return Protocol Error, close connection | N/A | |
| client initiated close session | send No-op with Close Session flag, close session | N/A | |
| Control-Only | receive Function Request | parse message, dispatch requested function, send result to server | Control-Only |
| receive Log entry | pass log entry to upper layer | Control-Only | |
| receive Session Close | close session | N/A | |
| receive Warning | pass warning (log w/ appropriate severity) to upper layer | Control-Only | |
| receive Error | pass error (log w/ appropriate severity) to upper layer | Control-Only | |
| receive other | return Protocol Error, close connection | N/A | |
| client initiated close session | send No-op with Close Session flag, close session | N/A | |
AJPv2 allows for multiple sessions within a connection so there is separate state information and state-transition rules for the connection and for each session. If authentication is configured to be enabled, the server begins by generating and sending a Challenge packet, then entering the "Unauthenticated" state. Otherwise, the initial state is "Open".
Due to the presence of flag bits, packets may contain more than one event applicable to the state tables. In such cases, the first event processed is based on the packet type and subtype. Then the flag bits are processed. A Close Connection flag supersedes and pre-empts the Session End Data and Session Close flags. A Session Close supersedes and pre-empts the Session End Data flag. Session Close and Session End Data flags MUST NOT be set on connection-oriented packets.
| Server Per-Connection State Transitions | |||
|---|---|---|---|
| State | Event | Action | New State |
| Unauthenticated | receive Authentication | if verification fails, close connection | N/A |
| if verification succeeds, continue | Open | ||
| receive Protocol Error | close connection | N/A | |
| receive other | return Protocol Error, close connection | N/A | |
| Open | receive any client-to-server per-session packet | pass to session handler | Open |
| receive Initialization | process initialization commands | Open | |
| receive Restart | if allowed by remote, run restart (closes connection) | N/A | |
| if not allowed by remote, ignore | Open | ||
| receive Shutdown | if allowed by remote, shut down (closes connection) | N/A | |
| if not allowed by remote, ignore | Open | ||
| receive Close Connection | close connection, terminate all sessions | N/A | |
| receive Protocol Error | close connection, terminate all sessions | N/A | |
| receive other | return Protocol Error, close connection | N/A | |
The server creates a new session when a Request Start packet is received that contains an ID for a session which is not currently open. The new session starts in the "New" state
| Server Per-Session State Transitions | |||
|---|---|---|---|
| State | Event | Action | New State |
| New | receive Request Start | open new session | Open-Data |
| receive other | send Protocol Error, close connection | N/A | |
| Open-Data | receive Function Response | pass on to upper layer | Open-Data |
| receive Request Start | process request headers and save entity fragment in servlet connection info, or pass to upper layer if accepted in fragments | Open-Data | |
| receive Request Entity | save entity fragment in servlet connection info, or pass to upper layer if accepted in fragments | Open-Data | |
| flag set - Session Data End | close request stream to servlet, leave it open for response | Control-Only | |
| flag set - Session Close | close session, cancel request to servlet | N/A | |
| receive other | send Protocol Error, close connection | N/A | |
| Control-Only | receive Function Response | pass on to upper layer | Control-Only |
| receive Session Close | close session, cancel request to servlet | N/A | |
| receive other | send Protocol Error, close connection | N/A | |
The "secret integer" authentication algorithm of the original Apache JServ protocol has not been carried forward to AJPv2.
The AJPv2 authentication algorithm was inspired by the MD5 Digest Authentication algorithm for HTTP. (MD5 is defined in RFC1321.) However, unlike HTTP, this algorithm depends on all clients and the server having access to a secret file or string with identical contents, and system clocks that can be kept in sync within a configurable number of seconds. This is based on the assumption that the administration of the AJPv2 client and server systems are either the same or in cooperation with each other.
This algorithm uses MD5 hashing but no strong cryptography, and is therefore exportable under cryptography restrictions for the United States, France and Russia in effect as of January, 1998. It is able to verify that both sides posses secret text (analogous to a password) without passing any of it in the clear over the network.
The shared secret is an arbitrary-length string (which does not necessarily need to be ASCII text - it could be an image file.) The only limitation on the shared secret is that the longer the string, the more processing will be necessary to compute an MD5 hash with it. Note: this algorithm is as vulnerable as the secret file or string contents - they SHOULD be adequately protected from unauthorized users by any security measures available.
It also has limited vulnerability to packet-sniffing attacks. Secret files or strings are not sent in the clear. The use of the challenge-response and time-checking means that sniffed hashes only respond to specific challenges and expire within seconds. Sniffed authentication strings cannot be re-used after they expire.
There is a small chance (estimated at less than 1 in 1,000,000,000,000 for each connection, with even smaller chances for longer challenge strings, with good pseudorandom number generation) that any given challenge could be used again for another connection. If this were to occur in less than the expiration time, a sniffed packet could be used to answer the authentication.
The authentication algorithm depends on good pseudorandom number generation and random number keys. Pseudorandom numbers, by definition, are not completely random and may fail in some ways to be able to cover all possible bit patterns, or may not cover them in completely unpredictable sequences. As one important example, the time in seconds MUST NOT be used alone for random number keys because, even though it contains 32 bits on Unix and other systems, it does not have 32 bits of variability each time it is used. So any knowledge of the time frame a seed was chosen allows a relatively small window of numbers from which to base an attack. Additional sources of randomness for seeds can be obtained from the process ID, parent process ID process group ID, microseconds since boot, contents of rapidly-changing buffers, and others. The more bits of variability (unpredictability) in the seed, the better.
Since some common random number libraries only use 15 bits of precision on random numbers returned with each pseudorandom number request, an authentication challenge string SHOULD be generated by separate calls to the pseudorandom number generator for each byte, using some transformation or truncation to take it down to 8 bits each time. The only exceptions would be when the implementor knows there are enough bits in use to cover all possible combinations within a 16- or 32-bit quantity.
Many more recommendations and ideas in this area can be found in RFC 1750, "Randomness Recommendations for Security".
The following protocol parameters are configurable on the client side.
The following protocol parameters are configurable on the server side.
The following are some additional notes for implementors:
This specification was developed through discussion and consensus on the Java Apache Project's mail list. The original idea for this model was evolved from ideas proposed by Ed Korthof, who continued to provide input throughout its development. The authentication algorithm and numerous modifications were provided by Ian Kluft. Stefano Mazzocchi also provided technical review and suggestions for nearly all parts of the spec.
Copyright (c) 1997-98 The
Java Apache Project.
$Id: AJPv2.html,v 1.3 1999/06/09 05:21:29 jonbolt Exp $
All rights reserved.