[xiph-commits] r14799 - trunk/theora/include/theora

[tterribe at svn.xiph.org]

Author: tterribe
Date: 2008-04-25 08:57:48 -0700 (Fri, 25 Apr 2008)
New Revision: 14799

Modified:
   trunk/theora/include/theora/theoradec.h
Log:
Add a security warning about large frame sizes.


Modified: trunk/theora/include/theora/theoradec.h
===================================================================
--- trunk/theora/include/theora/theoradec.h	2008-04-25 14:18:40 UTC (rev 14798)
+++ trunk/theora/include/theora/theoradec.h	2008-04-25 15:57:48 UTC (rev 14799)
@@ -213,6 +213,22 @@
 extern int th_decode_headerin(th_info *_info,th_comment *_tc,
  th_setup_info **_setup,ogg_packet *_op);
 /**Allocates a decoder instance.
+ *
+ * <b>Security Warning:</b> The Theora format supports very large frame sizes,
+ *  potentially even larger than the address space of a 32-bit machine, and
+ *  creating a decoder context allocates the space for several frames of data.
+ * If the allocation fails here, your program will crash, possibly at some
+ *  future point because the OS kernel returned a valid memory range and will
+ *  only fail when it tries to map the pages in it the first time they are
+ *  used.
+ * Even if it succeeds, you may experience a denial of service if the frame
+ *  size is large enough to cause excessive paging.
+ * If you are integrating libtheora in a larger application where such things
+ *  are undesirable, it is highly recommended that you check the frame size in
+ *  \a _info before calling this function and refuse to decode streams where it
+ *  is larger than some reasonable maximum.
+ * libtheora will not check this for you, because there may be machines that
+ *  can handle such streams and applications that wish to.
  * \param _info  A #th_info struct filled via th_decode_headerin().
  * \param _setup A #th_setup_info handle returned via
  *                th_decode_headerin().
@@ -253,7 +269,7 @@
  *                       The player can skip the call to th_decode_ycbcr_out(),
  *                        as the contents of the decoded frame buffer have not
  *                        changed.
- * \retval TH_EFAULT     \a _dec or _op was <tt>NULL</tt>.
+ * \retval TH_EFAULT     \a _dec or \a _op was <tt>NULL</tt>.
  * \retval TH_EBADPACKET \a _op does not contain encoded video data.
  * \retval TH_EIMPL      The video data uses bitstream features which this
  *                        library does not support.*/