3.1 Navigator Extension: requestMediaKeySystemAccess()

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

3.2 MediaKeySystemConfiguration dictionary

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

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

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.

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

3.3 MediaKeySystemMediaCapability dictionary

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

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

4.1 Attributes

keySystem of type DOMString, readonly

Identifies the Key System being used.

4.2 Methods

createMediaKeys

Creates a new MediaKeys object for keySystem.

No parameters.

Return type: Promise<MediaKeys>

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

1. Let promise be a new promise.

2. Run the following steps in parallel:

   1. Let configuration be the value of this object's configuration value.

   2. Let distinctive identifier be the value of configuration's distinctiveIdentifier member.

   3. Follow the steps for the value of distinctive identifier from the following list:

      "required"

      Let use distinctive identifier be true.

      "not-allowed"

      Let use distinctive identifier be false.

      Note

      The value of distinctive identifier cannot be "optional".

   4. Let persistent state be the value of configuration's persistentState member.

   5. Follow the steps for the value of persistent state from the following list:

      "required"

      Let persistent state allowed be true.

      "not-allowed"

      Let persistent state allowed be false.

      Note

      The value of persistent state cannot be "optional".

   6. Load and initialize the Key System implementation represented by this object's cdm implementation value if necessary.

   7. Let instance be a new instance of the Key System implementation represented by this object's cdm implementation value.

   8. If use distinctive identifier is false, prevent instance from using Distinctive Identifier(s).

   9. If persistent state allowed is false, prevent instance from persisting any state related to the application or origin of this object's Document.

   10. If any of the preceding steps failed, reject promise with a new DOMException whose name is the appropriate error name.

   11. Let media keys be a new MediaKeys object, and initialize it as follows:

       1. Let the use distinctive identifier value be use distinctive identifier.

       2. Let the persistent state allowed value be persistent state allowed.

       3. Let the supported session types value be be the value of configuration's sessionTypes member.

       4. Let the cdm implementation value be this object's cdm implementation value.

       5. Let the cdm instance value be instance.

   12. Resolve promise with media keys.

3. Return promise.

getConfiguration

Returns the supported combination of configuration options selected by the requestMediaKeySystemAccess() algorithm.

The returned object is a non-strict subset (plus any implied defaults) of the first satisfiable MediaKeySystemConfiguration configuration passed to the requestMediaKeySystemAccess() call that returned the promise that was resolved with this object. It does not contain values capabilities not specified in that single configuration (other than implied defaults) and thus may not reflect all capabilities of the Key System implementation. All values in the configuration may be used in any combination. Members of type MediaKeysRequirement reflect whether the capability is required for any combination. They will not have the value "optional".

No parameters.

Return type: MediaKeySystemConfiguration

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

1. Return this object's configuration value.

   Note

   This results in a new JavaScript object being created and initalized from configuration each time this method is called.

5.1 Methods

createSession

Returns a new MediaKeySession object.

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

Return type: MediaKeySession

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

1. If this object's supported session types value does not contain sessionType, throw a NotSupportedError.

   Note

   sessionType values for which the Is persistent session type? algorithm returns true will fail if this object's persistent state allowed value is false.

2. Let session be a new MediaKeySession object, and initialize it as follows:

   1. Let the sessionId attribute be the empty string.

   2. Let the expiration attribute be NaN.

   3. Let the closed attribute be a new promise.

   4. Let key status be a new empty MediaKeyStatusMap object, and initialize it as follows:

      1. Let the size attribute be 0.

   5. Let the session type value be sessionType.

   6. Let the uninitialized value be true.

   7. Let the callable value be false.

   8. Let the use distinctive identifier value be this object's use distinctive identifier value.

   9. Let the cdm implementation value be this object's cdm implementation.

   10. Let the cdm instance value be this object's cdm instance.

3. Return session.

setServerCertificate

Provides a server certificate to be used to encrypt messages to the license server.

Key Systems that use such certificates MUST also support requesting the certificate from the server via the Queue a "message" Event algorithm.

Note

This method allows an application to proactively provide a server certificate to implementations that support it to avod the additional round trip should the CDM request it. It is intended as an optimization, and applications are not required to use it.

Parameter	Type	Nullable	Optional	Description
serverCertificate	BufferSource	✘	✘	The server certificate. 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:

