Encrypted Media Extensions

Abstract

This proposal extends HTMLMediaElement [HTML5] providing APIs to control playback of protected content.

The API supports use cases ranging from simple clear key decryption to high value video (given an appropriate user agent implementation). License/key exchange is controlled by the application, facilitating the development of robust playback applications supporting a range of content decryption and protection technologies.

This specification does not define a content protection or Digital Rights Management system. Rather, it defines a common API that may be used to discover, select and interact with such systems as well as with simpler content encryption systems. Implementation of Digital Rights Management is not required for compliance with this specification: only the Clear Key system is required to be implemented as a common baseline.

The common API supports a simple set of content encryption capabilities, leaving application functions such as authentication and authorization to page authors. This is achieved by requiring content protection system-specific messaging to be mediated by the page rather than assuming out-of-band communication between the encryption system and a license or other server.

2. Definitions

Content Decryption Module (CDM)

Content Decryption Module (CDM) is a generic term for the client component that provides the functionality, including decryption, for one or more Key Systems.

Note

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.

All messages and communication to and from the CDM, such as between the CDM and a license server, MUST be passed through the user agent. The CDM MUST NOT make direct out-of band network requests. All messages and communication other than those covered in the following paragraph MUST be passed through the application via the APIs defined in this specification. Specifically, all communication that contains application-, origin-, or content-specific information or is sent to a URL specified by the application or based on its origin, MUST pass through the APIs. This includes all license exchange messages.

Application- and origin-independent messages related to per-client initialization (or reinitialization) that are sent to a fixed non-application-dependent URL MUST be handled by the user agent and MUST NOT be passed to the application via the APIs. The related message exchange and operations MUST be performed by the user agent via the user agent's network stack.

Note

For example, an initialization, provisioning, or individualization process for a client device that involves communicating with a server hosted by the user agent or CDM vendor and does not contain application- or origin-specific information MUST be performed by the user agent without involving the application. The same applies to reinitialization, reprovisioning, or reindividualization.

For implementations that support per-origin initialization, such messages MUST be passed to the application via the APIs. Such messages MUST NOT contain non-origin-specific per-client information, such as a Distinctive Identifier. As with all other uses of the APIs, responses passed to the CDM MUST NOT contain executable code.

Note

To preserve the privacy properties of per-origin initialization, applications and key system servers should not defer initialization to a non-origin-specific server. See Individualization.

Key System

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 a CDM and identify the source of a key-related event. User agents MUST support the Common Key Systems. User agents MAY also provide additional CDMs with corresponding Key System strings.

A Key System string is always a reverse domain name. Key System strings are compared using case-sensitive matching. It is RECOMMENDED that CDMs use simple lower-case ASCII key system strings.

Note

For example, "com.example.somesystem".

Note

Within a given system ("somesystem" in the example), subsystems may be defined as determined by the key system provider. 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.

Key Session

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 the CDM. Sessions are embodied as MediaKeySession objects. Each Key session is associated with a single instance of Initialization Data provided in the generateRequest() call.

Each Key Session is associated with a single MediaKeys object, and only media element(s) associated with that object may access key(s) associated with the session. Other MediaKeys objects, CDM instances, and media elements MUST NOT 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 session is closed, including when the MediaKeySession object is destroyed.

Key IDs MUST be unique within a session.

Session ID

A Session ID is a unique string identifier generated by the CDM that can be used by the application to identify MediaKeySession objects.

A new Session ID is generated each time the user agent and CDM successfully create a new session.

Each Session ID SHALL be unique within the browsing context in which it was created. Session IDs for "persistent-license" and "persistent-release-message" sessions MUST be unique within the origin over time, including across browsing sessions.

Note

The underlying content protection protocol does not necessarily need to support Session IDs.

Key

Unless otherwise stated, key refers to a decryption key that can be used to decrypt blocks within media data. Each such key is uniquely identified by a key ID. A key is associated with the session used to provide it to the CDM. (The same key may be present in multiple sessions.) Such keys MUST only be provided to the CDM via an update() call. (They may later be loaded by load() as part of the stored session data.)

A key is considered usable if the CDM is certain the key is currently usable to decrypt media data

Note

For example, a key is not usable if its license has expired.

Key ID

A key 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 media data. Initialization Data 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 media data or media resource. Licenses provided to the CDM associate each key with a key ID so the CDM can select the appropriate key when decrypting an encrypted block of media data.

Known Key

A key is considered to be known to a session if the CDM's implementation of the session contains any information - specifically the key ID - about it, regardless of whether the actual key is usable or its value is known. Known keys are exposed via the keyStatuses attribute.

Keys are considered known even after they become unusable, such as due to expiration. Keys only become unknown when they are explicitly removed from a session.

Note

For example, a key could become unknown if an update() call provides a new license that does not include the key and includes instructions to replace the license(s) that previously contained the key.

License

A license is key system-specific state information that includes one or more key(s) - each associated with a key ID - and potentially other information about key usage.

Initialization Data

Note

Key Systems 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. It should always allow unique identification of the key(s) needed to decrypt the content. This initialization information MAY be obtained in some application-specific way or provided with the media data.

Initialization Data is a generic term for container-specific data that is used by a CDM to generate a license request. Initialization data found with the media data is provided to the application in the initData attribute of the encrypted event.

The format of the initialization data depends upon the type of container, and containers MAY support more than one format of initialization data. The Initialization Data Type is a string that indicates what format the initialization data is provided in. Initialization Data Type strings are always matched case-sensitively. It is RECOMMENDED that Initialization Data Type strings are lower-case ASCII strings.

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.

Initialization Data MUST be a fixed value for a given set of stream(s) or media data. It MUST only contain information related to the keys required to play a given set of stream(s) or media data. It MUST NOT contain application data, client-specific data, user-specific data, key(s), or executable code.

Initialization Data SHOULD NOT contain Key System-specific data or values. Implementations MUST support the common formats defined [EME-REGISTRY] for each Initialization Data Type they support.

Note

Use of proprietary formats/contents is discouraged, and supporting or using only proprietary formats is strongly discouraged. Proprietary formats should only be used with pre-existing content or on pre-existing devices that do not support the common formats.

Distinctive Identifier

A distinctive identifier is a piece of data, implication of the possession of a piece of data, or an observable behavior or timing for which all of the following criteria hold:

It is not shared across a large population of users or devices.
It is exposed outside the client device or exposed to the application such that the application has the opportunity to send it (even if in encrypted form if decryptable outside the device) or information about it outside the client device.
It is used in more than one session or is potentially used in one persistent session across the point of persistence.

Note

A distinctive identifier is typically unique to a user or device, but an identifier does not need to be strictly unique to be distinctive. For example, an identifier shared among a small number of users could still be distinctive.

Note

Examples of distinctive identifiers include but are not limited to:

A string of bytes that is included in key requests and that is different from the string included by other devices.
A public key included in key requests that is different from the public keys included in the requests by other devices.
Demonstration of possession of a private key (e.g. by signing some data) that other devices do not have.
An identifier for such a key.

Examples of things that are not distinctive identifiers:

A public key shared among all copies of a given CDM version if the installed base is large.
A nonce that is unique but used in only one session.
Device-unique keys used in attestations between, for example, the video pipeline and the CDM when the CDM does not let these attestations further flow to the application and instead makes a new attestation on its own using a key that does not constitute a distinctive identifier.

Note

The source of the identifier does not affect whether it is distinctive. For example, an identifier that is permanently part of the client device, contained in the CDM, generated on the client, or generated as part of some individualization or other provisioning process is considered distinctive if it meets the criteria above.

Cross Origin Limitations

During playback, embedded media data is exposed to script in the embedding origin. In order for the API to provide Initialization Data in the encrypted event, media data MUST be CORS-same-origin with the embedding page. If media data is cross-origin with the embedding document, authors SHOULD use the crossorigin attribute on the HTMLMediaElement and CORS headers on the media data response to make it CORS-same-origin.

Mixed Content Limitations

During playback, embedded media data is exposed to script in the embedding origin. In order for the API to provide Initialization Data in the encrypted event, media data MUST NOT be Mixed Content [MIXED-CONTENT].

3. Obtaining Access to Key Systems

This section defines the mechanism for obtaining access to a key system. The inclusion of capabilities in the request also enables feature detection.

Issue 3

This section is new and may change.

3.1 `Navigator` Extension: `requestMediaKeySystemAccess()`

partial interface Navigator {
    Promise<MediaKeySystemAccess> requestMediaKeySystemAccess (DOMString keySystem, sequence<MediaKeySystemConfiguration> supportedConfigurations);
};

3.1.1 Methods

requestMediaKeySystemAccess

Requests access to the specified Key System. When supportedConfigurations is specified, the configuration specified by at least one of its elements must be supported. The resulting MediaKeySystemAccess will correspond to the first such elment.

Any permission checks or user interaction, such as a prompt, SHOULD be performed before resolving the promise.

If the keySystem is not supported or not allowed (in one at least one of the supportedConfigurations, if specified), the promise is rejected. Otherwise, it is resolved with a new MediaKeySystemAccess object.

Parameter	Type	Nullable	Optional	Description
keySystem	`DOMString`	✘	✘	The Key System for which access is being requested.
supportedConfigurations	`sequence<MediaKeySystemConfiguration>`	✘	✘	A sequence of `MediaKeySystemConfiguration` configurations to try in order. The first element with a satisfiable configuration will be used.

Return type: Promise<MediaKeySystemAccess>

When this method is invoked, the user agent must run the following steps:

If keySystem is the empty string, return a promise rejected with a new DOMException whose name is InvalidAccessError.
If supportedConfigurations is empty, return a promise rejected with a new DOMException whose name is InvalidAccessError.
Let document be the calling context's Document.
If the result of running the May Document use powerful features? algorithm [MIXED-CONTENT] on document is not Allowed:
- Issue 4
  Bug 26332 - The availability of this API on unauthenticated origins is an open issue. It has been proposed that such access not be allowed at all or be allowed only in specific circumstances. It is likely that there will be scenarios where access from an unauthenticated origin is not allowed. It is also an open issue whether and how the impact of serving audio/video media over secure transport can be mitigated.
Let origin be the origin of document.
Let promise be a new promise.
Run the following steps asynchronously:
1. If keySystem is not one of the Key Systems supported by the user agent, reject promise with a new DOMException whose name is NotSupportedError. String comparison is case-sensitive.
2. Let implementation be the implementation of keySystem.
3. For each value in supportedConfigurations:
  1. Let candidate configuration be the value.
  2. Let supported configuration be the result of executing the Get Supported Configuration algorithm on implementation, candidate configuration, and origin.
  3. If supported configuration is not null, run the following steps:
    1. Let access be a new MediaKeySystemAccess object, and initialize it as follows:
      1. Set the keySystem attribute to keySystem.
      2. Let supported configuration object be a new MediaKeySystemConfiguration object populated with the values in supported configuration.
        supported configuration object is a non-strict subset of candidate configuration.
      3. Let the configuration value be supported configuration object.
      4. Let the cdm implementation value be implementation.
    2. Resolve promise with access and abort these steps.
4. Reject promise with a new DOMException whose name is NotSupportedError.
  
  Note
  keySystem was not supported/allowed or none of the configurations in supportedConfigurations were supported/allowed.
Return promise.

3.1.2 Algorithms

3.1.2.1 Get Supported Configuration

Given a Key Systems implementation implementation, MediaKeySystemConfiguration candidate configuration, and origin, this algorithm returns a supported configuration or null as appropriate.

Note

Unrecognized dictionary members in candidate configuration are ignored per [WebIDL] and will never reach this algorithm. Thus, they cannot be considered as part of the configuration.

Let accumulated configuration be empty.
If candidate configuration's initDataTypes attribute is not empty, run the following steps:
1. Let supported types be empty.
2. For each value in candidate configuration's initDataTypes attribute:
  1. Let initDataType be the value.
  2. If initDataType is the empty string, return null.
  3. If the implementation supports generating requests based on initDataType, add initDataType to supported types.
