Revision control
Copy as Markdown
// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qthttpserver-security.html
\title Qt HTTP Server Security Considerations
\ingroup security
\brief Provides the recommended security settings for Qt HTTP Server.
\section1 Overview
Qt HTTP Server provides several configuration settings to help protect
an application against misuse scenarios such as malformed requests or
unauthorized access. Qt 6.10 added several security configuration
settings. This page summarizes recommended configurations and explains
when and how to use them.
\warning Do not expose Qt HTTP Server directly to the internet. Qt HTTP
Server is not hardened against network-based attacks.
\section1 Network setups and configurations
Here are different ways to set up a network with a Qt HTTP Server.
\section2 No internet access
Ideally there should be no access to the internet at all. This is the
safest setup, but you often need internet access. If Qt HTTP Server
is bound to localhost or to a \l{QLocalServer}, it does not accept
connections from the internet. If multiple clients are connected to
127.0.0.1, the connections are added to connections per host,
and \l{QHttpServerConfiguration::}{setMaximumConnectionsPerHost()}
is affected. By default, no per-host connection limit is set.
\section2 Binding to QSslServer on the internet
It is possible, but not supported to bind the Qt HTTP Server to a
\l{QSslServer} that is bound to a network interface that is reachable from
the internet. Despite all the options in \l{QHttpServerConfiguration}, this
setup is not supported because Qt HTTP Server is not sufficiently
hardened.
\section1 Application setup
If using a thread pool, make sure it is not so large that the server
cannot handle simultaneous, resource-intensive incoming requests.
Though the \l{QHttpServer::}{route()} call makes parsing from the URL
in the HTTP requests easy, it is the developer's responsibility to
handle input validation.
\section1 Qt HTTP Server security configuration
Configure Qt HTTP Server through the \l{QHttpServerConfiguration} class.
Adjust the limits based on your platform's capabilities and network setup.
\section2 Rate limits
\list
\li Configure the maximum number of requests per second
per client IP using
\l{QHttpServerConfiguration::}{setRateLimitPerSecond()}.
By default, there is no rate limit. When the limit is exceeded,
the server responds with status code 429 (Too Many Requests).
\li Configure the maximum number of simultaneous connections
using \l{QHttpServerConfiguration::}{setMaximumConnections()}.
By default, there is no connection limit. When the limit is
exceeded, the server responds with status code 429 (Too Many
Requests), and the connection is closed.
\li Configure the maximum number of simultaneous
connections per client IP using
\l{QHttpServerConfiguration::}{setMaximumConnectionsPerHost()}.
By default, there is no limit. When the limit is exceeded,
the server responds with status code 429 (Too Many Requests), and
the connection is closed.
\endlist
\section2 Connection limits
\list
\li Configure the maximum idle time for keep-alive connections
using \l{QHttpServerConfiguration::}{setKeepAliveTimeout()}.
By default, the timeout is 15 seconds.
\endlist
\section2 Allowlisting and denylisting
\list
\li Configure the list of client subnets that are allowed to access the
server using \l{QHttpServerConfiguration::}{setWhitelist()}.
By default, the allowlist is empty, and all clients are allowed.
If the allowlist is not empty, only addresses in this list
are accepted.
The allowlist is checked before the denylist.
\li Configure the denied client subnets using
\l{QHttpServerConfiguration::}{setBlacklist()}.
The denylist is only applied when the allowlist is empty.
By default, the denylist is empty.
\endlist
\section2 Request size limits
\list
\li Configure the maximum URL size using
\l{QHttpServerConfiguration::}{setMaximumUrlSize()}.
If the limit is exceeded, the server responds with HTTP status
code 414 (Request-URI Too Long).
The default maximum URL size is 64 KiB.
\li Configure the maximum total size of all HTTP request headers
using \l{QHttpServerConfiguration::}{setMaximumTotalHeaderSize()}.
If the limit is exceeded, the server responds with HTTP status code
431 (Request Header Fields Too Large).
The default total header size is 64 KiB.
\li Configure the maximum size of a single HTTP header field
using \l{QHttpServerConfiguration::}{setMaximumHeaderFieldSize()}.
If the limit is exceeded, the server responds with HTTP status code
431 (Request Header Fields Too Large).
The default maximum header field size is 48 KiB.
\li Configure the maximum number of HTTP header fields per request
using \l{QHttpServerConfiguration::}{setMaximumHeaderFieldCount()}.
If the limit is exceeded, the server responds with HTTP status code
431 (Request Header Fields Too Large).
The default maximum header field count is 128.
\li Configure the maximum request body size using
\l{QHttpServerConfiguration::}{setMaximumBodySize()}.
If the limit is exceeded, the server responds with HTTP status code
413 (Content Too Large).
The default maximum body size is 32 MiB.
\endlist
\note Always use the latest security updates for Qt and all dependent libraries.
*/