The Java Apache Project

Apache JServ Protocol version 2.1 (AJPv2.1)

draft - July 1, 1998

This is a pre-implementation draft of the Apache JServ 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 servlet engine.

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:

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:

Packet Format

Octet

0

1

2

3

4 - (n+3)

Bits

0

1

2

3

4

5

6

7

Contents

Type

Subtype

Data Length

Data

Packet Types and Subtypes

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

Packet Type/Subtype Definition Table

Type Type Description Subtype Originator

Bit Map

Data Length

Subtype Description

0

Authentication

0

Server

0000-0000

[5 - 16777215]

Server authentication

1

Client

0001-0000

16

Client authentication

2

Server

0010-0000

0

Authentication success

3

Server

0011-0000

[0 - 16777215]

Authentication failure

1

Request

0

Client

0000-0001

[0 - 16777215]

Request (data block still not complete)

1

0001-0001

[0 - 16777215]

Request (data block complete)

2

Function

0

Either

0000-0010

[0 - 16777215]

Function call

1

0001-0010

[0 - 16777215]

Function success

2

0010-0010

[0 - 16777215]

Function failure

3

Response

0

Server

0000-0011

[0 - 16777215]

Response

1

0001-0011

[0 - 16777215]

Logs (newline-delimited)

2

0010-0011

[0 - 16777215]

Warning

3

0011-0011

[0 - 16777215]

Error

4

0100-0011

0

End of response

15

Protocol

0

Either

0000-0100

0

Close connection

1

0001-0100

0

Connection closed

2

0010-0100

[0 - 16777215]

Fatal protocol error

The tables fields are as follows.

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]

See the section on Security for more details.

Request Packets [1,x]

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

Function Request Packets [2,x]

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

Response Packets [3,x]

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

Protocol Packets [15,x]

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 List

Function Code

Description

0

Applies alias rules to the specified virtual path and returns the corresponding real path

1

Maps a file name to its MIME type

2

Returns the content of a file specified by a virtual path

3

Returns the content of a file specified by a real path

4-253

Reserved for future use (must return "function not implemented)

254

Signals receiver to cleanup and restart

255

Signals receiver to shutdown

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.

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

Client Side State Transition Table

State Event

Packet
Received

Action

Packet
Sent

New State

closed

 

 

open connection

 

unauthenticated

unauthenticated

receive authentication challenge

[0,0]

send authentication response

[0,1]

waiting for authentication
receive other

[x,x]

close connection

 

closed

waiting for authentication

receive authentication success

[0,2]

 

 

open
receive authentication failure

[0,3]

close connection

 

closed
receive other

[x,x]

close connection

 

closed

open

 

 

send request fragment

[1,0]

open
 

 

send final request fragment

[1,1]

waiting for response
 

 

send function request

[2,0]

waiting for function response
 

 

send close connection

[15,0]

closed
receive function request

[2,0]

evaluate function

on success, send response

[2,1]

open
on failure, send error message

[2,2]

open
receive close connection

[15,0]

close connection   closed
receive protocol error

[15,1]

close connection

 

closed
receive other

[x,x]

send protocol error, close connection

[15,1]

closed

waiting for response

    send close connection

[15,0]

closed
receive response

[3,0]

 

 

waiting for response
receive log

[3,1]

 

 

waiting for response
receive warning

[3,2]

 

 

waiting for response
receive error

[3,3]

 

 

waiting for response
receive function request

[2,0]

evaluate function

on success, send response

[2,1]

waiting for response
on failure, send error message

[2,2]

waiting for response
receive end of response

[3,4]

 

 

open
receive close connection

[15,0]

close connection   closed
receive protocol error

[15,1]

close connection

 

closed
receive other

[x,x]

send protocol error, close connection

[15,1]

closed

waiting for function response

    send close connection

[15,0]

closed
receive function response

[2,1]

 

 

open
receive function failure

[2,2]

 

 

open
receive close connection

[15,0]

close connection   closed
receive protocol error

[15,1]

close connection

 

closed
receive other

[x,x]

send protocol error, close connection

[15,2]

closed

Server State Transitions Table

State

Event

Packet Received

Action

Packet Sent

New State

listening

connection is requested

 

send authentication challenge

[0,0]

waiting for authentication

waiting for authentication

receive authentication response

[0,1]

check authentication

on success

[0,2]

open
on failure send packet and close connection

[0,3]

listening
receive other

[x,x]

close connection

 

listening

open

    send close connection

[15,0]

listening
receive request fragment

[1,0]

 

 

open
receive final request fragment

[1,1]

 

 

handling request
receive function request

[2,0]

evaluate function

on success, send response

[2,1]

open
on failure, send error message

[2,2]

open
receive close connection

[15,0]

close connection

[15,1]

listening
receive protocol error

[15,1]

close connection

 

listening
receive other

[x,x]

send protocol error, close connection

[15,1]

listening

handling request

 

 

send response

[3,0]

handling request
 

 

send log

[3,1]

handling request
 

 

send warning

[3,2]

handling request
 

 

send error

[3,3]

handling request
 

 

send end of response

[3,4]

open
 

 

send function request

[2,0]

waiting for function response
 

 

send close connection

[15,0]

listening
receive function request

[2,0]

evaluate function

on success, send response

[2,1]

handling request
on failure, send error message

[2,2]

handling request
receive close connection

[15,0]

close connection   listening
receive protocol error

[15,1]

close connection

 

listening
receive other

[x,x]

send protocol error, close connection

[15,1]

listening

waiting for function response

    send close connection

[15,0]

listening
receive function response

[2,1]

 

 

handling request
receive function error

[2,2]

 

 

handling request
receive close connection

[15,0]

close connection   listening
receive protocol error

[15,1]

close connection   listening
receive other

[x,x]

send protocol error, close connection

[15,1]

listening

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

Contributors

in strict alphabetical order from left to right

Federico Barbieri
Brescia, Italy
Pierpaolo Fumagalli
Erba, Italy
Ian Kluft
San Jose, California, USA
Ed Korthof
San Francisco, California, USA
Stefano Mazzocchi
Pavia, Italy
Martin Pool
Brisbane, Australia

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.