En esta página

Consideraciones de seguridad de Qt OpenAPI

Gestión de especificaciones OpenAPI procedentes de fuentes externas

El archivo de especificación OpenAPI es la entrada principal del proceso de generación de código. Define toda la superficie del cliente generado: puntos finales de la API, modelos de datos, URL de servidor, esquemas de autenticación y parámetros operativos. Dado que el generador traduce el contenido de la especificación directamente a código fuente C++, solo debe utilizarse con entradas fiables.

Los usuarios son responsables de verificar cualquier especificación OpenAPI obtenida de una fuente externa antes de generar código a partir de ella. Una especificación descargada de un servicio de terceros o de un repositorio público puede contener valores que, una vez compilados, se comporten de forma inesperada o perjudicial. Antes de utilizar una especificación externa, revísala para detectar:

  • Patrones de URL de servidor y definiciones de variables inesperados o sospechosamente complejos.
  • Campos de descripción o atributos de extensión que contengan contenido que no debería aparecer en el código fuente generado.
  • Referencias de modelo excesivamente profundas o circulares que podrían afectar a la estabilidad en tiempo de ejecución.
  • Valores de enumeración o valores predeterminados de variables del servidor que podrían alterar los destinos de solicitud previstos.

Aunque el generador aplica el escape para evitar la inyección directa de código a través de cadenas derivadas de la especificación, una especificación maliciosa sigue controlando la estructura y el comportamiento del cliente generado —incluidos los nombres de clase, las URL de los puntos finales, el flujo de datos y la semántica operativa—. Ningún nivel de escape puede hacer que una especificación fundamentalmente poco fiable sea segura de usar sin una revisión previa.

Protección contra el agotamiento de recursos

Además de revisar el contenido semántico de una especificación OpenAPI, los usuarios que procesen especificaciones procedentes de fuentes no fiables deberían considerar la posibilidad de limitar los recursos consumidos durante la generación y ejecución del código.

Una especificación elaborada con fines maliciosos puede provocar un consumo excesivo de recursos durante el propio proceso de generación de código, por ejemplo, a través de estructuras de esquemas extremadamente complejas, un gran número de referencias o modelos profundamente anidados. Además, el código generado a partir de dicha especificación puede consumir recursos excesivos en tiempo de ejecución si la especificación está diseñada para activar rutas de código o estructuras de datos que consumen muchos recursos, lo que podría provocar el agotamiento de los recursos o situaciones de denegación de servicio.

El analizador YAML subyacente admite varias opciones de configuración que ayudan a mitigar los ataques de denegación de servicio causados por entradas YAML maliciosas, como la expansión excesiva de alias (por ejemplo, los ataques «Billion Laughs»), colecciones profundamente anidadas, claves de mapeo recursivas o documentos inusualmente grandes. Estos límites se pueden configurar a través de las propiedades del sistema de la JVM (por ejemplo, utilizando JAVA_OPTIONS o JAVA_TOOL_OPTIONS), entre las que se incluyen:

PropiedadFinalidad
maxYamlReferencesLimita el recuento total de todos los alias YAML (*) en un archivo, independientemente de su tipo de datos. Actúa como un amplio mecanismo anti-DoS contra la duplicación a nivel de texto. Ejemplo de uso de anclajes y alias:
// Declaration (also called an anchor)
original: &name "John"
// Usage
copy: *name

Los alias afectan al análisis sintáctico del YAML sin procesar; no guardan relación alguna con los punteros $ref de OpenAPI.

maxYamlAliasesForCollectionsLimita los alias (*) que apuntan específicamente a matrices u objetos, ignorando las cadenas de texto simples. Esto mitiga los ataques del tipo «Billion Laughs».
supportYamlAnchorsHabilita o deshabilita por completo el procesamiento de anclajes YAML. Al deshabilitar los anclajes, se elimina toda una clase de ataques basados en alias.
maxYamlDepthLimita la profundidad máxima de anidamiento de las colecciones YAML para evitar el agotamiento de la pila y una recursión excesiva del analizador. Cada vez que se aumenta la sangría hacia la derecha para crear un subobjeto o una sublista, la profundidad de anidamiento vertical aumenta en 1. Ten en cuenta que solo cuenta la sangría literal del archivo e ignora por completo los punteros lógicos « $ref » de OpenAPI.
maxYamlCodePointsLimita el tamaño total del documento de entrada YAML.

Ejemplo:

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

Aunque el analizador sintáctico de YAML detiene los ataques a nivel sintáctico, no puede prevenir todas las variantes de agotamiento de recursos. Ni el analizador sintáctico ni el OpenAPI Generator limitan la complejidad del esquema, miden la profundidad de las cadenas « $ref » ni calculan el espacio de pila que consumirá la estructura C++ resultante. Por consiguiente, el éxito en la generación y compilación del código no garantiza la seguridad en tiempo de ejecución. Al procesar el tráfico de red en producción, la aplicación sigue siendo vulnerable a dos vectores críticos:

  • Expansión horizontal (cargas útiles amplias): un esquema puede tener una profundidad de anidamiento mínima, pero permitir un número inmenso de objetos hermanos. Analizar estos en tiempo de ejecución exige una asignación excesiva de memoria dinámica, lo que provoca una grave fragmentación de la memoria o fallos por falta de memoria (OOM).
  • Profundización vertical (cargas útiles profundas): un esquema puede definir válidamente matrices de matrices profundamente anidadas o cadenas de objetos que superan la compilación. Sin embargo, cuando llega a través de la red una carga maliciosa que aprovecha esta profundidad, la ejecución recursiva del analizador en tiempo de ejecución agotará rápidamente el espacio fijo de la pila del hilo, lo que provocará un desbordamiento de pila irrecuperable.

En el caso de aplicaciones que procesan especificaciones procedentes de fuentes no fiables, los usuarios deben realizar una revisión manual adicional de la especificación antes de invocar el generador. Se recomienda comprobar lo siguiente:

Revisión recomendadaFinalidad
Referencias circulares de « $ref »Evita los grafos de referencias recursivos que pueden aumentar la complejidad del procesamiento o poner de manifiesto limitaciones específicas de la implementación.
Profundidad máxima de anidamiento del esquema (objetos anidados)Evita jerarquías de objetos excesivamente profundas.
Profundidad máxima de resolución de « $ref » (referencias de esquema anidadas)Evita cadenas de referencias excesivamente largas.
Número máximo de esquemasLimita el tamaño y la complejidad generales de la especificación.
Profundidad máxima de anidamiento de matrices y mapasEvita tipos de colección profundamente anidados que puedan consumir recursos excesivos.

Comunicación de red

Los clientes generados realizan solicitudes HTTP utilizando QNetworkAccessManager. Las credenciales (claves API, tokens de portador, autenticación básica) se adjuntan a las solicitudes salientes. La biblioteca no exige el uso de HTTPS; las aplicaciones deben asegurarse de que las credenciales se transmitan únicamente a través de conexiones seguras.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.