Properly compute redundancy_bytes
[opus.git] / doc / draft-ietf-codec-oggopus.xml
index e2b38aa..128816e 100644 (file)
@@ -43,7 +43,7 @@
 ]>
 <?rfc toc="yes" symrefs="yes" ?>
 
-<rfc ipr="trust200902" category="std" docName="draft-ietf-codec-oggopus-13"
+<rfc ipr="trust200902" category="std" docName="draft-ietf-codec-oggopus-14"
  updates="5334">
 
 <front>
@@ -93,7 +93,7 @@
 </address>
 </author>
 
-<date day="12" month="February" year="2016"/>
+<date day="22" month="February" year="2016"/>
 <area>RAI</area>
 <workgroup>codec</workgroup>
 
@@ -164,8 +164,32 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
 
 <section anchor="packet_organization" title="Packet Organization">
 <t>
-An Ogg Opus stream is organized as follows.
+An Ogg Opus stream is organized as follows (see
+ <xref target="packet-org-example"/> for an example).
 </t>
+
+<figure anchor="packet-org-example"
+ title="Example packet organization for a logical Ogg Opus stream"
+ align="center">
+<artwork align="center"><![CDATA[
+    Page 0         Pages 1 ... n        Pages (n+1) ...
+ +------------+ +---+ +---+ ... +---+ +-----------+ +---------+ +--
+ |            | |   | |   |     |   | |           | |         | |
+ |+----------+| |+-----------------+| |+-------------------+ +-----
+ |||ID Header|| ||  Comment Header || ||Audio Data Packet 1| | ...
+ |+----------+| |+-----------------+| |+-------------------+ +-----
+ |            | |   | |   |     |   | |           | |         | |
+ +------------+ +---+ +---+ ... +---+ +-----------+ +---------+ +--
+ ^      ^                           ^
+ |      |                           |
+ |      |                           Mandatory Page Break
+ |      |
+ |      ID header is contained on a single page
+ |
+ 'Beginning Of Stream'
+]]></artwork>
+</figure>
+
 <t>
 There are two mandatory header packets.
 The first packet in the logical Ogg bitstream MUST contain the identification
@@ -224,12 +248,16 @@ The first audio data page could have the 'continued packet' flag set
  (indicating the first audio data packet is continued from a previous page) if,
  for example, it was a live stream joined mid-broadcast, with the headers
  pasted on the front.
-A demuxer SHOULD NOT attempt to decode the data for the first packet on a page
- with the 'continued packet' flag set if the previous page with packet data
- does not end in a continued packet (i.e., did not end with a lacing value of
- 255) or if the page sequence numbers are not consecutive, unless the demuxer
- has some special knowledge that would allow it to interpret this data
- despite the missing pieces.
+If a page has the 'continued packet' flag set and one of the following
+ conditions is also true:
+<list style="symbols">
+<t>the previous page with packet data does not end in a continued packet (does
+ not end with a lacing value of 255) OR</t>
+<t>the page sequence numbers are not consecutive,</t>
+</list>
+ then a demuxer MUST NOT attempt to decode the data for the first packet on the
+ page unless the demuxer has some special knowledge that would allow it to
+ interpret this data despite the missing pieces.
 An implementation MUST treat a zero-octet audio data packet as if it were a
  malformed Opus packet as described in
  Section&nbsp;3.4 of&nbsp;<xref target="RFC6716"/>.
@@ -242,12 +270,17 @@ There is no reason for the final packet on the last page to be a continued
  packet, i.e., for the final lacing value to be 255.
 However, demuxers might encounter such streams, possibly as the result of a
  transfer that did not complete or of corruption.
-A demuxer SHOULD NOT attempt to decode the data from a packet that continues
- onto a subsequent page (i.e., when the page ends with a lacing value of 255)
- if the next page with packet data does not have the 'continued packet' flag
- set or does not exist, or if the page sequence numbers are not consecutive,
- unless the demuxer has some special knowledge that would allow it to interpret
- this data despite the missing pieces.
+If a packet continues onto a subsequent page (i.e., when the page ends with a
+ lacing value of 255) and one of the following conditions is also true:
+<list style="symbols">
+<t>the next page with packet data does not have the 'continued packet' flag
+ set OR</t>
+<t>there is no next page with packet data OR</t>
+<t>the page sequence numbers are not consecutive,</t>
+</list>
+ then a demuxer MUST NOT attempt to decode the data from that packet unless the
+ demuxer has some special knowledge that would allow it to interpret this data
+ despite the missing pieces.
 There MUST NOT be any more pages in an Opus logical bitstream after a page
  marked 'end of stream'.
 </t>