1. If serverCertificate is an empty array, return a promise rejected with a new a newly created TypeError.

2. If the Key System implementation represented by this object's cdm implementation value does not support server certificates, return a promise rejected with a NotSupportedError.

3. Let certificate be a copy of the contents of the serverCertificate parameter.

4. Let promise be a new promise.

5. Run the following steps in parallel:

   1. Use this object's cdm instance to process certificate.

   2. If the preceding step failed, reject promise with a new DOMException whose name is the appropriate error name.

   3. Resolve promise.

6. Return promise.

5.2 Algorithms

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 or if the license explicitly never expires, as determined by the CDM. The value of Infinity should never be used.

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. Persisted data should not be released or cleared.

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:

1. If the Session Close algorithm has been run on this object, return a resolved promise.

2. If this object's callable value is false, return a promise rejected with an InvalidStateError.

3. Let promise be a new promise.

4. Run the following steps in parallel:

   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. Do not generate or send key or license release messages.

      2. If the preceding step caused the session to be closed, run the Session Close algorithm on this object.

   3. Resolve promise.

5. Return promise.

generateRequest

Generates a license request based on the initData. A message of type "license-request" will always be queued if the algorithm succeeds and the promise is resolved.

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:

1. If the Session Close algorithm has been run on this object, return a promise rejected with an InvalidStateError.

2. If this object's uninitialized value is false, return a promise rejected with an InvalidStateError.

3. Let this object's uninitialized value be false.

4. If initDataType is the empty string, return a promise rejected with a newly created TypeError.

5. If initData is an empty array, return a promise rejected with a newly created TypeError.

6. 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 NotSupportedError. String comparison is case-sensitive.

7. Let init data be a copy of the contents of the initData parameter.

8. Let session type be this object's session type.

9. Let promise be a new promise.

10. Run the following steps in parallel:

    1. If the init data is not valid for initDataType, reject promise with a newly created TypeError.

    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 supports multiple entries, the user agent SHOULD remove entries that are not needed by the CDM. The user agent MUST NOT re-order entries within the Initialization Data.

    3. If the preceding step failed, reject promise with a newly created TypeError.

    4. If sanitized init data is empty, reject promise with a NotSupportedError.

    5. Let session id be the empty string.

    6. Let message 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 the sanitized init data is not supported by the cdm, reject promise with a NotSupportedError.

       2. Follow the steps for the value of session type from the following list:

          "temporary"

          Let requested license type be a temporary non-persistable license.

          Note

          The returned license must not be persistable or require persisting information related to it.

          "persistent-usage-record"

          1. Initialize this object's record of key usage as follows.

             • Set the list of key IDs known to the session to an empty list.

             • Set the first decrypt time to null.

             • Set the latest decrypt time to null.

          2. Let requested license type be a non-persistable license that will persist a record of key usage.

          "persistent-license"

          Let requested license type be a persistable license.

       3. Let session id be a unique Session ID string.

          If the result of running the Is persistent session type? algorithm on session type is true, 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 sanitized init data, which is interpreted per initDataType.

          The cdm MUST NOT use any stream-specific data, including media data, not provided via the sanitized init data.

          The cdm SHOULD NOT store session data, including the session ID, at this point. See Session Storage and Persistence.

    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 session id.

    11. Let this object's callable value be true.

    12. Run the Queue a "message" Event algorithm on the session, providing "license-request" and message.

    13. Resolve promise.

        Issue 5

        Issue 19 - Ensure promises returned by methods are fulfilled before event handlers are executed.

11. 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:

1. If the Session Close algorithm has been run on this object, return a promise rejected with an InvalidStateError.

2. If this object's uninitialized value is false, return a promise rejected with an InvalidStateError.

3. Let this object's uninitialized value be false.

4. If sessionId is the empty string, return a promise rejected with a newly created TypeError.

5. If the result of running the Is persistent session type? algorithm on this object's session type is false, return a promise rejected with a newly created TypeError.

6. Let origin be the origin of this object's Document.

7. Let promise be a new promise.

