Apache JServ Protocol Version 1.1 (AJPv1.1)

Standard - September 9, 1998

describes the protocol used to communicate between a web server module
and the Apache JServ servlet engine over a TCP socket.

Introduction

The authentication scheme used for AJPv1.0 (used by Apache JServ 0.9.xx) was considered too simple and worked only on local environments. For this reason, while the request/response phase of the protocol were kept unchanged, authentication handshake was ported from higher versions of the protocol (proposed as a future extension) and implemented here for security reasons.

This will also provide more feedback to developers for newer revisions of the AJP protocol.

Protocol States

A request is made by requesting a TCP connection to the port Apache JServ is listening to.

If authentication is enabled (authentication must be enabled or disabled on both sides) the authentication handshake is performed (see Authentication), otherwise authentication is skipped and request metadata is sent right away.

The client sends the request metadata to the servlet engine (see Request) and waits for response metadata (see Response).

When finished, the servlet engine closes the connection, indicating that the request has been completed.

Authentication

The AJPv1.1 authentication algorithm depends on all clients and the servlet engine having access to a secret file or string with identical contents. This is based on the assumption that the administration of both sides 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.

Note: all numbers are sent on the connection streams using big endian format (network order), where most significant bits come first.

Client side

receive 4 octects (32 bits) from the server indicating the challenge string length.

receive as many octects as specified by the octects above.

obtain the shared secret S from a client configured file.

concatenate C and S

compute the MD5 hash of the resulting string

send the MD5 hash to the server

Server side:

generate a challenge string of random octets R with length defined using local configuration parameters (minimum length is forced for security reasons to be at least 5 octets)

obtain a 64 bit system time T using milliseconds since 01/01/1970

concatenate C and T and save it as R

send length of R to client using 4 octets (32 bits)

send R to client.

obtain the shared secret S from a file or the server configuration

concatenate R and S

compute the MD5 hash of the resulting string

receive the MD5 hash from the client (16 octets)

if the resulting MD5 hash and the received MD5 hash ARE NOT the same, close the connection.

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, so, since authentication must be performed on every request and MD5 strength does not depend very much on string length, this could as small as a few lines of text.

The server does not acknowledge the authentication success to the client to avoid round trip time and speed up the request process. For this reason, the client must control the availability of the connection while writing the request, since this indicates the success of that operation.

Authentication may be disabled to increment performance. If this is done, both client and server must disable the authentication handshake and skip the authentication phase. Systems administrators that want to avoid untrusted execution of servlets, should secure their networks using other systems.

Request

The module sends the request metadata to the servlet engine. These are sent as lines, with two parts: a one-character identifier, and the data. This is preceded with a four-digit hex number indicating the length of the following string (with leading 0s), e.g. "000dHDate Friday", where "000d" is the length, "H" is the identifier, and "Date Friday" is the data.

Server name
The module sends "S<hostname>". This is the virtual host that is requesting the servlet.
Servlet zone and class name
The module sends "C<zone><tab><classname>". The first element is the servlet zone to which the servlet has been mapped. The class name is the fully qualified name of the class in dot notation. i.e. foo.bar.Servlet. The servlet would load from one of the repository defined for that zone or from the CLASSPATH.
Environment variables
The module sends "E<var name><tab><var value>". The vars should contain all the standard CGI variables, but should not include the HTTP_ set, since the HTTP headers are sent later. e.g, "EPATH_INFO /foo" The following variables are required. Most are CGI/1.1 variables, but a few are Apache-specific. The following should all be sent (except for those marked with an asterix(*), which should only be sent if appropriate), as well as any additional CGI variables available:
Request headers
The module sends all of the client's request headers, in the form "H<header name><tab><header value>". e.g., "HUser-Agent Mozilla/4.0 (Windows NT)"
A blank line
When all the E and H lines (they may be interpolated), the module sends a blank line. (i.e., 0-length) This indicates that the metadata has been completed.
The request entity
If there is a request entity, it is sent. If not, nothing further is sent.
Signals
The servlet engine receives signals with the request data, in the form "s<signal code>" where signal code may be "01" for restart (SIGHUP) or "15" for termination (SIGTERM). If a signal code is received, any other data sent with the request will be discarded and if the signal code is not recognized, the request is terminated with no further processing.

Response

The response consists of two parts, response headers and the response entity. This is sent basically the same way CGI responses are sent:

Response headers
The headers to be set for the response should then be sent, in MIME format: "<header name>: <header value>", terminated with a crlf. Headers set here will be outputted by the server. The server will add the HTTP line, and Server:, Date: and other headers, so only headers that the servlet needs to set should be set. e.g., Content-type, Cookie, whatever. When the last header has been sent, a blank line should be sent.
A few headers have special meanings:
- Status: <code> <string>
  This sets the response status to <code>, with a status message of <string>. This is the same as the CGI output header of the same name. e.g., "Status: 404 Not Found"
- Servlet-Log: <string>. This sends a message to be logged in the server's log. This is currently not used by JServ 1.0.
- Servlet-Error: <message>. This indicates that the servlet engine had an error occur. The server should send an error response back to the browser, with the status set by a separate Status: header (see above). 500 should be used if Status: is not present. The <message> strong should be logged to the server's error log, as the reason why the request failed. No response entity will be present for this response.
Response entity
JServ outputs the contents of the response to the module through the socket. When it is finished, JServ closes the socket. This will indicate to the module that the request has been completed.