Encrypted Media Extensions

requestMediaKeySystemAccess() is a policy-controlled feature identified by the string encrypted-media. Its default allowlist is 'self' [PERMISSIONS-POLICY].

WebIDL[Exposed=Window]
partial interface Navigator {
  [SecureContext] Promise<MediaKeySystemAccess> requestMediaKeySystemAccess (
      DOMString keySystem,
      sequence<MediaKeySystemConfiguration> supportedConfigurations);
};

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

The MediaKeysRequirement enumeration is defined as follows:

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

The dictionary MediaKeySystemConfiguration contains the following members:

label of type DOMString, defaulting to ""

An optional label that will be preserved in the MediaKeySystemConfiguration returned from the getConfiguration() method of MediaKeySystemAccess.

initDataTypes of type sequence<DOMString>, defaulting to []

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.

audioCapabilities of type sequence<MediaKeySystemMediaCapability>, defaulting to []

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. An empty list indicates that no audio capabilities are supported. In this case, the videoCapabilities element must not be empty.

videoCapabilities of type sequence<MediaKeySystemMediaCapability>, defaulting to []

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. An empty list indicates that no video capabilities are supported. In this case, the audioCapabilities element must not be empty.

distinctiveIdentifier of type MediaKeysRequirement, defaulting to "optional"

Whether use of a Distinctive Identifier(s) is required.

When this member is "not-allowed", the implementation MUST NOT use Distinctive Identifier(s) or Distinctive Permanent Identifier(s) for any operations associated with any object created from this configuration.

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.

The CDM MUST NOT persist any state related to the application or origin of this object's Document when this member is "not-allowed".

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 member to "required" when calling requestMediaKeySystemAccess().

sessionTypes of type sequence<DOMString>

A list of MediaKeySessionTypes that must be supported. All values must be supported.

If this member is not present [Infra] when the dictionary is passed to requestMediaKeySystemAccess(), the dictionary will be treated as if this member is set to [ "temporary" ].

Implementations SHOULD NOT add members to 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.

WebIDLdictionary MediaKeySystemMediaCapability {
  DOMString contentType = "";
  DOMString? encryptionScheme = null;
  DOMString robustness = "";
};

In order for the capability represented by this object to be considered supported, contentType MUST NOT be the empty string and its entire value, including all codecs, MUST be supported with robustness.

keySystem of type DOMString, readonly

Identifies the Key System being used.

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

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 object being created and initialized from configuration each time this method is called.

   Note

   If encryptionScheme was not given by the application, the accumulated configuration MUST still contain an encryptionScheme field with a value of null, so that polyfills can detect the user agent's support for the field without specifying specific values.

createMediaKeys()

Creates a new MediaKeys object for keySystem.

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 use distinctive identifier be true if the value of configuration's distinctiveIdentifier member is "required" and false otherwise.

   3. Let persistent state allowed be true if the value of configuration's persistentState member is "required" and false otherwise.

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

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

   6. Initialize instance to enable, disable and/or select Key System features using configuration.

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

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

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

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

   11. Resolve promise with media keys.

3. Return promise.

createSession()

Returns a new MediaKeySession object.

Note

The sessionType parameter affects the behavior of the returned object.

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 [WEBIDL] 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. If the implementation does not support MediaKeySession operations in the current state, throw [WEBIDL] an InvalidStateError.

   Note

   Some implementations are unable to execute MediaKeySession algorithms until this MediaKeys object is associated with a media element using setMediaKeys(). This step enables applications to detect this uncommon behavior before attempting to perform such operations.

3. 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 closing or closed value be false.

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

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

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

4. Return session.

getStatusForPolicy()

Returns the MediaKeyStatus for a given MediaKeysPolicy.

WebIDLdictionary MediaKeysPolicy {
    DOMString minHdcpVersion;
};

The MediaKeysPolicy dictionary is an object consisting of only optional properties. Each property represents a policy requirement. A policy is said to be fulfilled if the CDM would allow presentation of decrypted media data based on all of the requirements.

The HDCP Policy is represented by minHdcpVersion. If the system can enable the HDCP version specified or higher, then the policy will result in a MediaKeyStatus of "usable". The [EME-HDCP-VERSION-REGISTRY] provides the mapping from minHdcpVersion values to HDCP specifications.

Note