8. Run the following steps in parallel:

   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 preceding step failed, or if sanitized session ID is empty, reject promise with a newly created TypeError.

   3. If there is an unclosed session in this object's Document whose sessionId attribute is sanitized session ID, reject promise with a 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 and abort these steps.

      2. If the stored session's session type is not the same as the current MediaKeySession session type, return a promise rejected with a newly created TypeError.

      3. 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.

      4. If there is an unclosed session in any Document representing the session data, reject promise with a 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.

      5. Load the session data.

      6. 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.

      7. 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 the appropriate error name.

   10. Set the sessionId attribute to sanitized session ID.

   11. Let this object's callable value 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 "status-pending". Once the additional processing for one or more keys has completed, run the Update Key Statuses algorithm again with the actual status(es).

   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.

       Issue 6

       Issue 19 - Ensure promises returned by methods are fulfilled before event handlers are executed.

9. 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:

1. If the Session Close algorithm has been run on this object, return a promise rejected with an InvalidStateError.

2. If this object's callable value is false, return a promise rejected with an InvalidStateError.

3. If the result of running the Is persistent session type? algorithm on this object's session type is false, return a promise rejected with a newly created TypeError.

4. Let promise be a new promise.

5. If this object's session type is "persistent-usage-record" or "persistent-license", run the following steps in parallel:

   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. If any license(s) and/or key(s) are associated with the session:

         1. Destroy the license(s) and/or key(s) associated with the session.

         2. Follow the steps for the value of this object's session type from the following list:

            "persistent-usage-record"

            1. Store this object's record of key usage.

            2. Let message be a message containing or reflecting this object's record of key usage.

            "persistent-license"

            1. Let record of license destruction be a record of license destruction for the license represented by this object.

            2. Store the record of license destruction.

            3. Let message be a message containing or reflecting the record of license destruction.

      2. Run the Update Key Statuses algorithm on the session, providing all key ID(s) in the session along with the "released" MediaKeyStatus value for each.

      3. Run the Update Expiration algorithm on the session, providing NaN.

      4. Let message type be "license-release".

      5. If any of the preceding steps failed, reject promise with a new DOMException whose name is the appropriate error name.

      6. Run the Queue a "message" Event algorithm on the session, providing message type and message.

   3. Resolve promise.

6. 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:

1. If the Session Close algorithm has been run on this object, return a promise rejected with an InvalidStateError.

2. If this object's callable value is false, return a promise rejected with an InvalidStateError.

3. If response is an empty array, return a promise rejected with a newly created TypeError.

4. Let response copy be a copy of the contents of the response parameter.

5. Let promise be a new promise.

6. Run the following steps in parallel:

   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 preceding step failed, or if sanitized response is empty, reject promise with a newly created TypeError.

   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 newly created TypeError.

      2. Process sanitized response, following the stipulation for the first matching condition from the following list:

         If sanitized response contains a license or key(s)

         Note

         This includes an initial license, an updated license, and a license renewal message.

         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

         Process sanitized response, not storing any session data.

         If sessionType is "persistent-usage-record" and sanitized response contains a non-persistable license

         Run the following steps:

         1. Process sanitized response, not storing any session data.

         2. If processing sanitized response results in the addition of keys to the set of known keys, add the key IDs of these keys to this object's record of key usage.

         If sessionType is "persistent-license" and sanitized response contains a persistable license

         Process sanitized response, storing the license/key(s) and related session data contained in sanitized response. Such data MUST be stored such that only the origin of this object's Document can access it.

         Otherwise

         Reject promise with a newly created TypeError.

         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.

         If sanitized response contains a license destruction acknowledgement and sessionType is "persistent-license"

         Run the following steps:

         1. Clear all stored session data associated with this object, including the sessionId and license destruction record.

            Note

            A subsequent call to load() with the value of this object's sessionId would fail because there is no data stored for that session ID.

         2. Run the Update Key Statuses algorithm on the session, providing an empty sequence.

         3. Run the Session Close algorithm on this object.

         If sanitized response contains a key usage record acknowledgement and sessionType is "persistent-usage-record"

         Run the following steps:

         1. Clear all stored session data associated with this object, including the sessionId and the record of key usage.

            Note

            A subsequent call to load() with the value of this object's sessionId would fail because there is no data stored for that session ID.

         2. Run the Update Key Statuses algorithm on the session, providing an empty sequence.

         3. Run the Session Close algorithm on this object.

         Otherwise

         Process sanitized response, not storing any session data.

         Note

         For example, sanitized response may contain information that will be used to generate another message event. In this case, there is no need to verify the contents against the sessionType.

      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 "status-pending". Once the additional processing for one or more keys has completed, run the Update Key Statuses algorithm again with the actual status(es).

      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.

