How to Enable Strict AVIF Compliance in libavif

This article explains how the libavif library enforces strict adherence to the AV1 Image File Format (AVIF) specifications using its dedicated API flags. You will learn about the avifStrictFlag enumeration, the specific validation checks each flag performs during image decoding, and how developers can configure these settings to ensure security, standard compliance, and consistent rendering across different platforms.

The libavif library, the de facto standard open-source library for encoding and decoding AVIF files, provides a robust validation mechanism through its decoder configuration. By default, image decoders often attempt to be lenient, parsing and displaying files even if they contain minor specification violations. However, for applications requiring high security, strict standards compliance, or precise rendering, libavif offers the strictFlags member in its avifDecoder struct.

To define and control compliance, libavif utilizes the avifStrictFlag enum. Developers can combine these bitwise flags to customize the level of strictness required during the decoding process.

The Strictness API Flags

The core compliance flags defined in libavif include:

• AVIF_STRICT_DISABLED (0): This disables all strict validation checks. The decoder will attempt to parse the file even if it violates non-critical parts of the ISO/IEC 23000-22 (AVIF) specification.
• AVIF_STRICT_PIXI (1 << 0): This flag enforces correct configuration of the Pixel Information (pixi) box. If the pixi box specifies a channel depth or channel count that does not match the actual AV1 bitstream properties, decoding will fail.
• AVIF_STRICT_CLAP (1 << 1): Enforces strict validation on the Clean Aperture (clap) box. The clap box defines the exact visible portion of the image. Under strict mode, the decoder rejects files if the crop coordinates are invalid, exceed image boundaries, or result in fractional pixel offsets that violate the specification.
• AVIF_STRICT_ALPHA_ISPE (1 << 2): This flag ensures that the auxiliary alpha image (if present) has an Image Spatial Extents (ispe) box that perfectly matches the dimensions of the primary color image. Mismatches are treated as errors to prevent rendering glitches and memory boundary issues.
• AVIF_STRICT_MANDATORY_COLO (1 << 3): Enforces the presence of color-related properties. The AVIF specification mandates certain color description boxes depending on the container configuration. This flag ensures the files explicitly and correctly define their color space.
• AVIF_STRICT_ENABLED: This is a helper macro that combines all of the individual flags (AVIF_STRICT_PIXI | AVIF_STRICT_CLAP | AVIF_STRICT_ALPHA_ISPE | AVIF_STRICT_MANDATORY_COLO). Enabling this flag ensures maximum compliance with the AVIF specification.

Implementing Strict Mode in Code

To implement strict validation, you must configure the strictFlags property of the avifDecoder instance before reading the container.

#include "avif/avif.h"

void decode_strict_avif(const uint8_t* raw_data, size_t data_size) {
    avifDecoder * decoder = avifDecoderCreate();
    
    // Enable maximum strict adherence to the AVIF specification
    decoder->strictFlags = AVIF_STRICT_ENABLED;

    // Alternatively, enable only specific checks (e.g., CLAP and PIXI)
    // decoder->strictFlags = AVIF_STRICT_CLAP | AVIF_STRICT_PIXI;

    avifResult result = avifDecoderSetIOMemory(decoder, raw_data, data_size);
    if (result == AVIF_RESULT_OK) {
        result = avifDecoderParse(decoder);
        if (result != AVIF_RESULT_OK) {
            // If the file violates specified AVIF rules, parsing fails here
            printf("AVIF validation failed: %s\n", avifResultToString(result));
        }
    }
    
    avifDecoderDestroy(decoder);
}

By leveraging these API flags, developers can safeguard their applications against malformed files that could exploit parser vulnerabilities, while guaranteeing that all processed AVIF images strictly conform to standardized specifications.