3. If supported types is empty, return null. String comparison is case-sensitive.
4. Add supported types to accumulated configuration.
Follow the steps for the value of candidate configuration's distinctiveIdentifier attribute from the following list:

"required"

If the implementation does not support a persistent Distinctive Identifier in combination with accumulated configuration, return null.

"optional"

Continue.

"not-allowed"

If the implementation requires a Distinctive Identifier in combination with accumulated configuration, return null.
Add distinctiveIdentifier and the value candidate configuration's corresponding attribute to accumulated configuration.
Follow the steps for the value of persistentState from the following list:

"required"

If the implementation does not support persisting state in combination with accumulated configuration, return null.

Note
Otherwise, the implementation MUST support creating "persistent-license" and/or "persistent-release-message" sessions.

"optional"

Continue.

"not-allowed"

If the implementation requires persisting state in combination with accumulated configuration, return null.
Add persistentState and the value candidate configuration's corresponding attribute to accumulated configuration.
If candidate configuration's videoCapabilities attribute is not empty, run the following steps:
1. Let video capabilities be the result of executing the Get Supported Capabilities for Media Type algorithm on Video, candidate configuration's videoCapabilities attribute, and accumulated configuration.
2. If video capabilities is null, return null.
3. Add video capabilities to accumulated configuration.
If candidate configuration's audioCapabilities attribute is not empty, run the following steps:
1. Let audio capabilities be the result of executing the Get Supported Capabilities for Media Type algorithm on Audio, candidate configuration's audioCapabilities attribute, and accumulated configuration.
2. If audio capabilities is null, return null.
3. Add audio capabilities to accumulated configuration.
If accumulated configuration's distinctiveIdentifier value is "optional", follow the steps for the first matching condition from the following list:

If the implementation requires a Distinctive Identifier for any of the combinations in accumulated configuration

Change accumulated configuration's distinctiveIdentifier value to "required".

Otherwise

Change accumulated configuration's distinctiveIdentifier value to "not-allowed".
If accumulated configuration's persistentState value is "optional", follow the steps for the first matching condition from the following list:

If the implementation requires persisting state for any of the combinations in accumulated configuration

Change accumulated configuration's persistentState value to "required".

Note
The implementation MUST support creating "persistent-license" and/or "persistent-release-message" sessions.

Otherwise

Change accumulated configuration's persistentState value to "not-allowed".
If implementation in the configuration specified by the combination of the values in accumulated configuration is not supported or not allowed in the origin, return null.

Note
In this step, "supported" includes the implementation being available for use when this algorithm returns, not just user agent support for such an implementation.

If accumulated configuration's persistentState value is "required", follow the steps for the first matching condition from the following list:

If the Distinctive Identifier is unique per-origin and clearable

If there is no persisted consent covering accumulated configuration for the the origin, it is RECOMMENDED that the user be prompted for consent to use Distinctive Identifier(s).

Otherwise

Prompt the user for consent to use Distinctive Identifier(s).

Note
A previous consent for a prompt that did not include use of a Distinctive Identifier (with similar properties) would not be considered as covering this accumulated configuration, which implies use of such an identifier.

Note
The "unique per-origin" and "clearable" conditions cannot be false in a compliant implementation because implementations MUST use per-origin identifiers and allow the user to clear identifier.
Return accumulated configuration.

3.1.2.2 Get Supported Capabilities for Media Type

Given a media type (Audio or Video), MediaKeySystemMediaCapability sequence capabilities, and partial configuration, this algorithm returns a list of supported configurations for this media type or null as appropriate.

Let accumulated capabilities be partial configuration.
Let media type capabilities be empty.
For each value in capabilities:
1. Let contentType be the value's contentType member.
2. Let robustness be the value's robustness member.
3. If contentType is the empty string, return null.
4. If contentType is an invalid or unrecognized MIME type, continue to the next iteration.
5. Let configuration be empty.
6. Let container be the container type specified by contentType.
7. If the user agent does not support container, continue to the next iteration. The case-sensitivity of string comparisons is determined by the appropriate RFC.
  
  Note
  Per RFC 6838 [RFC6838], "Both top-level type and subtype names are case-insensitive."
8. Add container to configuration.
9. Let parameters be the RFC 6381 [RFC6381] parameters, if any, specified by contentType.
10. If parameters is not empty, run the following steps:
  1. If the user agent does not recognize one or more parameters, continue to the next iteration.
  2. Let media types be the set of media types specified by parameters. It MAY be empty. The case-sensitivity of string comparisons is determined by the appropriate RFC or other specification.
    
    Note
    For example, all of the codecs. Case-sensitive string comparison is RECOMMENDED because RFC 6381 [RFC6381] says, "Values are case sensitive" for some formats.
  3. Add all media types to configuration.
11. If contentType is not a media type type, continue to the next iteration.
  
  Note
  For example, if media type is Audio and the top-level type is not "audio" or media types contains non-audio codecs.
12. If robustness is not the empty string, run the following steps:
  1. If robustness is an unrecognized value or not supported by implementation, continue to the next iteration. String comparison is case-sensitive.
  2. Add robustness to configuration.
13. If the user agent and implementation do not support playback of encrypted media data as specified by configuration, including all media types, in combination with accumulated capabilities, continue to the next iteration.
  
  Note
  This configuration (content type and robustness) must be supported with all previously added supported configurations.
14. Add configuration to media type capabilities.
15. Add configuration to accumulated capabilities.
  
  Note
  This step ensures that combinations of audio/video capabilities are always checked instead of only checking combinations of video capabilities when checking an audio capbility.
If media type capabilities is empty, return null.

Note
None of the MediaKeySystemMediaCapability elements in capabilities is supported in combination with partial configuration.
Return media type capabilities.

3.2 `MediaKeySystemConfiguration` dictionary

enum MediaKeysRequirement {
    "required",
    "optional",
    "not-allowed"
};

Enumeration description
`required`	When used in a call to `requestMediaKeySystemAccess()` The returned object MUST support this feature. When returned by a `MediaKeySystemAccess` object CDM instances created by the object MAY use this feature.
`optional`	When used in a call to `requestMediaKeySystemAccess()` The returned object MAY support and use this feature. When returned by a `MediaKeySystemAccess` object This value cannot and MUST NOT be present in such an object.
`not-allowed`	When used in a call to `requestMediaKeySystemAccess()` The returned object MUST function without using this feature and MUST NOT use it at any time. When returned by a `MediaKeySystemAccess` object CDM instances created by the object MUST NOT use this feature.

dictionary MediaKeySystemConfiguration {
    sequence<DOMString>                     initDataTypes;
    sequence<MediaKeySystemMediaCapability> audioCapabilities;
    sequence<MediaKeySystemMediaCapability> videoCapabilities;
    MediaKeysRequirement                    distinctiveIdentifier = "optional";
    MediaKeysRequirement                    persistentState = "optional";
};

3.2.1 Dictionary `MediaKeySystemConfiguration` Members

audioCapabilities of type sequence<MediaKeySystemMediaCapability>: A list of supported audio type and capability pairs. The audio capability of this object is considered supported if the list is empty or contains one or more values that are supported with all other members (as determined by the algorithm). When there is a conflict between values, the earlier value will be selected.
distinctiveIdentifier of type MediaKeysRequirement, defaulting to "optional": Whether a persistent Distinctive Identifier is required.
Messages from the CDM, such as message events, MUST NOT contain a Distinctive Identifier, even in an encrypted form, when this member is .
initDataTypes of type sequence<DOMString>: A list of supported Initialization Data Type names. The Initialization Data Type capability of this object is considered supported if the list is empty or contains one or more values that are supported with all other members (as determined by the algorithm). Values in the sequence MUST not be the empty string.
persistentState of type MediaKeysRequirement, defaulting to "optional": Whether the ability to persist state is required. This includes session data and any other type of state.
Note
For the purposes of this member, persistent state does not include persistent unique identifiers (Distinctive Identifiers) controlled by the Key System implementation. distinctiveIdentifier independently reflects this requirement.

Only "temporary" sessions may be created when persistent state is not supported.

Note
For "temporary" sessions, the need and ability to store state is Key System implementation-specific and may vary by feature used.

Note
Applications intending to create non-"temporary" sessions, should set this attribute to "required" when calling requestMediaKeySystemAccess().
videoCapabilities of type sequence<MediaKeySystemMediaCapability>: A list of supported video type and capability pairs. The video capability of this object is considered supported if the list is empty or contains one or more values that are supported with all other members (as determined by the algorithm). When there is a conflict between values, the earlier value will be selected.

Implementations SHOULD NOT add members to the this dictionary. Should member(s) be added, they MUST be of type MediaKeysRequirement, and it is RECOMMENDED that they have default values of "optional" to support the widest range of application and client combinations.

Note

Dictionary members not recognized by a user agent implementation are ignored per [WebIDL] and will not be considered in the requestMediaKeySystemAccess() algorithm. Should an an application use non-standard dictionary member(s), it MUST NOT rely on user agent implementations rejecting a configuration that includes such dictionary members.

This dictionary MUST NOT be used to pass state or data to the CDM.

3.3 `MediaKeySystemMediaCapability` dictionary

dictionary MediaKeySystemMediaCapability {
    DOMString contentType = "";
    DOMString robustness = "";
};

3.3.1 Dictionary `MediaKeySystemMediaCapability` Members

contentType of type DOMString, defaulting to "": The content type. MUST not be the empty string.
robustness of type DOMString, defaulting to "": The robustness level associated with the content type. The empty string indicates that any ability to decrypt and decode the content type is acceptable.

The entire contentType, including all codecs, must be supported with robustness in order for the capability represented by this object to be considered supported.

Note

If any of a set of codecs is acceptable, use a separate instances of this dictionary for each codec.

Enumeration description
`temporary`	A session for which a record of or data related to the session MUST NOT be persisted. The application need not worry about managing such storage. Support for this session type is REQUIRED.
`persistent-license`	A session for which the license and other data related to the session MAY be persisted. The session MUST be loadable via its Session ID as long as such data is persisted. The application is responsible for managing any such storage that may be generated by the CDM. See Session Storage and Persistence. Support for this session type is OPTIONAL.
`persistent-release-message`	A session for which a proof of license release and other data related to the session MAY be persisted. The license and any key(s) it contains SHALL NOT be persisted. The session MUST be loadable via its Session ID as long as such data is persisted. The application is responsible for managing any such storage that may be generated by the CDM. See Session Storage and Persistence. Support for this session type is OPTIONAL.

Parameter	Type	Nullable	Optional	Description
sessionType	`MediaKeySessionType = "temporary"`	✘	✔	The type of session to create. The session type affects the behavior of the returned object.

Parameter	Type	Nullable	Optional	Description
serverCertificate	`BufferSource`	✘	✘	The server certificate. The contents are Key System-specific. It MUST NOT contain executable code.

6. `MediaKeySession` Interface

The MediaKeySession object represents a key session.

For methods that return a promise, all errors are reported asynchronously by rejecting the returned Promise. This includes [WebIDL] type mapping errors.

The steps of an algorithm are always aborted when resolving or rejecting a promise.

interface MediaKeySession : EventTarget {
    readonly    attribute DOMString           sessionId;
    readonly    attribute unrestricted double expiration;
    readonly    attribute Promise<void>       closed;
    readonly    attribute MediaKeyStatusMap   keyStatuses;
    Promise<void>    generateRequest (DOMString initDataType, BufferSource initData);
    Promise<boolean> load (DOMString sessionId);
    Promise<void>    update (BufferSource response);
    Promise<void>    close ();
    Promise<void>    remove ();
};

6.1 Attributes

closed of type Promise<void>, readonly: Signals when object becomes closed as a result of the session close algorithm being run. This promise can only be fulfilled and is never rejected.
expiration of type unrestricted double, readonly: The time, in milliseconds since 01 January, 1970 UTC, after which the key(s) in the session will no longer be usable to decrypt media data, or NaN if no such time exists, as determined by the CDM.

