From 335947359ce2dd3862cd9f7c49f92eba065dfed4 Mon Sep 17 00:00:00 2001 From: Su_Laus Date: Thu, 1 Feb 2024 13:06:08 +0000 Subject: [PATCH] manpage: Update TIFF documentation about TIFFOpenOptions.rst and TIFFOpenOptionsSetMaxSingleMemAlloc() usage and some other small fixes. CVE: CVE-2023-52355 Upstream-Status: Backport [https://gitlab.com/libtiff/libtiff/-/commit/335947359ce2dd3862cd9f7c49f92eba065dfed4] Signed-off-by: Yogita Urade --- doc/functions/TIFFDeferStrileArrayWriting.rst | 5 +++ doc/functions/TIFFError.rst | 3 ++ doc/functions/TIFFOpen.rst | 13 +++--- doc/functions/TIFFOpenOptions.rst | 44 ++++++++++++++++++- doc/functions/TIFFStrileQuery.rst | 5 +++ doc/libtiff.rst | 31 ++++++++++++- 6 files changed, 91 insertions(+), 10 deletions(-) diff --git a/doc/functions/TIFFDeferStrileArrayWriting.rst b/doc/functions/TIFFDeferStrileArrayWriting.rst index 60ee746..705aebc 100644 --- a/doc/functions/TIFFDeferStrileArrayWriting.rst +++ b/doc/functions/TIFFDeferStrileArrayWriting.rst @@ -61,6 +61,11 @@ Diagnostics All error messages are directed to the :c:func:`TIFFErrorExtR` routine. Likewise, warning messages are directed to the :c:func:`TIFFWarningExtR` routine. +Note +---- + +This functionality was introduced with libtiff 4.1. + See also -------- diff --git a/doc/functions/TIFFError.rst b/doc/functions/TIFFError.rst index 99924ad..cf4b37c 100644 --- a/doc/functions/TIFFError.rst +++ b/doc/functions/TIFFError.rst @@ -65,6 +65,9 @@ or :c:func:`TIFFClientOpenExt`. Furthermore, a **custom defined data structure** *user_data* for the error handler can be given along. +Please refer to :doc:`/functions/TIFFOpenOptions` for how to setup the +application-specific handler introduced with libtiff 4.5. + Note ---- diff --git a/doc/functions/TIFFOpen.rst b/doc/functions/TIFFOpen.rst index db79d7b..adc474f 100644 --- a/doc/functions/TIFFOpen.rst +++ b/doc/functions/TIFFOpen.rst @@ -94,8 +94,9 @@ TIFF structure without closing the file handle and afterwards the file should be closed using its file descriptor *fd*. :c:func:`TIFFOpenExt` (added in libtiff 4.5) is like :c:func:`TIFFOpen`, -but options, such as re-entrant error and warning handlers may be passed -with the *opts* argument. The *opts* argument may be NULL. +but options, such as re-entrant error and warning handlers and a limit in byte +that libtiff internal memory allocation functions are allowed to request per call +may be passed with the *opts* argument. The *opts* argument may be NULL. Refer to :doc:`TIFFOpenOptions` for allocating and filling the *opts* argument parameters. The allocated memory for :c:type:`TIFFOpenOptions` can be released straight after successful execution of the related @@ -105,9 +106,7 @@ can be released straight after successful execution of the related but opens a TIFF file with a Unicode filename. :c:func:`TIFFFdOpenExt` (added in libtiff 4.5) is like :c:func:`TIFFFdOpen`, -but options, such as re-entrant error and warning handlers may be passed -with the *opts* argument. The *opts* argument may be NULL. -Refer to :doc:`TIFFOpenOptions` for filling the *opts* argument. +but options argument *opts* like for :c:func:`TIFFOpenExt` can be passed. :c:func:`TIFFSetFileName` sets the file name in the tif-structure and returns the old file name. @@ -326,5 +325,5 @@ See also :doc:`libtiff` (3tiff), :doc:`TIFFClose` (3tiff), -:doc:`TIFFStrileQuery`, -:doc:`TIFFOpenOptions` \ No newline at end of file +:doc:`TIFFStrileQuery` (3tiff), +:doc:`TIFFOpenOptions` diff --git a/doc/functions/TIFFOpenOptions.rst b/doc/functions/TIFFOpenOptions.rst index 5c67566..23f2975 100644 --- a/doc/functions/TIFFOpenOptions.rst +++ b/doc/functions/TIFFOpenOptions.rst @@ -38,12 +38,17 @@ opaque structure and returns a :c:type:`TIFFOpenOptions` pointer. :c:func:`TIFFOpenOptionsFree` releases the allocated memory for :c:type:`TIFFOpenOptions`. The allocated memory for :c:type:`TIFFOpenOptions` can be released straight after successful execution of the related -TIFF open"Ext" functions like :c:func:`TIFFOpenExt`. +TIFFOpen"Ext" functions like :c:func:`TIFFOpenExt`. :c:func:`TIFFOpenOptionsSetMaxSingleMemAlloc` sets parameter for the maximum single memory limit in byte that ``libtiff`` internal memory allocation functions are allowed to request per call. +.. note:: + However, the ``libtiff`` external functions :c:func:`_TIFFmalloc` + and :c:func:`_TIFFrealloc` **do not apply** this internal memory + allocation limit set by :c:func:`TIFFOpenOptionsSetMaxSingleMemAlloc`! + :c:func:`TIFFOpenOptionsSetErrorHandlerExtR` sets the function pointer to an application-specific and per-TIFF handle (re-entrant) error handler. Furthermore, a pointer to a **custom defined data structure** *errorhandler_user_data* @@ -55,6 +60,43 @@ The *errorhandler_user_data* argument may be NULL. :c:func:`TIFFOpenOptionsSetErrorHandlerExtR` but for the warning handler, which is invoked through :c:func:`TIFFWarningExtR` +Example +------- + +:: + + #include "tiffio.h" + + typedef struct MyErrorHandlerUserDataStruct + { + /* ... any user data structure ... */ + } MyErrorHandlerUserDataStruct; + + static int myErrorHandler(TIFF *tiff, void *user_data, const char *module, + const char *fmt, va_list ap) + { + MyErrorHandlerUserDataStruct *errorhandler_user_data = + (MyErrorHandlerUserDataStruct *)user_data; + /*... code of myErrorHandler ...*/ + return 1; + } + + + main() + { + tmsize_t limit = (256 * 1024 * 1024); + MyErrorHandlerUserDataStruct user_data = { /* ... any data ... */}; + + TIFFOpenOptions *opts = TIFFOpenOptionsAlloc(); + TIFFOpenOptionsSetMaxSingleMemAlloc(opts, limit); + TIFFOpenOptionsSetErrorHandlerExtR(opts, myErrorHandler, &user_data); + TIFF *tif = TIFFOpenExt("foo.tif", "r", opts); + TIFFOpenOptionsFree(opts); + /* ... go on here ... */ + + TIFFClose(tif); + } + Note ---- diff --git a/doc/functions/TIFFStrileQuery.rst b/doc/functions/TIFFStrileQuery.rst index f8631af..7931fe4 100644 --- a/doc/functions/TIFFStrileQuery.rst +++ b/doc/functions/TIFFStrileQuery.rst @@ -66,6 +66,11 @@ Diagnostics All error messages are directed to the :c:func:`TIFFErrorExtR` routine. Likewise, warning messages are directed to the :c:func:`TIFFWarningExtR` routine. +Note +---- + +This functionality was introduced with libtiff 4.1. + See also -------- diff --git a/doc/libtiff.rst b/doc/libtiff.rst index 6a0054c..d96a860 100644 --- a/doc/libtiff.rst +++ b/doc/libtiff.rst @@ -90,11 +90,15 @@ compatibility on machines with a segmented architecture. :c:func:`realloc`, and :c:func:`free` routines in the C library.) To deal with segmented pointer issues ``libtiff`` also provides -:c:func:`_TIFFmemcpy`, :c:func:`_TIFFmemset`, and :c:func:`_TIFFmemmove` +:c:func:`_TIFFmemcpy`, :c:func:`_TIFFmemset`, and :c:func:`_TIFFmemcmp` routines that mimic the equivalent ANSI C routines, but that are intended for use with memory allocated through :c:func:`_TIFFmalloc` and :c:func:`_TIFFrealloc`. +With ``libtiff`` 4.5 a method was introduced to limit the internal +memory allocation that functions are allowed to request per call +(see :c:func:`TIFFOpenOptionsSetMaxSingleMemAlloc` and :c:func:`TIFFOpenExt`). + Error Handling -------------- @@ -106,6 +110,10 @@ routine that can be specified with a call to :c:func:`TIFFSetErrorHandler`. Likewise warning messages are directed to a single handler routine that can be specified with a call to :c:func:`TIFFSetWarningHandler` +Further application-specific and per-TIFF handle (re-entrant) error handler +and warning handler can be set. Please refer to :doc:`/functions/TIFFError` +and :doc:`/functions/TIFFOpenOptions`. + Basic File Handling ------------------- @@ -139,7 +147,7 @@ a ``"w"`` argument: main() { TIFF* tif = TIFFOpen("foo.tif", "w"); - ... do stuff ... + /* ... do stuff ... */ TIFFClose(tif); } @@ -157,6 +165,25 @@ to always call :c:func:`TIFFClose` or :c:func:`TIFFFlush` to flush any buffered information to a file. Note that if you call :c:func:`TIFFClose` you do not need to call :c:func:`TIFFFlush`. +.. warning:: + + In order to prevent out-of-memory issues when opening a TIFF file + :c:func:`TIFFOpenExt` can be used and then the maximum single memory + limit in byte that ``libtiff`` internal memory allocation functions + are allowed to request per call can be set with + :c:func:`TIFFOpenOptionsSetMaxSingleMemAlloc`. + +Example + +:: + + tmsize_t limit = (256 * 1024 * 1024); + TIFFOpenOptions *opts = TIFFOpenOptionsAlloc(); + TIFFOpenOptionsSetMaxSingleMemAlloc(opts, limit); + TIFF *tif = TIFFOpenExt("foo.tif", "w", opts); + TIFFOpenOptionsFree(opts); + /* ... go on here ... */ + TIFF Directories ---------------- -- 2.40.0