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 qtopenapi-security.html
\title Qt OpenAPI Security Considerations
\ingroup security-considerations
\brief Security considerations and recommended network setups for Qt OpenAPI.
\section1 Handling OpenAPI Specifications from External Sources
The OpenAPI specification file is the primary input to the code generation
pipeline. It defines the entire surface of the generated client: API
endpoints, data models, server URLs, authentication schemes, and
operational parameters. Because the generator translates spec content
directly into C++ source code, it should be used with trusted input only.
\b{Users are responsible for vetting any OpenAPI specification obtained
from an external source before generating code from it.} A specification
downloaded from a third-party service or public repository may contain
values that, once compiled, behave in unexpected or harmful ways. Before
using an external specification, review it for:
\list
\li Unexpected or suspiciously complex server URL patterns and variable
definitions.
\li Description fields or extension attributes containing content that
should not appear in generated source code.
\li Overly deep or circular model references that could affect runtime
stability.
\li Server variable enum values or defaults that could alter the
intended request targets.
\endlist
While the generator applies escaping to prevent direct code injection
through spec-derived strings, a malicious specification still controls
the structure and behavior of the generated client — including class
names, endpoint URLs, data flow, and operational semantics. No amount
of escaping can make a fundamentally untrusted specification safe to
use without prior review.
\section1 Protecting Against Resource Exhaustion
In addition to reviewing the semantic content of an OpenAPI specification,
users processing specifications from untrusted sources should consider
limiting the resources consumed during code generation and execution.
A maliciously crafted specification may cause excessive resource consumption
during the code generation process itself, for example through extremely
complex schema structures, large numbers of references, or deeply nested
models. Furthermore, generated code derived from such a specification may
consume excessive resources at runtime if the specification is designed
to trigger resource-intensive code paths or data structures, potentially
leading to resource exhaustion or denial-of-service conditions.
The underlying YAML parser supports several configuration options that
help mitigate denial-of-service attacks caused by malicious YAML input,
such as excessive alias expansion (for example, Billion Laughs attacks),
deeply nested collections, recursive mapping keys, or unusually large
documents. These limits can be configured through JVM system properties
(for example, using \c JAVA_OPTIONS or \c JAVA_TOOL_OPTIONS), including:
\table
\header
\li Property
\li Purpose
\row
\li \c maxYamlReferences
\li Limits the total count of all YAML aliases (*) in a file,
regardless of their data type. Acts as a broad anti-DoS counter
for text-level duplication.
Example of anchor and alias usage:
\code
// Declaration (also called an anchor)
original: &name "John"
// Usage
copy: *name
\endcode
Aliases affect raw YAML syntax parsing; completely unrelated
to OpenAPI $ref pointers.
\row
\li \c maxYamlAliasesForCollections
\li Limits aliases (*) that specifically point to arrays or objects,
ignoring plain strings. This mitigates Billion Laughs-style
attacks.
\row
\li \c supportYamlAnchors
\li Enables or disables YAML anchors processing entirely. Disabling
anchors removes an entire class of alias-based attacks.
\row
\li \c maxYamlDepth
\li Limits the maximum nesting depth of YAML collections to prevent
stack exhaustion and excessive parser recursion.
Every time you indent further to the right to create a sub-object
or a sub-list, the vertical nesting depth increases by 1.
Note that it only counts literal file indentation and completely
ignores logical OpenAPI \c $ref pointers.
\row
\li \c maxYamlCodePoints
\li Limits the total size of the YAML input document.
\endtable
Example:
\code
qt_add_openapi_client(Example
SPEC_FILE
${CMAKE_CURRENT_SOURCE_DIR}/unstructed-source-spec.yaml
JAVA_OPTIONS
-DmaxYamlAliasesForCollections=10
-DmaxYamlDepth=100
-DmaxYamlCodePoints=5000000
-DmaxYamlReferences=10
-DsupportYamlAnchors=false
OUTPUT_DIRECTORY
${CMAKE_CURRENT_BINARY_DIR}
)
\endcode
While the YAML parser stops syntax-level attacks, it cannot prevent
all variants of resource exhaustion. Neither the parser nor the
OpenAPI Generator limits schema complexity, measures the depth of \c $ref
chains, or calculates the stack space the resulting C++ structure
will consume.
Consequently, successful code generation and compilation do not
guarantee runtime safety. When processing production network traffic,
the application remains vulnerable to two critical vectors:
\list
\li Horizontal Expansion (Wide Payloads) -
a schema can have minimal nesting depth but allow an immense number
of sibling objects. Parsing these at runtime demands excessive heap
allocation, causing severe memory fragmentation or Out-of-Memory (OOM)
crashes.
\li Vertical Deepening (Deep Payloads) -
a schema might validly define deeply nested arrays of arrays or object
chains that pass compilation. However, when a malicious payload
exploiting this depth arrives over the network, the runtime parser's
recursive execution will rapidly exhaust the thread's fixed stack
space, triggering an unrecoverable Stack Overflow.
\endlist
For applications that process specifications from untrusted sources,
users should perform an additional manual review of the specification
before invoking the generator. Consider checking the following:
\table
\header
\li Recommended review
\li Purpose
\row
\li Circular \c $ref references
\li Prevents recursive reference graphs that may increase processing
complexity or expose implementation-specific limitations.
\row
\li Maximum schema nesting depth (nested objects)
\li Avoids excessively deep object hierarchies.
\row
\li Maximum \c $ref resolution depth (nested schema refs)
\li Avoids excessively long reference chains.
\row
\li Maximum number of schemas
\li Limits the overall size and complexity of the specification.
\row
\li Maximum array and map nesting depth
\li Avoids deeply nested collection types that may consume
excessive resources.
\endtable
\section1 Network communication
Generated clients perform HTTP requests using \l{QNetworkAccessManager}.
Credentials (API keys, bearer tokens, Basic Auth) are attached to outgoing
requests. The library does not enforce HTTPS; applications must ensure
that credentials are transmitted only over secure connections.
*/