Note
This value MAY change during the session lifetime, such as when an action triggers the start of a window.
keyStatuses of type MediaKeyStatusMap, readonly: A reference to a read-only map of key IDs known to the session to the current status of the associated key. Each entry MUST have a unique key ID.

Note
The map entries and their values may be updated whenever the event loop spins. The map can never be inconsistent or partially updated, but it may change between accesses if the event loop spins in between accesses. Key IDs may be added as the result of a load() or update() call. Key IDs may be removed as the result of a update() call that removes knowledge of existing keys (or replaces the existing set of keys with a new set). Key IDs MUST NOT be removed because they became unusable, such as due to expiration. Instead, such keys MUST be given an appropriate status, such as "expired".
sessionId of type DOMString, readonly: The Session ID for this object and the associated key(s) or license(s).

6.2 Methods

close

Indicates that the application no longer needs the session and the CDM should release any resources associated with this object and close it.

Note

The returned promise is resolved when the request has been processed, and the closed attribute promise is resolved when the session is closed.

No parameters.

Return type: Promise<void>

When this method is invoked, the user agent must run the following steps:

If this object's callable value is false, return a promise rejected with a new DOMException whose name is InvalidStateError.
If the session close algorithm has been run on this object, return a resolved promise.
Let promise be a new promise.
Run the following steps asynchronously:
1. Let cdm be the CDM instance represented by this object's cdm instance value.
2. Use the cdm to execute the following steps:
  1. Process the close request.
    
    Do not remove stored session data.
    
    Issue 5
    More specific details are needed for "persistent-license" and "persistent-release-message" sessions.
  2. If the previous step caused the session to be closed, run the session close algorithm on this object.
3. Resolve promise.
Return promise.

generateRequest

Generates a request based on the initData.

Parameter	Type	Nullable	Optional	Description
initDataType	`DOMString`	✘	✘	The Initialization Data Type of the `initData`.
initData	`BufferSource`	✘	✘	Initialization Data

Return type: Promise<void>

When this method is invoked, the user agent must run the following steps:

If this object's uninitialized value is false, return a promise rejected with a new DOMException whose name is InvalidStateError.
Let this object's uninitialized be false.
If initDataType is the empty string, return a promise rejected with a new DOMException whose name is InvalidAccessError.
If initData is an empty array, return a promise rejected with a new DOMException whose name is InvalidAccessError.
If the Key System implementation represented by this object's cdm implementation value does not support initDataType as an Initialization Data Type, return a promise rejected with a new DOMException whose name is NotSupportedError. String comparison is case-sensitive.
Let init data be a copy of the contents of the initData parameter.
Let session type be this object's session type.
Let promise be a new promise.
Run the following steps asynchronously:
1. If the init data is not valid for initDataType, reject promise with a new DOMException whose name is InvalidAccessError.
2. Let sanitized init data be a validated and sanitized version of init data.
  
  The user agent MUST thoroughly validate the Initialization Data before passing it to the CDM. This includes verifying that the length and values of fields are reasonable, verifying that values are within reasonable limits, and stripping irrelevant, unsupported, or unknown data or fields. It is RECOMMENDED that user agents pre-parse, sanitize, and/or generate a fully sanitized version of the Initialization Data. If the Initialization Data format specified by initDataType support multiple entries, the user agent SHOULD remove entries that are not needed by the CDM.
3. If the previous step failed, reject promise with a new DOMException whose name is InvalidAccessError.
4. Let session id be the empty string.
5. Let message be null.
6. Let cdm be the CDM instance represented by this object's cdm instance value.
7. Use the cdm to execute the following steps:
  1. If the init data is not supported by the cdm, reject promise with a new DOMException whose name is NotSupportedError.
  2. Follow the steps for the first matching condition from the following list:
    
    If session type is "temporary"
    
    Let requested license type be a temporary non-persistable license.
    
    Note
    The returned license must not be persistable or require persisting proof of license release.
    
    If session type is "persistent-license"
    
    Let requested license type be a persistable license.
    
    If session type is "persistent-release-message"
    
    Let requested license type be a non-persistable license that will generate a persistable proof of license release.
  3. Let session id be a unique Session ID string.
    
    If session type is "persistent-license" or "persistent-release-message", the ID MUST be unique within the origin of this object's Document over time, including across Documents and browsing sessions.
  4. Let message be a license request for the requested license type generated based on the init data, which is interpreted per initDataType.
    
    The cdm MUST NOT use any stream-specific data, including media data, not provided via the init data.
    
    The cdm SHOULD NOT store session data, including the session ID, at this point. See Session Storage and Persistence.
8. If any of the preceding steps failed, reject promise with a new DOMException whose name is the appropriate error name.
9. Set the sessionId attribute to session id.
10. Let this object's callable be true.
11. Run the queue a "message" event algorithm on the session, providing "license-request" and message.
12. Resolve promise.
Return promise.

load

Loads the data stored for the specified session into this object.

Parameter	Type	Nullable	Optional	Description
sessionId	`DOMString`	✘	✘	The Session ID of the session to load.

Return type: Promise<boolean>

When this method is invoked, the user agent must run the following steps:

If this object's uninitialized value is false, return a promise rejected with a new DOMException whose name is InvalidStateError.
Let this object's uninitialized be false.
If sessionId is the empty string, return a promise rejected with a new DOMException whose name is InvalidAccessError.
If this object's session type is not "persistent-license" or "persistent-release-message", return a promise rejected with a new DOMException whose name is InvalidAccessError.
If the Key System implementation represented by this object's cdm implementation value does not support loading previous sessions, return a promise rejected with a new DOMException whose name is NotSupportedError.
Let origin be the origin of this object's Document.
Let promise be a new promise.
Run the following steps asynchronously:
1. Let sanitized session ID be a validated and/or sanitized version of sessionId.
  
  Note
  The user agent should thoroughly validate the sessionId value before passing it to the CDM. At a minimum, this should include checking that the length and value (e.g. alphanumeric) are reasonable.
2. If the previous step failed, reject promise with a new DOMException whose name is InvalidAccessError.
3. If there is an unclosed session in the object's Document whose sessionId attribute is sanitized session ID, reject promise with a new DOMException whose name is QuotaExceededError.
  
  Note
  In other words, do not create a session if a non-closed session, regardless of type, already exists for this sanitized session ID in this browsing context.
4. Let expiration time be NaN.
5. Let message be null.
6. Let message type be null.
7. Let cdm be the CDM instance represented by this object's cdm instance value.
8. Use the cdm to execute the following steps:
  1. If there is no data stored for the sanitized session ID in the origin, resolve promise with false.
  2. Let session data be the data stored for the sanitized session ID in the origin. This MUST NOT include data from other origin(s) or that is not associated with an origin.
  3. If there is an unclosed "persistent-license" or "persistent-release-message" session in any Document representing the session data, reject promise with a new DOMException whose name is QuotaExceededError.
    
    Note
    In other words, do not create a session if a non-closed persistent session already exists for this sanitized session ID in any browsing context.
  4. Load the session data.
  5. If the session data indicates an expiration time for the session, let expiration time be the expiration time in milliseconds since 01 January 1970 UTC.
  6. If the CDM needs to send a message:
    1. Let message be a message generated by the CDM based on the session data.
    2. Let message type be the appropriate MediaKeyMessageType for the message.
9. If any of the preceding steps failed, reject promise with a new DOMException whose name is the appropriate error name.
10. Set the sessionId attribute to sanitized session ID.
11. Let this object's callable be true.
12. If the loaded session contains information about any keys (there are known keys), run the update key statuses algorithm on the session, providing each key's key ID along with the appropriate MediaKeyStatus.
  
  Should additional processing be necessary to determine with certainty the status of a key, use the non-"usable" MediaKeyStatus value that corresponds to the reason for the additional processing. Once the additional processing for one or more keys has completed, run the update key statuses algorithm again if any of the statuses has changed.
13. Run the update expiration algorithm on the session, providing expiration time.
14. If message is not null, run the queue a "message" event algorithm on the session, providing message type and message.
15. Resolve promise with true.
Return promise.

remove

Removes stored session data associated with this object.

No parameters.

Return type: Promise<void>

When this method is invoked, the user agent must run the following steps:

If this object's callable value is false, return a promise rejected with a new DOMException whose name is InvalidStateError.
If this object's session type is not "persistent-license" or "persistent-release-message", return a promise rejected with a new DOMException whose name is InvalidAccessError.
If the session close algorithm has been run on this object, return a promise rejected with a new DOMException whose name is InvalidStateError.
Let promise be a new promise.
Run the following steps asynchronously:
1. Let cdm be the CDM instance represented by this object's cdm instance value.
2. Use the cdm to execute the following steps:
  1. Process the remove request.
    
    This MAY involve exchanging message(s) with the application.
    
    Unless this step fails, the CDM MUST have cleared all stored session data associated with this object, including the sessionId, before proceeding to the next step.
    
    Issue 6
    More specific details are needed for "persistent-license" and "persistent-release-message" sessions.
    
    Note
    A subsequent call to load() with the value sessionId would fail because there is no data stored for that session ID.
3. Run the following steps asynchronously once the above step has completed:
  1. If any of the preceding steps failed, reject promise with a new DOMException whose name is the appropriate error name.
  2. Run the session close algorithm on this object.
  3. Resolve promise.
Return promise.

update

Provides messages, including licenses, to the CDM.

Parameter	Type	Nullable	Optional	Description
response	`BufferSource`	✘	✘	A message to be provided to the CDM. The contents are Key System-specific. It MUST NOT contain executable code.

Return type: Promise<void>

When this method is invoked, the user agent must run the following steps:

If this object's callable value is false, return a promise rejected with a new DOMException whose name is InvalidStateError.
If response is an empty array, return a promise rejected with a new DOMException whose name is InvalidAccessError.
Let response copy be a copy of the contents of the response parameter.
Let promise be a new promise.
Run the following steps asynchronously:
1. Let sanitized response be a validated and/or sanitized version of response copy.
  
  Note
  The user agent should thoroughly validate the response before passing it to the CDM. This may include verifying values are within reasonable limits, stripping irrelevant data or fields, pre-parsing it, sanitizing it, and/or generating a fully sanitized version. The user agent should check that the length and values of fields are reasonable. Unknown fields should be rejected or removed.
2. If the previous step failed, reject promise with a new DOMException whose name is InvalidAccessError.
3. Let message be null.
4. Let message type be null.
5. Let cdm be the CDM instance represented by this object's cdm instance value.
6. Use the cdm to execute the following steps:
  1. If the format of sanitized response is invalid in any way, reject promise with a new DOMException whose name is InvalidAccessError.
  2. Process sanitized response, following the stipulation for the first matching condition from the following list:
    
    If sessionType is "temporary" and sanitized response does not specify that session data, including any license, key(s), or similar session data it contains, should be stored
    
    Continue processing sanitized response, not storing any session data.
    
    If sessionType is "persistent-license"
    
    Continue processing sanitized response, storing the license, key(s), or similar session data contained in sanitized response as permitted or instructed by the license. Such data MUST be stored such that only the origin of this object's Document can access it.
    
    If sessionType is "persistent-release-message"
    
    Continue processing sanitized response, storing session data contained in sanitized response as permitted or instructed by the license. Such data MUST be stored such that only the origin of this object's Document can access it. The license and any key(s) it contains MUST NOT be stored.
    
    Otherwise
    
    Reject promise with a new DOMException whose name is InvalidAccessError.
    
    See also Session Storage and Persistence.
    
    Note
    When sanitized response contains key(s) and/or related data, cdm will likely cache the key and related data indexed by key ID.
    
    Note
    The replacement algorithm within a session is Key System-dependent.
    
    Keys from different sessions SHOULD be cached independently such that closing one session does not affect keys in other sessions, even if they have overlapping key IDs.
    
    Note
    It is RECOMMENDED that CDM implementations support a standard and reasonably high minimum number of keys per MediaKeySession object, including a standard replacement algorithm, and a standard and reasonably high minimum number of MediaKeySession objects. This enables a reasonable number of key rotation algorithms to be implemented across user agents and may reduce the likelihood of playback interruptions in use cases that involve various streams in the same element (i.e. adaptive streams, various audio and video tracks) using different keys.
  3. If the set of keys known to the CDM for this object changed or the status of any key(s) changed, run the update key statuses algorithm on the session, providing each known key's key ID along with the appropriate MediaKeyStatus.
    
    Should additional processing be necessary to determine with certainty the status of a key, use the non-"usable" MediaKeyStatus value that corresponds to the reason for the additional processing. Once the additional processing for one or more keys has completed, run the update key statuses algorithm again if any of the statuses has changed.
  4. If the expiration time for the session changed, run the update expiration algorithm on the session, providing the new expiration time.
  5. If a message needs to be sent to the server, execute the following steps:
    1. Let message be that message.
    2. Let message type be the appropriate MediaKeyMessageType for the message.
