Apache JServ Protocol Version 2 (AJPv2)

Implementation-Phase 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 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.

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.

• Introduction
  • The Original JServ Protocol
  • Improving Upon the Original JServ Protocol
  • Overview of Apache JServ Protocol Version 2 (AJPv2)
  • Glossary
• The AJPv2 Header
  • The AJPv2 Packet Types and Subtypes
  • Challenge Packets
  • Initialization Packets
  • Function Packets
  • Request Packets
  • Response Packets
  • Asynchronous Event Packets
  • Protocol Control Packets
• Client-side State Transitions
• Server-side State Transitions
• Authentication Algorithm
  • Impacts of Pseudorandom Number Generation on Security
• Client-Side Protocol Configuration Parameters
• Server-Side Protocol Configuration Parameters
• Implementation Notes
• References

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

• The servlet output is always buffered. But unbuffered output is desirable in many cases.
• Developers have expressed a desire to be able to send requests back to the Apache HTTPD process for various processing with configuration information only available to the HTTPD. (i.e. subrequest handling, URL/path evaluation)
• The single-connection-per-request has been identified as a potential performance bottleneck. Although some sites may not be able to significantly avoid this, at sites which can, it should simulate the advantages of HTTP's keepalives for reducing or eliminating additional socket setup overhead while a client is waiting for an HTTP request.
• Logging messages for the Apache HTTPD can only be sent with the request headers. If they're not ready at that time for one request, they must be saved and sent during the header phase of the next request, guaranteeing that any late log messages for the last request will be lost.

[Note: we had some difficulty in our discussion using the MRPS acronym. The concept is fairly easy but it was sometimes mis-typed as MSRP, which is an acronym seen on American car commercials for "manufacturer's suggested retail price." :-) ]

Overview of Apache JServ Protocol Version 2 (AJPv2)

Each session begins with the request environment, including information analagous 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.

• Data is sent in packets formed by a header describing some info about the packet and a data length and data payload.
• All packets MUST be 32-bit aligned and MUST always follow big endian style ("network order").
• The packet header is either 64 bits long so that the data payload is also 32 bit aligned inside the packet.
• Octet 0 (8 bits) contains the packet type and subtype
  • The least significant 5 bits (Bits 0-4) indicate the "packet type" of the packet using an unsigned value.
  • The most significant 3 bits (Bits 5-7) indicate the subtype of the packet using an unsigned value.
• Octet 1 (8 bits) contains flag bits.
  • Bit 0 (the least significant bit) contains the "Session Data End" flag.
  • Bit 1 contains the "Session Close" flag.
  • Bit 2 contains the "Connection Close" flag.
  • Bits 3-7 are reserved for future expansion. They MUST currently be set to zero by the sender and ignored by the receiver.
• Octet 2-3 (16 bits) give the session to which the packet applies.
• Octet 4-7 of the packet (32 bits), set the length of the data payload carried by the packet itself and MAY be zero. (This value may be also calculated like this: data length = packet length - 8.) Note that since packet must be 32-bit aligned, 0-3 octets of padding MUST be added after the length indicated in the packet to make the next packet begin on a 32-bit boundary.
• Octet 8 is "data octet 0" and Octet "data length + 7" is the last "data octet".

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

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.

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

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 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 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 intented 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 intented 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 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

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

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 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 posess secret text (analagous to a password) without passing any of it in the clear over the network.

• Client side:
  • receive a 5-63 octet challenge C from the server
  • generate a 4-octet T from 4 bytes in big-endian order of the current Unix-style time (a 32-bit quantity with seconds since January 1, 1970 midnight GMT)
  • obtain the shared secret S from a file or the client configuration
  • concatenate C, T and S
  • compute the MD5 hash of the resulting string
  • send T and the MD5 hash to the server in the authentication string
• Server side:
  • generate a challenge string C with 5-63 random octets (if present, use local configuration parameters to set the length)
  • save C when it is sent to the client
  • receive T and the MD5 hash from the client
  • make sure T is within the time tolerance (in seconds), it must be no farther in the past or future than the number of seconds configured for the server
  • obtain the shared secret S from a file or the server configuration
  • concatenate C, T and S
  • compute the MD5 hash of the resulting string
  • for validity, the resulting MD5 hash and the received MD5 hash MUST be the same

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

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

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.

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.

• The server is assumed to be multithreaded, since this is originally intended for implementation with the Apache JServ servlet engine, and Java is multithreaded.
• Since the client could be single-threaded, it controls the number of threads in use by the number of connections it opens simultaneously.
• The server MUST NOT perform more than one Function Request to the client at a time due to the potential for a single-threaded client. Instead, the server MUST wait for a Function Response before sending a new Function Request.
• The client MAY send Function Requests while it has Requests and other Function Requests pending.
• While sessions are open, both the client and server SHOULD refrain from closing the connection (which would terminate all open sessions) except in urgent situations, such as a server shutdown. Resource management SHOULD favor existing connections over new ones, i.e. refuse to open a new connection when it would have to close an open and active one to free the resources.

• S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, Harvard University, March 1997
• D. Eastlake, S. Crocker, and J. Schiller, "Randomness Recommendations for Security", RFC 1750, IETF Network Working Group, December 1994
• J. Gettys and H. Nielsen, "Simple Multiplexing Protocol", W3C Working Draft 25-August-97, World Wide Web Consortium (W3C), August 1997
• A. Kosut, mod_jserv protocol.txt, Java-Apache Project, July 1997
• R. McCool, "The Common Gateway Interface", Version 1.1, National Center for Supercomputing Applications (NCSA), 1994.
• R. Rivest "The MD5 Message-Digest Algorithm", RFC 1321, MIT Laboratory for Computer Science, April 1992