The Java Apache Project

Apache JServ Protocol Version 2 (AJPv2)

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

Status of this Document

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.


Abstract

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.


Table of Contents


Introduction

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 JServ 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.

Improving Upon the Original JServ Protocol

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.

Overview of Apache JServ Protocol Version 2 (AJPv2)

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.

Glossary

Client
The HTTP server process becomes the "client" in the context of the AJPv2 protocol because it initiates the request and waits for the response.
Connection
A finite-duration link between the AJPv2 client and server, upon which all AJPv2 transmissions occur. This can theoretically be over any reliable ordered-stream transport but is expected to usually be delivered over a TCP-based socket.
Error
A fatal condition forcing termination of the request. Errors reported to the client SHOULD be logged by the client.
Octet
An 8-bit quantity, or byte.
Server
The Servlet Engine performs the server function in the context of the AJPv2 protocol.
Session
AJPv2 borrows the term "session" from the W3C MUX protocol and its predecessor, Simon Spero's Session Control Protocol (SCP) proposal. In this context, it refers to a multiplexed channel within the larger connection that contains this protocol. There may be multiple sessions on a single connection.
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.
Warning
An abnormal but non-fatal condition which allows processing of the request to continue. Warnings reported to the client SHOULD be logged by the client.

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.


The AJPv2 Header

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.

The AJPv2 Packet Types and Subtypes

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.

Challenge Packets

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.

Initialization Packets

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.

Function Call Packets

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.

Request Packets

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.

Response Packets

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.

Asynchronous Event Packets

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.

Protocol Control Packets

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.


Client-side State Transitions

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

Server-side State Transitions

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

Authentication Algorithm

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.

Impacts of Pseudorandom Number Generation on Security

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".


Client-Side Protocol Configuration Parameters

The following protocol parameters are configurable on the client side.

authentication
This setting determines whether authentication is in use on the server. The default value MUST be to enable authentication. Implementors SHOULD warn administrators to ensure the client's authentication configuration matches the server's.
secret file or string
This must be configured to the same contents as used on the server which will interoperate with the client.

Server-Side Protocol Configuration Parameters

The following protocol parameters are configurable on the server side.

authentication
This setting determines whether authentication is in use on the server. The default value MUST be to enable authentication. Administrators who choose to disable authentication SHOULD be warned by the implementor to provide their own security (such as a firewall or router with filtering) to protect the server from intruders.
secret file or string
This must be configured to the same contents as used on all clients which will interoperate with the server.
challenge minimum length
The protocol-enforced minimum challenge length of 5 octets will (with proper pseudorandom number generation) approximate 1 in 1 quadrillion odds of any given challenge being chosen. For each octet in length added, this minimum figure is multiplied by 256. If computing power increases at current rates (which has doubled every 18 months for over 30 years, according to Moore's Law), this number will need to be increased at least by one every 4 years computed from 1998 to maintain wide margins of safety over potential intruders' computational processing availability. The recommended default is 5 plus one for every two years since 1998.
challenge maximum length
The protocol-enforced maximum challenge length of 63 octets is considered an estimated maximum need throughout the lifetime of the protocol. To cut the connection-establishment overhead, this number can be reduced to 16 plus one for every two years since 1998. The recommended default is 63.
challenge expiration interval
This value MUST BE used to reject old authentication strings, which could have been sniffed from network packets in attempts to re-use them. It SHOULD be set to a number slightly larger than the maximum number of seconds that client and server system clocks would be expected to differ with normal drifting and re-setting. If the client and server are always on the same system, a value of 5 seconds should be enough allowance for the heaviest system loads. For sites running NTP (Network Time Protocol) and connected via a LAN, a value of 15 seconds would work. Other sites might choose 300 seconds (5 minutes) to 600 seconds (10 minutes). If the client and server clocks drift to a greater difference than this parameter toward either the past or future, all client connections will be rejected by the server until the clocks are sufficiently synchronized again. The recommended default is 300.

Implementation Notes

The following are some additional notes for implementors:


References


Acknowledgements

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.