The determination of HDCP status should be done in the same way that the CDM would enforce such a restriction during playback. In this way, application developers can get a reasonable hint to allow them to optimize what content they fetch to start playback.

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

1. If policy has no present dictionary members, return a promise rejected with a newly created TypeError.

2. Let promise be a new promise.

3. Queue a task to run the following steps:

   1. For each dictionary member of policy, run the following steps:

      1. If the key is not a valid MediaKeysPolicy member or the type of the value is incorrect, then reject promise with TypeError and abort these steps.

   2. For each dictionary member of policy, run the following steps:

      1. If the CDM cannot determine the MediaKeyStatus for the dictionary member, then reject promise with NotSupportedError and abort these steps.

   3. For each dictionary member of policy, run the following steps:

      1. If the CDM would block presentation of decrypted media data for the dictionary member, then resolve promise with "output-restricted".

   4. Resolve promise with "usable".

4. Return promise.

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 avoid the additional round trip should the CDM request it. It is intended as an optimization, and applications are not required to use it.

The server certificate contents are Key System-specific. It MUST NOT contain executable code.

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

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

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

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. Let sanitized certificate be a validated and/or sanitized version of certificate.

      Note

      The user agent should thoroughly validate the certificate 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. Use this object's cdm instance to process sanitized certificate.

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

   4. Resolve promise with true.

6. Return promise.

This section describes general requirements related to storage and persistence.

If a MediaKeys object's persistent state allowed value is false then the object's cdm instance SHALL NOT persist state or access previously persisted state as a result of operations on this object or any sessions that it creates.

If a MediaKeys object's persistent state allowed value is true then the object's cdm instance MAY persist state or access previously persisted state as a result of operations on this object or any sessions that it creates.

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 browsing profile; other browsing profiles, user agents, and applications MUST NOT be able to access the stored data. See Information Stored on User Devices.

See 10. Security and 11. Privacy for additional considerations when supporting persistent storage.

sessionId of type DOMString, readonly

The Session ID for this object and the associated key(s) or license(s).

expiration of type unrestricted double, readonly

The expiration time for all key(s) in the session, or NaN if no such time exists or if the license explicitly never expires, 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.

closed of type Promise<MediaKeySessionClosedReason>, readonly

Signals when the object becomes closed as a result of the Session Closed algorithm being run. This promise can only be fulfilled and is never rejected.

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 MUST NOT ever be inconsistent or partially updated, but it may change between accesses if the event loop spins in between the 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".

Note

Some older platforms may contain Key System implementations that do not expose key IDs, making it impossible to provide a compliant user agent implementation. To maximize interoperability, user agent implementations exposing such CDMs SHOULD implement this member as follows: Whenever a non-empty list is appropriate, such as when the key session represented by this object may contain key(s), populate the map with a single pair containing the one-byte key ID 0 and the MediaKeyStatus most appropriate for the aggregated status of this object.

onkeystatuseschange of type EventHandler

Event handler for the keystatuseschange event.

onmessage of type EventHandler

Event handler for the message event.

generateRequest()

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

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

1. If this object's closing or closed value is true, 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 message type be null.

    8. Let cdm be the CDM instance represented by this object's cdm instance value.

    9. 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-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. If a license request for the requested license type can be generated based on the sanitized init data:

          1. Let message be a license request for the requested license type generated based on the sanitized init data 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.

          2. Let message type be "license-request".

          Otherwise:

          1. Let message be the request that needs to be processed before a license request request for the requested license type can be generated based on the sanitized init data.

             In a subsequent call to update() the CDM MUST generate a license request for the requested license type based on the sanitized init data, which is interpreted per initDataType.

          2. Let message type reflect the type of message, either "license-request" or "individualization-request".

    10. Queue a task to run the following steps:

        1. If any of the preceding steps failed due to a lack of resources, reject promise with QuotaExceededError.

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

        3. Set the sessionId attribute to session id.

        4. Set this object's callable value to true.

        5. Resolve promise with undefined.

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

11. Return promise.

load()

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

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