7. If any of the preceding steps failed, reject promise with a new DOMException whose name is the appropriate error name.
8. If message is not null, run the queue a "message" event algorithm on the session, providing message type and message.
9. Resolve promise.
Return promise.

6.3 `MediaKeyMessageEvent`

The MediaKeyMessageEvent object is used for the message event.

Events are constructed as defined in Constructing events [DOM].

enum MediaKeyMessageType {
    "license-request",
    "license-renewal",
    "license-release"
};

Enumeration description
`license-request`	The message contains a request for a new license.
`license-renewal`	The message contains a request to renew an existing license.
`license-release`	The message contains a proof of license release.

[ Constructor (DOMString type, optional MediaKeyMessageEventInit eventInitDict)]
interface MediaKeyMessageEvent : Event {
    readonly    attribute MediaKeyMessageType messageType;
    readonly    attribute ArrayBuffer         message;
};

6.3.1 Constructors

MediaKeyMessageEvent

Parameter	Type	Nullable	Optional	Description
type	`DOMString`	✘	✘
eventInitDict	`MediaKeyMessageEventInit`	✘	✔

6.3.2 Attributes

message of type ArrayBuffer, readonly: The message from the CDM. Messages are Key System-specific.
messageType of type MediaKeyMessageType, readonly: The type of the message.
Implementations MUST NOT require applications to handle message types. Implementations MUST support applications that do not differentiate messages and MUST NOT require that applications handle message types. Specifically, Key Systems MUST support passing all types of messages to a single URL.

Note
This attribute allows an application to differentiate messages without parsing the message. It is intended to enable optional application and/or server optimizations, but applications are not required to use it.

6.3.3 `MediaKeyMessageEventInit`

dictionary MediaKeyMessageEventInit : EventInit {
    MediaKeyMessageType messageType = "license-request";
    ArrayBuffer         message;
};

6.3.3.1 Dictionary `MediaKeyMessageEventInit` Members

message of type ArrayBuffer: The message.
messageType of type MediaKeyMessageType, defaulting to "license-request": The type of the message.

6.4 Event Summary

This section is non-normative.

Note

In some implementations, MediaKeySession objects may not fire any events until the MediaKeys object is associated with a media element using setMediaKeys().

Event name	Interface	Dispatched when...
`keyschange`	`Event`	There has been a change in the keys in the session or their status.
`message`	`MediaKeyMessageEvent`	The CDM has generated a message for the session.

6.5 Algorithms

6.5.1 Queue a "message" Event

The Queue a "message" Event algorithm is run when the CDM needs to queue a message event to a MediaKeySession object. Requests to run this algorithm include a target MediaKeySession object, a message type, and a message.

message MUST NOT contain a Distinctive Identifier, even in an encrypted form, if the MediaKeySession object's use distinctive identifier value is false.

The following steps are run:

Let the session be the specified MediaKeySession object.
Queue a task to fire a simple event named message at the session.

The event is of type MediaKeyMessageEvent and has:
- messageType = the specified message type
  
  message = the specified message

6.5.2 Update Key Statuses

The Update Key Statuses algorithm is run when the CDM changes the set of keys known to the session or the status of one or more of the keys. This can happen as the result of a load() or update() call or some other event, such as expiration. Requests to run this algorithm include a target MediaKeySession object and a sequence of key ID and associated MediaKeyStatus pairs.

The following steps are run:

Let the session be the associated MediaKeySession object.
Let the input statuses be the sequence of pairs key ID and associated MediaKeyStatus pairs.
Let the statuses be session's keyStatuses attribute.
Run the following steps to replace the contents of statuses:
1. Empty statuses.
2. For each pair in input statuses.
  1. Let pair be the pair.
  2. Insert an entry for pair's key ID into statuses with the value of pair's MediaKeyStatus value.
Note
The effect of this steps is that the contents of session's keyStatuses attribute are replaced without invalidating existing references to the attribute. This replacement is atomic from a script perspective. That is, script MUST NOT ever see a partially populated sequence.
Queue a task to fire a simple event named keyschange at the session.
Queue a task to run the attempt to resume playback if necessary algorithm on each of the media element(s) whose mediaKeys attribute is the MediaKeys object that created the session.

The user agent MAY choose to skip this step if it knows resuming will fail.

Note
For example, the user agent may skip this step if no additional keys became "usable".

6.5.3 Update Expiration

The Update Expiration algorithm is run when the CDM changes the expiration time of a session. This can happen as the result of an update() call or some other event. Requests to run this algorithm include a target MediaKeySession object and the new expiration time, which may be NaN.

The following steps are run:

Let the session be the associated MediaKeySession object.
Let expiration time be NaN.
If the new expiration time is not NaN, let expiration time be the new expiration time in milliseconds since 01 January 1970 UTC.
Set the session's expiration attribute to expiration time.

6.5.4 Session Close

The Session Close algorithm is run when the CDM closes the session associated with a MediaKeySession object.

Closing a session means that the license(s) and key(s) associated with it are no longer available to decrypt media data

Note

The CDM may close a session at any point, such as in response to a close() 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.

The following steps are run:

Let the session be the associated MediaKeySession object.
Let promise be the closed attribute of the session.
Resolve promise.

6.6 Exceptions

The methods report errors by rejecting the returned promise with a DOMException. The following DOMException names from WebIDL [WebIDL] 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.

Name	Possible Causes (non-exhaustive)
`NotSupportedError`	The existing MediaKeys object cannot be removed. The key system is not supported. The key system is not supported on insecure origins. The initialization data type is not supported by the key system. The session type is not supported by the key system. The initialization data is not supported by the key system. The operation is not supported by the key system.
`InvalidStateError`	The existing MediaKeys object cannot be removed at this time. The session has already been used. The session is not yet initialized. The session is closed.
`InvalidAccessError`	The parameter is empty. Invalid initialization data. The operation is not supported on sessions of this type. Invalid response format. A persistent license was provided for a `"temporary"` session.
`QuotaExceededError`	The MediaKeys object cannot be used with additional HTMLMediaElements. A non-closed session already exists for this sessionId.

6.7 Session Storage and Persistence

This section provides an overview of session stroage and persistence that complements the algorithms.

If this object's session type is not "persistent-license" or "persistent-release-message", the user agent and CDM MUST NOT persist a record of or data related to the session at any point. This includes license(s), key(s), proof of license release, and the Session ID.

The remainder of this section applies to "persistent-license" and "persistent-release-message" sessions, which are OPTIONAL for implementatations to support.

Persisted data MUST always be stored such that only the origin of this object's Document can access it. In addition, the data MUST only be accessible by the current profile of this user agent; other user agent profiles, user agents, and applications MUST NOT be able to access the stored data. See Information Stored on User Devices.

The CDM SHOULD NOT store session data, including the Session ID, until update() is called the first time. Specifically, the CDM SHOULD NOT store session data during the generateRequest() algorithm. This ensures that the application is aware of the session and knows it needs to eventually remove it.

The CDM MUST ensure that data for a given session is only present in one active unclosed session in any Document. In other words, load() MUST fail when there is already a MediaKeySession representing the session specified by the sessionId parameter, either because the object that created it via generateRequest() is still active or it has been loaded into another object via load(). A session MAY only be loaded again after the session close algorithm has not been run on the object representing it.

An application that creates a "persistent-license" or "persistent-release-message" session SHOULD later remove the stored data using remove(). The CDM MAY also remove sessions as appropriate, but applications SHOULD NOT rely on this.

See the Security and Privacy sections for additional considerations when supporting persistent storage.

Enumeration description
`usable`	The CDM is certain the key is currently usable to decrypt media data. Keys that may not currently be usable MUST NOT have this status.
`expired`	The key is no longer usable to decrypt media data because its expiration time has passed. The time represented by the `expiration` attribute MUST be earlier than the current time. All other keys in the session MUST have this status.
`output-not-allowed`	The key is not currently usable to decrypt media data because its output requirements cannot currently be met.
`internal-error`	The key is not currently usable to decrypt media data because of an error in the CDM unrelated to the other values. This value is not actionable by the application.

8. `HTMLMediaElement` Extensions

This section specifies additions to and modifications of the HTMLMediaElement [HTML5] when the Encrypted Media Extensions are supported.

For methods that return a promise, all errors are reported asynchronously by rejecting the returned Promise. This includes [WebIDL] type mapping errors.

The steps of an algorithm are always aborted when resolving or rejecting a promise.

enum MediaWaitingFor {
    "none",
    "data",
    "key"
};

Enumeration description
`none`	The media element is not waiting for anything.
`data`	The media element is not waiting for data.
`key`	The media element is not waiting for a key.

partial interface HTMLMediaElement : EventTarget {
    readonly    attribute MediaKeys?      mediaKeys;
    readonly    attribute MediaWaitingFor waitingFor;
                attribute EventHandler    onencrypted;
    Promise<void> setMediaKeys (MediaKeys? mediaKeys);
};

8.1 Attributes

mediaKeys of type MediaKeys, readonly , nullable: The MediaKeys being used when decrypting encrypted media data for this media element.
onencrypted of type EventHandler,: Event handler for the encrypted event MUST be supported by all HTMLMediaElements as both a content attribute and an IDL attribute.
waitingFor of type MediaWaitingFor, readonly: Indicates what the media element is waiting for, if anything (indicated by the waiting and canplay events). This is described in the encrypted block encountered algorithm.

8.2 Methods

setMediaKeys

Provides the MediaKeys to use when decrypting media data during playback.

Note

Support for clearing or replacing the associated MediaKeys object during playback is a quality of implementation issue. In many cases it will result in a bad user experience or rejected promise.

Note

As a best practice, applications should create a MediaKeys object and call setMediaKeys() before providing media data (for example, setting the src attribute). This avoids potential delays in some implementations.

Parameter	Type	Nullable	Optional	Description
mediaKeys	`MediaKeys`	✔	✘	A `MediaKeys` object.

Return type: Promise<void>

When this method is invoked, the user agent must run the following steps:

If mediaKeys and the mediaKeys attribute are the same object, return a resolved promise.
If this object's attaching media keys value is true, return a promise rejected with a new DOMException whose name is InvalidStateError.
Let this object's attaching media keys value be true.
Let promise be a new promise.
Run the following steps asynchronously:
1. If mediaKeys is not null, it is already in use by another media element, and the user agent is unable to use it with this element, let this object's attaching media keys value be false and reject promise with a new DOMException whose name is QuotaExceededError.
2. If the mediaKeys attribute is not null, run the following steps:
  1. If the user agent or CDM do not support removing the association, let this object's attaching media keys value be false and reject promise with a new DOMException whose name is NotSupportedError.
  2. If the association cannot currently be removed, let this object's attaching media keys value be false and reject promise with a new DOMException whose name is InvalidStateError.
    
    Note
    For example, some implementations may not allow removal during playback.
  3. Stop using the CDM instance represented by the mediaKeys attribute to decrypt media data and remove the association with the media element.
  4. If the preceding step failed, let this object's attaching media keys value be false and reject promise with a new DOMException whose name is the appropriate error name.
