docs/enduser-youtube.html

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   3     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   4 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   6 <meta name="description" content="Explains how to safely allow the embedding of flash from trusted sites in HTML Purifier." />
   7 <link rel="stylesheet" type="text/css" href="./style.css" />
   8
   9 <title>Embedding YouTube Videos - HTML Purifier</title>
  10
  11 </head><body>
  12
  13 <h1 class="subtitled">Embedding YouTube Videos</h1>
  14 <div class="subtitle">...as well as other dangerous active content</div>
  15
  16 <div id="filing">Filed under End-User</div>
  17 <div id="index">Return to the <a href="index.html">index</a>.</div>
  18 <div id="home"><a href="http://htmlpurifier.org/">HTML Purifier</a> End-User Documentation</div>
  19
  20 <p>Clients like their YouTube videos. It gives them a warm fuzzy feeling when
  21 they see a neat little embedded video player on their websites that can play
  22 the latest clips from their documentary &quot;Fido and the Bones of Spring&quot;.
  23 All joking aside, the ability to embed YouTube videos or other active
  24 content in their pages is something that a lot of people like.</p>
  25
  26 <p>This is a <em>bad</em> idea. The moment you embed anything untrusted,
  27 you will definitely be slammed by a manner of nasties that can be
  28 embedded in things from your run of the mill Flash movie to
  29 <a href="http://blog.spywareguide.com/2006/12/myspace_phish_attack_leads_use.html">Quicktime movies</a>.
  30 Even <code>img</code> tags, which HTML Purifier allows by default, can be
  31 dangerous. Be distrustful of anything that tells a browser to load content
  32 from another website automatically.</p>
  33
  34 <p>Luckily for us, however, whitelisting saves the day. Sure, letting users
  35 include any old random flash file could be dangerous, but if it's
  36 from a specific website, it probably is okay. If no amount of pleading will
  37 convince the people upstairs that they should just settle with just linking
  38 to their movies, you may find this technique very useful.</p>
  39
  40 <h2>Looking in</h2>
  41
  42 <p>Below is custom code that allows users to embed
  43 YouTube videos. This is not favoritism: this trick can easily be adapted for
  44 other forms of embeddable content.</p>
  45
  46 <p>Usually, websites like YouTube give us boilerplate code that you can insert
  47 into your documents. YouTube's code goes like this:</p>
  48
  49 <pre>
  50 &lt;object width=&quot;425&quot; height=&quot;350&quot;&gt;
  51   &lt;param name=&quot;movie&quot; value=&quot;http://www.youtube.com/v/AyPzM5WK8ys&quot; /&gt;
  52   &lt;param name=&quot;wmode&quot; value=&quot;transparent&quot; /&gt;
  53   &lt;embed src=&quot;http://www.youtube.com/v/AyPzM5WK8ys&quot;
  54          type=&quot;application/x-shockwave-flash&quot;
  55          wmode=&quot;transparent&quot; width=&quot;425&quot; height=&quot;350&quot; /&gt;
  56 &lt;/object&gt;
  57 </pre>
  58
  59 <p>There are two things to note about this code:</p>
  60
  61 <ol>
  62     <li><code>&lt;embed&gt;</code> is not recognized by W3C, so if you want
  63         standards-compliant code, you'll have to get rid of it.</li>
  64     <li>The code is exactly the same for all instances, except for the
  65         identifier <tt>AyPzM5WK8ys</tt> which tells us which movie file
  66         to retrieve.</li>
  67 </ol>
  68
  69 <p>What point 2 means is that if we have code like <code>&lt;span
  70 class=&quot;embed-youtube&quot;&gt;AyPzM5WK8ys&lt;/span&gt;</code> your
  71 application can reconstruct the full object from this small snippet that
  72 passes through HTML Purifier <em>unharmed</em>.
  73 <a href="http://htmlpurifier.org/svnroot/htmlpurifier/trunk/library/HTMLPurifier/Filter/YouTube.php">Show me the code!</a></p>
  74
  75 <p>And the corresponding usage:</p>
  76
  77 <pre>&lt;?php
  78     // assuming $purifier is an instance of HTMLPurifier
  79     require_once 'HTMLPurifier/Filter/YouTube.php';
  80     $purifier-&gt;addFilter(new HTMLPurifier_Filter_YouTube());
  81 ?&gt;</pre>
  82
  83 <p>There is a bit going in the two code snippets, so let's explain.</p>
  84
  85 <ol>
  86     <li>This is a Filter object, which intercepts the HTML that is
  87         coming into and out of the purifier. You can add as many
  88         filter objects as you like. <code>preFilter()</code>
  89         processes the code before it gets purified, and <code>postFilter()</code>
  90         processes the code afterwards. So, we'll use <code>preFilter()</code> to
  91         replace the object tag with a <code>span</code>, and <code>postFilter()</code>
  92         to restore it.</li>
  93     <li>The first preg_replace call replaces any YouTube code users may have
  94         embedded into the benign span tag. Span is used because it is inline,
  95         and objects are inline too. We are very careful to be extremely
  96         restrictive on what goes inside the span tag, as if an errant code
  97         gets in there it could get messy.</li>
  98     <li>The HTML is then purified as usual.</li>
  99     <li>Then, another preg_replace replaces the span tag with a fully fledged
 100         object. Note that the embed is removed, and, in its place, a data
 101         attribute was added to the object. This makes the tag standards
 102         compliant! It also breaks Internet Explorer, so we add in a bit of
 103         conditional comments with the old embed code to make it work again.
 104         It's all quite convoluted but works.</li>
 105 </ol>
 106
 107 <h2>Warning</h2>
 108
 109 <p>There are a number of possible problems with the code above, depending
 110 on how you look at it.</p>
 111
 112 <h3>Cannot change width and height</h3>
 113
 114 <p>The width and height of the final YouTube movie cannot be adjusted. This
 115 is because I am lazy. If you really insist on letting users change the size
 116 of the movie, what you need to do is package up the attributes inside the
 117 span tag (along with the movie ID). It gets complicated though: a malicious
 118 user can specify an outrageously large height and width and attempt to crash
 119 the user's operating system/browser. You need to either cap it by limiting
 120 the amount of digits allowed in the regex or using a callback to check the
 121 number.</p>
 122
 123 <h3>Trusts media's host's security</h3>
 124
 125 <p>By allowing this code onto our website, we are trusting that YouTube has
 126 tech-savvy enough people not to allow their users to inject malicious
 127 code into the Flash files.  An exploit on YouTube means an exploit on your
 128 site.  Even though YouTube is run by the reputable Google, it
 129 <a href="http://ha.ckers.org/blog/20061213/google-xss-vuln/">doesn't</a>
 130 mean they are
 131 <a href="http://ha.ckers.org/blog/20061208/xss-in-googles-orkut/">invulnerable.</a>
 132 You're putting a certain measure of the job on an external provider (just as
 133 you have by entrusting your user input to HTML Purifier), and
 134 it is important that you are cognizant of the risk.</p>
 135
 136 <h3>Poorly written adaptations compromise security</h3>
 137
 138 <p>This should go without saying, but if you're going to adapt this code
 139 for Google Video or the like, make sure you do it <em>right</em>. It's
 140 extremely easy to allow a character too many in <code>postFilter()</code> and
 141 suddenly you're introducing XSS into HTML Purifier's XSS free output. HTML
 142 Purifier may be well written, but it cannot guard against vulnerabilities
 143 introduced after it has finished.</p>
 144
 145 <h2>Help out!</h2>
 146
 147 <p>If you write a filter for your favorite video destination (or anything
 148 like that, for that matter), send it over and it might get included
 149 with the core!</p>
 150
 151 </body>
 152 </html>