1. If this object's closing or closed value is true, 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 are reasonable (e.g., not longer than tens of characters and alphanumeric).

   2. If the preceding step failed, or if sanitized session ID is empty, reject promise with a newly created TypeError.

   3. If there is a MediaKeySession object that is not closed 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, reject promise 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 a MediaKeySession object that is not closed in any Document and that represents 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 that expiration time.

      7. If a message needs to be sent, execute the following steps:

         1. Let message be a message generated based on the session data.

         2. Let message type be the appropriate MediaKeyMessageType for the message.

   9. Queue a task to run the following steps:

      1. If any of the preceding steps failed, reject promise with the appropriate error name.

      2. Set the sessionId attribute to sanitized session ID.

      3. Set this object's callable value to true.

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

      5. Run the Update Expiration algorithm on the session, providing expiration time.

      6. Resolve promise with true.

      7. If message is not null, run the Queue a "message" Event algorithm on the session, providing message type and message.

9. Return promise.

update()

Provides messages, including licenses, to the CDM.

The response parameter contains a message to be provided to the CDM. The contents are Key System-specific. It MUST NOT contain executable code.

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

1. If this object's closing or closed value is true, 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 session closed be false.

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

         State information, including keys, for each session MUST be stored in such a way that closing one session does not affect the observable state in other session(s), even if they contain overlapping key IDs.

         Note

         When sanitized response contains key(s) and/or related data, cdm will likely store (in memory) the key and related data indexed by key ID.

         Note

         The replacement algorithm within a session is Key System-dependent.

         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 (e.g., adaptive streams, various audio and video tracks) using different keys.

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

         Run the following steps:

         1. Close the key session and clear all stored session data associated with this object, including the sessionId and record of license destruction.

            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. Set session closed to true.

         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 a message needs to be sent, execute the following steps:

         1. Let message be that message.

         2. Let message type be the appropriate MediaKeyMessageType for the message.

   8. Queue a task to run the following steps:

      1. If session closed is true:

         Run the Session Closed algorithm on this object with reason "release-acknowledged".

         Otherwise:

         Run the following steps:

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

         2. If the expiration time for the session changed, run the Update Expiration algorithm on the session, providing the new expiration time.

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

         4. If message is not null, run the Queue a "message" Event algorithm on the session, providing message type and message.

      2. Resolve promise with undefined.

7. Return promise.

close()

Indicates that the application no longer needs the session and the CDM should release any resources associated with the session 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 with "closed-by-application" when the session is closed.

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

1. If this object's closing or closed value is true, return a promise resolved with undefined.

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

3. Let promise be a new promise.

4. Set this object's closing or closed value to true.

5. Run the following steps in parallel:

   1. Let cdm be the CDM instance represented by this object's cdm instance value.

   2. Use cdm to close the key session associated with this object.

      Note

      Closing the key session results in the destruction of any license(s) and key(s) that have not been explicitly stored.

   3. Queue a task to run the following steps:

      1. Resolve promise with undefined.

      2. Run the Session Closed algorithm on this object with reason "closed-by-application".

6. Return promise.

remove()

Removes all license(s) and key(s) associated with the session. For persistent session types, other session data will be cleared as defined for each session type once a release message acknowledgment is processed by update().

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

1. If this object's closing or closed value is true, return a promise rejected with an InvalidStateError.

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. Let message be null.

   3. Let message type be null.

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

            Note

            This implies destruction of the license(s) and/or keys(s) whether they are in memory, persistent store or both.

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

            "temporary"

            Continue with the following steps.

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

   5. Queue a task to run the following steps:

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

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

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

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

      5. Resolve promise with undefined.

      6. If message is not null, run the Queue a "message" Event algorithm on the session, providing message type and message.

5. Return promise.

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.

WebIDL[Exposed=Window, SecureContext] interface MediaKeyStatusMap {
  iterable<BufferSource,MediaKeyStatus>;
  readonly attribute unsigned long size;
  boolean has (BufferSource keyId);
  (MediaKeyStatus or undefined) get (BufferSource keyId);
};

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

The MediaKeyStatus enumeration is defined as follows:

The MediaKeyMessageEvent object is used for the message event.

WebIDLenum MediaKeyMessageType {
  "license-request",
  "license-renewal",
  "license-release",
  "individualization-request"
};

The MediaKeyMessageType is defined as follows:

WebIDL[Exposed=Window, SecureContext]
interface MediaKeyMessageEvent : Event {
  constructor(DOMString type, MediaKeyMessageEventInit eventInitDict);
  readonly attribute MediaKeyMessageType messageType;
  readonly attribute ArrayBuffer         message;
};

WebIDLdictionary MediaKeyMessageEventInit : EventInit {
  required MediaKeyMessageType messageType;
  required ArrayBuffer         message;
};

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

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

