1 /*
2 * ====================================================================
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements. See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership. The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License. You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied. See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 * ====================================================================
20 *
21 * This software consists of voluntary contributions made by many
22 * individuals on behalf of the Apache Software Foundation. For more
23 * information on the Apache Software Foundation, please see
24 * <http://www.apache.org/>.
25 *
26 */
27
28 package org.apache.hc.client5.http.protocol;
29
30 import java.io.IOException;
31
32 import org.apache.hc.core5.annotation.Contract;
33 import org.apache.hc.core5.annotation.ThreadingBehavior;
34 import org.apache.hc.core5.http.EntityDetails;
35 import org.apache.hc.core5.http.Header;
36 import org.apache.hc.core5.http.HttpException;
37 import org.apache.hc.core5.http.HttpHeaders;
38 import org.apache.hc.core5.http.HttpRequest;
39 import org.apache.hc.core5.http.HttpRequestInterceptor;
40 import org.apache.hc.core5.http.Method;
41 import org.apache.hc.core5.http.ProtocolException;
42 import org.apache.hc.core5.http.protocol.HttpContext;
43 import org.apache.hc.core5.util.Args;
44
45 /**
46 * <h1>RequestTraceInterceptor</h1>
47 *
48 * <p>This class serves as an interceptor for HTTP TRACE requests, ensuring they adhere to specific security and protocol guidelines.</p>
49 *
50 * <p><strong>Responsibilities:</strong></p>
51 * <ul>
52 * <li>Validates TRACE requests by checking for sensitive headers such as {@code Authorization} and {@code Cookie}.</li>
53 * <li>Ensures that TRACE requests do not contain a request body, throwing a {@link ProtocolException} if a body is present.</li>
54 * </ul>
55 *
56 * <p><strong>Thread Safety:</strong> This class is stateless and therefore thread-safe, as indicated by its {@code ThreadingBehavior.STATELESS} annotation.</p>
57 *
58 * <p><strong>Interceptor Behavior:</strong></p>
59 * <ul>
60 * <li>If the HTTP method is TRACE, the interceptor throws a {@link ProtocolException} if any {@code Authorization} or {@code Cookie} headers are present to prevent sensitive data leakage.</li>
61 * <li>If a TRACE request contains a body, a {@link ProtocolException} is thrown.</li>
62 * </ul>
63 *
64 * @version 5.4
65 * @see HttpRequestInterceptor
66 * @see HttpException
67 * @see IOException
68 * @see ProtocolException
69 * @see Method#TRACE
70 * @see HttpHeaders#AUTHORIZATION
71 * @see HttpHeaders#COOKIE
72 *//**
73 * <h1>RequestTraceInterceptor</h1>
74 *
75 * <p>This class serves as an interceptor for HTTP TRACE requests, ensuring they adhere to specific security and protocol guidelines.</p>
76 *
77 * <p><strong>Responsibilities:</strong></p>
78 * <ul>
79 * <li>Validates TRACE requests by checking for sensitive headers such as {@code Authorization} and {@code Cookie}.</li>
80 * <li>Ensures that TRACE requests do not contain a request body, throwing a {@link ProtocolException} if a body is present.</li>
81 * </ul>
82 *
83 * <p><strong>Thread Safety:</strong> This class is stateless and therefore thread-safe, as indicated by its {@code ThreadingBehavior.STATELESS} annotation.</p>
84 *
85 * <p><strong>Interceptor Behavior:</strong></p>
86 * <ul>
87 * <li>If the HTTP method is TRACE, the interceptor throws a {@link ProtocolException} if any {@code Authorization} or {@code Cookie} headers are present to prevent sensitive data leakage.</li>
88 * <li>If a TRACE request contains a body, a {@link ProtocolException} is thrown.</li>
89 * </ul>
90 *
91 * @version 5.4
92 * @see HttpRequestInterceptor
93 * @see HttpException
94 * @see IOException
95 * @see ProtocolException
96 * @see Method#TRACE
97 * @see HttpHeaders#AUTHORIZATION
98 * @see HttpHeaders#COOKIE
99 */
100 @Contract(threading = ThreadingBehavior.STATELESS)
101 public class RequestValidateTrace implements HttpRequestInterceptor {
102
103 /**
104 * Default instance of {@link RequestValidateTrace}.
105 */
106 public static final HttpRequestInterceptor INSTANCE = new RequestValidateTrace();
107
108 /**
109 * Default constructor.
110 */
111 public RequestValidateTrace() {
112 super();
113 }
114
115 /**
116 * Processes an incoming HTTP request. If the request is of type TRACE, it performs the following actions:
117 * <ul>
118 * <li>Throws a {@link ProtocolException} if the request contains an {@code Authorization} header to prevent sensitive data leakage.</li>
119 * <li>Throws a {@link ProtocolException} if the request contains a {@code Cookie} header to prevent sensitive data leakage.</li>
120 * <li>Throws a {@link ProtocolException} if the request contains a body.</li>
121 * </ul>
122 *
123 * @param request The incoming HTTP request. Cannot be {@code null}.
124 * @param entity Details of the request entity. Can be {@code null}.
125 * @param context The HTTP context.
126 * @throws HttpException If a protocol error occurs.
127 * @throws IOException If an I/O error occurs.
128 */
129 @Override
130 public void process(final HttpRequest request, final EntityDetails entity, final HttpContext context)
131 throws HttpException, IOException {
132
133 Args.notNull(request, "HTTP request");
134 Args.notNull(context, "HTTP context");
135
136 // Check if the request method is TRACE
137 if (Method.TRACE.isSame(request.getMethod())) {
138
139 // A client MUST NOT send content in a TRACE request.
140 if (entity != null) {
141 throw new ProtocolException("TRACE request MUST NOT contain a request body.");
142 }
143
144 // Check for sensitive headers
145 final Header authHeader = request.getHeader(HttpHeaders.AUTHORIZATION);
146 if (authHeader != null) {
147 throw new ProtocolException("TRACE request MUST NOT contain an Authorization header.");
148 }
149
150 // Check for cookies
151 final Header cookieHeader = request.getHeader(HttpHeaders.COOKIE);
152 if (cookieHeader != null) {
153 throw new ProtocolException("TRACE request MUST NOT contain a Cookie header.");
154 }
155 }
156 }
157 }