Request decompression in ASP.NET Core
Note
This isn't the latest version of this article. For the current release, see the .NET 9 version of this article.
Warning
This version of ASP.NET Core is no longer supported. For more information, see the .NET and .NET Core Support Policy. For the current release, see the .NET 9 version of this article.
Important
This information relates to a pre-release product that may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
For the current release, see the .NET 9 version of this article.
By David Acker
Request decompression middleware:
- Enables API endpoints to accept requests with compressed content.
- Uses the
Content-Encoding
HTTP header to automatically identify and decompress requests which contain compressed content. - Eliminates the need to write code to handle compressed requests.
When the Content-Encoding
header value on a request matches one of the available decompression providers, the middleware:
- Uses the matching provider to wrap the HttpRequest.Body in an appropriate decompression stream.
- Removes the
Content-Encoding
header, indicating that the request body is no longer compressed.
Requests that don't include a Content-Encoding
header are ignored by the request decompression middleware.
Decompression:
- Occurs when the body of the request is read. That is, decompression occurs at the endpoint on model binding. The request body isn't decompressed eagerly.
- When attempting to read the decompressed request body with invalid compressed data for the specified
Content-Encoding
, an exception is thrown. Brotli can throw System.InvalidOperationException: Decoder ran into invalid data. Deflate and GZip can throw System.IO.InvalidDataException: The archive entry was compressed using an unsupported compression method.
If the middleware encounters a request with compressed content but is unable to decompress it, the request is passed to the next delegate in the pipeline. For example, a request with an unsupported Content-Encoding
header value or multiple Content-Encoding
header values is passed to the next delegate in the pipeline.
Configuration
The following code uses AddRequestDecompression(IServiceCollection) and UseRequestDecompression to enable request decompression for the default Content-Encoding
types:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRequestDecompression();
var app = builder.Build();
app.UseRequestDecompression();
app.MapPost("/", (HttpRequest request) => Results.Stream(request.Body));
app.Run();
Default decompression providers
The Content-Encoding
header values that the request decompression middleware supports by default are listed in the following table:
Content-Encoding header values |
Description |
---|---|
br |
Brotli compressed data format |
deflate |
DEFLATE compressed data format |
gzip |
Gzip file format |
Custom decompression providers
Support for custom encodings can be added by creating custom decompression provider classes that implement IDecompressionProvider:
public class CustomDecompressionProvider : IDecompressionProvider
{
public Stream GetDecompressionStream(Stream stream)
{
// Perform custom decompression logic here
return stream;
}
}
Custom decompression providers are registered with RequestDecompressionOptions along with their corresponding Content-Encoding
header values:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRequestDecompression(options =>
{
options.DecompressionProviders.Add("custom", new CustomDecompressionProvider());
});
var app = builder.Build();
app.UseRequestDecompression();
app.MapPost("/", (HttpRequest request) => Results.Stream(request.Body));
app.Run();
Request size limits
In order to protect against zip bombs or decompression bombs:
- The maximum size of the decompressed request body is limited to the request body size limit enforced by the endpoint or server.
- If the number of bytes read from the decompressed request body stream exceeds the limit, an InvalidOperationException is thrown to prevent additional bytes from being read from the stream.
In order of precedence, the maximum request size for an endpoint is set by:
- IRequestSizeLimitMetadata.MaxRequestBodySize, such as RequestSizeLimitAttribute or DisableRequestSizeLimitAttribute for MVC endpoints.
- The global server size limit IHttpMaxRequestBodySizeFeature.MaxRequestBodySize.
MaxRequestBodySize
can be overridden per request with IHttpMaxRequestBodySizeFeature.MaxRequestBodySize, but defaults to the limit configured for the web server implementation.
Web server implementation | MaxRequestBodySize configuration |
---|---|
HTTP.sys | HttpSysOptions.MaxRequestBodySize |
IIS | IISServerOptions.MaxRequestBodySize |
Kestrel | KestrelServerLimits.MaxRequestBodySize |
Warning
Disabling the request body size limit poses a security risk in regards to uncontrolled resource consumption, particularly if the request body is being buffered. Ensure that safeguards are in place to mitigate the risk of denial-of-service (DoS) attacks.
Additional Resources
ASP.NET Core