Apache JServ Protocol version 2.1 (AJPv2.1)

draft - July 1, 1998

Abstract

The original protocol that was built into Apache JServ Servlet Engine 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.1 provides new features such as 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 built on top a connection and depends only on the ability of two ends to communicate between each other in a full duplex manner. This is kept sufficiently generalized that the connection layer can be of any type, even if first implementation will based on plain TCP/IP connections.

Glossary

Client

The HTTP server process/thread becomes the client in the context of this protocol because it initiates the request and waits for the response.

Connection

A finite-duration link between client and server, upon which all 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 this protocol.

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 Original JServ Protocol (AJPv1)

The original protocol (AJPv1), 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 Web Server would start the JServ 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 "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 issues:

• 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 Web Server for various processing with configuration information only available to the HTTPD. (i.e. subrequest handling, URL/path evaluation)
• The socket setup overhead has been identified as a potential performance bottleneck.
• Logging messages for the Apache Web Server 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.

One option to avoid the socket setup overhead was based on the multiple-requests-per-socket goal as in W3C's MUX protocol. However MUX was determined to have excessive overhead for this purpose because the support for arbitrary protocols introduces generalization not necessary in this environment. Even a lighter version of MUX developed into AJPv2 was considered too complex and its performance improvement too small compared to the implementation effort due to its complexity.

Overview

AJPv2.1 is a packet oriented protocol and all data passed through the AJPv2.1 connection must be encapsulated into one or more packets. This form of binary behavior was chosen instead of more readable plain text protocol (such as HTTP) because more performant (less traffic is generated) and faster to implement (packet types are better understood by machines that text string). The packet format was kept small (32 bits) for performance reasons and while some packets MUST contain all data they carry into a single packet, a few may divide their payload into one or more successive packets (Request and Response). This was needed to allow payloads bigger than 16 Mb, a big value but suppose to be restricting for some necessities and for future communication enhancements.

This protocol uses an authentication to secure connections and to deny possible requests bypassing web server security: if properly setup (see Security for more info on this topic), AJPv2.1 is considered secure and therefore protects the servlet engine from untrusted requests and/or attacks.

Since one of the main issues AJPv1 was not addressing was performance and socket creation was found as one of the bottlenecks, this protocol is based on the idea of "recyclable" sockets, which may be reused instead of being closed and created when needed (see Socket Recycling for more info on this topic).

To make this possible, requests (and not connections) drive protocol behavior. Each connection is considered idle if authenticated but not yet received a packet starting the request. Once a connection is used by a request, it SHOULD not be used for other requests since unknown state transitions may arise. This forces the protocol to be single-request-per-connection oriented (unlike MUX or AJPv2.0 that were multiple-requests-per-connection oriented) and uses socket recycling to avoid socket creation overhead, instead of multiplexing multiple requests on a single connection.

While this clearly increases the number of simultaneous connections that may be needed to fulfill the request flow a web server generates, but clearly simplifies the work needed to implement this protocol and increases its performance since little processing is needed on top of the connection protocol (i.e. TCP/IP).

Each request 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. (see Functions for more info on this topic)

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 request by terminating the response.

At any point when there are no open requests, 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.

Data Packet Format

All data sent on the full duplex connection between the client and server MUST follow this structure:

• 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 follow big endian style ("network order").
• The packet header is always 32 bits long and follow this format:
  • Octet 0 (8 bits) contains the packet type and subtype
    • The least significant 4 bits (Bits 0-3) indicate the "packet type" of the packet using an unsigned value.
    • The most significant 4 bits (Bits 4-7) indicate the subtype of the packet using an unsigned value.
  • Octet 1-3 (24 bits) set the length of the data payload carried by the packet itself in octets and MAY be zero.
• Octet 4 is "data octet 0" and Octet "data length + 3" is the last "data octet".

Packet Types and Subtypes

Packet types MUST have a corresponding subtype and valid values are shown in the following table:

The tables fields are as follows.

• Type contains the the numbers to be used in the packet type field of the packet header.
• Type Description contains a one-word description which will be used as a name for that type of packet in following sections.
• Originator 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 only on the side(s) allowed in the table.
• Subtype contains the numbers to be used in the packet subtype field of the packet header.
• Bitmap shows the bit map found into the first octet of the packet header (LSB is on the right side of the table)
• Data Length contains the data length in octets the referring packet is allowed to carry (16Mb is maximum allowed packet size by the header format, given its 24 bits for data length)
• 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, origination or size not as shown in the table above constitutes a fatal protocol error.

All packets will be referred as the couple [n,m] where n will be the packet type and m the subtype.

Authentication Packets [0,x]

