Discourage the inclusion of private headers outside libpng

Add checks inside the private png*.h header files, in order to reduce
unintentional occurences of application backdoors.

Such backdoors might occur, for example, when we make changes to the
internal data structures that might somehow "leak" from the libpng
code into the user code. The applications that use the libpng API must
pretend not to know that these headers exist at all.

Co-authored-by: John Bowler <jbowler@acm.org>
Signed-off-by: John Bowler <jbowler@acm.org>
Signed-off-by: Cosmin Truta <ctruta@gmail.com>

pngdebug.h

@@ -1,6 +1,6 @@
-/* pngdebug.h - Debugging macros for libpng, also used in pngtest.c
+/* pngdebug.h - internal debugging macros for libpng
  *
- * Copyright (c) 2018 Cosmin Truta
+ * Copyright (c) 2018-2025 Cosmin Truta
  * Copyright (c) 1998-2002,2004,2006-2013 Glenn Randers-Pehrson
  * Copyright (c) 1996-1997 Andreas Dilger
  * Copyright (c) 1995-1996 Guy Eric Schalnat, Group 42, Inc.
@@ -10,6 +10,10 @@
  * and license in png.h
  */
 
+#ifndef PNGPRIV_H
+#  error This file must not be included by applications; please include <png.h>
+#endif
+
 /* Define PNG_DEBUG at compile time for debugging information.  Higher
  * numbers for PNG_DEBUG mean more debugging information.  This has
  * only been added since version 0.95 so it is not implemented throughout

pnginfo.h

@@ -1,4 +1,4 @@
-/* pnginfo.h - header file for PNG reference library
+/* pnginfo.h - internal structures for libpng
  *
  * Copyright (c) 2018-2025 Cosmin Truta
  * Copyright (c) 1998-2002,2004,2006-2013,2018 Glenn Randers-Pehrson
@@ -10,43 +10,20 @@
  * and license in png.h
  */
 
- /* png_info is a structure that holds the information in a PNG file so
+#ifndef PNGPRIV_H
- * that the application can find out the characteristics of the image.
+#  error This file must not be included by applications; please include <png.h>
- * If you are reading the file, this structure will tell you what is
+#endif
- * in the PNG file.  If you are writing the file, fill in the information
+
- * you want to put into the PNG file, using png_set_*() functions, then
+/* INTERNAL, PRIVATE definition of a PNG.
- * call png_write_info().
  *
- * The names chosen should be very close to the PNG specification, so
+ * png_info is a modifiable description of a PNG datastream.  The fields inside
- * consult that document for information about the meaning of each field.
+ * this structure are accessed through png_get_<CHUNK>() functions and modified
+ * using png_set_<CHUNK>() functions.
  *
- * With libpng < 0.95, it was only possible to directly set and read the
+ * Some functions in libpng do directly access members of png_info.  However,
- * the values in the png_info_struct, which meant that the contents and
+ * this should be avoided.  png_struct objects contain members which hold
- * order of the values had to remain fixed.  With libpng 0.95 and later,
+ * caches, sometimes optimised, of the values from png_info objects, and
- * however, there are now functions that abstract the contents of
+ * png_info is not passed to the functions which read and write image data.
- * png_info_struct from the application, so this makes it easier to use
- * libpng with dynamic libraries, and even makes it possible to use
- * libraries that don't have all of the libpng ancillary chunk-handing
- * functionality.  In libpng-1.5.0 this was moved into a separate private
- * file that is not visible to applications.
- *
- * The following members may have allocated storage attached that should be
- * cleaned up before the structure is discarded: palette, trans, text,
- * pcal_purpose, pcal_units, pcal_params, hist, iccp_name, iccp_profile,
- * splt_palettes, scal_unit, row_pointers, and unknowns.   By default, these
- * are automatically freed when the info structure is deallocated, if they were
- * allocated internally by libpng.  This behavior can be changed by means
- * of the png_data_freer() function.
- *
- * More allocation details: all the chunk-reading functions that
- * change these members go through the corresponding png_set_*
- * functions.  A function to clear these members is available: see
- * png_free_data().  The png_set_* functions do not depend on being
- * able to point info structure members to any of the storage they are
- * passed (they make their own copies), EXCEPT that the png_set_text
- * functions use the same storage passed to them in the text_ptr or
- * itxt_ptr structure argument, and the png_set_rows and png_set_unknowns
- * functions do not make their own copies.
  */
 #ifndef PNGINFO_H
 #define PNGINFO_H

pngpriv.h

@@ -19,8 +19,20 @@
  * they should be well aware of the issues that may arise from doing so.
  */
 
+
+/* pngpriv.h must be included first in each translation unit inside libpng.
+ * On the other hand, it must not be included at all, directly or indirectly,
+ * by any application code that uses the libpng API.
+ */
 #ifndef PNGPRIV_H
 #  define PNGPRIV_H
+#else
+#  error Duplicate inclusion of pngpriv.h; please check the libpng source files
+#endif
+
+#if defined(PNG_H) || defined(PNGCONF_H) || defined(PNGLCONF_H)
+#  error This file must not be included by applications; please include <png.h>
+#endif
 
 /* Feature Test Macros.  The following are defined here to ensure that correctly
  * implemented libraries reveal the APIs libpng needs to build and hide those
@@ -57,7 +69,6 @@
  */
 #if defined(HAVE_CONFIG_H) && !defined(PNG_NO_CONFIG_H)
 #  include <config.h>
-
    /* Pick up the definition of 'restrict' from config.h if it was read: */
 #  define PNG_RESTRICT restrict
 #endif
@@ -67,9 +78,7 @@
  * are not internal definitions may be required.  This is handled below just
  * before png.h is included, but load the configuration now if it is available.
  */
-#ifndef PNGLCONF_H
 #include "pnglibconf.h"
-#endif
 
 /* Local renames may change non-exported API functions from png.h */
 #if defined(PNG_PREFIX) && !defined(PNGPREFIX_H)
@@ -2162,4 +2171,3 @@ PNG_INTERNAL_FUNCTION(int,
 #endif
 
 #endif /* PNG_VERSION_INFO_ONLY */
-#endif /* PNGPRIV_H */

pngstruct.h

@@ -1,4 +1,4 @@
-/* pngstruct.h - header file for PNG reference library
+/* pngstruct.h - internal structures for libpng
  *
  * Copyright (c) 2018-2025 Cosmin Truta
  * Copyright (c) 1998-2002,2004,2006-2018 Glenn Randers-Pehrson
@@ -10,11 +10,9 @@
  * and license in png.h
  */
 
-/* The structure that holds the information to read and write PNG files.
+#ifndef PNGPRIV_H
- * The only people who need to care about what is inside of this are the
+#  error This file must not be included by applications; please include <png.h>
- * people who will be modifying the library for their own special needs.
+#endif
- * It should NOT be accessed directly by an application.
- */
 
 #ifndef PNGSTRUCT_H
 #define PNGSTRUCT_H