From e01da6ce4fab2a8a8159dd5f2e20b211cafc2ad6 Mon Sep 17 00:00:00 2001 From: Luca Toscano Date: Tue, 24 Jan 2017 09:58:47 +0000 Subject: [PATCH] Merge r1779927 from trunk: Reworked and added examples to the HTTPProtocolOptions doc On #httpd-dev a user gave us some hints about what kind of things would have been great to see in the HTTPProtocolOptions directive's documentation, so I tried to apply them all. I also added some examples taken from http_strict.t and tested a bit. I didn't follow completely the complete change-set of the HTTPProtocolOptions directive, so please review the change and let me know if anything is wrong or missing. Submitted by: elukey git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1780045 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/core.xml | 145 +++++++++++++++++++++++++-------------- 1 file changed, 93 insertions(+), 52 deletions(-) diff --git a/docs/manual/mod/core.xml b/docs/manual/mod/core.xml index 7a254dff02..0afe34148f 100644 --- a/docs/manual/mod/core.xml +++ b/docs/manual/mod/core.xml @@ -1257,61 +1257,102 @@ EnableSendfile On >RFC 7230 §3.2), which are now applied by default or using the Strict option. Due to legacy modules, applications or custom user-agents which must be deprecated the Unsafe - option has been added to revert to the legacy behaviors. These rules - are applied prior to request processing, so must be configured at the - global or default (first) matching virtual host section, by IP/port - interface (and not by name) to be honored.

- -

Prior to the introduction of this directive, the Apache HTTP Server - request message parsers were tolerant of a number of forms of input - which did not conform to the protocol. - RFC 7230 §9.4 Request Splitting and - §9.5 Response Smuggling call out only two of the potential - risks of accepting non-conformant request messages, while - RFC 7230 §3.5 "Message Parsing Robustness" identify the - risks of accepting obscure whitespace and request message formatting. - As of the introduction of this directive, all grammar rules of the - specification are enforced in the default Strict operating - mode, and the strict whitespace suggested by section 3.5 is enforced - and cannot be relaxed.

- -

Users are strongly cautioned against toggling the Unsafe - mode of operation, particularly on outward-facing, publicly accessible - server deployments. If an interface is required for faulty monitoring - or other custom service consumers running on an intranet, users should - toggle the Unsafe option only on a specific virtual host configured - to service their internal private network.

- -

Reviewing the messages logged to the ErrorLog, - configured with LogLevel debug level, + option has been added to revert to the legacy behaviors.

+ +

These rules are applied prior to request processing, + so must be configured at the global or default (first) matching + virtual host section, by IP/port interface (and not by name) + to be honored.

+ +

The directive accepts three parameters from the following list + of choices, applying the default to the ones not specified:

+ +
+
Strict|Unsafe
+
+

Prior to the introduction of this directive, the Apache HTTP Server + request message parsers were tolerant of a number of forms of input + which did not conform to the protocol. + RFC 7230 §9.4 Request Splitting and + §9.5 Response Smuggling call out only two of the potential + risks of accepting non-conformant request messages, while + RFC 7230 §3.5 "Message Parsing Robustness" identify the + risks of accepting obscure whitespace and request message formatting. + As of the introduction of this directive, all grammar rules of the + specification are enforced in the default Strict operating + mode, and the strict whitespace suggested by section 3.5 is enforced + and cannot be relaxed.

+ + Security risks of Unsafe +

Users are strongly cautioned against toggling the Unsafe + mode of operation, particularly on outward-facing, publicly accessible + server deployments. If an interface is required for faulty monitoring + or other custom service consumers running on an intranet, users should + toggle the Unsafe option only on a specific virtual host configured + to service their internal private network.

+ + + + Example of a request leading to HTTP 400 with Strict mode + # Missing CRLF
+ GET / HTTP/1.0\n\n + +
+
RegisteredMethods|LenientMethods
+
+

RFC 7231 §4.1 "Request Methods" "Overview" requires that + origin servers shall respond with a HTTP 501 status code when an + unsupported method is encountered in the request line. + This already happens when the LenientMethods option is used, + but administrators may wish to toggle the RegisteredMethods + option and register any non-standard methods using the + RegisterHttpMethod + directive, particularly if the Unsafe + option has been toggled.

+ + Forward Proxy compatibility +

The RegisteredMethods option should not + be toggled for forward proxy hosts, as the methods supported by the + origin servers are unknown to the proxy server.

+ + + + Example of a request leading to HTTP 501 with LenientMethods mode + # Unknown HTTP method
+ WOW / HTTP/1.0\r\n\r\n

+ # Lowercase HTTP method
+ get / HTTP/1.0\r\n\r\n
+ +
+
Allow0.9|Require1.0
+
+

RFC 2616 §19.6 "Compatibility With Previous Versions" had + encouraged HTTP servers to support legacy HTTP/0.9 requests. RFC 7230 + supersedes this with "The expectation to support HTTP/0.9 requests has + been removed" and offers additional comments in + RFC 7230 Appendix A. The Require1.0 option allows + the user to remove support of the default Allow0.9 option's + behavior.

+ + + Example of a request leading to HTTP 400 with Require1.0 mode + # Unsupported HTTP version
+ GET /\r\n\r\n + +
+
+

Reviewing the messages logged to the + ErrorLog, configured with + LogLevel debug level, can help identify such faulty requests along with their origin. Users should pay particular attention to the 400 responses in the access log for invalid requests which were unexpectedly rejected.

- -

RFC 7231 §4.1 "Request Methods" "Overview" requires that - origin servers shall respond with an error when an unsupported method - is encountered in the request line. This already happens when the - LenientMethods option is used, but administrators may wish - to toggle the RegisteredMethods option and register any - non-standard methods using the RegisterHttpMethod - directive, particularly if the Unsafe option has been toggled. - The RegisteredMethods option should not - be toggled for forward proxy hosts, as the methods supported by the - origin servers are unknown to the proxy server.

- -

RFC 2616 §19.6 "Compatibility With Previous Versions" had - encouraged HTTP servers to support legacy HTTP/0.9 requests. RFC 7230 - supersedes this with "The expectation to support HTTP/0.9 requests has - been removed" and offers additional comments in - RFC 7230 Appendix A. The Require1.0 option allows - the user to remove support of the default Allow0.9 option's - behavior.

-- 2.40.0