libextractor

heif_extractor.c (48697B)

---

 /*
      This file is part of libextractor.
      Copyright (C) 2026 Vidyut Samanta and Christian Grothoff
 
      libextractor is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published
      by the Free Software Foundation; either version 3, or (at your
      option) any later version.
 
      libextractor is distributed in the hope that it will be useful, but
      WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
      General Public License for more details.
 
      You should have received a copy of the GNU General Public License
      along with libextractor; see the file COPYING.  If not, write to the
      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
      Boston, MA 02110-1301, USA.
  */
 /**
  * @file plugins/heif_extractor.c
  * @brief plugin to support HEIF/HEIC and AVIF still images
  * @author Christian Grothoff
  *
  * HEIC (the default camera format on recent iPhones) and AVIF (now
  * common on the web) are both ISO base media file format containers
  * carrying a still image instead of a movie.  We parse the container
  * only: no HEVC or AV1 bitstream is decoded, and no external decoder
  * library is linked, because this is a fast identification pass.
  *
  * Structure, per ISO/IEC 14496-12 (box structure), ISO/IEC 23008-12
  * (HEIF item structures) and the AV1 Image File Format (AVIF brands):
  *
  *   ftyp                       major brand + compatible brands
  *   meta                       (FullBox)
  *     hdlr                     'pict' for a still image collection
  *     pitm                     which item is the displayed image
  *     iinf / infe              the items and their types
  *     iref                     thumbnail / auxiliary relationships
  *     iprp
  *       ipco                   the properties, addressed by 1-based index
  *         ispe pixi irot imir colr av1C hvcC ...
  *       ipma                   item -> property index associations
  *   mdat                       the coded data (never read here)
  *   moov                       only for image sequences (bursts, Live Photos)
  *
  * Every box walk below is bounded by the extent of its parent box, never
  * by the size of the file, and the whole parse shares one box budget and
  * one byte budget so that a crafted file cannot make us loop or read the
  * whole volume.  There is no recursion: the nesting we care about is
  * fixed and spelled out as nested calls.
  */
 #include "platform.h"
 #include "extractor.h"
 #include "forensics.h"
 
 
 /**
  * Total number of boxes we are willing to look at in one file.
  */
 #define HEIF_MAX_BOXES 4096
 
 /**
  * Total number of bytes we are willing to read from one file.  Header
  * parsing needs a few kilobytes; anything beyond this is a file trying
  * to make us do work.
  */
 #define HEIF_READ_BUDGET (256 * 1024)
 
 /**
  * Maximum number of compatible brands we report.
  */
 #define HEIF_MAX_BRANDS 32
 
 /**
  * Maximum number of property boxes we index out of 'ipco'.
  */
 #define HEIF_MAX_PROPS 64
 
 /**
  * Maximum number of properties we follow for the primary item.
  */
 #define HEIF_MAX_ASSOC 32
 
 /**
  * Maximum number of 'infe' entries we classify.  The reported item
  * count still comes from the 'iinf' header, so a truncated walk does
  * not falsify #EXTRACTOR_METATYPE_ENTRY_COUNT.
  */
 #define HEIF_MAX_INFE 512
 
 /**
  * Maximum number of item references we follow.
  */
 #define HEIF_MAX_IREF 512
 
 /**
  * Largest 'ipma' box we pull into memory.
  */
 #define HEIF_IPMA_MAX 8192
 
 /**
  * Seconds between 1904-01-01 (the ISO-BMFF epoch) and 1970-01-01.
  */
 #define HEIF_EPOCH_OFFSET 2082844800LL
 
 
 /**
  * One box, as located by #heif_next_box().
  */
 struct HeifBox
 {
   /**
    * Four character box type.  Not NUL terminated.
    */
   unsigned char type[4];
 
   /**
    * Absolute offset of the first payload byte.
    */
   uint64_t payload;
 
   /**
    * Absolute offset one past the last payload byte.
    */
   uint64_t end;
 };
 
 
 /**
  * One entry of the 'ipco' property container, addressed by its 1-based
  * index from 'ipma'.
  */
 struct HeifProp
 {
   /**
    * Four character property box type.
    */
   unsigned char type[4];
 
   /**
    * Absolute offset of the first payload byte.
    */
   uint64_t payload;
 
   /**
    * Absolute offset one past the last payload byte.
    */
   uint64_t end;
 };
 
 
 /**
  * Everything we carry through the parse.
  */
 struct HeifState
 {
   /**
    * Extraction context we were handed.
    */
   struct EXTRACTOR_ExtractContext *ec;
 
   /**
    * Properties found in 'ipco', in file order.
    */
   struct HeifProp props[HEIF_MAX_PROPS];
 
   /**
    * Property indices (1-based) associated with the primary item.
    */
   unsigned int assoc[HEIF_MAX_ASSOC];
 
   /**
    * Bytes we may still read.
    */
   uint64_t budget;
 
   /**
    * Boxes we may still visit.
    */
   unsigned int boxes;
 
   /**
    * Number of entries used in @e props.
    */
   unsigned int num_props;
 
   /**
    * Number of entries used in @e assoc.
    */
   unsigned int num_assoc;
 
   /**
    * Item ID of the primary item, from 'pitm'.
    */
   uint32_t primary_item;
 
   /**
    * Number of items declared by 'iinf'.
    */
   uint32_t num_items;
 
   /**
    * Number of coded image items seen.
    */
   unsigned int num_image_items;
 
   /**
    * Number of items that are the source of a 'thmb' reference.
    */
   unsigned int num_thumbnails;
 
   /**
    * Number of items that are the source of an 'auxl' reference
    * (alpha and depth planes).
    */
   unsigned int num_auxiliary;
 
   /**
    * Number of 'Exif' items.
    */
   unsigned int num_exif;
 
   /**
    * Number of 'mime' (XMP and friends) items.
    */
   unsigned int num_mime;
 
   /**
    * Item type of the primary item, if we saw its 'infe'.
    */
   unsigned char primary_type[4];
 
   /**
    * True if @e primary_item is valid.
    */
   int have_pitm;
 
   /**
    * True if @e primary_type is valid.
    */
   int have_primary_type;
 
   /**
    * True if a 'moov' box was found, which makes this a sequence.
    */
   int have_moov;
 
   /**
    * Set once #EXTRACTOR_ExtractContext::proc asked us to stop.
    */
   int stop;
 };
 
 
 /**
  * Read @a len bytes at @a offset, charged against the read budget.
  *
  * @param hs parser state
  * @param offset absolute offset to read from
  * @param buf where to put the data
  * @param len number of bytes to read
  * @return 1 on success, 0 on a short file or an exhausted budget
  */
 static int
 heif_read (struct HeifState *hs,
            uint64_t offset,
            void *buf,
            size_t len)
 {
   if ( (len > hs->budget) ||
        (offset > INT64_MAX) )
     return 0;
   hs->budget -= len;
   return EXTRACTOR_forensic_read_ (hs->ec,
                                    (int64_t) offset,
                                    buf,
                                    len);
 }
 
 
 /**
  * Test whether @a box has the given four character type.
  *
  * @param box the box
  * @param type four characters to compare against
  * @return 1 on a match, 0 otherwise
  */
 static int
 heif_is (const struct HeifBox *box,
          const char *type)
 {
   return 0 == memcmp (box->type,
                       type,
                       4);
 }
 
 
 /**
  * Locate the box that starts at @a pos inside a parent that ends at
  * @a limit.
  *
  * Handles all three ISO-BMFF size encodings: a 32-bit size, size 1
  * meaning a 64-bit largesize follows the type, and size 0 meaning "up
  * to the end of the enclosing box".  A size that does not cover its own
  * header, or that runs past the parent, terminates the walk rather than
  * being clamped: a box that lies about its size is not one we want to
  * keep reading past.
  *
  * @param hs parser state
  * @param pos absolute offset of the box header
  * @param limit absolute offset one past the end of the parent
  * @param[out] box the box that was found
  * @return 1 on success, 0 if there is no further box here
  */
 static int
 heif_next_box (struct HeifState *hs,
                uint64_t pos,
                uint64_t limit,
                struct HeifBox *box)
 {
   unsigned char hdr[8];
   uint64_t size;
   unsigned int hlen = 8;
 
   if (0 == hs->boxes)
     return 0;
   hs->boxes--;
   if ( (pos >= limit) ||
        (limit - pos < 8) )
     return 0;
   if (! heif_read (hs,
                    pos,
                    hdr,
                    sizeof (hdr)))
     return 0;
   size = EXTRACTOR_forensic_be32_ (hdr);
   memcpy (box->type,
           &hdr[4],
           4);
   if (1 == size)
   {
     unsigned char large[8];
 
     if (limit - pos < 16)
       return 0;
     if (! heif_read (hs,
                      pos + 8,
                      large,
                      sizeof (large)))
       return 0;
     size = EXTRACTOR_forensic_be64_ (large);
     hlen = 16;
     if (size < 16)
       return 0;
   }
   else if (0 == size)
   {
     size = limit - pos;   /* extends to the end of the parent */
   }
   else if (size < 8)
   {
     return 0;   /* smaller than its own header */
   }
   if (size > limit - pos)
     return 0;
   box->payload = pos + hlen;
   box->end = pos + size;
   if (box->payload > box->end)
     return 0;
   return 1;
 }
 
 
 /**
  * Number of payload bytes in @a box.
  *
  * @param box the box
  * @return payload length
  */
 static uint64_t
 heif_payload_len (const struct HeifBox *box)
 {
   return box->end - box->payload;
 }
 
 
 /**
  * Read the version byte of a FullBox.
  *
  * @param hs parser state
  * @param box the box, which must be a FullBox
  * @param[out] version the version byte
  * @param[out] flags the 24-bit flags field
  * @return 1 on success, 0 if the box is too short
  */
 static int
 heif_full_header (struct HeifState *hs,
                   const struct HeifBox *box,
                   unsigned int *version,
                   uint32_t *flags)
 {
   unsigned char vf[4];
 
   if (heif_payload_len (box) < 4)
     return 0;
   if (! heif_read (hs,
                    box->payload,
                    vf,
                    sizeof (vf)))
     return 0;
   *version = vf[0];
   *flags = EXTRACTOR_forensic_be32_ (vf) & 0xFFFFFF;
   return 1;
 }
 
 
 /**
  * A brand we recognise, and what it says about the file.
  */
 struct HeifBrand
 {
   /**
    * The four character brand.
    */
   const char *brand;
 
   /**
    * MIME type family, without the "-sequence" suffix.
    */
   const char *family;
 
   /**
    * Coding format the brand implies, NULL if the brand is generic.
    */
   const char *codec;
 
   /**
    * True if the brand denotes an image sequence rather than a still.
    */
   int sequence;
 };
 
 
 /**
  * Brands that make a file ours.  'mif1'/'msf1' are the generic HEIF
  * brands and say nothing about the codec, which is why the compatible
  * brand list has to be consulted as well: "mif1" as major brand with
  * "avif" among the compatible brands is what several AVIF encoders
  * produce.
  */
 static const struct HeifBrand heif_brands[] = {
   { "heic", "image/heic", "HEVC", 0 },
   { "heix", "image/heic", "HEVC", 0 },
   { "heim", "image/heic", "HEVC", 0 },
   { "heis", "image/heic", "HEVC", 0 },
   { "hevc", "image/heic", "HEVC", 1 },
   { "hevx", "image/heic", "HEVC", 1 },
   { "hevm", "image/heic", "HEVC", 1 },
   { "hevs", "image/heic", "HEVC", 1 },
   { "avif", "image/avif", "AV1", 0 },
   { "avis", "image/avif", "AV1", 1 },
   { "mif1", "image/heif", NULL, 0 },
   { "mif2", "image/heif", NULL, 0 },
   { "msf1", "image/heif", NULL, 1 },
   { NULL, NULL, NULL, 0 }
 };
 
 
 /**
  * Look @a brand up in #heif_brands.
  *
  * @param brand four bytes from the file
  * @return the entry, or NULL if we do not know the brand
  */
 static const struct HeifBrand *
 heif_lookup_brand (const unsigned char *brand)
 {
   for (unsigned int i = 0; NULL != heif_brands[i].brand; i++)
     if (0 == memcmp (brand,
                      heif_brands[i].brand,
                      4))
       return &heif_brands[i];
   return NULL;
 }
 
 
 /**
  * Human readable name for an item type as it appears in 'infe'.
  *
  * @param type four bytes from the file
  * @return the name, or NULL if we do not know the type
  */
 static const char *
 heif_item_type_name (const unsigned char *type)
 {
   static const struct
   {
     const char *type;
     const char *name;
   } names[] = {
     { "hvc1", "HEVC" },
     { "hev1", "HEVC" },
     { "av01", "AV1" },
     { "avc1", "AVC" },
     { "vvc1", "VVC" },
     { "jpeg", "JPEG" },
     { "j2k1", "JPEG 2000" },
     { "grid", "tiled grid" },
     { "iovl", "overlay" },
     { "iden", "identity" },
     { "mask", "mask" },
     { NULL, NULL }
   };
 
   for (unsigned int i = 0; NULL != names[i].type; i++)
     if (0 == memcmp (type,
                      names[i].type,
                      4))
       return names[i].name;
   return NULL;
 }
 
 
 /**
  * True if @a type names a coded or derived image item, as opposed to a
  * metadata item such as 'Exif' or 'mime'.
  *
  * @param type four bytes from the file
  * @return 1 if this is an image item
  */
 static int
 heif_is_image_item (const unsigned char *type)
 {
   return NULL != heif_item_type_name (type);
 }
 
 
 /**
  * Parse the 'pitm' box, which names the item that a viewer displays.
  *
  * @param hs parser state
  * @param box the 'pitm' box
  */
 static void
 heif_parse_pitm (struct HeifState *hs,
                  const struct HeifBox *box)
 {
   unsigned char buf[4];
   unsigned int version;
   uint32_t flags;
 
   if (! heif_full_header (hs,
                           box,
                           &version,
                           &flags))
     return;
   if (0 == version)
   {
     if (heif_payload_len (box) < 6)
       return;
     if (! heif_read (hs,
                      box->payload + 4,
                      buf,
                      2))
       return;
     hs->primary_item = EXTRACTOR_forensic_be16_ (buf);
   }
   else
   {
     if (heif_payload_len (box) < 8)
       return;
     if (! heif_read (hs,
                      box->payload + 4,
                      buf,
                      4))
       return;
     hs->primary_item = EXTRACTOR_forensic_be32_ (buf);
   }
   hs->have_pitm = 1;
 }
 
 
 /**
  * Parse the 'iinf' box and its 'infe' children: how many items there
  * are, what kinds they are, and what the primary item is made of.
  *
  * @param hs parser state
  * @param box the 'iinf' box
  */
 static void
 heif_parse_iinf (struct HeifState *hs,
                  const struct HeifBox *box)
 {
   unsigned char buf[16];
   unsigned int version;
   uint32_t flags;
   uint64_t pos;
   unsigned int n;
 
   if (! heif_full_header (hs,
                           box,
                           &version,
                           &flags))
     return;
   if (0 == version)
   {
     if (heif_payload_len (box) < 6)
       return;
     if (! heif_read (hs,
                      box->payload + 4,
                      buf,
                      2))
       return;
     hs->num_items = EXTRACTOR_forensic_be16_ (buf);
     pos = box->payload + 6;
   }
   else
   {
     if (heif_payload_len (box) < 8)
       return;
     if (! heif_read (hs,
                      box->payload + 4,
                      buf,
                      4))
       return;
     hs->num_items = EXTRACTOR_forensic_be32_ (buf);
     pos = box->payload + 8;
   }
   n = 0;
   while ( (pos < box->end) &&
           (n < HEIF_MAX_INFE) )
   {
     struct HeifBox infe;
     unsigned int iversion;
     uint32_t item_id;
     const unsigned char *item_type;
     size_t need;
 
     if (! heif_next_box (hs,
                          pos,
                          box->end,
                          &infe))
       break;
     if (infe.end <= pos)
       break;   /* no forward progress */
     pos = infe.end;
     n++;
     if (! heif_is (&infe,
                    "infe"))
       continue;
     /* ItemInfoEntry: version 2 uses a 16-bit item_ID, version 3 and up
        a 32-bit one; both are followed by a 16-bit protection index and
        then the four character item_type.  Versions 0 and 1 predate
        item_type and carry a file name instead, which tells us nothing
        about the coding format. */
     need = 14;
     if (heif_payload_len (&infe) < 4)
       continue;
     if (heif_payload_len (&infe) < need)
       need = (size_t) heif_payload_len (&infe);
     if (need > sizeof (buf))
       need = sizeof (buf);
     if (! heif_read (hs,
                      infe.payload,
                      buf,
                      need))
       continue;
     iversion = buf[0];
     if (2 == iversion)
     {
       if (need < 12)
         continue;
       item_id = EXTRACTOR_forensic_be16_ (&buf[4]);
       item_type = &buf[8];
     }
     else if (iversion >= 3)
     {
       if (need < 14)
         continue;
       item_id = EXTRACTOR_forensic_be32_ (&buf[4]);
       item_type = &buf[10];
     }
     else
     {
       continue;   /* no item_type in this version */
     }
     if (heif_is_image_item (item_type))
       hs->num_image_items++;
     else if (0 == memcmp (item_type,
                           "Exif",
                           4))
       hs->num_exif++;
     else if (0 == memcmp (item_type,
                           "mime",
                           4))
       hs->num_mime++;
     if ( (hs->have_pitm) &&
          (item_id == hs->primary_item) )
     {
       memcpy (hs->primary_type,
               item_type,
               4);
       hs->have_primary_type = 1;
     }
   }
 }
 
 
 /**
  * Parse the 'iref' box: which items are thumbnails of, or auxiliary
  * planes for, another item.
  *
  * @param hs parser state
  * @param box the 'iref' box
  */
 static void
 heif_parse_iref (struct HeifState *hs,
                  const struct HeifBox *box)
 {
   unsigned int version;
   uint32_t flags;
   uint64_t pos;
   unsigned int n;
 
   if (! heif_full_header (hs,
                           box,
                           &version,
                           &flags))
     return;
   pos = box->payload + 4;
   n = 0;
   while ( (pos < box->end) &&
           (n < HEIF_MAX_IREF) )
   {
     struct HeifBox ref;
 
     if (! heif_next_box (hs,
                          pos,
                          box->end,
                          &ref))
       break;
     if (ref.end <= pos)
       break;   /* no forward progress */
     pos = ref.end;
     n++;
     /* Each child is one reference: its type is the relationship and its
        from_item_ID is the item that plays the subordinate role. */
     if (heif_is (&ref,
                  "thmb"))
       hs->num_thumbnails++;
     else if (heif_is (&ref,
                       "auxl"))
       hs->num_auxiliary++;
   }
 }
 
 
 /**
  * Parse the 'ipco' box, indexing its children so that 'ipma' can refer
  * to them by their 1-based position.
  *
  * @param hs parser state
  * @param box the 'ipco' box
  */
 static void
 heif_parse_ipco (struct HeifState *hs,
                  const struct HeifBox *box)
 {
   uint64_t pos = box->payload;
 
   while ( (pos < box->end) &&
           (hs->num_props < HEIF_MAX_PROPS) )
   {
     struct HeifBox prop;
 
     if (! heif_next_box (hs,
                          pos,
                          box->end,
                          &prop))
       break;
     if (prop.end <= pos)
       break;   /* no forward progress */
     pos = prop.end;
     memcpy (hs->props[hs->num_props].type,
             prop.type,
             4);
     hs->props[hs->num_props].payload = prop.payload;
     hs->props[hs->num_props].end = prop.end;
     hs->num_props++;
   }
 }
 
 
 /**
  * Parse the 'ipma' box and collect the property indices associated with
  * the primary item.
  *
  * @param hs parser state
  * @param box the 'ipma' box
  */
 static void
 heif_parse_ipma (struct HeifState *hs,
                  const struct HeifBox *box)
 {
   unsigned char *buf;
   size_t len;
   size_t off;
   unsigned int version;
   uint32_t flags;
   uint32_t entries;
   int wide_index;
 
   if (! hs->have_pitm)
     return;
   if (0 != hs->num_assoc)
     return;   /* a previous 'ipma' already answered the question */
   len = (size_t) heif_payload_len (box);
   if (len < 8)
     return;
   if (len > HEIF_IPMA_MAX)
     len = HEIF_IPMA_MAX;
   buf = malloc (len);
   if (NULL == buf)
     return;
   if (! heif_read (hs,
                    box->payload,
                    buf,
                    len))
   {
     free (buf);
     return;
   }
   version = buf[0];
   flags = EXTRACTOR_forensic_be32_ (buf) & 0xFFFFFF;
   wide_index = (0 != (flags & 1));
   entries = EXTRACTOR_forensic_be32_ (&buf[4]);
   off = 8;
   /* The entry count is a 32-bit field out of the file, so it is not a
      loop bound we can trust; the buffer running out is what actually
      ends the walk, and `truncated' carries that out of the inner
      loop without ever incrementing `e' past its own maximum. */
   for (uint32_t e = 0; e < entries; e++)
   {
     uint32_t item_id;
     unsigned int count;
     int mine;
     int truncated = 0;
 
     if (version < 1)
     {
       if (off + 2 > len)
         break;
       item_id = EXTRACTOR_forensic_be16_ (&buf[off]);
       off += 2;
     }
     else
     {
       if (off + 4 > len)
         break;
       item_id = EXTRACTOR_forensic_be32_ (&buf[off]);
       off += 4;
     }
     if (off >= len)
       break;
     count = buf[off];
     off++;
     mine = (item_id == hs->primary_item);
     for (unsigned int a = 0; a < count; a++)
     {
       unsigned int index;
 
       if (wide_index)
       {
         if (off + 2 > len)
         {
           truncated = 1;
           break;
         }
         index = EXTRACTOR_forensic_be16_ (&buf[off]) & 0x7FFF;
         off += 2;
       }
       else
       {
         if (off + 1 > len)
         {
           truncated = 1;
           break;
         }
         index = buf[off] & 0x7F;
         off++;
       }
       if ( (mine) &&
            (0 != index) &&
            (hs->num_assoc < HEIF_MAX_ASSOC) )
         hs->assoc[hs->num_assoc++] = index;
     }
     if (truncated)
       break;
   }
   free (buf);
 }
 
 
 /**
  * Emit the image dimensions from an 'ispe' property.
  *
  * @param hs parser state
  * @param prop the property
  */
 static void
 heif_emit_ispe (struct HeifState *hs,
                 const struct HeifProp *prop)
 {
   unsigned char buf[12];
 
   if (prop->end - prop->payload < 12)
     return;
   if (! heif_read (hs,
                    prop->payload,
                    buf,
                    sizeof (buf)))
     return;
   if (0 != EXTRACTOR_forensic_emit_ (hs->ec,
                                      "heif",
                                      EXTRACTOR_METATYPE_IMAGE_DIMENSIONS,
                                      "%ux%u",
                                      (unsigned int) EXTRACTOR_forensic_be32_ (
                                        &buf[4]),
                                      (unsigned int) EXTRACTOR_forensic_be32_ (
                                        &buf[8])))
     hs->stop = 1;
 }
 
 
 /**
  * Emit the bit depth from a 'pixi' property.  A 10-bit still is the
  * usual signal that the file carries HDR content.
  *
  * @param hs parser state
  * @param prop the property
  */
 static void
 heif_emit_pixi (struct HeifState *hs,
                 const struct HeifProp *prop)
 {
   unsigned char buf[8];
   unsigned int channels;
   uint64_t len = prop->end - prop->payload;
 
   if (len < 5)
     return;
   if (! heif_read (hs,
                    prop->payload,
                    buf,
                    5))
     return;
   channels = buf[4];
   if ( (0 == channels) ||
        (channels > 4) ||
        (len < 5 + channels) )
     return;
   if (! heif_read (hs,
                    prop->payload + 5,
                    buf,
                    channels))
     return;
   /* All channels normally share a depth; report the first and say how
      many planes there are, which distinguishes monochrome from YUV. */
   if (0 != EXTRACTOR_forensic_emit_ (hs->ec,
                                      "heif",
                                      EXTRACTOR_METATYPE_COLOR_DEPTH,
                                      "%u",
                                      (unsigned int) buf[0]))
     hs->stop = 1;
 }
 
 
 /**
  * Emit the rotation recorded in an 'irot' property.
  *
  * @param hs parser state
  * @param prop the property
  */
 static void
 heif_emit_irot (struct HeifState *hs,
                 const struct HeifProp *prop)
 {
   unsigned char buf[1];
 
   if (prop->end - prop->payload < 1)
     return;
   if (! heif_read (hs,
                    prop->payload,
                    buf,
                    1))
     return;
   /* The low two bits count anti-clockwise quarter turns to apply when
      displaying the image. */
   if (0 != EXTRACTOR_forensic_emit_ (hs->ec,
                                      "heif",
                                      EXTRACTOR_METATYPE_ORIENTATION,
                                      "rotate %u degrees counter-clockwise",
                                      (unsigned int) (buf[0] & 0x03) * 90))
     hs->stop = 1;
 }
 
 
 /**
  * Emit the mirroring recorded in an 'imir' property.
  *
  * @param hs parser state
  * @param prop the property
  */
 static void
 heif_emit_imir (struct HeifState *hs,
                 const struct HeifProp *prop)
 {
   unsigned char buf[1];
 
   if (prop->end - prop->payload < 1)
     return;
   if (! heif_read (hs,
                    prop->payload,
                    buf,
                    1))
     return;
   /* axis == 0 mirrors about a vertical axis, i.e. left and right are
      swapped; axis == 1 mirrors about a horizontal axis. */
   if (0 != EXTRACTOR_forensic_emit_ (hs->ec,
                                      "heif",
                                      EXTRACTOR_METATYPE_ORIENTATION,
                                      "mirrored %s",
                                      (0 == (buf[0] & 0x01))
                                      ? "horizontally"
                                      : "vertically"))
     hs->stop = 1;
 }
 
 
 /**
  * Emit the colour information from a 'colr' property.
  *
  * @param hs parser state
  * @param prop the property
  */
 static void
 heif_emit_colr (struct HeifState *hs,
                 const struct HeifProp *prop)
 {
   unsigned char buf[12];
   uint64_t len = prop->end - prop->payload;
 
   if (len < 4)
     return;
   if (! heif_read (hs,
                    prop->payload,
                    buf,
                    (len < sizeof (buf)) ? (size_t) len : sizeof (buf)))
     return;
   if (0 == memcmp (buf,
                    "nclx",
                    4))
   {
     unsigned int primaries;
     unsigned int transfer;
     unsigned int matrix;
     const char *hdr = NULL;
 
     if (len < 11)
       return;
     primaries = EXTRACTOR_forensic_be16_ (&buf[4]);
     transfer = EXTRACTOR_forensic_be16_ (&buf[6]);
     matrix = EXTRACTOR_forensic_be16_ (&buf[8]);
     if (0 != EXTRACTOR_forensic_emit_ (hs->ec,
                                        "heif",
                                        EXTRACTOR_METATYPE_COLOR_PROFILE,
                                        "nclx: primaries %u, transfer %u, "
                                        "matrix %u, %s range",
                                        primaries,
                                        transfer,
                                        matrix,
                                        (0 != (buf[10] & 0x80))
                                        ? "full"
                                        : "limited"))
     {
       hs->stop = 1;
       return;
     }
     /* Transfer characteristics 16 and 18 are the two HDR curves; they
        are worth spelling out because they are what distinguishes an HDR
        capture from an ordinary one. */
     if (16 == transfer)
       hdr = "HDR: PQ transfer function (SMPTE ST 2084)";
     else if (18 == transfer)
       hdr = "HDR: HLG transfer function (ARIB STD-B67)";
     if (NULL != hdr)
     {
       if (0 != EXTRACTOR_forensic_emit_ (hs->ec,
                                          "heif",
                                          EXTRACTOR_METATYPE_COMMENT,
                                          "%s",
                                          hdr))
         hs->stop = 1;
     }
     return;
   }
   if ( (0 == memcmp (buf,
                      "prof",
                      4)) ||
        (0 == memcmp (buf,
                      "rICC",
                      4)) )
   {
     /* We deliberately do not parse the ICC payload: exiv2 and the
        colour management stack do that far better than we could. */
     if (0 != EXTRACTOR_forensic_emit_ (hs->ec,
                                        "heif",
                                        EXTRACTOR_METATYPE_COLOR_PROFILE,
                                        "ICC profile (%.4s), %llu bytes",
                                        (const char *) buf,
                                        (unsigned long long) (len - 4)))
       hs->stop = 1;
   }
 }
 
 
 /**
  * Emit what an 'av1C' configuration record says about the bit depth,
  * which is the fallback when the file carries no 'pixi'.
  *
  * @param hs parser state
  * @param prop the property
  * @param have_pixi true if a 'pixi' property will report the depth
  */
 static void
 heif_emit_av1c (struct HeifState *hs,
                 const struct HeifProp *prop,
                 int have_pixi)
 {
   unsigned char buf[4];
   unsigned int depth;
 
   if (have_pixi)
     return;
   if (prop->end - prop->payload < 4)
     return;
   if (! heif_read (hs,
                    prop->payload,
                    buf,
                    sizeof (buf)))
     return;
   if (0x81 != buf[0])
     return;   /* marker bit plus version 1 */
   /* byte 2: seq_tier_0(1) high_bitdepth(1) twelve_bit(1) monochrome(1)
      chroma_subsampling_x(1) chroma_subsampling_y(1)
      chroma_sample_position(2) */
   if (0 != (buf[2] & 0x40))
     depth = (0 != (buf[2] & 0x20)) ? 12 : 10;
   else
     depth = 8;
   if (0 != EXTRACTOR_forensic_emit_ (hs->ec,
                                      "heif",
                                      EXTRACTOR_METATYPE_COLOR_DEPTH,
                                      "%u",
                                      depth))
     hs->stop = 1;
 }
 
 
 /**
  * Walk the properties selected for the primary item and emit what they
  * say.  Only the first property of each kind is reported: a file may
  * legally associate several, but the extra ones describe alternative
  * renderings rather than the image a user would see.
  *
  * @param hs parser state
  */
 static void
 heif_emit_properties (struct HeifState *hs)
 {
   unsigned int order[HEIF_MAX_PROPS];
   unsigned int n = 0;
   int did_ispe = 0;
   int did_pixi = 0;
   int did_irot = 0;
   int did_imir = 0;
   int did_colr = 0;
   int did_av1c = 0;
   int have_pixi = 0;
 
   if (0 != hs->num_assoc)
   {
     for (unsigned int i = 0; i < hs->num_assoc; i++)
       if (hs->assoc[i] <= hs->num_props)
         order[n++] = hs->assoc[i] - 1;
   }
   else
   {
     /* No usable association: fall back to file order.  The first 'ispe'
        in 'ipco' belongs to a thumbnail often enough that this is worth
        flagging, but it is still better than reporting nothing. */
     for (unsigned int i = 0; i < hs->num_props; i++)
       order[n++] = i;
   }
   /* 'pixi' wins over 'av1C' for the bit depth, so find out whether one
      is coming before deciding to use the configuration record. */
   for (unsigned int i = 0; i < n; i++)
     if (0 == memcmp (hs->props[order[i]].type,
                      "pixi",
                      4))
       have_pixi = 1;
   for (unsigned int i = 0; i < n; i++)
   {
     const struct HeifProp *prop = &hs->props[order[i]];
 
     if (hs->stop)
       return;
     if ( (0 == memcmp (prop->type, "ispe", 4)) &&
          (! did_ispe) )
     {
       did_ispe = 1;
       heif_emit_ispe (hs,
                       prop);
     }
     else if ( (0 == memcmp (prop->type, "pixi", 4)) &&
               (! did_pixi) )
     {
       did_pixi = 1;
       heif_emit_pixi (hs,
                       prop);
     }
     else if ( (0 == memcmp (prop->type, "irot", 4)) &&
               (! did_irot) )
     {
       did_irot = 1;
       heif_emit_irot (hs,
                       prop);
     }
     else if ( (0 == memcmp (prop->type, "imir", 4)) &&
               (! did_imir) )
     {
       did_imir = 1;
       heif_emit_imir (hs,
                       prop);
     }
     else if ( (0 == memcmp (prop->type, "colr", 4)) &&
               (! did_colr) )
     {
       did_colr = 1;
       heif_emit_colr (hs,
                       prop);
     }
     else if ( (0 == memcmp (prop->type, "av1C", 4)) &&
               (! did_av1c) )
     {
       did_av1c = 1;
       heif_emit_av1c (hs,
                       prop,
                       have_pixi);
     }
   }
 }
 
 
 /**
  * Parse the 'iprp' box: the property container and the associations.
  *
  * @param hs parser state
  * @param box the 'iprp' box
  */
 static void
 heif_parse_iprp (struct HeifState *hs,
                  const struct HeifBox *box)
 {
   uint64_t pos = box->payload;
 
   /* 'ipco' always precedes 'ipma' in practice, but do not rely on it:
      index the container first in one pass, then read the associations. */
   while (pos < box->end)
   {
     struct HeifBox child;
 
     if (! heif_next_box (hs,
                          pos,
                          box->end,
                          &child))
       break;
     if (child.end <= pos)
       break;   /* no forward progress */
     pos = child.end;
     if (heif_is (&child,
                  "ipco"))
       heif_parse_ipco (hs,
                        &child);
   }
   pos = box->payload;
   while (pos < box->end)
   {
     struct HeifBox child;
 
     if (! heif_next_box (hs,
                          pos,
                          box->end,
                          &child))
       break;
     if (child.end <= pos)
       break;
     pos = child.end;
     if (heif_is (&child,
                  "ipma"))
       heif_parse_ipma (hs,
                        &child);
   }
 }
 
 
 /**
  * Find where the children of a 'meta' box start.
  *
  * In ISO/IEC 14496-12 'meta' is a FullBox, so its children begin four
  * bytes into the payload.  QuickTime writes the same box without the
  * version and flags word, and such files do turn up; probe for a
  * plausible child box at both offsets rather than guessing.
  *
  * @param hs parser state
  * @param box the 'meta' box
  * @param[out] start where the children begin
  * @return 1 if a starting offset was found
  */
 static int
 heif_meta_children (struct HeifState *hs,
                     const struct HeifBox *box,
                     uint64_t *start)
 {
   struct HeifBox probe;
 
   if ( (heif_payload_len (box) > 4) &&
        (heif_next_box (hs,
                        box->payload + 4,
                        box->end,
                        &probe)) )
   {
     *start = box->payload + 4;
     return 1;
   }
   if (heif_next_box (hs,
                      box->payload,
                      box->end,
                      &probe))
   {
     *start = box->payload;
     return 1;
   }
   return 0;
 }
 
 
 /**
  * Parse the 'meta' box: the items, their properties and their
  * relationships.
  *
  * @param hs parser state
  * @param box the 'meta' box
  * @param brand_codec coding format implied by the brand, may be NULL
  */
 static void
 heif_parse_meta (struct HeifState *hs,
                  const struct HeifBox *box,
                  const char *brand_codec)
 {
   struct HeifBox pitm;
   struct HeifBox iinf;
   struct HeifBox iref;
   struct HeifBox iprp;
   int have_pitm_box = 0;
   int have_iinf = 0;
   int have_iref = 0;
   int have_iprp = 0;
   uint64_t pos;
 
   memset (&pitm, 0, sizeof (pitm));
   memset (&iinf, 0, sizeof (iinf));
   memset (&iref, 0, sizeof (iref));
   memset (&iprp, 0, sizeof (iprp));
   if (! heif_meta_children (hs,
                             box,
                             &pos))
     return;
   while (pos < box->end)
   {
     struct HeifBox child;
 
     if (! heif_next_box (hs,
                          pos,
                          box->end,
                          &child))
       break;
     if (child.end <= pos)
       break;   /* no forward progress */
     pos = child.end;
     if ( (heif_is (&child, "pitm")) &&
          (! have_pitm_box) )
     {
       pitm = child;
       have_pitm_box = 1;
     }
     else if ( (heif_is (&child, "iinf")) &&
               (! have_iinf) )
     {
       iinf = child;
       have_iinf = 1;
     }
     else if ( (heif_is (&child, "iref")) &&
               (! have_iref) )
     {
       iref = child;
       have_iref = 1;
     }
     else if ( (heif_is (&child, "iprp")) &&
               (! have_iprp) )
     {
       iprp = child;
       have_iprp = 1;
     }
   }
   /* The order below is ours, not the file's: the primary item ID has to
      be known before 'iinf' and 'ipma' can be interpreted. */
   if (have_pitm_box)
     heif_parse_pitm (hs,
                      &pitm);
   if (have_iinf)
     heif_parse_iinf (hs,
                      &iinf);
   if (have_iref)
     heif_parse_iref (hs,
                      &iref);
 
   /* CODEC: the item type of the primary item is more specific than the
      brand, so prefer it and fall back to the brand. */
   if (hs->have_primary_type)
   {
     const char *name = heif_item_type_name (hs->primary_type);
 
     if (NULL != name)
     {
       if (0 != EXTRACTOR_forensic_emit_ (hs->ec,
                                          "heif",
                                          EXTRACTOR_METATYPE_CODEC,
                                          "%s (%.4s)",
                                          name,
                                          (const char *) hs->primary_type))
       {
         hs->stop = 1;
         return;
       }
       if ( (0 == memcmp (hs->primary_type, "grid", 4)) ||
            (0 == memcmp (hs->primary_type, "iovl", 4)) ||
            (0 == memcmp (hs->primary_type, "iden", 4)) )
       {
         if (0 != EXTRACTOR_forensic_emit_ (hs->ec,
                                            "heif",
                                            EXTRACTOR_METATYPE_RESOURCE_TYPE,
                                            "derived image (%.4s)",
                                            (const char *) hs->primary_type))
         {
           hs->stop = 1;
           return;
         }
       }
     }
   }
   else if (NULL != brand_codec)
   {
     if (0 != EXTRACTOR_forensic_emit_ (hs->ec,
                                        "heif",
                                        EXTRACTOR_METATYPE_CODEC,
                                        "%s",
                                        brand_codec))
     {
       hs->stop = 1;
       return;
     }
   }
 
   if (have_iprp)
   {
     heif_parse_iprp (hs,
                      &iprp);
     heif_emit_properties (hs);
     if (hs->stop)
       return;
   }
 
   if (0 != hs->num_items)
   {
     if (0 != EXTRACTOR_forensic_emit_ (hs->ec,
                                        "heif",
                                        EXTRACTOR_METATYPE_ENTRY_COUNT,
                                        "%u",
                                        (unsigned int) hs->num_items))
     {
       hs->stop = 1;
       return;
     }
     if (0 != EXTRACTOR_forensic_emit_ (hs->ec,
                                        "heif",
                                        EXTRACTOR_METATYPE_COMMENT,
                                        "%u image item%s, %u thumbnail%s, "
                                        "%u auxiliary, %u metadata item%s",
                                        hs->num_image_items,
                                        (1 == hs->num_image_items) ? "" : "s",
                                        hs->num_thumbnails,
                                        (1 == hs->num_thumbnails) ? "" : "s",
                                        hs->num_auxiliary,
                                        hs->num_exif + hs->num_mime,
                                        (1 == hs->num_exif + hs->num_mime)
                                        ? "" : "s"))
     {
       hs->stop = 1;
       return;
     }
   }
   /* We do not touch the payload of these items: parsing EXIF and XMP is
      the exiv2 plugin's job.  Saying that they are there is what lets a
      downstream tool decide to run it. */
   if (0 != hs->num_exif)
   {
     if (0 != EXTRACTOR_forensic_emit_ (hs->ec,
                                        "heif",
                                        EXTRACTOR_METATYPE_COMMENT,
                                        "contains an Exif metadata item"))
     {
       hs->stop = 1;
       return;
     }
   }
   if (0 != hs->num_mime)
   {
     if (0 != EXTRACTOR_forensic_emit_ (hs->ec,
                                        "heif",
                                        EXTRACTOR_METATYPE_COMMENT,
                                        "contains an XMP or MIME metadata item"))
     {
       hs->stop = 1;
       return;
     }
   }
 }
 
 
 /**
  * Parse 'moov' and its 'mvhd', which only a sequence file has.
  *
  * @param hs parser state
  * @param box the 'moov' box
  */
 static void
 heif_parse_moov (struct HeifState *hs,
                  const struct HeifBox *box)
 {
   uint64_t pos = box->payload;
 
   while (pos < box->end)
   {
     struct HeifBox child;
     unsigned char buf[28];
     int64_t created;
     int64_t modified;
 
     if (! heif_next_box (hs,
                          pos,
                          box->end,
                          &child))
       break;
     if (child.end <= pos)
       break;   /* no forward progress */
     pos = child.end;
     if (! heif_is (&child,
                    "mvhd"))
       continue;
     if (heif_payload_len (&child) < 5)
       return;
     if (! heif_read (hs,
                      child.payload,
                      buf,
                      5))
       return;
     /* The ISO-BMFF epoch is 1904-01-01; these fields are also famously
        written as local time labelled as UTC by most muxers, so treat
        the result as an approximate wall clock reading, not as UTC. */
     if (0 == buf[0])
     {
       if (heif_payload_len (&child) < 20)
         return;
       if (! heif_read (hs,
                        child.payload + 4,
                        buf,
                        16))
         return;
       created = (int64_t) EXTRACTOR_forensic_be32_ (&buf[0]);
       modified = (int64_t) EXTRACTOR_forensic_be32_ (&buf[4]);
     }
     else
     {
       if (heif_payload_len (&child) < 32)
         return;
       if (! heif_read (hs,
                        child.payload + 4,
                        buf,
                        28))
         return;
       created = (int64_t) (EXTRACTOR_forensic_be64_ (&buf[0])
                            & INT64_MAX);
       modified = (int64_t) (EXTRACTOR_forensic_be64_ (&buf[8])
                             & INT64_MAX);
     }
     if (0 != created)
     {
       if (0 != EXTRACTOR_forensic_emit_unix_time_ (hs->ec,
                                                    "heif",
                                                    EXTRACTOR_METATYPE_CREATION_DATE,
                                                    created - HEIF_EPOCH_OFFSET))
       {
         hs->stop = 1;
         return;
       }
     }
     if (0 != modified)
     {
       if (0 != EXTRACTOR_forensic_emit_unix_time_ (hs->ec,
                                                    "heif",
                                                    EXTRACTOR_METATYPE_MODIFICATION_DATE,
                                                    modified
                                                    - HEIF_EPOCH_OFFSET))
         hs->stop = 1;
     }
     return;
   }
 }
 
 
 /**
  * Main entry method for the HEIF/HEIC/AVIF extraction plugin.
  *
  * @param ec extraction context provided to the plugin
  */
 void
 EXTRACTOR_heif_extract_method (struct EXTRACTOR_ExtractContext *ec);
 
 void
 EXTRACTOR_heif_extract_method (struct EXTRACTOR_ExtractContext *ec)
 {
   struct HeifState hs;
   struct HeifBox meta;
   struct HeifBox moov;
   unsigned char head[16];
   unsigned char brands[HEIF_MAX_BRANDS * 4];
   const struct HeifBrand *major;
   const char *family;
   const char *codec;
   char mime[64];
   char compat[HEIF_MAX_BRANDS * 5 + 1];
   uint64_t fsize;
   uint64_t ftyp_size;
   unsigned int num_brands;
   unsigned int sequence;
   uint64_t pos;
   int have_meta = 0;
 
   fsize = ec->get_size (ec->cls);
   if ( (UINT64_MAX == fsize) ||
        (fsize < 16) )
     return;
   memset (&hs,
           0,
           sizeof (hs));
   memset (&meta, 0, sizeof (meta));
   memset (&moov, 0, sizeof (moov));
   hs.ec = ec;
   hs.boxes = HEIF_MAX_BOXES;
   hs.budget = HEIF_READ_BUDGET;
 
   /* Bail out on the first 16 bytes: almost every file we are handed is
      not ours, and this is the only read those files should cost. */
   if (! heif_read (&hs,
                    0,
                    head,
                    sizeof (head)))
     return;
   if (0 != memcmp (&head[4],
                    "ftyp",
                    4))
     return;
   ftyp_size = EXTRACTOR_forensic_be32_ (head);
   if ( (ftyp_size < 16) ||
        (ftyp_size > fsize) )
     return;   /* 'ftyp' never uses the 64-bit or to-end-of-file forms */
   major = heif_lookup_brand (&head[8]);
 
   num_brands = (unsigned int) ((ftyp_size - 16) / 4);
   if (num_brands > HEIF_MAX_BRANDS)
     num_brands = HEIF_MAX_BRANDS;
   if ( (0 != num_brands) &&
        (! heif_read (&hs,
                      16,
                      brands,
                      num_brands * 4)) )
     num_brands = 0;
 
   family = (NULL != major) ? major->family : NULL;
   codec = (NULL != major) ? major->codec : NULL;
   sequence = (NULL != major) ? (unsigned int) major->sequence : 0;
   if (NULL == codec)
   {
     /* Either the major brand is generic ('mif1'/'msf1') or we do not
        know it at all; the compatible brands decide. */
     for (unsigned int i = 0; i < num_brands; i++)
     {
       const struct HeifBrand *b = heif_lookup_brand (&brands[i * 4]);
 
       if (NULL == b)
         continue;
       if (NULL == family)
       {
         family = b->family;
         sequence = (unsigned int) b->sequence;
       }
       if (NULL != b->codec)
       {
         codec = b->codec;
         family = b->family;
         sequence |= (unsigned int) b->sequence;
         break;
       }
     }
   }
   if (NULL == family)
     return;   /* neither the major nor any compatible brand is ours */
 
   snprintf (mime,
             sizeof (mime),
             "%s%s",
             family,
             (0 != sequence) ? "-sequence" : "");
   if (0 != ec->proc (ec->cls,
                      "heif",
                      EXTRACTOR_METATYPE_MIMETYPE,
                      EXTRACTOR_METAFORMAT_UTF8,
                      "text/plain",
                      mime,
                      strlen (mime) + 1))
     return;
   if (0 != EXTRACTOR_forensic_emit_text_ (ec,
                                           "heif",
                                           EXTRACTOR_METATYPE_FORMAT,
                                           (const char *) &head[8],
                                           4))
     return;
   if (0 != num_brands)
   {
     size_t off = 0;
 
     for (unsigned int i = 0; i < num_brands; i++)
     {
       /* Skip the padding brands some encoders write. */
       if (0 == memcmp (&brands[i * 4],
                        "\0\0\0\0",
                        4))
         continue;
       if (off + 5 >= sizeof (compat))
         break;
       if (0 != off)
         compat[off++] = ',';
       memcpy (&compat[off],
               &brands[i * 4],
               4);
       off += 4;
     }
     if (0 != off)
     {
       if (0 != EXTRACTOR_forensic_emit_text_ (ec,
                                               "heif",
                                               EXTRACTOR_METATYPE_COMPATIBLE_BRANDS,
                                               compat,
                                               off))
         return;
     }
   }
 
   /* Top level walk: we only care about 'meta' and 'moov'.  'mdat' is
      stepped over by its size and never read.  One pass records where
      they are; the emission order below is ours, not the file's. */
   pos = ftyp_size;
   while (pos < fsize)
   {
     struct HeifBox box;
 
     if (! heif_next_box (&hs,
                          pos,
                          fsize,
                          &box))
       break;
     if (box.end <= pos)
       break;   /* no forward progress */
     pos = box.end;
     if ( (heif_is (&box, "meta")) &&
          (! have_meta) )
     {
       meta = box;
       have_meta = 1;
     }
     else if ( (heif_is (&box, "moov")) &&
               (! hs.have_moov) )
     {
       moov = box;
       hs.have_moov = 1;
     }
   }
   if (have_meta)
   {
     heif_parse_meta (&hs,
                      &meta,
                      codec);
     if (hs.stop)
       return;
   }
   if ( (0 != sequence) ||
        (hs.have_moov) )
   {
     /* A burst, a Live Photo or an animated AVIF: several coded images
        that belong together, which is worth calling out because it means
        there is more here than the one frame a viewer shows. */
     if (0 != EXTRACTOR_forensic_emit_ (ec,
                                        "heif",
                                        EXTRACTOR_METATYPE_RESOURCE_TYPE,
                                        "image sequence"))
       return;
     if (0 != EXTRACTOR_forensic_emit_ (ec,
                                        "heif",
                                        EXTRACTOR_METATYPE_COMMENT,
                                        "image sequence (burst, animation or "
                                        "Live Photo)"))
       return;
   }
   if (hs.have_moov)
     heif_parse_moov (&hs,
                      &moov);
 }
 
 
 /* end of heif_extractor.c */