3. If mediaKeys is not null, run the following steps:
  1. Associate the CDM instance represented by mediaKeys with the media element for decrypting media data.
  2. If the preceding step failed, run the following steps:
    1. Set the mediaKeys attribute to null.
    2. Let this object's attaching media keys value be false.
    3. Reject promise with a new DOMException whose name is the appropriate error name.
  3. Queue a task to run the attempt to resume playback if necessary algorithm on the media element.
    
    The user agent MAY choose to skip this step if it knows resuming will fail.
    
    Note
    For example, the user agent may skip this step if mediaKeys has no sessions.
4. Set the mediaKeys attribute to mediaKeys.
5. Let this object's attaching media keys value be false.
6. Resolve promise.
Return promise.

8.3 `MediaEncryptedEvent`

The MediaEncryptedEvent object is used for the encrypted event.

Events are constructed as defined in Constructing events [DOM].

[ Constructor (DOMString type, optional MediaEncryptedEventInit eventInitDict)]
interface MediaEncryptedEvent : Event {
    readonly    attribute DOMString    initDataType;
    readonly    attribute ArrayBuffer? initData;
};

8.3.1 Constructors

MediaEncryptedEvent

Parameter	Type	Nullable	Optional	Description
type	`DOMString`	✘	✘
eventInitDict	`MediaEncryptedEventInit`	✘	✔

8.3.2 Attributes

initData of type ArrayBuffer, readonly , nullable: The Initialization Data for the event.
initDataType of type DOMString, readonly: Indicates the Initialization Data Type of the Initialization Data contained in the initData attribute.

8.3.3 `MediaEncryptedEventInit`

dictionary MediaEncryptedEventInit : EventInit {
    DOMString    initDataType = "";
    ArrayBuffer? initData = null;
};

8.3.3.1 Dictionary `MediaEncryptedEventInit` Members

initData of type ArrayBuffer, nullable, defaulting to null: The Initialization Data.
initDataType of type DOMString, defaulting to "": The Initialization Data Type.

8.4 Event Summary

This section is non-normative.

Event name	Interface	Dispatched when...	Preconditions
`encrypted`	`MediaEncryptedEvent`	The user agent encounters Initialization Data in the media data.	`readyState` is equal to `HAVE_METADATA` or greater. Note It is possible that the element is playing or has played.

8.5 Algorithms

8.5.1 Initialization Data Encountered

The following steps are run when the media element encounters Initialization Data in the media data during the resource fetch algorithm:

Let initDataType be the empty string.
Let initData be null.
If the media data is CORS-same-origin and not mixed content, run the following steps:
1. Let initDataType be the string representing the Initialization Data Type of the Initialization Data.
2. Let initData be the Initialization Data.
Note
While the media element may allow loading of "Optionally-blockable Content" [MIXED-CONTENT], the user agent MUST NOT expose Initialization Data from such media data to the application.
Queue a task to fire a simple event named encrypted at the media element.

The event is of type MediaEncryptedEvent and has:
- initDataType = initDataType
  
  initData = initData
Note
readyState is not changed and no algorithms are aborted. This event merely provides information.

Note
The initData attribute will be null if the media data is not CORS-same-origin or is mixed content. Applications may retrieve the Initialization Data from an alternate source.
Continue Normal Flow: Continue with the existing media element's resource fetch algorithm.

8.5.2 Encrypted Block Encountered

The following steps are run when the media element encounters a block of encrypted media data during the resource fetch algorithm:

If the media element's mediaKeys attribute is not null, run the following steps:
1. Let media keys be the MediaKeys object referenced by that atribute.
2. Let cdm be the CDM instance represented by media keys's cdm instance value.
3. If there is at least one MediaKeySession created by the media keys on which the session close algorithm has not been run, run the following steps:
  
  Note
  This check ensures the cdm has finished loading and is a prequisite for a matching key being available.
  1. Let the block key ID be the key ID of the current block.
    
    Note
    The key ID is generally specified by the container.
  2. Use the cdm to execute the following steps:
    1. Let available keys be the union of keys in sessions that were created by the media keys.
    2. Let block key be null.
    3. If any of the available keys corresponds to the block key ID and is usable, let block key be that key.
      
      Note
      If multiple sessions contain a usable key for the block key ID, which key to use is Key System-dependent.
    4. If the status of any of the available keys changed as the result of running the previous step, run the update key statuses algorithm on each affected session, providing all key ID(s) in the session along with the appropriate MediaKeyStatus value(s) for each.
    5. If block key is not null, run the following steps:
      1. Use the cdm to decrypt the block using block key.
      2. Follow the steps for the first matching condition from the following list:
        
        If decryption fails
        
        Abort the media element's resource fetch algorithm, run the steps to report a MEDIA_ERR_DECODE error, and abort these steps.
        
        Otherwise
        
        Run the following steps:
        
        If the waitingFor attribute on the media element is "key", set the waitingFor attribute on the media element to "none".
        
        Abort these steps and process the decrypted block as normal.
        
        Note
        In other words, decode the block.
        
        Note
        Not all decryption problems (i.e. using the wrong key) will result in a decryption failure. In such cases, no error is fired here but one may be fired during decode.
      Note
      Otherwise, there is no key for the block key ID in any session so continue.
Run the following steps:

Note
These steps are reached when there is no usable key for the block.
1. Run the queue a "waiting" event algorithm on the media element.
2. Wait for a signal to resume playback.

Note

For frame-based encryption, this may be implemented as follows when the media element attempts to decode a frame as part of the resource fetch algorithm:

Let encrypted be false.
Detect whether the frame is encrypted.

If the frame is encrypted

Run the steps above.

Otherwise

Continue.
Decode the frame.
Provide the frame for rendering.

8.5.3 Queue a "waiting" Event

The Queue a "waiting" Event algorithm is run when the CDM needs to queue a waiting event to a HTMLMediaElement object. Requests to run this algorithm include a target HTMLMediaElement object.

The following steps are run:

Let the media element be the specified HTMLMediaElement object.
If the waitingFor attribute on the media element is not "key", run the following steps:
1. Set the waitingFor attribute on the media element to "key".
2. Queue a task to fire a simple event named waiting at the media element.
Suspend playback.

8.5.4 Attempt to Resume Playback If Necessary

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 HTMLMediaElement object.

The following steps are run:

Let the media element be the specified HTMLMediaElement object.
If the waitingFor attribute on the media element is not "key", abort these steps.
Attempt to resume the resource fetch algorithm by running the encrypted block encountered algorithm.
If the user agent can advance the current playback position in the direction of playback, run the following steps:
1. Queue a task to fire a simple event named canplay at the media element.
2. If the paused attribute on the media element is false, queue a task to fire a simple event named playing at the media element.
Otherwise, the waitingFor attribute on the media element MUST NOT be "none".

8.5.5 Playing the Media Resource Algorithm Modifications

The following steps are added to readyState change algorithms in Playing the media resource:

If a readyState change queues a task to fire a waiting event, the user agent MUST also set the waitingFor attribute on the Media Element to "data".
If a readyState change queues a task to fire a canplay event, the user agent MUST also set the waitingFor attribute on the Media Element to "none".

8.6 Media Element Restrictions

This section is non-normative.

Media data processed by a CDM MAY be unavailable 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.

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 be unavailable. 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.

10. Common Key Systems

All user agents MUST support the common key systems described in this section.

Note

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.

10.1 Clear Key

The "org.w3.clearkey" Key System 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.

10.1.1 Capabilities

The following describe how Clear Key supports key system-specific capabilities:

MediaKeySystemConfiguration:
1. robustness: Only the empty string is supported.
2. distinctiveIdentifier: "required" is not supported.
3. persistentState: Not "required" unless the application intends to create non-"temporary" sessions, if supported.
The "persistent-license" MediaKeySessionType: Implementations MAY support this type when the object's persistent state allowed value is true.
The "persistent-release-message" MediaKeySessionType: Implementations MAY support this type when the object's persistent state allowed value is true.

Issue 11
A release message format needs to be defined.
The setServerCertificate() method: Not supported.
The setMediaKeys() method: Implementations MAY support associating the MediaKeys object with more than one HTMLMediaElement.

10.1.2 Behavior

The following describe how Clear Key implements key system-specific behaviors:

In the generateRequest() algorithm:
- The generated message is a JSON object encoded in UTF-8 as described in License Request Format.
- The request is generated by extracting the key IDs from the init data.
- The "type" member value is the value of the sessionType parameter.
The sessionId attribute is a numerical value representable by a 32-bit integer.
The expiration attribute is always NaN.
In the update() algorithm:
- The response parameter is a JWK Set as described in License Format.
- sanitized response is considered invalid if it is not a valid JWK Set with at least one valid JWK key of a valid length for the media type.
The keyStatuses attribute method always contains all key IDs that have been provided via update(), and their status is always "usable".
Initialization Data: Implementations MAY support any combination of registered Initialization Data Types [EME-REGISTRY]. Implementations SHOULD support the "keyids" type and other types appropriate for content types supported by the user agent.

10.1.3 License Request Format

This section describes the format of the license request provided to the application via the message attribute of the message event.

The format is a JSON object containing the following members:

"kids": An array of key IDs. Each element of the array is the base64url encoding of the octet sequence containing the key ID value.
"type": The requested MediaKeySessionType

When contained in the ArrayBuffer message attribute of a MediaKeyMessageEvent object, the JSON string is encoded in UTF-8 as specified in the Encoding specification [ENCODING]. Applications MAY decode the contents of the ArrayBuffer to a JSON string using the TextDecoder interface [ENCODING].

10.1.3.1 Example

This section is non-normative.

The following example is a license request for a temporary license for two key IDs. (Line breaks are for readability only.)

Example 1

{
  "kids":
    [
     "67ef0gd8pvfd0",
     "77ef0gd8pvfd0"
    ],
  "type":"temporary"
}

10.1.4 License Format

This section describes the format of the license to be provided via the response parameter of the update() method.

The format is a JSON Web Key (JWK) Set containing representation of the symmetric key to be used for decryption, as defined in the JSON Web Key (JWK) specification [JWK].

For each JWK in the set, the parameter values are as follows:

"kty" (key type): "oct" (octet sequence)
"alg" (algorithm): "A128KW" (AES key wrap using a 128-bit key)
"k" (key value): The base64url encoding of the octet sequence containing the symmetric key value
"kid" (key ID): The base64url encoding of the octet sequence containing the key ID value

The JSON object MAY have an optional "type" member value, which MUST be one of the MediaKeySessionType values. If not specified, the default value of "temporary" is used. The update() algorithm compares this value to the sessionType.

When passed to the update() method as the ArrayBuffer response parameter, the JSON string MUST be encoded in UTF-8 as specified in the Encoding specification [ENCODING]. Applications MAY encode the JSON string using the TextEncoder interface [ENCODING].

10.1.4.1 Example

This section is non-normative.

The following example is a JWK Set containing a single symmetric key. (Line breaks are for readability only.)

Example 2

{
  "keys":
    [{
      "kty":"oct",
      "alg":"A128KW",
      "k":"GawgguFyGrWKav7AX4VKUg"
      "kid":"67ef0gd8pvfd0",
    }],
  "type":"temporary"
}

10.1.5 Using base64url

This section is non-normative.

For more information on base64url and working with it, see the "Base64url Encoding" terminology definition and "Notes on implementing base64url encoding without padding" in [JWS]. Specifically, there is no '=' padding, and the characters '-' and '_' MUST be used instead of '+' and '/', respectively.

11. Security

11.1 Input Data Attacks and Vulnerabilities

User Agent and Key System implementations MUST consider media data, Initialization Data, data passed to update(), licenses, key data, and all other data provided by the application as untrusted content and potential attack vectors. They MUST use appropriate safeguards to mitigate any associated threats and take care to safely parse, decrypt, etc. such data. User Agents SHOULD validate data before passing it to the CDM.

Note

Such validation is especially important if the CDM does not run in the same (sandboxed) context as, for example, the DOM.

Implementations MUST NOT return active content or passive content that affects program control flow to the application.

Note

