1From 335947359ce2dd3862cd9f7c49f92eba065dfed4 Mon Sep 17 00:00:00 2001
2From: Su_Laus <sulau@freenet.de>
3Date: Thu, 1 Feb 2024 13:06:08 +0000
4Subject: [PATCH] manpage: Update TIFF documentation about TIFFOpenOptions.rst
5 and TIFFOpenOptionsSetMaxSingleMemAlloc() usage and some other small fixes.
6
7CVE: CVE-2023-52355
8Upstream-Status: Backport [https://gitlab.com/libtiff/libtiff/-/commit/335947359ce2dd3862cd9f7c49f92eba065dfed4]
9
10Signed-off-by: Yogita Urade <yogita.urade@windriver.com>
11---
12 doc/functions/TIFFDeferStrileArrayWriting.rst |  5 +++
13 doc/functions/TIFFError.rst                   |  3 ++
14 doc/functions/TIFFOpen.rst                    | 13 +++---
15 doc/functions/TIFFOpenOptions.rst             | 44 ++++++++++++++++++-
16 doc/functions/TIFFStrileQuery.rst             |  5 +++
17 doc/libtiff.rst                               | 31 ++++++++++++-
18 6 files changed, 91 insertions(+), 10 deletions(-)
19
20diff --git a/doc/functions/TIFFDeferStrileArrayWriting.rst b/doc/functions/TIFFDeferStrileArrayWriting.rst
21index 60ee746..705aebc 100644
22--- a/doc/functions/TIFFDeferStrileArrayWriting.rst
23+++ b/doc/functions/TIFFDeferStrileArrayWriting.rst
24@@ -61,6 +61,11 @@ Diagnostics
25 All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
26 Likewise, warning messages are directed to the :c:func:`TIFFWarningExtR` routine.
27
28+Note
29+----
30+
31+This functionality was introduced with libtiff 4.1.
32+
33 See also
34 --------
35
36diff --git a/doc/functions/TIFFError.rst b/doc/functions/TIFFError.rst
37index 99924ad..cf4b37c 100644
38--- a/doc/functions/TIFFError.rst
39+++ b/doc/functions/TIFFError.rst
40@@ -65,6 +65,9 @@ or :c:func:`TIFFClientOpenExt`.
41 Furthermore, a **custom defined data structure** *user_data* for the
42 error handler can be given along.
43
44+Please refer to :doc:`/functions/TIFFOpenOptions` for how to setup the
45+application-specific handler introduced with libtiff 4.5.
46+
47 Note
48 ----
49
50diff --git a/doc/functions/TIFFOpen.rst b/doc/functions/TIFFOpen.rst
51index db79d7b..adc474f 100644
52--- a/doc/functions/TIFFOpen.rst
53+++ b/doc/functions/TIFFOpen.rst
54@@ -94,8 +94,9 @@ TIFF structure without closing the file handle and afterwards the
55 file should be closed using its file descriptor *fd*.
56
57 :c:func:`TIFFOpenExt` (added in libtiff 4.5) is like :c:func:`TIFFOpen`,
58-but options, such as re-entrant error and warning handlers may be passed
59-with the *opts* argument. The *opts* argument may be NULL.
60+but options, such as re-entrant error and warning handlers and a limit in byte
61+that libtiff internal memory allocation functions are allowed to request per call
62+may be passed with the *opts* argument. The *opts* argument may be NULL.
63 Refer to :doc:`TIFFOpenOptions` for allocating and filling the *opts* argument
64 parameters. The allocated memory for :c:type:`TIFFOpenOptions`
65 can be released straight after successful execution of the related
66@@ -105,9 +106,7 @@ can be released straight after successful execution of the related
67 but opens a TIFF file with a Unicode filename.
68
69 :c:func:`TIFFFdOpenExt` (added in libtiff 4.5) is like :c:func:`TIFFFdOpen`,
70-but options, such as re-entrant error and warning handlers may be passed
71-with the *opts* argument. The *opts* argument may be NULL.
72-Refer to :doc:`TIFFOpenOptions` for filling the *opts* argument.
73+but options argument *opts* like for :c:func:`TIFFOpenExt` can be passed.
74
75 :c:func:`TIFFSetFileName` sets the file name in the tif-structure
76 and returns the old file name.
77@@ -326,5 +325,5 @@ See also
78
79 :doc:`libtiff` (3tiff),
80 :doc:`TIFFClose` (3tiff),
81-:doc:`TIFFStrileQuery`,
82-:doc:`TIFFOpenOptions`
83\ No newline at end of file
84+:doc:`TIFFStrileQuery` (3tiff),
85+:doc:`TIFFOpenOptions`
86diff --git a/doc/functions/TIFFOpenOptions.rst b/doc/functions/TIFFOpenOptions.rst
87index 5c67566..23f2975 100644
88--- a/doc/functions/TIFFOpenOptions.rst
89+++ b/doc/functions/TIFFOpenOptions.rst
90@@ -38,12 +38,17 @@ opaque structure and returns a :c:type:`TIFFOpenOptions` pointer.
91 :c:func:`TIFFOpenOptionsFree` releases the allocated memory for
92 :c:type:`TIFFOpenOptions`. The allocated memory for :c:type:`TIFFOpenOptions`
93 can be released straight after successful execution of the related
94-TIFF open"Ext" functions like :c:func:`TIFFOpenExt`.
95+TIFFOpen"Ext" functions like :c:func:`TIFFOpenExt`.
96
97 :c:func:`TIFFOpenOptionsSetMaxSingleMemAlloc` sets parameter for the
98 maximum single memory limit in byte that ``libtiff`` internal memory allocation
99 functions are allowed to request per call.
100
101+.. note::
102+    However, the ``libtiff`` external functions :c:func:`_TIFFmalloc`
103+    and :c:func:`_TIFFrealloc` **do not apply** this internal memory
104+    allocation limit set by :c:func:`TIFFOpenOptionsSetMaxSingleMemAlloc`!
105+
106 :c:func:`TIFFOpenOptionsSetErrorHandlerExtR` sets the function pointer to
107 an application-specific and per-TIFF handle (re-entrant) error handler.
108 Furthermore, a pointer to a **custom defined data structure** *errorhandler_user_data*
109@@ -55,6 +60,43 @@ The *errorhandler_user_data* argument may be NULL.
110 :c:func:`TIFFOpenOptionsSetErrorHandlerExtR` but for the warning handler,
111 which is invoked through  :c:func:`TIFFWarningExtR`
112
113+Example
114+-------
115+
116+::
117+
118+    #include "tiffio.h"
119+
120+    typedef struct MyErrorHandlerUserDataStruct
121+    {
122+        /* ... any user data structure ... */
123+    } MyErrorHandlerUserDataStruct;
124+
125+    static int myErrorHandler(TIFF *tiff, void *user_data, const char *module,
126+                          const char *fmt, va_list ap)
127+    {
128+        MyErrorHandlerUserDataStruct *errorhandler_user_data =
129+            (MyErrorHandlerUserDataStruct *)user_data;
130+        /*... code of myErrorHandler ...*/
131+        return 1;
132+    }
133+
134+
135+    main()
136+    {
137+        tmsize_t limit = (256 * 1024 * 1024);
138+        MyErrorHandlerUserDataStruct user_data = { /* ... any data ... */};
139+
140+        TIFFOpenOptions *opts = TIFFOpenOptionsAlloc();
141+        TIFFOpenOptionsSetMaxSingleMemAlloc(opts, limit);
142+        TIFFOpenOptionsSetErrorHandlerExtR(opts, myErrorHandler, &user_data);
143+        TIFF *tif = TIFFOpenExt("foo.tif", "r", opts);
144+        TIFFOpenOptionsFree(opts);
145+        /* ... go on here ... */
146+
147+        TIFFClose(tif);
148+    }
149+
150 Note
151 ----
152
153diff --git a/doc/functions/TIFFStrileQuery.rst b/doc/functions/TIFFStrileQuery.rst
154index f8631af..7931fe4 100644
155--- a/doc/functions/TIFFStrileQuery.rst
156+++ b/doc/functions/TIFFStrileQuery.rst
157@@ -66,6 +66,11 @@ Diagnostics
158 All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
159 Likewise, warning messages are directed to the :c:func:`TIFFWarningExtR` routine.
160
161+Note
162+----
163+
164+This functionality was introduced with libtiff 4.1.
165+
166 See also
167 --------
168
169diff --git a/doc/libtiff.rst b/doc/libtiff.rst
170index 6a0054c..d96a860 100644
171--- a/doc/libtiff.rst
172+++ b/doc/libtiff.rst
173@@ -90,11 +90,15 @@ compatibility on machines with a segmented architecture.
174 :c:func:`realloc`, and :c:func:`free` routines in the C library.)
175
176 To deal with segmented pointer issues ``libtiff`` also provides
177-:c:func:`_TIFFmemcpy`, :c:func:`_TIFFmemset`, and :c:func:`_TIFFmemmove`
178+:c:func:`_TIFFmemcpy`, :c:func:`_TIFFmemset`, and :c:func:`_TIFFmemcmp`
179 routines that mimic the equivalent ANSI C routines, but that are
180 intended for use with memory allocated through :c:func:`_TIFFmalloc`
181 and :c:func:`_TIFFrealloc`.
182
183+With ``libtiff`` 4.5 a method was introduced to limit the internal
184+memory allocation that functions are allowed to request per call
185+(see  :c:func:`TIFFOpenOptionsSetMaxSingleMemAlloc` and :c:func:`TIFFOpenExt`).
186+
187 Error Handling
188 --------------
189
190@@ -106,6 +110,10 @@ routine that can be specified with a call to :c:func:`TIFFSetErrorHandler`.
191 Likewise warning messages are directed to a single handler routine
192 that can be specified with a call to :c:func:`TIFFSetWarningHandler`
193
194+Further application-specific and per-TIFF handle (re-entrant) error handler
195+and warning handler can be set. Please refer to :doc:`/functions/TIFFError`
196+and :doc:`/functions/TIFFOpenOptions`.
197+
198 Basic File Handling
199 -------------------
200
201@@ -139,7 +147,7 @@ a ``"w"`` argument:
202     main()
203     {
204         TIFF* tif = TIFFOpen("foo.tif", "w");
205-        ... do stuff ...
206+        /* ... do stuff ... */
207         TIFFClose(tif);
208     }
209
210@@ -157,6 +165,25 @@ to always call :c:func:`TIFFClose` or :c:func:`TIFFFlush` to flush any
211 buffered information to a file.  Note that if you call :c:func:`TIFFClose`
212 you do not need to call :c:func:`TIFFFlush`.
213
214+.. warning::
215+
216+    In order to prevent out-of-memory issues when opening a TIFF file
217+    :c:func:`TIFFOpenExt` can be used and then the maximum single memory
218+    limit in byte that ``libtiff`` internal memory allocation functions
219+    are allowed to request per call can be set with
220+    :c:func:`TIFFOpenOptionsSetMaxSingleMemAlloc`.
221+
222+Example
223+
224+::
225+
226+    tmsize_t limit = (256 * 1024 * 1024);
227+    TIFFOpenOptions *opts = TIFFOpenOptionsAlloc();
228+    TIFFOpenOptionsSetMaxSingleMemAlloc(opts, limit);
229+    TIFF *tif = TIFFOpenExt("foo.tif", "w", opts);
230+    TIFFOpenOptionsFree(opts);
231+    /* ... go on here ... */
232+
233 TIFF Directories
234 ----------------
235
236--
2372.40.0
238
239