• packet [0,0] contains an array of random-value octets used as authentication challenge string. This is the first packet sent by the server upon establishment of each connection. The length MUST be at least 5 octets to force a reasonable security on the connection authentication. A new random challenge MUST be chosen for each connection.
• Packet [0,1] contains the authentication string in response of server challenge. The length MUST be 16 octets since this is the length of the MD5 hash needed to authenticate the socket.
• Packet [0,2] acknowledges the client that authentication was successful and connection was established properly. This packet MUST NOT contain any data and MUST have its data length set to zero.
• Packet [0,3] indicates authentication failed and connection could not be established. Any data placed in this packet is OPTIONAL but MAY be used to contain a message explaining the failure of such operation.

See the section on Security for more details.

Request Packets [1,x]

• packet [1,0] contains a fragment of the request data block, indicating others (at least one) request packets will be needed by the server to obtain all request data. This packet SHOULD be used only when request fragmenting is needed or when request data is bigger then 16 Mb.
• packet [1,1] contains all the request data if received alone, or completes the request data if received after one or more [1,0] packet. This packet activates the connection receiving it and SHOULD lock the connection so that no other requests may be done before response has been terminated.

See the section on Request for more details on request data format.

Function Request Packets [2,x]

• packet [2,0] contains the name of the function that the other side must execute and the value passed to it.
• packet [2,1] contains the return value of the function call or nothing is function is not supposed to return a value.
• packet [2,2] indicates the function requested failed and MAY contain a message explaining the failure of such operation. This packet MUST be sent back to caller if the function requested could not be processed (function not enabled, not supported, or some exceptional behavior was caused by its execution).

See the section of Functions for details on function request format.

Response Packets [3,x]

• packet [3,0] contains a response data block. There MAY be more than one [3,0] packet on the same request process. A packet [3,4] will be used to indicate the end of the response data block. The server MAY fragment the response data block without any constrain, this to allow unbuffered response, or sending of other packets during a response phase.
• packet [3,1] contains one or more log entry lines from the server to the client. This is intended as routine per-request logging while 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 [3,1] packet sent from the server to the client within a request process.
• packet [3,2] contains a text message describing the warning condition. This intended for logging on the client.
• packet [3,3] 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.
• packet [3,4] indicates the end of request and unlocks the connection. Any further response packet sent from the server before another request is received SHALL be treated as a fatal protocol error, since the connection may handle only a request process at a time.

See the section on Response for details on response data format.

Protocol Packets [15,x]

• Packet [15,0] forces the receiver to close the connection receiving the packet. This packet MUST NOT contain any data and MUST have its data length set to zero.
• Packet [15,1] indicates a fatal failure due to a protocol error. It also indicates that the originating process is closing the connection. Any data placed in a protocol error packet is OPTIONAL and MAY be used for debugging purposes.

Request

Request metadata may be sent by the client in one or more request packets [1,0] that the server SHALL treat as a single data block. Request data block MAY be fragmented with no specific constrains. Packet [1,1] terminates the request data block and activates request processing on server side.

The request consists of two parts, request headers and the request entity. Request entity MAY NOT be present.

Request headers

The headers to be set for the request follow MIME format:

"<header name>: <header value>'crlf'"

where 'crlf' are carriage return (hex value 0x0D), line feed (hex value 0x0A) characters indicating the end of the single header. This poses a constrain on header values that MUST NOT contain these characters in the given order.When the last header has been sent, a blank line (another couple 'crlf' alone) should be sent.

All headers found on the following list MUST be sent only if their value is both meaningful and known by the client at request time. If value is not known or not meaningful, the variable MUST not be passed, allowing the use of the empty header value as a meaningful one. Note that header names will be treated as case dependent..

Request Headers List
Header Group	Header Name	Description
CGI Environment	AUTH_TYPE	The type of authentication used
	CONTENT_LENGTH	The length of the request entity
	CONTENT_TYPE	The media type of the request entity
	DOCUMENT_ROOT	The client's main document root
	PATH_INFO	Extra URI path information
	PATH_TRANSLATED	The translated path info
	QUERY_STRING	The query arguments
	REQUEST_METHOD	The method used for the request
	REMOTE_USER	The authenticated username used for the request
	REMOTE_ADDR	The IP address of the requesting host
	REMOTE_HOST	The hostname of the requesting host
	SCRIPT_NAME	The URI portion that refers to the servlet
	SERVER_NAME	The hostname of the server
	SERVER_PORT	The port number of the server
	SERVER_PROTOCOL	The protocol used for the request
	SERVER_SOFTWARE	The name of the server software
HTTP Header		All headers sent with the HTTP request

Response entity

If the request entity is present, it is sent after the request headers with no further formatting.

Function