For example, it is not safe to expose URLs or other information that may have come from media data, such as is the case for the Initialization Data passed to generateRequest(). Applications must determine the URLs to use. The messageType attribute of the message event can be used by the application to select among a set of URLs if applicable.

11.2 CDM Attacks and Vulnerabilities

User Agents are responsible for providing users with a secure way to browse the web, including any functionality, such as CDMs, from third parties. User agent implementers MUST obtain sufficient information from Key System implementers to enable them to properly assess the security implications of integrating with the Key System. User agent implementers MUST ensure CDM implementations provide and/or support sufficient controls for the user agent to provide security for the user. User agent implementers MUST ensure CDM implementations can and will be quickly and proactively updated in the event of security vulnerabilities.

Exploiting a CDM implementation that is not fully sandboxed and/or uses platform features may allow an attacker to access OS or platform features, elevate privilege (e.g. to run as system or root), and/or access drivers, kernel, firmware, hardware, etc. Such features, software, and hardware may not be written to be robust against hostile software or web-based attacks and may not be updated with security fixes, especially compared to the user agent. Lack of, infrequent, or slow updates for fixes to security vulnerabilities in CDM implementations increases the risk. Such CDM implementations and UAs that expose them MUST be especially careful in all areas of security, including parsing of all data.

Note

User agents should be especially diligent when using a CDM or underlying mechanism that is part of or provided by the client OS, platform and/or hardware.

If a user agent chooses to support a Key System implementation that cannot be sufficiently sandboxed or otherwise secured, the user agent SHOULD ensure that users are fully informed and/or give explicit consent before loading or invoking it. Such implementations SHOULD only be supported on secure origins to mitigate the potential for Network Attacks.

Note

Granting permissions to unauthenticated origins is equivalent to granting the permissions to any origin in the presence of a network attacker. See also User Alerts / Prompts and Use Secure Origin and Transport.

11.3 Network Attacks

11.3.1 Potential Attacks

This section is non-normative.

Potential network attacks and their implications include:

DNS spoofing attacks: One cannot guarantee that a host claiming to be in a certain domain (origin) really is from that domain.
Passive network attacks: One cannot guarantee that data, including Distinctive Identifiers, transmitted between the client and server is not viewed by other entities. See User Tracking.
Active network attacks: One cannot guarantee that Additional scripts or iframes are not injected into pages (both those that use these APIs for legitimate purposes and pages that do not use these APIs). The consequences are that:
- Calls to these APIs can be injected into any page.
- Calls to these APIs from pages using them for legitimate reasons can be manipulated, including modifying the requested functionality, modifying or adding calls, and modifying or injecting data. See also Input Data Attacks and Vulnerabilities
- Data, including Distinctive Identifiers, transmitted between the client and server can be viewed and/or modified by other entities. See User Tracking.

11.3.2 Mitigations

The following techniques may mitigate the risks:

Use TLS

Applications using TLS can be sure that only the user, software working on behalf of the user, and other pages using TLS that have certificates identifying them as being from the same domain, can interact with that application. Furthermore, origin-specific permissions in combination with a secure origin, ensure that permissions granted to an application cannot be abused by a network attacker.

User agents MAY choose to only support these 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 cannot be sufficiently sandboxed or otherwise secured. See also Secure Origin and Transport.

Block Mixed Content

User agents MUST properly handle Mixed Content [MIXED-CONTENT], including blocking "Blockable Content" [MIXED-CONTENT] to avoid potential exposure to insecure content. Such exposure could compromise other mitigations, such as use of TLS.

User agents MAY choose to block all Mixed Content, including "Optionally-blockable Content" [MIXED-CONTENT] to further increase security by preventing untrusted media data from being passed to the CDM (see CDM Attacks and Vulnerabilities).

Per-origin user alerts / prompts and permissions

User Agents SHOULD ensure that users are fully informed and/or give explicit consent before a Key System that presents security concerns that are greater than other user agent features (e.g. DOM content) may be accessed by an origin. Such alerts and consent SHOULD be per origin to avoid valid uses enabling subsequent malicious access. (A full origin MUST be used rather than just the domain because the protocol is important for security as described above.) User agents SHOULD only persist consent for secure origins (see Secure Origin and Transport), to mitigate the potential for future abuse via Network Attacks.

Note

Granting permissions to unauthenticated origins is equivalent to granting the permissions to any origin in the presence of a network attacker. Alerting or prompting the user for consent on insecure origins without persisting the choice provides at least a minimum level of security because the user would be alerted to unexpected use (e.g. on a site that does not have protected media.

11.4 `iframe` Attacks

11.4.1 Potential Attacks

This section is non-normative.

Malicious pages could host legitimate applications in an iframe in an attempt hide an attack or deceive the user as to the source, such as making the use appear to be from a legitimate content provider. This is especially relevent for user agents that support have user alerts, prompts, and/or permissions. In addition to Network Attacks, attackers could try to exploit legitimate uses of these APIs by hosting them in an iframe. By having the legitimate application performing the actions, the attacker can reuse existing granted permissions (or whitelisting) and/or appear to be a legitimate request or use.

11.4.2 Mitigations

User agents are RECOMMENDED to base the UI and persistence of user alerts, prompts, and/or permissions on the combination of origin of the top-level Document and the origin using these APIs. This ensures that users are informed of the main document making the request and that persisting a permission for one (legitimate) combination does not inadvertently allow malicious use to go undetected.

Authors are RECOMMENDED to prevent other entities from hosting their applications in iframes. Applications that must support being hosted for legitimate application-design reasons SHOULD NOT allow hosting documents to provide any data to be passed to the CDM - either via these APIs or as media data - and SHOULD NOT allow hosting frames to invoke these APIs.

11.5 Cross-Directory Attacks

This section is non-normative.

Different authors sharing one host name, for example users hosting content on geocities.com, all share one origin. User agents do not provide features to restrict access to APIs by pathname.

Using these APIs on shared hosts compromises origin-based security and privacy mitigations implemented by user agents. For example, per-origin Distinctive Identifiers are shared by all authors on one host name, and peristed data may be accessed and manipulated by any author on the host. The latter is especially important if, for example, modification or deletion of such data could erase a user's right to specific content.

Note

Even if a path-restriction feature was made available by user agents, the usual DOM scripting security model would make it trivial to bypass this protection and access the data from any path.

Authors on shared hosts are therefore RECOMMENDED to avoid using these APIs because doing so compromises origin-based security and privacy mitigations in user agents.

12. Privacy

The presence or use of Key System(s) 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 Key System messages and (b) user-specific information that may be persistently stored on the user's device.

User Agents MUST 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.

12.1 Information Disclosed by EME and Key Systems

Concerns regarding information disclosed by EME and Key Systems fall into two categories: (a) concerns about non-specific information that may nevertheless contribute to the possibility of fingerprinting a user agent or device and (b) user-specific information that may be used directly for user tracking.

12.2 Fingerprinting

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 MUST not share key or other data between origins.

12.3 Information Leakage

12.3.1 Concerns

This section is non-normative.

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. Failure to do so could lead to information leakage to/from private browsing sessions, across profiles, and even across different browsers, applications, and operating system user accounts.

12.3.2 Mitigations

To avoid such issues, user agent and CDM implementations MUST ensure that:

CDMs have a concept of a CDM instance that is associated one-to-one with a MediaKeys object.
Keys, licenses, other session data, and the presence of sessions are restricted to the CDM instance associated with the MediaKeys object that created the session.
Session data is not shared between MediaKeys objects or CDM instances.
Session data is not shared with media elements not associated with the MediaKeys object that created the session. Among other things, this means a session's keys MUST not be used to decrypt content loaded by a media element whose mediaKeys attribute is not that MediaKeys object.
MediaKeys objects and the underlying implementation do not expose information outside the origin.
Persisted session data, if applicable, is stored on a per-origin basis.
Only data stored by the requesting origin may be loaded.

12.4 User Tracking

12.4.1 Concerns

This section is non-normative.

A third-party host (or any entity, such as an advertiser, capable of getting content distributed to multiple sites) could use a Distinctive Identifier or data, including keys, stored in the CDM's client-side database to track a user across multiple sessions (including across profiles and user accounts on the client device), building a profile of the user's activities or interests. Such tracking would undermine the privacy protections provided by the rest of the web platform and could, for example, enable highly-targeted advertising not otherwise possible. In conjunction with a site that is aware of the user's real identity (for example, a content provider or e-commerce site that requires authenticated credentials), this could allow oppressive groups to target individuals with greater accuracy than in a world with purely anonymous Web usage.

User- or client-specific information that could be obtained via the APIs in this specification includes:

Distinctive Identifier(s)
Origins visisted (via stored or in-memory data, permissions, etc.)
Content viewed (via stored or in-memory keys, key IDs, data, etc.)

This specification presents a specific concern because such information is commonly stored outside the user agent (and its profile storage), often in the CDM.

Key Systems may access or create persistent or semi-persistent identifier(s), Distinctive Identifier(s), 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.

It is important to note that such identifiers, especially those that are non-clearable, non-origin-specific or hardware-bound, exceed the tracking impact of existing techniques such as cookies [COOKIES] or session identifiers embedded in URLs.

If not mitigated, such tracking may take three forms depending on the design of the Key System:

In all cases, such identifiers are expected to be available to sites and/or servers that fully support the Key System (and thus can interpret Key System messages) enabling tracking by such sites.
If identifiers exposed by Key Systems are not origin-specific, then two sites and/or servers that fully support the Key System may collude to track the user.
If Key System messages contain information derived from a user identifier in a consistent manner, for example such that a portion of the initial Key System message for a specific content item does not change over time and is dependent on the user identifier, then this information could be used by any application to track the device or user over time.

In addition, if a Key System permits keys to be stored and to be re-used between origins, then it may be possible for two origins to collude and track a unique user by recording their ability to access a common key.

Finally, if any user interface for user control of Key Systems presents data separately from data in HTTP session cookies [COOKIES] or persistent storage, then users are likely to modify site authorization or delete data in one and not the others. This would allow sites to use the various features as redundant backup for each other, defeating a user's attempts to protect his privacy.

The following section describes techniques that may mitigate the risks of tracking without user consent.

12.4.2 Mitigations

Do not use Distinctive Identifiers

Key System implementations SHOULD avoid using Distinctive Identifiers whenever possible and only use them when they meaningfully contribute to the robustness of the implementation. See Limit or Avoid use of Distinctive Identifiers.

User deletion of Distinctive Identifiers

User agents MUST provide users with the ability to clear any Distinctive Identifiers maintained by Key Systems. See Allow Identifiers to be Cleared.

Use of (non-reversible) per-origin identifiers

Implementations that use Distinctive Identifiers MUST use a different value for each origin, either by allocation of different identifiers for different origins or by use of a non-reversible origin-specific mapping from an origin-independent identifier. See Use Per-Origin Identifiers.

Encryption of Distinctive Identifiers

Distinctive Identifiers in Key System messages MUST be encrypted, together with a timestamp or nonce, such that the Key System messages are always different. This prevents the use of Key System messages for tracking except by servers fully supporting the Key System. See Encrypt Identifiers.

Blocking third-party access

User agents MAY restrict access to Key Systems and/or features to scripts originating at the origin of the top-level Document of the browsing context. For example, requestMediaKeySystemAccess() may deny requests for certain configurations for pages from other origins running in iframes.

Expiring stored data

User agents MAY, possibly in a manner configured by the user, automatically delete Distinctive Identifiers and/or other Key System data after a period of time.

Note

For example, a user agent could be configured to such data as session-only storage, deleting the data once the user had closed all the browsing contexts that could access it.

This can restrict the ability of a site to track a user, as the site would then only be able to track the user across multiple sessions when he authenticates with the site itself (e.g. by making a purchase or logging in to a service).

However, this can also put the user's access to content, especially purchased or rented content, at risk if the user does not fully understand the implications of such expiration.

Treating Distinctive Identifiers and Key System stored data like cookies / web storage

User agents SHOULD present the presence of Distinctive Identifiers and data stored by Key Systems to the user in a way that associates them strongly with HTTP session cookies [COOKIES]. This might encourage users to view such identifiers with healthy suspicion. User agents SHOULD help the user avoid Incomplete Clearing of Data.

Site-specific white-listing of access to each Key System

User agents MAY require the user to explicitly authorize access to each Key System - and/or certain features - before a site can use it. User agents SHOULD enable users to revoke this authorization either temporarily or permanently.

Shared blacklists

User agents MAY allow users to share their Key System origin blacklists. This would allow communities to act together to protect their privacy.

Per-origin user alerts / prompts and permissions

User agents MUST ensure that users are fully informed and/or give explicit consent before Distinctive Identifier(s) are exposed, such as in messages from the Key System implementation.

User agents MUST prompt or otherwise inform the user before allowing use of a Distinctive Identifier that is not unique per-origin and/or not clearable is used. User agents SHOULD prompt or otherwise inform the user before allowing use of all other Distinctive Identifier.

Note

The "not unique per-origin" and "not clearable" conditions cannot be true in a compliant implementation because implementations MUST use per-origin identifiers and allow the user to clear identifier.

Such alerts and consent SHOULD be per origin to avoid valid uses enabling subsequent malicious access. User agent implementers that consider such alerts or consent appropriate for a Key System implementation SHOULD only support such Key Systems on secure origins (see Secure Origin and Transport), especially if they allow such consent to be persisted.

Note

Granting permissions to unauthenticated origins is equivalent to granting the permissions to any origin in the presence of a network attacker.

User controls to disable Key Systems or Key System use of identifiers

User Agents SHOULD provide users with a global control of whether a Key System is enabled and/or whether Key System use of Distinctive Identifier(s) is enabled (if supported by the Key System). User agents SHOULD help the user avoid Incomplete Clearing of Data.

Note

While these suggestions prevent trivial use of this API for user tracking, they do not block it altogether. Within a single origin, 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 unique per-origin, then a profile can still be created.

12.4.3 Individualization

Distinctive Identifier(s) are sometimes obtained via a process called individualization or provisioning. In all cases, implementations SHOULD avoid sending per-origin information to centralized servers since this could create a central record of all origins visited by a user or device.

Per-origin individualization (resulting in a per-origin Distinctive Identifier) can - with appropriate precautions - provide better privacy than other individualization models. To preserve the benefits of such a design and to avoid introducing other privacy concerns:

Such implementations SHOULD not use distinctive identifier(s) for a device or user of a device in the individualization process.
Such implementations and the applications that support them SHOULD also avoid deferring or forwarding the individualization process to a central server or other server not controlled by the application author.

12.5 Information Stored on User Devices

12.5.1 Concerns

This section is non-normative.

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.

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.

If information stored for one browsing profile, browser, or user account on the client device affects the operation of the Key System for other profiles, browsers, or accounts, then potentially the sites visited or content viewed by in one may be revealed by or correlatable with another profile, browser, or account.

12.5.2 Mitigations

In summary, user agent and CDM implementations that allow the CDM to persist data:

MUST ensure it is restricted to the origin for which it was created.
MUST ensure it is restricted to the current profile and does not leak to or from private browsing sessions.
MUST allow the user to clear it, preferably by origin.
SHOULD treat it like other site data, including presenting it along with cookies [COOKIES], including it in "remove all data", and presenting it in the same UI locations.

Origin-specific Key System storage: Any data persistently stored by the CDM that might impact messages or behavior in an application- or license server-visible way MUST be stored in an origin-specific way. Session data, licenses, and keys that are persistently stored MUST be stored per-origin. See Session Storage and Persistence.
User deletion of Key System storage: User agents SHOULD present the user with a way to delete Key System storage for a specific origin or all origins. User agents SHOULD help the user avoid Incomplete Clearing of Data.
Treating Distinctive Identifiers and Key System stored data like cookies / web storage: See the identical section above.
Encryption or obfuscation of Key System stored data: User agents SHOULD treat data stored by Key Systems as potentially sensitive; it is quite possible for user privacy to be compromised by the release of this information. To this end, user agents SHOULD ensure that such data is securely stored and when deleting data, it is promptly deleted from the underlying storage.

12.6 Incomplete Clearing of Data

12.6.1 Concerns

This section is non-normative.

A user's attempts to protect his or her privacy by clearing Distinctive Identifiers and stored data and/or disabling a Key System may be defeated if all such data and functionality as well as cookies [COOKIES] and other site data are not cleared and/or disabled at the same time. For example:

If a user clears cookies or other persistent storage without also clearing Distinctive Identifiers and data stored by Key Systems, sites can defeat those attempts by using the various features as redundant backup for each other.
If a user disables a key system, especially for a specific origin, without also clearing cookies or other persistent storage, sites can defeat those attempts by using the remaining features.
If a user disables a key system, then later decide to enable the key system, without also clearing clearing cookies or other persistent storage, Distinctive Identifiers, and data stored by Key Systems, sites may be able to associate data prior to the disabling with data and behavior after the key system is re-enabled.

12.6.2 Mitigations

User agents SHOULD present the interfaces for clearing Distinctive Identifiers and Key System stored data in a way that helps users to understand this possibility and enables them to delete data in all persistent identification and storage features, including HTTP session cookies [COOKIES] and web storage, simultaneously. Likewise, User agents SHOULD present the interfaces for disabling and re-enabling a Key System in a way that helps users to understand this possibility and enables them to delete all such data in all persistent storage features simultaneously.

12.7 Private Browsing Modes

User agents may support a mode (e.g. private browsing) of operation intended to preserve user anonymity and/or ensure records of browsing activity are not persisted on the client. The privacy concerns discussed in previous sections may be expecially concerning for users employing such modes.

User agent implementers that support such mode(s) SHOULD carefully consider whether access to Key Systems should be disabled in these mode(s). For example, such modes MAY prohibit creation of MediaKeySystemAccess objects that support or use persistentState or a distinctiveIdentifier (either as part of the CDM implementation or because the application indicated they were "required"). If implementations do not prohibit such creation, they SHOULD inform the user of the implications and potential consequences for the expected privacy properties of such modes before allowing their use.

12.8 Secure Origin and Transport

In order to protect identifiers and other information discussed in previous sections, user agents MAY choose to only support these 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 expose Distinctive Identifiers or other such information without effectively anonymizing it in transit.

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 message events and to update()).

