--- a/encrypted-media/encrypted-media-respec.html Fri Oct 10 14:39:26 2014 -0700
+++ b/encrypted-media/encrypted-media-respec.html Fri Oct 10 14:40:15 2014 -0700
@@ -158,7 +158,9 @@
-->
</section>
- <h2 id="introduction">1. Introduction</h2>
+ <!-- TODO: Indent the contents of each <section>. -->
+ <section id="introduction">
+ <h2>Introduction</h2>
<non-normative-section/>
<p>
This proposal allows JavaScript to select content protection mechanisms, control license/key exchange, and implement custom license management algorithms.
@@ -169,16 +171,20 @@
</p>
<img src="stack_overview.svg" alt="A generic stack implemented using the proposed APIs" height="700"></img>
- <h3 id="definitions">1.1. Definitions</h3>
+ <section id="definitions">
+ <h3>Definitions</h3>
<p>Text in <span class="non-normative">this font and color</span> is non-normative.</p>
- <h4 id="cdm">1.1.1. Content Decryption Module (CDM)</h4>
+ <section id="cdm">
+ <h4>Content Decryption Module (CDM)</h4>
<p>The Content Decryption Module (CDM) is a generic term for the client component that provides the functionality, including decryption, for one or more <a href="#key-system">Key Systems</a>.</p>
<p class="non-normative">Implementations may or may not separate the implementations of CDMs or treat them as separate from the user agent.
This is transparent to the API and application.
A user agent may support one or more CDMs.</p>
+ </section>
- <h4 id="key-system">1.1.2. Key System</h4>
+ <section id="key-system">
+ <h4>Key System</h4>
<p>A Key System is a generic term for a decryption mechanism and/or content protection provider.
Key System strings provide unique identification of a Key System.
They are used by the user agent to select the <a href="#cdm">Content Decryption Modules</a> and identify the source of a key-related event.
@@ -193,8 +199,10 @@
For example, "com.example.somesystem.1" and "com.example.somesystem.1_5".
Key System providers should keep in mind that these will be used for comparison and discovery, so they should be easy to compare and the structure should remain reasonably simple.
</p>
+ </section>
- <h4 id="key-session">1.1.3. Key Session</h4>
+ <section id="key-session">
+ <h4>Key Session</h4>
<p>A Key Session, or simply Session, provides a context for message exchange with the CDM as a result of which key(s) are made available to be <a href="#cdm">CDM</a>.
Sessions are embodied as <coderef>MediaKeySession</coderef> objects.
Each Key session is associated with a single instance of <a href="#initialization-data">Initialization Data</a> provided in the <methodref>generateRequest</methodref> call.
@@ -203,8 +211,10 @@
Other <coderef>MediaKeys</coderef> objects, <a href="#cdm">CDM</a> instances, and media elements may <em>not</em> access the key session or use its key(s).
Key sessions and the keys they contain are no longer usable by the CDM for decryption when the <a href="#algorithms-session-close">session is closed</a>, including when the <coderef>MediaKeySession</coderef> object is destroyed.
</p>
+ </section>
- <h4 id="session-id">1.1.4. Session ID</h4>
+ <section id="session-id">
+ <h4>Session ID</h4>
<p>A Session ID is a unique string identifier generated by the <a href="#cdm">CDM</a> that can be used by the application to identify <coderef>MediaKeySession</coderef> objects.
<span class="non-normative">(The underlying content protection protocol does not necessarily need to support Session IDs.)</span>
</p>
@@ -214,8 +224,10 @@
<p>Each Session ID shall be unique within the browsing context in which it was created.
Session IDs for "<coderef prefix="sessiontype">persistent</coderef>" sessions must be unique within the <a href="http://www.w3.org/TR/html5/browsers.html#origin-0">origin</a> over time, including across browsing sessions.
</p>
+ </section>
- <h4 id="decryption-key">1.1.5. Key</h4>
+ <section id="decryption-key">
+ <h4>Key</h4>
<p>Unless otherwise stated, key refers to a decryption key that can be used to decrypt blocks within <videoanchor name="media-data">media data</videoanchor>.
Each such key is uniquely identified by a <a href="#decryption-key-id">key ID</a>.
A key is associated with the <a href="#key-session">session</a> used to provide it to the CDM. (The same key may be present in multiple sessions.)
@@ -223,19 +235,25 @@
</p>
<p>A key is considered <em>usable</em> if the CDM is certain the key is currently usable for decryption. <span class="non-normative">For example, a key is not usable if its license has expired.</span></p>
-
- <h4 id="decryption-key-id">1.1.6. Key ID</h4>
+ </section>
+
+ <section id="decryption-key-id">
+ <h4>Key ID</h4>
<p>A <a href="#decryption-key">key</a> is associated with a key ID, which uniquely identifies a key.
The container specifies the ID of the key that can decrypt a block or set of blocks within the <videoanchor name="media-data">media data</videoanchor>.
<a href="#initialization-data">Initialization Data</a> may contain key ID(s) to identify the keys that are needed to decrypt the media data.
However, there is no requirement that Initialization Data contain any or all key IDs used in the <videoanchor name="media-data">media data</videoanchor> or <videoanchor name="media-resource">media resource</videoanchor>.
<a href="#license">Licenses</a> provided to the CDM associate each key with a key ID so the <a href="#cdm">CDM</a> can select the appropriate key when decrypting an encrypted block of media data.
</p>
+ </section>
- <h4 id="license">1.1.7. License</h4>
+ <section id="license">
+ <h4>License</h4>
<p>A license is key system-specific state information that includes one or more <a href="#decryption-key">key(s)</a> - each associated with a <a href="#decryption-key-id">key ID</a> - and potentially other information about key usage.</p>
+ </section>
- <h4 id="initialization-data">1.1.8. Initialization Data</h4>
+ <section id="initialization-data">
+ <h4>Initialization Data</h4>
<p class="non-normative">
<a href="#key-system">Key Systems</a> usually require a block of initialization data containing information about the stream to be decrypted before they can construct a license request message.
This block could be a simple key or content ID or a more complex structure containing such information.
@@ -259,21 +277,28 @@
The Encrypted Media Extensions Stream Format and Initialization Data Format Registry [[EME-REGISTRY]]
provides the mapping from initialization data type string to the specification for each format.
</p>
+ </section>
-
- <h4 id="cross-origin">1.1.9. Cross Origin Limitations</h4>
+ <section id="cross-origin">
+ <h4>Cross Origin Limitations</h4>
<p>During playback, embedded media data is exposed to script in the embedding <a href="http://www.w3.org/TR/html5/browsers.html#origin-0">origin</a>.
In order for the API to provide <coderef>initData</coderef> in the <coderef>encrypted</coderef> event, <videoanchor name="media-data">media data</videoanchor> must be <cors-same-origin/> with the embedding page.
If <videoanchor name="media-data">media data</videoanchor> is cross-origin with the embedding document, authors should use the <videoanchor name="attr-media-crossorigin">crossorigin</videoanchor> attribute
on the <a href="#media-element">media element</a> and CORS headers on the <videoanchor name="media-data">media data</videoanchor> response to make it <cors-same-origin/>.
</p>
+ </section>
- <h4 id="mixed-content">1.1.10. Mixed Content Limitations</h4>
+ <section id="mixed-content">
+ <h4>Mixed Content Limitations</h4>
<p>During playback, embedded media data is exposed to script in the embedding <a href="http://www.w3.org/TR/html5/browsers.html#origin-0">origin</a>.
In order for the API to provide <coderef>initData</coderef> in the <coderef>encrypted</coderef> event, <videoanchor name="media-data">media data</videoanchor> must not be mixed content as defined in [MIXED-CONTENT].
</p>
+ </section>
+ </section>
+ </section>
- <h2 id="mediakeys">2. MediaKeys Object</h2>
+ <section id="mediakeys">
+ <h2>MediaKeys Object</h2>
<p>The MediaKeys object represents a set of keys that an associated HTMLMediaElement can use for decryption of <videoanchor name="media-data">media data</videoanchor> during playback.
It also represents a CDM instance.
</p>
@@ -292,11 +317,14 @@
};
</pre>
- <h3 id="mediakeys-attributes">2.1. Attributes</h3>
+ <section id="mediakeys-attributes">
+ <h3>Attributes</h3>
<p>The <codedfn>keySystem</codedfn> attribute identifies the <a href="#key-system">Key System</a> being used.</p>
+ </section>
- <h3 id="mediakeys-methods">2.2. Methods</h3>
+ <section id="mediakeys-methods">
+ <h3>Methods</h3>
<p>For methods that return a promise, all errors are reported asynchronously by rejecting the returned Promise. This includes WebIDL type mapping errors.</p>
<p>The steps of an algorithm are always aborted when resolving or rejecting a promise.</p>
@@ -442,9 +470,12 @@
</dl>
</li>
</ol>
-
+ </section>
+ </section>
- <h2 id="mediakeysession">3. MediaKeySession Object</h2>
+
+ <section id="mediakeysession">
+ <h2>MediaKeySession Object</h2>
<p>The MediaKeySession object represents a <a href="#key-session">key session</a>.</p>
<pre class="was-idl">
interface <precodedfn>MediaKeySession</precodedfn> : <dom4ref name="eventtarget">EventTarget</dom4ref> {
@@ -466,7 +497,8 @@
};
</pre>
- <h3 id="mediakeysession-attributes">3.1. Attributes</h3>
+ <section id="mediakeysession-attributes">
+ <h3>Attributes</h3>
<p>The <codedfn>sessionId</codedfn> attribute is the <a href="#session-id">Session ID</a> for this object and the associated key(s) or license(s).</p>
@@ -475,8 +507,10 @@
<p>The <codedfn>closed</codedfn> attribute signals when object becomes closed as a result of the <a href="#algorithms-session-close">Session Close</a> algorithm being run.
This promise can only be fulfilled and is never rejected.</p>
+ </section>
- <h3 id="mediakeysession-methods">3.2. Methods</h3>
+ <section id="mediakeysession-methods">
+ <h3>Methods</h3>
<p>For methods that return a promise, all errors are reported asynchronously by rejecting the returned Promise. This includes WebIDL type mapping errors.</p>
<p>The steps of an algorithm are always aborted when resolving or rejecting a promise.</p>
@@ -743,8 +777,10 @@
</ol>
</li>
</ol>
+ </section>
- <h3 id="mediakeysession-event-definitions">3.3. Event Definitions</h3>
+ <section id="mediakeysession-event-definitions">
+ <h3>Event Definitions</h3>
<pre class="was-idl">
enum <precodedfn>MediaKeyMessageType</precodedfn> { "<precodedfn>licenserequest</precodedfn>", "<precodedfn>licenserenewal</precodedfn>", "<precodedfn>licenserelease</precodedfn>" };
@@ -775,8 +811,10 @@
<p>The <codedfn>message</codedfn> attribute contains a message from the CDM. Messages are Key System-specific.</p>
<p>Events are constructed as defined in <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#constructing-events">Constructing events</a>, in [DOM4].</p>
</div>
+ </section>
- <h3 id="mediakeysession-events">3.4. Event Summary</h3>
+ <section id="mediakeysession-events">
+ <h3>Event Summary</h3>
<non-normative-section/>
<p>Note: In some implementations, <coderef>MediaKeySession</coderef> objects may not fire any events until the <coderef>MediaKeys</coderef> object is associated with a media element using <methodref>setMediaKeys</methodref>.</p>
@@ -802,10 +840,13 @@
</tr>
</tbody>
</table>
+ </section>
- <h3 id="mediakeysession-algorithms">3.5. Algorithms</h3>
+ <section id="mediakeysession-algorithms">
+ <h3>Algorithms</h3>
- <h4 id="algorithms-queue-message">3.5.1. Queue a "message" Event</h4>
+ <section id="algorithms-queue-message">
+ <h4>Queue a "message" Event</h4>
<p>The Queue a "message" Event algorithm is run when the CDM needs to queue a message event to a <coderef>MediaKeySession</coderef> object.
Requests to run this algorithm include a target <coderef>MediaKeySession</coderef> object, a <var title="true">message type</var>, and a <var title="true">message</var>.
</p>
@@ -821,8 +862,10 @@
</li></ul>
</li>
</ol>
+ </section>
- <h4 id="algorithms-keys-changed">3.5.2. Usable Keys Changed</h4>
+ <section id="algorithms-keys-changed">
+ <h4>Usable Keys Changed</h4>
<p>The Usable Keys Changed algorithm is run when the CDM changes the set of keys in the session that may be used for decryption.
This can happen as the result of an <methodref>update</methodref> call or some other event.
Requests to run this algorithm include a target <coderef>MediaKeySession</coderef> object.
@@ -835,8 +878,10 @@
<p>The user agent may choose to skip this step if it knows resuming will fail <span class="non-normative">(i.e. no additional keys became available)</span>.</p>
</li>
</ol>
+ </section>
- <h4 id="algorithms-update-expiration">3.5.3. Update Expiration</h4>
+ <section id="algorithms-update-expiration">
+ <h4>Update Expiration</h4>
<p>The Update Expiration algorithm is run when the CDM changes the expiration time of a session.
This can happen as the result of an <methodref>update</methodref> call or some other event.
Requests to run this algorithm include a target <coderef>MediaKeySession</coderef> object and the new expiration time, which may be <code>NaN</code>.
@@ -848,8 +893,10 @@
<li><p>If the new expiration time is not <code>NaN</code>, let <var title="true">expiration time</var> be the new expiration time in milliseconds since 01 January 1970 UTC.</p></li>
<li><p>Set the <var title="true">session</var>'s <coderef>expiration</coderef> attribute to <var title="true">expiration time</var>.</p></li>
</ol>
+ </section>
- <h4 id="algorithms-session-close">3.5.4. Session Close</h4>
+ <section id="algorithms-session-close">
+ <h4>Session Close</h4>
<p>The Session Close algorithm is run when the CDM closes the session associated with a <coderef>MediaKeySession</coderef> object.</p>
<p class="non-normative">The CDM may close a session at any point, such as in response to a <methodref>close</methodref> call, when the session is no longer needed, or when system resources are lost.
Keys in other sessions should be unaffected, even if they have overlapping key IDs.
@@ -861,8 +908,11 @@
<li><p>Let <var>promise</var> be the <coderef>closed</coderef> attribute of the <var title="true">session</var>.</p></li>
<li><p>Resolve <var>promise</var>.</p></li>
</ol>
+ </section>
+ </section>
- <h3 id="exceptions">3.6. Exceptions</h3>
+ <section id="exceptions">
+ <h3>Exceptions</h3>
<p id="error-names">The methods report errors by rejecting the returned promise with a <code><dom4ref name="exception-domexception">DOMException</dom4ref></code>.
The following <dom4ref name="error-names">DOMException names from DOM4</dom4ref> are used in the algorithms.
Causes specified specified in the algorithms are listed alongside each name, though these names may be used for other reasons as well.
@@ -912,8 +962,10 @@
</tr>
</tbody>
</table>
+ </section>
- <h3 id="session-storage">3.7. Session Storage and Persistence</h3>
+ <section id="session-storage">
+ <h3>Session Storage and Persistence</h3>
<p>This section provides an overview of session stroage and persistence that complements the algorithms.</p>
<p>If this object's <var title="true">session type</var> is not "<coderef prefix="sessiontype">persistent</coderef>", the user agent and CDM must <em>not</em> persist a record of or data related to the session at any point.
This includes license(s), key(s), and the <a href="#session-id">Session ID</a>.
@@ -934,9 +986,12 @@
The CDM may also remove sessions as appropriate, but applications should not rely on this.
</p>
<p class="non-normative">See the <a href="#security">Security Considerations</a> and <a href="#privacy">Privacy Considerations</a> sections for additional considerations when supporting persistent storage.</p>
+ </section>
+ </section>
- <h2 id="htmlmediaelement-extensions">4. HTMLMediaElement Extensions</h2>
+ <section id="htmlmediaelement-extensions">
+ <h2>HTMLMediaElement Extensions</h2>
<p>This section specifies additions to and modifications of the <a href="http://www.w3.org/TR/html5/embedded-content-0.html#htmlmediaelement">HTMLMediaElement</a> when the Encrypted Media Extensions are supported.</p>
<pre class="was-idl">
enum <precodedfn>MediaWaitingFor</precodedfn> { "<precodedfn prefix="waitingfor">none</precodedfn>", "<precodedfn prefix="waitingfor">data</precodedfn>", "<precodedfn prefix="waitingfor">key</precodedfn>" };
@@ -951,15 +1006,18 @@
};
</pre>
- <h3 id="htmlmediaelement-attributes">4.1. Attributes</h3>
+ <section id="htmlmediaelement-attributes">
+ <h3>Attributes</h3>
<p>The <codedfn prefix="attr">mediaKeys</codedfn> attribute is the <coderef>MediaKeys</coderef> being used when decrypting encrypted <videoanchor name="media-data">media data</videoanchor> for this <a href="#media-element">media element</a>.</p>
<p>The <codedfn>waitingFor</codedfn> attribute indicates what the media element is waiting for, if anything (indicated by the <videoref name="event-media-waiting">waiting</videoref> and <videoref name="event-media-canplay">canplay</videoref> events). This is described in the <a href="#algorithms-encrypted-block">Encrypted Block Encountered</a> algorithm.</p>
<p>The <codedfn>onencrypted</codedfn> event handler for the <coderef>encrypted</coderef> event must be supported by all HTMLMediaElements as both a content attribute and an IDL attribute.</p>
+ </section>
- <h3 id="htmlmediaelement-methods">4.2. Methods</h3>
+ <section id="htmlmediaelement-methods">
+ <h3>Methods</h3>
<p>For methods that return a promise, all errors are reported asynchronously by rejecting the returned Promise. This includes WebIDL type mapping errors.</p>
<p>The steps of an algorithm are always aborted when resolving or rejecting a promise.</p>
@@ -1007,8 +1065,10 @@
<p class="non-normative">Note: Support for clearing or replacing the associated <coderef>MediaKeys</coderef> object during playback is a quality of implementation issue. In many cases it will result in a bad user experience or rejected promise.</p>
<p class="non-normative">Note: As a best practice, applications should create a MediaKeys object and call <methodref>setMediaKeys</methodref> before providing <videoanchor name="media-data">media data</videoanchor> (for example, setting the src attribute of the <a href="#media-element">media element</a>). This avoids potential delays in some implementations.</p>
+ </section>
- <h3 id="htmlmediaelement-event-definitions">4.3. Event Definitions</h3>
+ <section id="htmlmediaelement-event-definitions">
+ <h3>Event Definitions</h3>
<pre class="was-idl">
[Constructor(DOMString type, optional <precoderef>MediaEncryptedEventInit</precoderef> eventInitDict)]
interface <precodedfn>MediaEncryptedEvent</precodedfn> : <dom4ref name="event">Event</dom4ref> {
@@ -1037,8 +1097,10 @@
<p>The <codedfn>initData</codedfn> attribute contains <a href="#initialization-data">Initialization Data</a> specific to the event.</p>
<p>Events are constructed as defined in <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#constructing-events">Constructing events</a>, in [DOM4].</p>
</div>
+ </section>
- <h3 id="htmlmediaelement-events">4.4. Event Summary</h3>
+ <section id="htmlmediaelement-events">
+ <h3>Event Summary</h3>
<non-normative-section/>
<table>
@@ -1061,10 +1123,13 @@
</tr>
</tbody>
</table>
+ </section>
- <h3 id="htmlmediaelement-algorithms">4.5. Algorithms</h3>
+ <section id="htmlmediaelement-algorithms">
+ <h3>Algorithms</h3>
- <h4 id="algorithms-initdata-encountered">4.5.1. Initialization Data Encountered</h4>
+ <section id="algorithms-initdata-encountered">
+ <h4>Initialization Data Encountered</h4>
<p>The following steps are run when the <a href="#media-element">media element</a> encounters <a href="#initialization-data">Initialization Data</a> in the <videoanchor name="media-data">media data</videoanchor> during the <resource-fetch-algorithm/>:</p>
<ol>
@@ -1093,8 +1158,10 @@
<li><p><i>Continue Normal Flow</i>: Continue with the existing media element's <resource-fetch-algorithm/>.</p></li>
</ol>
+ </section>
- <h4 id="algorithms-encrypted-block">4.5.2. Encrypted Block Encountered</h4>
+ <section id="algorithms-encrypted-block">
+ <h4>Encrypted Block Encountered</h4>
<p>The following steps are run when the <a href="#media-element">media element</a> encounters a block <span class="non-normative">(i.e. frame)</span> of encrypted <videoanchor name="media-data">media data</videoanchor> during the <resource-fetch-algorithm/>:</p>
<ol>
@@ -1175,8 +1242,10 @@
<li><p>Provide the frame for rendering.</p></li>
</ol>
</div>
+ </section>
- <h4 id="algorithms-queue-waiting">4.5.3. Queue a "waiting" Event</h4>
+ <section id="algorithms-queue-waiting">
+ <h4>Queue a "waiting" Event</h4>
<p>The Queue a "waiting" Event algorithm is run when the CDM needs to queue a waiting event to a <coderef>HTMLMediaElement</coderef> object.
Requests to run this algorithm include a target <coderef>HTMLMediaElement</coderef> object.
</p>
@@ -1191,8 +1260,10 @@
</li>
<li><p>Suspend playback.</p></li>
</ol>
+ </section>
- <h4 id="algorithms-resume-playback">4.5.4. Attempt to Resume Playback If Necessary</h4>
+ <section id="algorithms-resume-playback">
+ <h4>Attempt to Resume Playback If Necessary</h4>
<p>The Attempt to Resume Playback If Necessary algorithm is run when one or more keys becomes available.
If playback is blocked waiting for a key, it resumes playback if a necessary key has been provided.
Requests to run this algorithm include a target <coderef>HTMLMediaElement</coderef> object.
@@ -1211,36 +1282,46 @@
<p>Otherwise, the <coderef>waitingFor</coderef> attribute on the <var title="true">media element</var> must not be "<coderef prefix="waitingfor">none</coderef>".</p>
</li>
</ol>
+ </section>
- <h4 id="htmlmediaelement-playing-the-media-resource">4.5.5. Playing the Media Resource Algorithm Modifications</h4>
+ <section id="htmlmediaelement-playing-the-media-resource">
+ <h4>Playing the Media Resource Algorithm Modifications</h4>
<p>The following steps are added to readyState change algorithms in <videoanchor name="playing-the-media-resource">Playing the media resource</videoanchor>:</p>
<ul>
<li>If a readyState change queues a task to fire a <videoref name="event-media-waiting">waiting</videoref> event, the user agent must also set the <coderef>waitingFor</coderef> attribute on the Media Element to "<coderef prefix="waitingfor">data</coderef>".</li>
<li>If a readyState change queues a task to fire a <videoref name="event-media-canplay">canplay</videoref> event, the user agent must also set the <coderef>waitingFor</coderef> attribute on the Media Element to "<coderef prefix="waitingfor">none</coderef>".</li>
</ul>
+ </section>
+ </section>
- <h3 id="media-element-restictions">4.4. Media Element Restrictions</h3>
+ <section id="media-element-restictions">
+ <h3>Media Element Restrictions</h3>
<non-normative-section/>
<p>Media data processed by a CDM may not be available through Javascript APIs in the usual way (for example using the CanvasRenderingContext2D drawImage() method and the AudioContext MediaElementAudioSourceNode).
This specification does not define conditions for such non-availability of media data, however, if media data is not available to Javascript APIs then these APIs may behave as if no media data was present at all.</p>
<p>Where media rendering is not performed by the UA, for example in the case of a hardware protected media pipeline, then the full set of HTML rendering capabilities, for example CSS Transforms, may not be available. One likely restriction is that
video media may be constrained to appear only in rectangular regions with sides parallel to the edges of the window and with normal orientation.</p>
+ </section>
+ </section>
- <h2 id="common-key-systems">5. Common Key Systems</h2>
+ <section id="common-key-systems">
+ <h2>Common Key Systems</h2>
<p>All user agents must support the common key systems described in this section.
<span class="non-normative">This ensures that there is a common baseline level of protection that is guaranteed to be supported in all user agents, including those that are entirely open source.
Thus, content providers that need only basic protection can build simple applications that will work on all platforms without needing to work with any content protection providers.</span>
</p>
<span id="simple-decryption-clear-key"></span> <!-- Legacy anchor name. -->
- <h3 id="clear-key">5.1. Clear Key</h3>
+ <section id="clear-key">
+ <h3>Clear Key</h3>
<p>The "org.w3.clearkey" <a href="#key-system">Key System</a> uses plain-text clear (unencrypted) key(s) to decrypt the source.
No additional client-side content protection is required.
This Key System is described below.
</p>
- <h4 id="clear-key-capabilities">5.1.1. Capabilities</h4>
+ <section id="clear-key-capabilities">
+ <h4>Capabilities</h4>
<p>The following describe how Clear Key supports key system-specific capabilities:</p>
<ul>
<li><p>The <methodref>setMediaKeys</methodref> method: Implementations may support associating the <coderef>MediaKeys</coderef> object with more than one <coderef>HTMLMediaElement</coderef>.</p></li>
@@ -1248,8 +1329,10 @@
<li><p>The <methodref>isTypeSupported</methodref> method: There are no supported <var title="true">capability</var> values.</p></li>
<li><p>The "<coderef prefix="sessiontype">persistent</coderef>" <coderef>SessionType</coderef>: Implementations may support this type.</p></li>
</ul>
-
- <h4 id="clear-key-behavior">5.1.2. Behavior</h4>
+ </section>
+
+ <section id="clear-key-behavior">
+ <h4>Behavior</h4>
<p>The following describe how Clear Key implements key system-specific behaviors:</p>
<ul>
<li><p>In the <methodref>generateRequest</methodref> algorithm:</p>
@@ -1272,8 +1355,10 @@
Implementations should support the "<a href="keyids-format.html">keyids</a>" type and other types appropriate for content types supported by the user agent.
</p></li>
</ul>
+ </section>
- <h4 id="clear-key-request-format">5.1.3. License Request Format</h4>
+ <section id="clear-key-request-format">
+ <h4>License Request Format</h4>
<p>This section describes the format of the license request provided to the application via the <coderef>message</coderef> attribute of the <precoderef prefix="event">message</precoderef> event.</p>
<p>The format is a JSON object containing the following members:</p>
@@ -1289,7 +1374,8 @@
</p>
<!-- Will be <section class="informative"> -->
- <h5 id="clear-key-request-format-example">5.1.3.1. Example</h5>
+ <section id="clear-key-request-format-example">
+ <h5>Example</h5>
<non-normative-section/>
<p>The following example is a license request for a temporary license for two key IDs. (Line breaks are for readability only.)</p>
<pre class="example">
@@ -1302,8 +1388,11 @@
"type":"<precoderef prefix="sessiontype">temporary</precoderef>"
}
</pre>
+ </section>
+ </section>
- <h4 id="clear-key-license-format">5.1.4. License Format</h4>
+ <section id="clear-key-license-format">
+ <h4>License Format</h4>
<p>This section describes the format of the license to be provided via the <var title="true">response</var> parameter of the <methodref>update</methodref> method.</p>
<p>The format is a JSON Web Key (JWK) Set containing representation of the symmetric key to be used for decryption, as defined in the <a href="http://tools.ietf.org/html/draft-ietf-jose-json-web-key">IETF Internet-draft JSON Web Key (JWK) specification</a>.</p>
@@ -1330,7 +1419,8 @@
</p>
<!-- Will be <section class="informative"> -->
- <h5 id="clear-key-license-format-example">5.1.4.1. Example</h5>
+ <section id="clear-key-license-format-example">
+ <h5>Example</h5>
<non-normative-section/>
<p>The following example is a JWK Set containing a single symmetric key. (Line breaks are for readability only.)</p>
<pre class="example">
@@ -1344,16 +1434,23 @@
}],
"type":"<precoderef prefix="sessiontype">temporary</precoderef>"
}</pre>
+ </section>
+ </section>
<!-- Will be <section class="informative"> -->
- <h4 id="using-base64url">5.1.5. Using base64url</h4>
+ <section id="using-base64url">
+ <h4>Using base64url</h4>
<non-normative-section/>
<p>For more information on base64url and working with it, see the Base64url Encoding entry in the <a href="http://tools.ietf.org/html/draft-ietf-jose-json-web-signature#section-2">Terminology section</a> and <a href="http://tools.ietf.org/html/draft-ietf-jose-json-web-signature#appendix-C">Notes on implementing base64url encoding without padding</a> of the JSON Web Signature (JWS) specification.
Specifically, there is no '=' padding, and the characters '-' and '_' must be used instead of '+' and '/', respectively.
</p>
+ </section>
+ </section>
+ </section>
- <h2 id="security">6. Security Considerations</h2>
+ <section id="security">
+ <h2>Security Considerations</h2>
<div class="nonnormative">
<p>User Agent and Key System implementations must consider <videoanchor name="media-data">media data</videoanchor>, <a href="#initialization-data">Initialization Data</a>, responses (i.e. data passed to <methodref>update</methodref>), licenses, key data, and all other data provided by the application as untrusted content and potential attack vectors.
@@ -1378,21 +1475,28 @@
</p>
</div>
+ </section>
- <h2 id="privacy">7. Privacy Considerations</h2>
+ <section id="privacy">
+ <h2>Privacy Considerations</h2>
<div class="nonnormative">
<p>The presence or use of Key Systems on a user's device raises a number of privacy issues, falling into two categories: (a) user-specific information that may be disclosed by the EME interface itself, or within messages from Key Systems and (b) user-specific information that may be persistently stored on the users device.</p>
<p>User Agents should take responsibility for providing users with adequate control over their own privacy. Since User Agents may integrate with third party CDM implementations, CDM implementers must provide sufficient information and controls to user agent implementers to enable them to implement appropriate techniques to ensure users have control over their privacy, including but not limited to the techniques described below.</p>
- <h3 id="privacy-disclosure">7.1. Information Disclosed by EME and Key Systems</h3>
+ <section id="privacy-disclosure">
+ <h3>Information Disclosed by EME and Key Systems</h3>
<p>Concerns regarding information disclosed by EME and Key Systems fall into two categories, concerns about non-specific information that may nevertheless contribute to the possibility of fingerprinting a user agent or device and user-specific information that may be used directly for user tracking.</p>
+ </section>
- <h4 id="privacy-fingerprinting">7.1.1 Fingerprinting</h4>
+ <section id="privacy-fingerprinting">
+ <h4>Fingerprinting</h4>
<p>Malicious applications may be able to fingerprint users or user agents by detecting or enumerating the list of Key Systems that are supported and related information. If proper origin protections are not provided this could include detection of sites that have been visited and information stored for those sites. In particular, Key Systems should not share key or other data between origins.</p>
+ </section>
- <h4 id="privacy-leakage">7.1.2 Information Leakage</h4>
+ <section id="privacy-leakage">
+ <h4>Information Leakage</h4>
<p>CDMs, especially those implemented outside the user agent, may not have the same fundamental isolations as the web platform.
It is important that steps be taken to avoid information leakage, especially across origins.
This includes both in-memory and stored data.
@@ -1409,8 +1513,10 @@
<li>Persisted session data, if applicable, is stored on a per-origin basis.</li>
<li>Only data stored by the requesting origin may be loaded.</li>
</ul>
+ </section>
- <h4 id="privacy-tracking">7.1.3 Tracking</h4>
+ <section id="privacy-tracking">
+ <h4>Tracking</h4>
<p>User-specific information may be obtained over the EME API in two ways: through detection of stored keys and through Key System messages.</p>
<p>Key Systems may access or create persistent or semi-persistent identifiers for a device or user of a device. In some cases these identifiers may be bound to a specific device in a secure manner. If these identifiers are present in Key System messages, then devices and/or users may be tracked. If the mitigations below are not applied this could include both tracking of users / devices over time and associating multiple users of a given device. If not mitigated, such tracking may take three forms depending on the design of the Key System:</p>
@@ -1459,8 +1565,10 @@
<p>While these suggestions prevent trivial use of this feature for user tracking, they do not block it altogether. Within a single domain, a site can continue to track the user during a session, and can then pass all this information to a third party along with any identifying information (names, credit card numbers, addresses) obtained by the site. If a third party cooperates with multiple sites to obtain such information, and if identifiers are not per-origin, then a profile can still be created.</p>
<p>It is important to note that identifiers that are non-clearable, non-origin-specific or hardware-bound exceed the tracking impact of existing techniques such as cookies or session identifiers embedded in URLs.</p>
<p>Thus, in addition to the various mitigations described above, if a browser supports a mode of operation intended to preserve user anonymity, then User Agent implementers should carefully consider whether access to Key Systems should be disabled in this mode.</p>
+ </section>
- <h3 id="privacy-storedinfo">7.2. Information Stored on User Devices</h3>
+ <section id="privacy-storedinfo">
+ <h3>Information Stored on User Devices</h3>
<p>Key Systems may store information on a user's device, or user agents may store information on behalf of Key Systems. Potentially, this could reveal information about a user to another user of the same device, including potentially the origins that have used a particular Key System (i.e. sites visited) or even the content that has been decrypted using a Key System.</p>
<p>If information stored by one origin affects the operation of the Key System for another origin, then potentially the sites visited or content viewed by a user on one site may be revealed to another, potentially malicious, site.</p>
<p>There are a number of techniques that can be used to mitigate these privacy risk to users:</p>
@@ -1486,17 +1594,22 @@
<li>Allow the user to clear it, preferably by origin.</li>
<li>Treat it like other site data, including presenting it along with cookies, including it in "remove all data", and presenting it in the same UI locations.</li>
</ul>
+ </section>
- <h3 id="privacy-secureorigin">7.3. Use Secure Origin and Transport</h3>
+ <section id="privacy-secureorigin">
+ <h3>Use Secure Origin and Transport</h3>
<p>In order to protect identifiers and other information discussed in previous sections, user agents may choose to only support the EME APIs and/or specific Key Systems (i.e. based on privacy and security risks) on secure origins.
This is especially important if a user agent chooses to support a Key System implementation that exposes identifiers or other such information without effectively anonymizing it in transit (i.e. without <a href="#identifier-encryption">encrypting identifiers</a>).
</p>
<p>Regardless of user agent limitations, applications should use secure transport (e.g. HTTPS) for all traffic containing messages from the CDM (i.e. all data passed from <coderef prefix="event">message</coderef> events and to <methodref>update</methodref>).</p>
<p>All user agents should properly handle <a href="https://w3c.github.io/webappsec/specs/mixedcontent/">Mixed Content</a> to avoid exposure to insecure content or transport when the user agent or application wish to enforce secure origin and transport.</p>
+ </section>
</div>
+ </section>
- <h2 id="examples">8. Examples</h2>
+ <section id="examples">
+ <h2>Examples</h2>
<non-normative-sections/>
<p>This section contains example solutions for various use cases using the proposed extensions.
These are not the only solutions to these use cases.
@@ -1504,7 +1617,8 @@
In some cases, such as using synchronous XHR, the examples are simplified to keep the focus on the extensions.
</p>
- <h3 id="example-source-and-key-known" class="exampleheader">8.1. Source and Key Known at Page Load (Clear Key)</h3>
+ <section id="example-source-and-key-known">
+ <h3>Source and Key Known at Page Load (Clear Key)</h3>
<p class="exampledescription">In this simple example, the source file and <a href="#clear-key">clear-text license</a> are hard-coded in the page.
Only one session will ever be created.</p>
@@ -1552,8 +1666,10 @@
<video src="foo.webm" autoplay id="video"></video>
</body>
</pre>
+ </section>
- <h3 id="example-selecting-key-system" class="exampleheader">8.2. Selecting a Supported Key System and Using Initialization Data from the "encrypted" Event</h3>
+ <section id="example-selecting-key-system">
+ <h3>Selecting a Supported Key System and Using Initialization Data from the "encrypted" Event</h3>
<p class="exampledescription">This example selects a supported <a href="#key-system">Key System</a> using the <methodref>isTypeSupported</methodref> method then uses
the <a href="#initialization-data">Initialization Data</a> from the <videoanchor name="media-data">media data</videoanchor> to generate the license request and send it to the appropriate license server.
One of the supported key systems uses a serverCertificate, which is provided proactively.
@@ -1642,8 +1758,10 @@
<video src="foo.webm" autoplay on<precoderef>encrypted</precoderef>="handleInitData(event)"></video>
</pre>
+ </section>
- <h3 id="example-mediakeys-before-source" class="exampleheader">8.3. Create MediaKeys Before Loading Media</h3>
+ <section id="example-mediakeys-before-source">
+ <h3>Create MediaKeys Before Loading Media</h3>
<p class="exampledescription">Initialization is much simpler if encrypted events do not need to be handled during MediaKeys initialization.
This can be accomplished either by providing the <a href="#initialization-data">Initialization Data</a> in other ways or setting the source after the MediaKeys object has been created.
This example does the latter.
@@ -1682,8 +1800,10 @@
<video id="v" autoplay on<precoderef>encrypted</precoderef>="handleInitData(event)"></video>
</pre>
+ </section>
- <h3 id="example-using-all-events" class="exampleheader">8.4. Using All Events</h3>
+ <section id="example-using-all-events">
+ <h3>Using All Events</h3>
<p class="exampledescription">This is a more complete example showing all events being used.</p>
<p class="exampledescription">Note that <code>handleMessage()</code> could be called multiple times, including in response to the <methodref>update</methodref> call if multiple round trips are required and for any other reason the Key System might need to send a message.</p>
@@ -1772,8 +1892,10 @@
<video id="v" autoplay on<precoderef>encrypted</precoderef>="handleInitData(event)"></video>
</pre>
+ </section>
- <h3 id="example-stored-license" class="exampleheader">8.5. Stored License</h3>
+ <section id="example-stored-license">
+ <h3>Stored License</h3>
<p class="exampledescription">This example requests a persistent license for future use and stores it. It also provides functions for later retrieving the license and for destroying it.</p>
<pre class="example">
@@ -1875,9 +1997,12 @@
<video id="v" src="foo.webm" autoplay></video>
</pre>
+ </section>
+ </section>
- <h2 id="revision-history">9. Revision History</h2>
+ <section id="revision-history">
+ <h2>Revision History</h2>
<table>
<thead>
<tr>
@@ -1940,5 +2065,7 @@
</tr>
</tbody>
</table>
+ </section>
+
</body>
</html>