The following requirements apply in addition to those in Storage and Persistence.

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), record(s) 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.

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.

All data associated with a session MUST be cleared when the session is cleared, such as in update() when processing a record of license destruction acknowledgement. See Persistent Data.

The CDM MUST ensure that data for a given session is only present in one MediaKeySession object that is not closed 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 if all objects that have ever represented it are closed.

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 by first initiating the removal process using remove() and then ensuring that the removal process, which may involve message exchange(s), successfully completes. The CDM MAY also remove sessions as appropriate, but applications SHOULD NOT rely on this.

See 10. Security and 11. Privacy for additional considerations when supporting persistent storage.

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. It MUST be supported by all HTMLMediaElements as both a content attribute and an IDL attribute.

onwaitingforkey of type EventHandler

Event handler for the waitingforkey event. It MUST be supported by all HTMLMediaElements as both a content attribute and an IDL attribute.

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.

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

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

2. If mediaKeys and the mediaKeys attribute are the same object, return a promise resolved with undefined.

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 all the following conditions hold:

      • mediaKeys is not null,

      • the CDM instance represented by mediaKeys is already in use by another media element

      • the user agent is unable to use it with this element

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

   4. Set the mediaKeys attribute to mediaKeys.

   5. Let this object's attaching media keys value be false.

   6. Resolve promise with undefined.

6. Return promise.

The MediaEncryptedEvent object is used for the encrypted event.

WebIDL[Exposed=Window]
interface MediaEncryptedEvent : Event {
    constructor(DOMString type, optional MediaEncryptedEventInit eventInitDict = {});
    readonly        attribute DOMString    initDataType;
    readonly        attribute ArrayBuffer? initData;
};

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

User agent implementers MUST ensure that CDMs do not access any information, storage or system capabilities that are not reasonably required for playback of protected media using the features of this specification. Specifically, the CDM SHALL NOT:

• Access network resources, either local or remote, except via the user agent as explicitly permitted by this specification.

• Access storage (e.g., disk or memory), except where reasonably required for playback of protected media using the features of this specification.

• Access user data other than CDM state and persistent data.

• Access hardware components or devices, except where reasonably required for playback of protected media using the features of this specification.

User Agent implementers may use various techniques to meet the above requirements. For example, a User Agent implementer also implementing their own CDM may include the above as design requirements for that component. A User Agent implementer making use of a third party CDM may ensure that it executes in a constrained environment (e.g., "sandbox") without access to the prohibited information and components.

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 described in Direct Individualization 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.

Persistent Data includes all data stored by the CDM, or by the User Agent on behalf of the CDM, that exists after the destruction of the MediaKeys object. Specifically, it includes any identifiers (including Distinctive Identifier(s)), licenses, keys, key IDs, or records of license destruction stored by the CDM or by the User Agent on behalf of the CDM.

Values exposed to or inferable by, such as via its use by the CDM, the application could be used to identify the client or user, regardless of whether they are designed to be identifiers. This section defines requirements for avoiding or at least mitigating such concerns. There are additional requirements for Identifiers.

The use of identifiers, especially Distinctive Identifier(s) or Distinctive Permanent Identifier(s), by implementations presents a privacy concern. This section defines requirements for avoiding or at least mitigating such concerns. The requirements for Values Exposed to the Application also apply to identifiers exposed to the application.

Identifiers, especially Distinctive Identifiers, are sometimes generated or obtained via a process called individualization or provisioning. The resulting identifier(s) MUST be non-associable by applications and use of them MUST only be exposed to a single origin from a single profile. This process MAY be performed multiple times, such as after identifier(s) are cleared.

This process MUST be performed either directly by the user agent or through the application. The mechanisms, flow, and restrictions for the two types of individualization are different, as described in the following sections. Which method is used depends on the CDM implementation and application of the requirements of this specification, especially those below.

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.

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

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" ]
}

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

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.

User Agents are responsible for providing users with a secure way to browse the web. This responsibility applies to any functionality used by User Agents, including functionalities 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.

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.

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.

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

The APIs defined in this specification are only supported on secure origins, protecting information discussed in previous sections. Identifiers are additionally encrypted as specified in Encrypt Identifiers.

Applications, including the servers they use, SHOULD use secure transport for all traffic involving or containing data or messages from the CDM, including but is not limited to 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.