All user agents MUST properly handle Mixed Content [MIXED-CONTENT] to avoid exposure to insecure content or transport when the user agent or application wish to enforce secure origin and transport.

13. Examples

This section is non-normative.

This section contains example solutions for various use cases using the proposed extensions. These are not the only solutions to these use cases. Video elements are used in the examples, but the same would apply to all media elements. In some cases, such as using synchronous XHR, the examples are simplified to keep the focus on the extensions.

13.1 Source and Key Known at Page Load (Clear Key)

In this simple example, the source file and clear-text license are hard-coded in the page. Only one session will ever be created.

Example 3

<script>
  function onLoad() {
    var video = document.getElementById("video");

    if (!video.mediaKeys) {
      navigator.requestMediaKeySystemAccess("org.w3.clearkey").then(
        function(keySystemAccess) {
          var promise =  keySystemAccess.createMediaKeys();
          promise.catch(
            console.error.bind(console, "Unable to create MediaKeys")
          );
          promise.then(
            function(createdMediaKeys) {
              return video.setMediaKeys(createdMediaKeys);
            }
          ).catch(
            console.error.bind(console, "Unable to set MediaKeys")
          );
          promise.then(
            function(createdMediaKeys) {
              var initData = new Uint8Array([ ... ]);
              var keySession = createdMediaKeys.createSession();
              keySession.addEventListener("message", handleMessage, false);
              return keySession.generateRequest("webm", initData);
            }
          ).catch(
            console.error.bind(console, "Unable to create or initialize key session")
          );
        }
      );
    }
  }

  function handleMessage(event) {
    var keySession = event.target;

    var license = new Uint8Array([ ... ]);
    keySession.update(license).catch(
      console.error.bind(console, "update() failed")
    );
  }
</script>

<body onload="onLoad()">
  <video src="foo.webm" autoplay id="video"></video>
</body>

13.2 Selecting a Supported Key System and Using Initialization Data from the "encrypted" Event

This example selects a supported Key System using the requestMediaKeySystemAccess() method then uses the Initialization Data from the media data 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.

Example 4

<script>
  var licenseUrl;
  var serverCertificate;

  // Returns a Promise<MediaKeys>.
  function createSupportedKeySystem() {
    someSystemOptions = [
     { initDataTypes: ["keyids", "webm"],
       audioCapabilities: [
         { contentType: "audio/webm; codecs='opus'" },
         { contentType: "audio/webm; codecs='vorbis'" }
       ],
       videoCapabilities: [
         { contentType: "video/webm; codecs='vp9'" },
         { contentType: "video/webm; codecs='vp8'" }
       ]
     }
    ];
    clearKeyOptions = [
     { initDataTypes: ["keyids", "webm"],
       audioCapabilities: [
         { contentType: "audio/webm; codecs='opus'" },
         { contentType: "audio/webm; codecs='vorbis'" }
       ],
       videoCapabilities: [
         { contentType: "video/webm; codecs='vp9'",
           robustness: "foo" },
         { contentType: "video/webm; codecs='vp9'",
           robustness: "bar" },
         { contentType: "video/webm; codecs='vp8'",
           robustness: "bar" },
       ]
     }
    ];

    navigator.requestMediaKeySystemAccess("com.example.somesystem", someSystemOptions).then(
      function(keySystemAccess) {
        // Not shown:
        // 1. Use both attributes of keySystemAccess.getConfiguration().audioCapabilities[0]
        //    and both attributes of keySystemAccess.getConfiguration().videoCapabilities[0]
        //    to retrieve appropriate stream(s).
        // 2. Set video.src.

        licenseUrl = "https://license.example.com/getkey";
        serverCertificate = new Uint8Array([ ... ]);
        return keySystemAccess.createMediaKeys();
      }
    ).catch(
      function(error) {
        // Try the next key system.
        navigator.requestMediaKeySystemAccess("org.w3.clearkey", clearKeyOptions).then(
          function(keySystemAccess) {
          // Not shown:
          // 1. Use keySystemAccess.getConfiguration().audioCapabilities[0].contentType
          //    and keySystemAccess.getConfiguration().videoCapabilities[0].contentType
          //    to retrieve appropriate stream(s).
          // 2. Set video.src.

            licenseUrl = "https://license.example.com/clearkey/request";
            return keySystemAccess.createMediaKeys();
          }
        );
      }
    ).catch(
      console.error.bind(console, "Unable to instantiate a key system supporting the required combinations")
    );
  }

  function handleInitData(event) {
    var video = event.target;
    if (video.mediaKeysObject === undefined) {
      video.mediaKeysObject = null; // Prevent entering this path again.
      video.pendingSessionData = []; // Will store all initData until the MediaKeys is ready.
      createSupportedKeySystem().then(
        function(createdMediaKeys) {
          video.mediaKeysObject = createdMediaKeys;

          if (serverCertificate)
            createdMediaKeys.setServerCertificate(serverCertificate);

          for (var i = 0; i < video.pendingSessionData.length; i++) {
            var data = video.pendingSessionData[i];
            makeNewRequest(video.mediaKeysObject, data.initDataType, data.initData);
          }
          video.pendingSessionData = [];

          return video.setMediaKeys(createdMediaKeys);
        }
      ).catch(
        console.error.bind(console, "Failed to create and initialize a MediaKeys object")
      );
    }
    addSession(video, event.initDataType, event.initData);
  }

  function addSession(video, initDataType, initData) {
    if (video.mediaKeysObject) {
      makeNewRequest(video.mediaKeysObject, initDataType, initData);
    } else {
      video.pendingSessionData.push({initDataType: initDataType, initData: initData});
    }
  }

  function makeNewRequest(mediaKeys, initDataType, initData) {
    var keySession = mediaKeys.createSession();
    keySession.addEventListener("message", licenseRequestReady, false);
    keySession.generateRequest(initDataType, initData).catch(
      console.error.bind(console, "Unable to create or initialize key session")
    );
  }

  function licenseRequestReady(event) {
    var request = event.message;

    var xmlhttp = new XMLHttpRequest();
    xmlhttp.keySession = event.target;
    xmlhttp.open("POST", licenseUrl);
    xmlhttp.onreadystatechange = function() {
      if (xmlhttp.readyState == 4) {
        var license = new Uint8Array(xmlhttp.response);
        xmlhttp.keySession.update(license).catch(
          console.error.bind(console, "update() failed")
        );
      }
    }
    xmlhttp.send(request);
  }