Each function call packet [2,0] contains a single request for a function call. This allows one side to call functions on the other using the same transmission channel used for request/response processing. These functions may well be called during request processing, for example to gather information not available at request startup, or on an open, idle connection, for example to signal the other side to restart/shutdown.

The data contained into the packet [2,0] follows a binary format:

"<function code (single octet)><function value>"

If function is successful, data contained by the packet [2,1] is what the function returned with no further formattation (a data length of zero means the function returned nothing or void), otherwise a packet [2,2] is received containing a message explaining the failure of the called function.

Here is a list of defined functions with their code:

Functions with codes ranging from 4 to 253 SHOULD return a [2,2] packet containing "Function not defined", while functions described above but not implemented SHOULD return "Function not implemented". Functions that are implemented but cannot execute the requested function SHOULD return a detailed message explaining the such impossibility or at least a "Function not available" message.

Response

As for requests, response metadata may be sent by the server in one or more response packets [3,0] that the client SHALL treat as a single data block. Response data block MAY be fragmented with no specific constrains. Packet [3,1] terminates the response data block, while Packet [3,5] terminates the request process. This packet duplicity is needed to allow the sending of other response packets after the response has been fully processed, thus reducing the transmission overhead of the response data to the client.

The response consists of two parts, response headers and the response entity. Response entity MAY NOT be present.

Response headers

The headers to be set for the response follow MIME format:

"<header name>: <header value>'crlf'"

where 'crlf' are carriage return (hex value 0x0D), line feed (hex value 0x0A) characters indicating the end of the single header. This poses a constrain on header values that MUST NOT contain these characters in the given order.When the last header has been sent, a blank line (another couple 'crlf' alone) should be sent.

All headers found on the following list MUST be sent only if their value is both meaningful and known by the server at response time. If value is not known or not meaningful, the header MUST not be passed, allowing the use of the empty header value as a meaningful one.

Response Headers List
Header Name	Header Format	Description
Status	"Status: <code> <string>"	sets the response status to <code>, with a status message of <string>

Response entity

The entity is the data block generated by the request process and, if present, it is sent with no further formatting.

Security

The "secret integer" authentication algorithm of AJPv1 has not been carried forward to AJPv2.1 because considered not secure.

The AJPv2.1 authentication algorithm depends on all clients and the server having access to a secret file or string with identical contents. This is based on the assumption that the administration of the AJPv2.1 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 July, 1998. It is able to verify that both sides possess secret text (analogous to a password) without passing any of it in the clear over the network.

• Client side
  • receive a packet [0,0] from the server carrying a challenge string (C). Packet data length is used to retrieve the challenge string length.
  • obtain the shared secret S from a file or the client configuration
  • concatenate C and S
  • compute the MD5 hash of the resulting string
  • send the MD5 hash to the server in the authentication string as a packet [0,1]
• Server side:
  • generate a challenge string of random octets C with length defined using local configuration parameters (minimum length is forced for security reasons to be at least 5 octets) and send it to the client using a [0,0] packet with data length given by the challenge string length. Packet [0,0] MUST contain only the challenge string and its data length MUST be the same as the challenge string length.
  • save C right after sending it to the client
  • obtain the shared secret S from a file or the server configuration
  • concatenate C and S
  • compute the MD5 hash of the resulting string
  • receive the MD5 hash from the client, as data carried by a packet [0,1]
  • if the resulting MD5 hash and the received MD5 hash ARE the same, send a Packet [0,2] to the client to acknowledge authentication success. This packet MUST have zero data length and MUST no carry any other information.
  • if the resulting MD5 hash and the received MD5 hash ARE NOT the same, send a Packet [0,3] to client to acknowledge authentication failure. Any data placed in this packet is OPTIONAL but MAY be used to contain a message explaining the authentication failure.

