Qt OpenAPI Security Considerations | Qt OpenAPI | Qt 6.12.0
Description: Security considerations and recommended network setups for Qt OpenAPI.

- Qt 6.12
- Qt OpenAPI
- Qt OpenAPI Security Considerations
- Qt 6.12.0 Reference Documentation

# Qt OpenAPI Security Considerations

## 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.

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:

- Unexpected or suspiciously complex server URL patterns and variable definitions.
- Description fields or extension attributes containing content that should not appear in generated source code.
- Overly deep or circular model references that could affect runtime stability.
- Server variable enum values or defaults that could alter the intended request targets.

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.

## 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 `JAVA_OPTIONS` or `JAVA_TOOL_OPTIONS`), including:

Property | Purpose
--- | ---
`maxYamlReferences` | 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:
     // Declaration (also called an anchor)
     original: &name "John"
     // Usage
     copy: *name
Aliases affect raw YAML syntax parsing; completely unrelated to OpenAPI $ref pointers.
`maxYamlAliasesForCollections` | Limits aliases (*) that specifically point to arrays or objects, ignoring plain strings. This mitigates Billion Laughs-style attacks.
`supportYamlAnchors` | Enables or disables YAML anchors processing entirely. Disabling anchors removes an entire class of alias-based attacks.
`maxYamlDepth` | 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 `$ref` pointers.
`maxYamlCodePoints` | Limits the total size of the YAML input document.

Example:

     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}
     )

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 `$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:

- 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.
- 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.

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:

Recommended review | Purpose
--- | ---
Circular `$ref` references | Prevents recursive reference graphs that may increase processing complexity or expose implementation-specific limitations.
Maximum schema nesting depth (nested objects) | Avoids excessively deep object hierarchies.
Maximum `$ref` resolution depth (nested schema refs) | Avoids excessively long reference chains.
Maximum number of schemas | Limits the overall size and complexity of the specification.
Maximum array and map nesting depth | Avoids deeply nested collection types that may consume excessive resources.

## Network communication

Generated clients perform HTTP requests using 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.