</script>

<video autoplay onencrypted="handleInitData(event)"></video>

13.3 Create MediaKeys Before Loading Media

Initialization is much simpler if encrypted events do not need to be handled during MediaKeys initialization. This can be accomplished either by providing the Initialization Data in other ways or setting the source after the MediaKeys object has been created. This example does the latter.

Example 5

<script>
  var licenseUrl;
  var serverCertificate;
  var mediaKeys;

  // See the previous example for implementations of these functions.
  function createSupportedKeySystem() { ... }
  function makeNewRequest(mediaKeys, initDataType, initData) { ... }
  function licenseRequestReady(event) { ... }

  function handleInitData(event) {
    makeNewRequest(mediaKeys, event.initDataType, event.initData);
  }

  createSupportedKeySystem().then(
    function(createdMediaKeys) {
      mediaKeys = createdMediaKeys;
      var video = document.getElementById("v");
      video.src = "foo.webm";
      if (serverCertificate)
        mediaKeys.setServerCertificate(serverCertificate);
      return video.setMediaKeys(mediaKeys);
    }
  ).catch(
    console.error.bind(console, "Failed to create and initialize a MediaKeys object")
  );
</script>

<video id="v" autoplay onencrypted="handleInitData(event)"></video>

13.4 Using All Events

This is a more complete example showing all events being used.

Note that handleMessage() could be called multiple times, including in response to the update() call if multiple round trips are required and for any other reason the Key System might need to send a message.

Example 6

<script>
  var licenseUrl;
  var serverCertificate;
  var mediaKeys;

  // See previous examples for implementations of these functions.
  // createSupportedKeySystem() additionally sets renewalUrl.
  function createSupportedKeySystem() { ... }
  function handleInitData(event) { ... }

  // This replaces the implementation in the previous example.
  function makeNewRequest(mediaKeys, initDataType, initData) {
    var keySession = mediaKeys.createSession();
    keySession.addEventListener("message", handleMessage, false);
    keySession.addEventListener("keyschange", handleKeysChange, false);
    keySession.closed.then(
      console.log.bind(console, "Session closed")
    );
    keySession.generateRequest(initDataType, initData).catch(
      console.error.bind(console, "Unable to create or initialize key session")
    );
  }

  function handleMessageResponse(keySession, response) {
    var license = new Uint8Array(response);
    keySession.update(license).catch(
      function(err) {
        console.error("update() failed: " + err);
      }
    );
  }

  function sendMessage(type, message, keySession) {
    var url = licenseUrl;
    if (type == "license-renewal")
      url = renewalUrl;
    xmlhttp = new XMLHttpRequest();
    xmlhttp.keySession = keySession;
    xmlhttp.open("POST", url);
    xmlhttp.onreadystatechange = function() {
      if (xmlhttp.readyState == 4)
        handleMessageResponse(xmlhttp.keySession, xmlhttp.response);
    }
    xmlhttp.send(message);
  }

  function handleMessage(event) {
    sendMessage(event.messageType, event.message, event.target);
  }

  function handleKeysChange(event) {
    // Evaluate the current state using one of the map-like methods exposed by
    // event.target.keyStatuses.
    // For example:
    event.target.keyStatuses.forEach(function(status, keyId, map) {
      switch (value) {
        case "usable":
          break;
        case "expired":
          // Report an expired key.
          break;
        default:
          // Do something with |keyId| and |status|.
        }
      }
    })
  }

  createSupportedKeySystem().then(
    function(createdMediaKeys) {
      mediaKeys = createdMediaKeys;
      var video = document.getElementById("v");
      video.src = "foo.webm";
      if (serverCertificate)
        mediaKeys.setServerCertificate(serverCertificate);
      return video.setMediaKeys(mediaKeys);
    }
  ).catch(
    console.error.bind(console, "Failed to create and initialize a MediaKeys object")
  );
</script>

<video id="v" autoplay onencrypted="handleInitData(event)"></video>

13.5 Stored License

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.

Example 7

<script>
  var licenseUrl;
  var serverCertificate;
  var mediaKeys;

  // See the previous examples for implementations of these functions.
  // createSupportedKeySystem() additionally sets persistentState: "required" in each options dictionary.
  function createSupportedKeySystem() { ... }
  function sendMessage(message, keySession) { ... }
  function handleMessage(event) { ... }

  // Called if the application does not have a stored sessionId for the media resource.
  function makeNewRequest(mediaKeys, initDataType, initData) {
    var keySession = mediaKeys.createSession("persistent-license");
    keySession.addEventListener("message", handleMessage, false);
    keySession.closed.then(
      function() {
        console.log("Session " + this.sessionId + " closed");
      }.bind(keySession)
    );
    keySession.generateRequest(initDataType, initData).then(
      function() {
        // Store this.sessionId in the application.
      }.bind(keySession)
    ).catch(
      console.error.bind(console, "Unable to request a persistent license")
    );
  }

  // Called if the application has a stored sessionId for the media resource.
  function loadStoredSession(mediaKeys, sessionId) {
    var keySession = mediaKeys.createSession("persistent-license");
    keySession.addEventListener("message", handleMessage, false);
    keySession.closed.then(
      console.log.bind(console, "Session closed")
    );
    keySession.load(sessionId).then(
      function(loaded) {
        if (!loaded) {
          console.error("No stored session with the ID " + sessionId + " was found.");
          // The application should remove its record of |sessionId|.
          return;
        }
      }
    ).catch(
      console.error.bind(console, "Unable to load or initialize the stored session with the ID " + sessionId)
    );
  }

  // Called when the application wants to stop using the session without removing the stored license.
  function closeSession(keySession) {
    keySession.close();
  }

  // Called when the application wants to remove the stored license.
  // The stored session data has not been completely removed until the promise returned by remove() is fulfilled.
  // The remove() call may initiate a series of messages to/from the server that must be completed before this occurs.
  function removeStoredSession(keySession) {
    keySession.remove().then(
      function() {
        console.log("Session " + this.sessionId + " removed");
        // The application should remove its record of this.sessionId.
      }.bind(keySession)
    ).catch(
      console.error.bind(console, "Failed to remove the session")
    );
  }

  // This replaces the implementation in the previous example.
  function handleMessageResponse(keySession, response) {
    var license = new Uint8Array(response);
    keySession.update(license).then(
      function() {
        // If this was the last required message from the server, the license is
        // now stored. Update the application state as appropriate.
      }
    ).catch(
      console.error.bind(console, "update() failed")
    );
  }

  createSupportedKeySystem().then(
    function(createdMediaKeys) {
      mediaKeys = createdMediaKeys;
      var video = document.getElementById("v");
      if (serverCertificate)
        mediaKeys.setServerCertificate(serverCertificate);
      return video.setMediaKeys(mediaKeys);
    }
  ).catch(
    console.error.bind(console, "Failed to create and initialize a MediaKeys object")
  );
</script>

<video id="v" src="foo.webm" autoplay></video>

Version	Comment
13 November 2014	Repository moved to GitHub.
10 October 2014	Converted to ReSpec.
3 September 2014	Reorganized by object.
27 August 2014	Moved license request generation and session loading to MediaKeySession.
18 August 2014	Produced candidate WD.
14 April 2014	Use promises.
1 April 2014	Moved Container Guidelines to the Encrypted Media Extensions Stream Format and Initialization Data Format Registry.
3 February 2014	Produced candidate WD.
17 September 2013	Produced candidate WD.
6 May 2013	Produced updated candidate FPWD.
14 January 2013	Produced candidate FPWD.
16 August 2012	Converted to the object-oriented API.
0.1b	Last non-object-oriented revision.
0.1a	Corrects minor mistakes in 0.1.
0.1	Initial Proposal

Abstract

Status of This Document

Table of Contents

1. Introduction

2. Definitions

3. Obtaining Access to Key Systems

3.1 Navigator Extension: requestMediaKeySystemAccess()

3.1.1 Methods

3.1.2 Algorithms

3.1.2.1 Get Supported Configuration

3.1.2.2 Get Supported Capabilities for Media Type

3.2 MediaKeySystemConfiguration dictionary

3.2.1 Dictionary MediaKeySystemConfiguration Members

3.3 MediaKeySystemMediaCapability dictionary

3.3.1 Dictionary MediaKeySystemMediaCapability Members

4. MediaKeySystemAccess Interface

4.1 Attributes

4.2 Methods

5. MediaKeys Interface

5.1 Methods

6. MediaKeySession Interface

6.1 Attributes

6.2 Methods

6.3 MediaKeyMessageEvent

6.3.1 Constructors

6.3.2 Attributes

6.3.3 MediaKeyMessageEventInit

6.3.3.1 Dictionary MediaKeyMessageEventInit Members

6.4 Event Summary

6.5 Algorithms

6.5.1 Queue a "message" Event

6.5.2 Update Key Statuses

6.5.3 Update Expiration

6.5.4 Session Close

6.6 Exceptions

6.7 Session Storage and Persistence

7. MediaKeyStatusMap Interface

7.1 Attributes

8. HTMLMediaElement Extensions

8.1 Attributes

8.2 Methods

8.3 MediaEncryptedEvent

8.3.1 Constructors

8.3.2 Attributes

8.3.3 MediaEncryptedEventInit

8.3.3.1 Dictionary MediaEncryptedEventInit Members

8.4 Event Summary

8.5 Algorithms

8.5.1 Initialization Data Encountered

8.5.2 Encrypted Block Encountered

8.5.3 Queue a "waiting" Event

8.5.4 Attempt to Resume Playback If Necessary

8.5.5 Playing the Media Resource Algorithm Modifications

8.6 Media Element Restrictions

9. Implementation Requirements

9.1 Identifiers

9.1.1 Limit or Avoid use of Distinctive Identifiers

9.1.2 Encrypt Identifiers

9.1.3 Use Per-Origin Identifiers

9.1.4 Allow Identifiers to be Cleared

10. Common Key Systems

10.1 Clear Key

10.1.1 Capabilities

10.1.2 Behavior

10.1.3 License Request Format

10.1.3.1 Example

10.1.4 License Format

10.1.4.1 Example

10.1.5 Using base64url

11. Security

11.1 Input Data Attacks and Vulnerabilities

11.2 CDM Attacks and Vulnerabilities

11.3 Network Attacks

11.3.1 Potential Attacks

11.3.2 Mitigations

11.4 iframe Attacks

11.4.1 Potential Attacks

11.4.2 Mitigations

11.5 Cross-Directory Attacks

12. Privacy

3.1 `Navigator` Extension: `requestMediaKeySystemAccess()`

3.2 `MediaKeySystemConfiguration` dictionary

3.2.1 Dictionary `MediaKeySystemConfiguration` Members

3.3 `MediaKeySystemMediaCapability` dictionary

3.3.1 Dictionary `MediaKeySystemMediaCapability` Members

4. `MediaKeySystemAccess` Interface

5. `MediaKeys` Interface

6. `MediaKeySession` Interface

6.3 `MediaKeyMessageEvent`

6.3.3 `MediaKeyMessageEventInit`

6.3.3.1 Dictionary `MediaKeyMessageEventInit` Members

7. `MediaKeyStatusMap` Interface

8. `HTMLMediaElement` Extensions

8.3 `MediaEncryptedEvent`

8.3.3 `MediaEncryptedEventInit`

8.3.3.1 Dictionary `MediaEncryptedEventInit` Members

11.4 `iframe` Attacks