Revision control
+ // 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.
+ */