@@ -739,7 +772,8 @@ Rates outside this range MAY be ignored by falling back to the default rate of
 This is a gain to be applied when decoding.
 It is 20*log10 of the factor by which to scale the decoder output to achieve
  the desired playback volume, stored in a 16-bit, signed, two's complement
- fixed-point value with 8 fractional bits (i.e., Q7.8).
+ fixed-point value with 8 fractional bits (i.e.,
+ Q7.8&nbsp;<xref target="q-notation"/>).
 <vspace blankLines="1"/>
 To apply the gain, an implementation could use
 <figure align="center">
@@ -991,9 +1025,12 @@ Players SHOULD perform channel mixing to increase or reduce the number of
 </t>
 
 <t>
-Implementations MAY use the following matrices to implement downmixing from
- multichannel files using <xref target="channel_mapping_1">Channel Mapping
- Family 1</xref>, which are known to give acceptable results for stereo.
+Implementations MAY use the matrices in
+ Figures&nbsp;<xref target="downmix-matrix-3" format="counter"/>
+ through&nbsp;<xref target="downmix-matrix-8" format="counter"/> to implement
+ downmixing from multichannel files using
+ <xref target="channel_mapping_1">Channel Mapping Family 1</xref>, which are
+ known to give acceptable results for stereo.
 Matrices for 3 and 4 channels are normalized so each coefficient row sums
  to 1 to avoid clipping.
 For 5 or more channels they are normalized to 2 as a compromise between
@@ -1210,7 +1247,8 @@ It MUST NOT indicate that the string is longer than the rest of the packet.
 </t>
 <t>User Comment #i String (variable length, UTF-8 vector):
 <vspace blankLines="1"/>
-This field contains a single user comment string.
+This field contains a single user comment encoded as a UTF-8
+ string&nbsp;<xref target="RFC3629"/>.
 There is one for each user comment indicated by the 'user comment list length'
  field.
 </t>
@@ -1246,9 +1284,9 @@ The comment header can be arbitrarily large and might be spread over a large
 Implementations MUST avoid attempting to allocate excessive amounts of memory
  when presented with a very large comment header.
 To accomplish this, implementations MAY treat a stream as invalid if it has a
- comment header larger than 125,829,120&nbsp;octets, and MAY ignore individual
- comments that are not fully contained within the first 61,440&nbsp;octets of
- the comment header.
+ comment header larger than 125,829,120&nbsp;octets (120&nbsp;MB), and MAY
+ ignore individual comments that are not fully contained within the first
61,440&nbsp;octets of the comment header.
 </t>
 
 <section anchor="comment_format" title="Tag Definitions">
@@ -1287,6 +1325,7 @@ R128_ALBUM_GAIN=111
  played as part of a particular collection of tracks.
 The gain is also a Q7.8 fixed point number in dB, as in the ID header's
  'output gain' field.
+The values '-573' and '111' given here are just examples.
 </t>
 <t>
 An Ogg Opus stream MUST NOT have more than one of each of these tags, and if
@@ -1511,14 +1550,63 @@ A brief summary of major implementations of this draft is available
 Implementations of the Opus codec need to take appropriate security
  considerations into account, as outlined in <xref target="RFC4732"/>.
 This is just as much a problem for the container as it is for the codec itself.