7. Return promise.

6.3 MediaKeyStatusMap Interface

The MediaKeyStatusMap object is a read-only map of key IDs to the current status of the associated key.

A key's status is independent of whether the key is currently being used and of media data.

interface MediaKeyStatusMap {
    iterable<BufferSource,MediaKeyStatus>;
    readonly        attribute unsigned long size;
    boolean        has (BufferSource keyId);
    MediaKeyStatus get (BufferSource keyId);
    void           forEach (ForEachCallback callback);
};

This interface has "entries", "keys", "values" and @@iterator methods brought by iterable.

The value pairs to iterate over are a snapshot of the set of pairs formed from the key ID and associated MediaKeyStatus value for all known keys, sorted by key ID.

callback ForEachCallback = void (BufferSource keyId, MediaKeyStatus status);

enum MediaKeyStatus {
    "usable",
    "expired",
    "released",
    "output-restricted",
    "output-downscaled",
    "status-pending",
    "internal-error"
};

6.4 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",
    "individualization-request"
};

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

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

6.6 Algorithms

6.7 Exceptions

The methods report errors by rejecting the returned promise with a simple exception or a DOMException. The following simple exceptions and 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.

6.8 Session Storage and Persistence

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

If the result of running the Is persistent session type? algorithm on this object's session type is false, 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), records of key usage or proof of license destruction, and the Session ID.

The remainder of this section applies to session types for which the Is persistent session type? algorithm returns true.

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 session using a type for which the Is persistent session type? algorithm returns true 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.

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

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

Some implementations may only support decrypting media data provided via Media Source Extensions [MEDIA-SOURCE]. This is not reflected in the results of calling requestMediaKeySystemAccess().

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:

1. If mediaKeys and the mediaKeys attribute are the same object, return a resolved promise.

2. If this object's attaching media keys value is true, return a promise rejected with an InvalidStateError.

3. Let this object's attaching media keys value be true.

4. Let promise be a new promise.

5. Run the following steps in parallel:

   1. If mediaKeys is not null, the CDM instance represented by mediaKeys 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 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 NotSupportedError.

      2. If the association cannot currently be removed, let this object's attaching media keys value be false and reject promise with an 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 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.

6. Return promise.

7.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;
};

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

7.5 Algorithms

8.1 Identifiers

The use of Distinctive Identifiers by implementations presents a privacy concern. This defines requirements for avoiding or at least mitigating such concerns.

8.2 Support Multiple Keys

Implementations MUST support multiple keys in each MediaKeySession object.

Implementations MUST support seamless switching between keys during playback. This includes both keys in the same MediaKeySession and keys in separate MediaKeySession objects.

8.3 Initialization Data Type Support

8.4 Supported Media

This section defines properties of content (media resources) supported by implementations of this specification.

9.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.

{
  "kids":
    [
     "LwVHf8JLtPrv2GUXFW2v_A",
     "0DdtU9od-Bh5L3xbv0Xf_A"
    ],
  "type":"temporary"
}

{
  "keys":
    [{
      "kty":"oct",
      "k":"tQ0bJVWb6b0KPL6KtZIy_A",
      "kid":"LwVHf8JLtPrv2GUXFW2v_A"
    }],
  'type':"temporary"
}

{
  "kids": [ "LwVHf8JLtPrv2GUXFW2v_A", "0DdtU9od-Bh5L3xbv0Xf_A" ],
  "tfirst" : 1430425323757,
  "tlatest" : 1430425383757
}

{
  "kids":
    [
     "LwVHf8JLtPrv2GUXFW2v_A",
     "0DdtU9od-Bh5L3xbv0Xf_A"
    ]
}

10.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.

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

10.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.

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 contexts to mitigate the potential for Network Attacks.

10.3 Network Attacks

10.4 iframe Attacks

11.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.

11.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.

11.3 Information Leakage

11.4 User Tracking

11.5 Information Stored on User Devices

11.6 Incomplete Clearing of Data

11.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.

11.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.