The shared secret is an arbitrary-length string (which does not necessarily need to be ASCII text - it could be any binary 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.

Security Hazards

Security is always a big issue for servers, since only trusted clients should be able to use and interact with the server. This protocol implements an authentication algorithm that is considered safe for most needs (at least as safe as MD5, on top of which it's constructed), allowing a client to authenticate a connection only if it knows the secret key of the server. Since this secret key is not passed onto the network and MD5 is considered computationally infeasible if suggested challenge sizes are used over time, this gives us enough confidence on this protocol.

Since the security of a transmission is granted by the whole protocol stack, problems may come out if we analyze the security holes that may be carried by the underlying transport protocols. (We concentrate on TCP/IP protocol since it will be the one used by the AJP implementations)

Here follows a list of possible security hazards and suggested security improvements and/or solutions to prevent them.

Intrusion

Servlet execution is protected by the web server since the servlet engine does not impose any restriction on servlet requests coming from authenticated connection because they are considered trusted and secure. Intruders may want to bypass this security to execute servlets and gather information about the system or data contained (administration servlets may have full access to databases or to system resources such as password lists, system configurations, or other private information that need to remain secret).

The authentication algorithm depends on good pseudo random number generation, since difference between each authentication handshake is given by the variability of the challenge string. The weakness of pseudo random number generation (the prevision of the random number sequence) is not an issue since the challenge string is sent to everyone, even possible intruders. On the other hand, the pseudo random number generator MUST guarantee the variability of the challenge string since this is the key for authentication safety. There is a very small chance that any given challenge could be used again for another connection. If this were to occur a sniffed packet could be used to answer the authentication. For this reason a minimum of 5 octets of challenge string were forced.

Many more recommendations and ideas in the area of impacts of pseudo random number generation on security can be found in RFC 1750, "Randomness Recommendations for Security"

Warning: this algorithm is as vulnerable as the secret file or string contents. For this reason, they SHOULD be adequately protected from unauthorized users by any security measures available.

Solutions for developers: use good pseudo random number generators. Implement a IP address filter list to deny connection to addresses not allowed.

Solutions for end users: keep your secret file protected from unauthorized users and increment challenge string length to enhance security keeping in mind that the bigger the challenge strings the slower the connection authentication. Configure the IP addresses filter list to match the addresses of the trusted clients.

Denial of Service

Another potential security hazard is the ability of causing the protocol stall by requesting connections without sending back the authentication response to the servlet engine. Since connections are a finite resource, this could cause denial of connection if some connections were still open but no more were available, or denial of service if all connections were stalled by the attack.

Solutions for developers: implement a time-out on authentication handshake, giving the ability to the server to drop a connection if the challenge response is not received in a configurable number of seconds. Implement a IP address filter list to deny connection to addresses not allowed.

Solutions for end users: configure this time-out on authentication handshake to match closely your network/systems performance. Configure the IP addresses filter list to match the addresses of the trusted clients.

Packet Sniffing

This protocol does not encrypts the data sent through the connection. Therefore it is possible to sniff protocol packets and retrieve the information that is being sent. Due to protocol complexity and legal restrictions on encryption software, packet masking is not implemented in current version of the protocol.

Solutions for end users: since the transport protocol is transparent for AJP, the use of secured sockets, or even placing both clients and servers on a secured network may be effective solutions against this security hazard. Another option would be that of placing both the client and the server on the same machine, restricting the sniffing capabilities to users of that machine that may be limited and controlled.

IP Spoofing

This protocol authenticates connections only when they are created. An intruder capable of faking IP addresses on its packets, may enter an authenticated connection and send packets behaving like the authenticated other side. Such kind of attack cannot retrieve information from the server since spoofed packets don't get returned to the attacker (as long as routing tables don't get altered) but to the authenticated client (that will probably return a Fatal Protocol Error and close the connection), but being able to make requests bypassing authentication could be a very dangerous thing (i.e. servlets executing free form queries on database may get used to destroy the whole database, or file uploading servlets may get used to fill up disk space causing denial of service or unpredictable behavior)

Solutions for end users: the solutions used to avoid packet sniffing may be used effectively also against this kind of attacks.

State Transitions

Configuration Parameters

Client Side

authentication

This setting determines whether authentication is in use on the server. The default value MUST be to enable authentication. Implementers 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

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 implementer to provide their own security (such as a firewall or router with filtering) to protect the server from intruders.

authentication timeout (optional)

This value is used to configure the time a connection is allowed to take to perform the authentication handshake.This value may vary depending on network/systems load/performance and must be carefully chosen to be as little as possible to avoid possible denial of service attacks.

secret file or string

This must be configured to the same contents as used on all clients which will interoperate with the server.

challenge string length

The protocol-enforced minimum challenge length of 5 octets will (with proper pseudo random 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.

References

• 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, "Apache JServ Protocol", version 1.0, Java Apache Project, July 1997
• I. Kluft, E. Korthof, S. Mazzocchi, "Apache JServ Protocol", version 2.0, Java Apache Project, February 1998
• 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

Contributors

Acknowledgements

This specification was developed through discussion and consensus on the Java Apache Project's mailing list. The original idea for this model was evolved from ideas proposed by Ed Korthof, Ian Kluft and Stefano Mazzocchi that were merged into the AJPv2.0 protocol. Its complexity forced developers to simplify the protocol and innovative ideas and contributions from people listed above made possible this protocol specification.

Copyright (c) 1997-98 The Java Apache Project.
$Id: AJPv21.html,v 1.3 1999/06/09 05:21:29 jonbolt Exp $
All rights reserved.