-Robustness against malicious payloads is extremely important.
-Malicious payloads MUST NOT cause an implementation to overrun its allocated
- memory or to take an excessive amount of resources to decode.
-Although problems in encoding applications are typically rarer, the same
- applies to the muxer.
-Malicious audio input streams MUST NOT cause an implementation to overrun its
- allocated memory or consume excessive resources because this would allow an
- attacker to attack transcoding gateways.
+Malicious payloads and/or input streams can be used to attack codec
+ implementations.
+Implementations MUST NOT overrun their allocated memory nor consume excessive
+ resources when decoding payloads or processing input streams.
+Although problems in encoding applications are typically rarer, this still
+ applies to a muxer, as vulnerabilities would allow an attacker to attack
+ transcoding gateways.
+</t>
+
+<t>
+Header parsing code contains the most likely area for potential overruns.
+It is important for implementations to ensure their buffers contain enough
+ data for all of the required fields before attempting to read it (for example,
+ for all of the channel map data in the ID header).
+Implementations would do well to validate the indices of the channel map, also,
+ to ensure they meet all of the restrictions outlined in
+ <xref target="channel_mapping"/>, in order to avoid attempting to read data
+ from channels that do not exist.
+</t>
+
+<t>
+To avoid excessive resource usage, we advise implementations to be especially
+ wary of streams that might cause them to process far more data than was
+ actually transmitted.
+For example, a relatively small comment header may contain values for the
+ string lengths or user comment list length that imply that it is many
+ gigabytes in size.
+Even computing the size of the required buffer could overflow a 32-bit integer,
+ and actually attempting to allocate such a buffer before verifying it would be
+ a reasonable size is a bad idea.
+After reading the user comment list length, implementations might wish to
+ verify that the header contains at least the minimum amount of data for that
+ many comments (4&nbsp;additional octets per comment, to indicate each has a
+ length of zero) before proceeding any further, again taking care to avoid
+ overflow in these calculations.
+If allocating an array of pointers to point at these strings, the size of the
+ pointers may be larger than 4&nbsp;octets, potentially requiring a separate
+ overflow check.
+</t>
+
+<t>
+Another bug in this class we have observed more than once involves the handling
+ of invalid data at the end of a stream.
+Often, implementations will seek to the end of a stream to locate the last
+ timestamp in order to compute its total duration.
+If they do not find a valid capture pattern and Ogg page from the desired
+ logical stream, they will back up and try again.
+If care is not taken to avoid re-scanning data that was already scanned, this
+ search can quickly devolve into something with a complexity that is quadratic
+ in the amount of invalid data.
+</t>
+
+<t>
+In general when seeking, implementations will wish to be cautious about the
+ effects of invalid granule position values, and ensure all algorithms will
+ continue to make progress and eventually terminate, even if these are missing
+ or out-of-order.
 </t>
 
 <t>
@@ -1588,8 +1676,8 @@ IANA is requested to create a new name space of "Opus Channel Mapping
  Families".
 This will be a new registry on the IANA Matrix, and not a subregistry of an
  existing registry.
-Modifications to this registry follow the "Specification Required with Expert
Review" registration policy as defined in <xref target="RFC5226"/>.
+Modifications to this registry follow the "Specification Required" registration
+ policy as defined in <xref target="RFC5226"/>.
 Each registry entry consists of a Channel Mapping Family Number, which is
  specified in decimal in the range 0 to 255, inclusive, and a Reference (or
  list of references)
@@ -1685,24 +1773,24 @@ In&nbsp;<xref target="iana"/>, "RFCXXXX" is to be replaced with the RFC number
 </reference>
 
 <reference anchor="hanning"
- target="https://en.wikipedia.org/wiki/Hamming_function#Hann_.28Hanning.29_window">
+ target="https://en.wikipedia.org/w/index.php?title=Window_function&amp;oldid=703074467#Hann_.28Hanning.29_window">
   <front>
     <title>Hann window</title>
     <author>
       <organization>Wikipedia</organization>
     </author>
-    <date month="May" year="2013"/>
+    <date month="February" year="2016"/>
   </front>
 </reference>
 
 <reference anchor="linear-prediction"
- target="https://en.wikipedia.org/wiki/Linear_predictive_coding">
+ target="https://en.wikipedia.org/w/index.php?title=Linear_predictive_coding&amp;oldid=687498962">
   <front>
     <title>Linear Predictive Coding</title>
     <author>
       <organization>Wikipedia</organization>
     </author>
-    <date month="January" year="2014"/>
+    <date month="October" year="2015"/>
   </front>
 </reference>
 
@@ -1717,6 +1805,14 @@ In&nbsp;<xref target="iana"/>, "RFCXXXX" is to be replaced with the RFC number
 </front>
 </reference>
 
+<reference anchor="q-notation"
+ target="https://en.wikipedia.org/w/index.php?title=Q_%28number_format%29&amp;oldid=697252615">
+<front>
+<title>Q (number format)</title>
+<author><organization>Wikipedia</organization></author>
+<date month="December" year="2015"/>
+</front>
+</reference>
 
 <reference anchor="replay-gain"
  target="https://wiki.xiph.org/VorbisComment#Replay_Gain">