加密媒体扩展

requestMediaKeySystemAccess() 是由字符串 encrypted-media 标识的 策略控制功能。其 默认允许列表 为 'self' [PERMISSIONS-POLICY].

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

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

MediaKeysRequirement 枚举定义如下：

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

字典 MediaKeySystemConfiguration 包含以下成员：

label 类型为 DOMString，默认值为 ""

一个可选标签，会在 MediaKeySystemConfiguration 通过 getConfiguration() 方法由 MediaKeySystemAccess 返回时保留。

initDataTypes 类型为 sequence<DOMString>， 默认值为 []

支持的 初始化数据类型（Initialization Data Type） 名称列表。此对象的 初始化数据类型 能力被视为支持，如果列表为空或包含一个或多个与所有其它成员（由算法决定）均兼容的值。序列中的值 MUST 不得为空字符串。

audioCapabilities 类型为 sequence<MediaKeySystemMediaCapability>， 默认值为 []

支持的音频类型与能力对的列表。该对象的音频能力被视为支持，如果列表为空或包含一个或多个与所有其它成员（由算法决定）均兼容的值。当值间冲突时，优先选择前面的值。空列表表示不支持任何音频能力，此时 videoCapabilities 元素不能为空。

videoCapabilities 类型为 sequence<MediaKeySystemMediaCapability>， 默认值为 []

支持的视频类型与能力对的列表。该对象的视频能力被视为支持，如果列表为空或包含一个或多个与所有其它成员（由算法决定）均兼容的值。当值间冲突时，优先选择前面的值。空列表表示不支持任何视频能力，此时 audioCapabilities 元素不能为空。

distinctiveIdentifier 类型为 MediaKeysRequirement， 默认值为 "optional"

是否要求使用 区别性标识符。

当该成员为 "not-allowed" 时，实现 MUST NOT 在从此配置创建的任何对象的任何操作中 使用区别性标识符或区别性永久标识符。

persistentState 类型为 MediaKeysRequirement，默认值为 "optional"

是否要求具备持久化状态的能力，包括会话数据及其它类型的状态。

当该成员为 "not-allowed" 时，CDM MUST NOT 持久化与应用或该对象的 origin 相关的任何状态。

注

就此成员而言，持久化状态不包括由 Key System 实现控制的持久化唯一标识符（区别性标识符）。distinctiveIdentifier 独立反映该要求。

当不支持持久化状态时，仅允许创建 "temporary" 会话。

注

对于 "temporary" 会话，是否需要及能否存储状态取决于 Key System 的具体实现，并可能随所使用的功能而异。

注

如果应用打算创建非 "temporary" 会话，应在调用 requestMediaKeySystemAccess() 时，将该成员设置为 "required"。

sessionTypes 类型为 sequence<DOMString>

必须支持的 MediaKeySessionType 列表。所有值都必须被支持。

如果此成员在字典传递给 requestMediaKeySystemAccess() 时 不存在 [Infra]，则该字典会被视为已设置为 [ "temporary" ]。

实现 SHOULD NOT 向该字典添加成员。如确需添加，MUST 类型为 MediaKeysRequirement，并且强烈建议（RECOMMENDED）默认值为 "optional"，以支持最广泛的应用与客户端组合。

此字典 MUST NOT 用于向 CDM 传递状态或数据。

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

为使该对象表示的能力被视为受支持，contentType MUST NOT 为空字符串，且其全部值（包括所有 codec）MUST 与 robustness 一起被支持。

keySystem 类型为 DOMString，只读

标识正在使用的 Key System。

getConfiguration()

返回由 requestMediaKeySystemAccess() 算法选择的受支持配置选项组合。

返回的对象是第一个可满足的 MediaKeySystemConfiguration 配置（加上任何隐含默认值）的非严格子集，来自于传递给 requestMediaKeySystemAccess() 的参数，该参数返回了被解析为本对象的 promise。它不包含未在该单一配置中指定的能力（除隐含默认值外），因此可能不反映 Key System 实现的所有能力。配置中的所有值都可以任意组合使用。类型为 MediaKeysRequirement 的成员反映该能力是否在任何组合中是必需的。它们不会有值 "optional"。

调用此方法时，用户代理 MUST 运行以下步骤：

1. 返回此对象的 configuration 值。

   注

   每次调用该方法都会创建并从 configuration 初始化一个新对象。

   注

   如果应用未指定 encryptionScheme，累计的 configuration MUST 仍包含 encryptionScheme 字段且值为 null，这样 polyfill 可以检测用户代理对该字段的支持，无需指定具体值。

createMediaKeys()

为 keySystem 创建一个新的 MediaKeys 对象。

调用此方法时，用户代理 MUST 运行以下步骤：

1. 令 promise 为一个新的 promise。

2. 并行运行下列步骤：

   1. 令 configuration 为此对象的 configuration 值。

   2. 若 configuration 的 distinctiveIdentifier 成员值为 "required"，则 use distinctive identifier 为 true，否则为 false。

   3. 若 configuration 的 persistentState 成员值为 "required"，则 persistent state allowed 为 true，否则为 false。

   4. 如有必要，加载并初始化由此对象的 cdm implementation 值表示的 Key System 实现。

   5. 令 instance 为此对象 cdm implementation 值表示的 Key System 实现的新实例。

   6. 用 configuration 初始化 instance，以启用、禁用和/或选择 Key System 功能。

   7. 如果 use distinctive identifier 为 false，则禁止 instance 使用区别性标识符或区别性永久标识符。

   8. 如果 persistent state allowed 为 false，则禁止 instance 持久化与应用或本对象 origin 相关的任何状态。

   9. 如果上述任何步骤失败，则以合适的 error name 拒绝 promise，并创建新的 DOMException。

   10. 令 media keys 为一个新的 MediaKeys 对象，并按如下方式初始化：

       1. use distinctive identifier 值为 use distinctive identifier。

       2. persistent state allowed 值为 persistent state allowed。

       3. supported session types 值为 configuration 的 sessionTypes 成员的值。

       4. cdm implementation 值为此对象的 cdm implementation 值。

       5. cdm instance 值为 instance。

   11. 用 media keys 解析 promise。

3. 返回 promise。

createSession()

返回一个新的 MediaKeySession 对象。

注

sessionType 参数会影响返回对象的行为。

调用此方法时，用户代理 MUST 运行以下步骤：

1. 如果此对象的 supported session types 值不包含 sessionType，则 抛出 [WEBIDL] 一个 NotSupportedError。

   注

   对于那些 Is persistent session type? 算法返回 true 的 sessionType，如果此对象的 persistent state allowed 值为 false，则会失败。

2. 如果实现不支持在当前状态下执行 MediaKeySession 操作，则 抛出 [WEBIDL] 一个 InvalidStateError。

   注

   有些实现直到该 MediaKeys 对象通过 setMediaKeys() 与媒体元素关联后，才可执行 MediaKeySession 算法。此步骤使应用在尝试执行此类操作之前能够检测到这种不常见的行为。

3. 令 session 为一个新的 MediaKeySession 对象，并按如下方式初始化：

   1. 令 sessionId 属性为一个空字符串。

   2. 令 expiration 属性为 NaN。

   3. 令 closed 属性 为一个新的 promise。

   4. 令 key status 为一个新的空的 MediaKeyStatusMap 对象，并按如下方式初始化：

      1. 令 size 属性为 0。

   5. 令 session type 值为 sessionType。

   6. 令 uninitialized 值为 true。

   7. 令 callable 值为 false。

   8. 令 closing or closed 值为 false。

   9. 令 use distinctive identifier 值为此对象的 use distinctive identifier 值。

   10. 令 cdm implementation 值为此对象的 cdm implementation。

   11. 令 cdm instance 值为此对象的 cdm instance。

4. 返回 session。

getStatusForPolicy()

返回给定 MediaKeyStatus 对应于指定的 MediaKeysPolicy。

WebIDLdictionary MediaKeysPolicy {
    DOMString minHdcpVersion;
};

MediaKeysPolicy 字典仅由可选属性组成。每个属性表示一项策略要求。如果 CDM 会基于所有这些要求允许呈现解密后的媒体数据，则该策略被认为已满足。

HDCP 策略由 minHdcpVersion 表示。如果系统能够启用所指定或更高版本的 HDCP，则该策略将导致返回的 MediaKeyStatus 为 "usable"。[EME-HDCP-VERSION-REGISTRY] 提供了从 minHdcpVersion 值到 HDCP 规范的映射。

注

HDCP 状态的判定应以 CDM 在播放期间执行此类限制时的方式一致。通过这种方式，应用开发者可以获得合理的提示，以便优化他们为开始播放而获取的内容。

调用此方法时，用户代理 MUST 运行以下步骤：

1. If policy 没有任何 存在的 字典成员，则返回一个以新建 TypeError 被拒绝的 promise。

2. 令 promise 为一个新的 promise。

3. 排队一个任务 来运行以下步骤：

   1. 对 policy 的每个 字典成员 运行下列步骤：

      1. 如果键不是有效的 MediaKeysPolicy 成员或值的类型不正确，则以 TypeError 拒绝 promise 并中止这些步骤。

   2. 对 policy 的每个 字典成员 运行下列步骤：

      1. 如果 CDM 无法确定该字典成员对应的 MediaKeyStatus，则以 NotSupportedError 拒绝 promise 并中止这些步骤。

   3. 对 policy 的每个 字典成员 运行下列步骤：

      1. 如果 CDM 会阻止就该字典成员呈现解密后的媒体数据，则用 "output-restricted" 解析 promise。

   4. 用 "usable" 解析 promise。

4. 返回 promise。

setServerCertificate()

提供一个服务器证书，用于加密发送到许可证服务器的消息。

使用此类证书的 Key Systems 必须也支持通过 排队 "message" 事件 算法从服务器请求该证书。

注

此方法允许应用主动向支持该功能的实现提供服务器证书，以避免当 CDM 请求证书时额外的往返。该方法用于优化，应用不必一定使用它。

服务器证书内容为 Key System 特定内容。它 MUST NOT 包含可执行代码。

调用此方法时，用户代理 MUST 运行以下步骤：

1. 如果此对象的 cdm implementation 值所表示的 Key System 实现不支持服务器证书，则返回一个解析为 false 的 promise。

2. 如果 serverCertificate 是空数组，则返回一个以新建 TypeError 被拒绝的 promise。

3. 令 certificate 为 serverCertificate 参数内容的副本。

4. 令 promise 为一个新的 promise。

5. 并行运行下列步骤：

   1. 令 sanitized certificate 为对 certificate 的验证和/或清理后的版本。

      注

      用户代理应在将证书传递给 CDM 之前对其进行彻底验证。此过程可能包括验证字段值在合理范围内、剥离无关数据或字段、预解析、对其进行清理，和/或生成完全清理后的版本。用户代理应检查字段的长度和值是否合理。未知字段应被拒绝或移除。

   2. 使用此对象的 cdm instance 来处理 sanitized certificate。

   3. 如果前一步失败，则以合适的 DOMException（其 name 为相应的 错误名）拒绝 promise。

   4. 用 true 解析 promise。

6. 返回 promise。

本节描述与存储和持久化相关的一般要求。

如果一个 MediaKeys 对象的 persistent state allowed 值为 false，则该对象的 cdm instance 不得（SHALL NOT） 因该对象或其创建的任何会话的操作而持久化状态或访问先前持久化的状态。

如果一个 MediaKeys 对象的 persistent state allowed 值为 true，则该对象的 cdm instance 可以（MAY） 因该对象或其创建的任何会话的操作而持久化状态或访问先前持久化的状态。

持久化的数据 必须（MUST） 始终以仅由该对象的 origin 的文档访问的方式存储。此外，该数据 必须（MUST） 仅能被当前的 浏览配置文件 访问；其它浏览配置文件、用户代理和应用不得访问存储的数据。参见 用户设备上存储的信息。

在支持持久化存储时，请参阅 10. 安全 和 11. 隐私 以获取更多考虑事项。

sessionId 类型为 DOMString, 只读

此对象及其关联的 key(s) 或 license(s) 的 Session ID。

expiration 类型为 unrestricted double, 只读

会话中所有 key(s) 的 到期时间，如果不存在此类时间或 CDM 明确指示许可证永不过期，则为 NaN，由 CDM 决定。

注

此值在会话生命周期内 可能（MAY） 发生变化，例如某个操作触发了窗口开始时间。

closed 类型为 Promise<MediaKeySessionClosedReason>, 只读

当因运行 Session Closed 算法而导致该对象被视为 closed 时发出信号。此 promise 只能被 fulfilled，不会被 rejected。

keyStatuses 类型为 MediaKeyStatusMap, 只读

对只读映射的引用，该映射将 key IDs（对会话已知）映射到关联密钥的当前状态。每个条目 必须（MUST） 具有唯一的 key ID。

注

映射条目及其值可能在事件循环运行时被更新。映射 不得（MUST NOT） 出现不一致或部分更新，但在两次访问之间如果事件循环运行过，映射可能发生变化。Key IDs 可能因调用 load() 或 update() 而被添加。Key IDs 可能因调用 update() 并移除对现有密钥的知识（或用新的一组密钥替换现有集合）而被移除。Key IDs 不得（MUST NOT） 因变得不可用（例如到期）而被移除。相反，此类密钥 必须（MUST） 被赋予适当的状态，例如 "expired"。

注

某些旧平台上的 Key System 实现可能不暴露 key IDs，从而无法提供完全符合规范的用户代理实现。为了最大化互操作性，暴露此类 CDMs 的用户代理实现 应（SHOULD） 如下实现此成员：每当应有非空列表（例如该对象表示的 key session 可能包含 key(s) 时），用一对条目填充映射，条目使用单字节 key ID 0 和最适合该对象聚合状态的 MediaKeyStatus。

onkeystatuseschange 类型为 EventHandler

用于处理 keystatuseschange 事件的事件处理器。

onmessage 类型为 EventHandler

用于处理 message 事件的事件处理器。

generateRequest()

基于 initData 生成许可证请求。如果算法成功并且 promise 被解析，则类型为 "license-request" 或 "individualization-request" 的 message 将始终被排入队列。

当调用此方法时，用户代理 MUST 运行以下步骤：

1. 如果此对象的 closing or closed 值为 true，则返回一个以 InvalidStateError 拒绝的 promise。

2. 如果此对象的 uninitialized 值为 false，则返回一个以 InvalidStateError 拒绝的 promise。

3. 将此对象的 uninitialized 值设为 false。

4. 如果 initDataType 是空字符串，则返回一个以新建的 TypeError 拒绝的 promise。

5. 如果 initData 是空数组，则返回一个以新建的 TypeError 拒绝的 promise。

6. 如果此对象的 cdm implementation 值所表示的 Key System 实现不支持将 initDataType 作为一种 Initialization Data Type，则返回一个以 NotSupportedError 拒绝的 promise。字符串比较区分大小写。

7. 令 init data 为 initData 参数内容的副本。

8. 令 session type 为此对象的 session type。

9. 令 promise 为一个新的 promise。

10. 并行运行下列步骤：

    1. 如果 init data 对于 initDataType 无效，则以新建的 TypeError 拒绝 promise。

    2. 令 sanitized init data 为经验证和清理后的 init data 版本。

       用户代理 MUST 在将 Initialization Data 传递给 CDM 之前对其进行彻底验证。这包括验证字段的长度和值是否合理、验证值是否在合理范围内，以及剥离无关、不支持或未知的数据或字段。建议用户代理对 Initialization Data 进行预解析、清理和/或生成完全清理后的版本。如果 initDataType 指定的 Initialization Data 格式支持多条目，用户代理 SHOULD 移除 CDM 不需要的条目。用户代理 MUST NOT 重新排序 Initialization Data 中的条目。

    3. 如果前一步失败，则以新建的 TypeError 拒绝 promise。

    4. 如果 sanitized init data 为空，则以 NotSupportedError 拒绝 promise。

    5. 令 session id 为空字符串。

    6. 令 message 为 null。

    7. 令 message type 为 null。

    8. 令 cdm 为由此对象的 cdm instance 值所表示的 CDM 实例。

    9. 使用 cdm 执行下列步骤：

       1. 如果 sanitized init data 不被 cdm 支持，则以 NotSupportedError 拒绝 promise。

       2. 按下列列表中与 session type 值相对应的条目执行步骤：

          "temporary"

          将 requested license type 设为一个临时的不可持久化的许可证。

          注

          返回的许可证不得为可持久化的，也不得要求持久化与其相关的信息。

          "persistent-license"

          将 requested license type 设为可持久化的许可证。

       3. 令 session id 为一个唯一的 Session ID 字符串。

          如果对 session type 运行 Is persistent session type? 算法的结果为 true，则该 ID MUST 在此对象的 origin 范围内随时间保持唯一，包括跨越不同的 Documents 和浏览会话。

       4. 如果可基于 sanitized init data 生成针对 requested license type 的许可证请求：

          1. 令 message 为基于按照 initDataType 解释的 sanitized init data 所生成的、用于 requested license type 的许可证请求。

             cdm MUST NOT 使用任何流特定数据，包括未通过 sanitized init data 提供的 media data。

             cdm SHOULD NOT 在此时存储会话数据，包括会话 ID。参见 会话存储与持久化。

          2. 令 message type 为 "license-request"。

          否则：

          1. 令 message 为在生成可基于 sanitized init data 的 requested license type 许可证请求之前需要被处理的请求。

             在随后对 update() 的调用中，CDM MUST 基于按照 initDataType 解释的 sanitized init data 生成针对 requested license type 的许可证请求。

          2. 令 message type 表示 message 的类型，为 "license-request" 或 "individualization-request"。

    10. 排队一个任务（Queue a task） 来运行下列步骤：

        1. 如果前述任何步骤因资源短缺而失败，则以 QuotaExceededError 拒绝 promise。

        2. 如果前述任何步骤因其它原因失败，则以一个新的 DOMException（其 name 为相应的 error name） 拒绝 promise。

        3. 将 sessionId 属性设为 session id。

        4. 将此对象的 callable 值设为 true。

        5. 用 undefined 解析 promise。

        6. 在 session 上运行 Queue a "message" Event 算法，提供 message type 和 message。

11. 返回 promise。

load()

将为指定会话存储的数据加载到此对象中。

当调用此方法时，用户代理 MUST 运行以下步骤：

1. 如果此对象的 closing or closed 值为 true，则返回一个以 InvalidStateError 拒绝的 promise。

2. 如果此对象的 uninitialized 值为 false，则返回一个以 InvalidStateError 拒绝的 promise。

3. 将此对象的 uninitialized 值设为 false。

4. 如果 sessionId 是空字符串，则返回一个以新建的 TypeError 拒绝的 promise。

5. 如果对本对象的 session type 运行 Is persistent session type? 算法的结果为 false，则返回一个以新建的 TypeError 拒绝的 promise。

6. 令 origin 为此对象的 origin。

7. 令 promise 为一个新的 promise。

8. 并行运行下列步骤：

   1. 令 sanitized session ID 为 sessionId 的经验证和/或清理后的版本。

      注

      用户代理在将 sessionId 值传递给 CDM 之前应对其进行彻底验证。至少应检查长度和值是否合理（例如，不超过几十个字符且为字母数字）。

   2. 如果前一步失败，或 sanitized session ID 为空，则以新建的 TypeError 拒绝 promise。

   3. 如果在本对象的 Document 中存在一个尚未被 closed 的 MediaKeySession 对象，且其 sessionId 属性等于 sanitized session ID，则以 QuotaExceededError 拒绝 promise。

      注

      换言之，如果在此浏览上下文中已存在一个针对该 sanitized session ID 的未关闭会话（不论类型），则不要创建新会话。

   4. 令 expiration time 为 NaN。

   5. 令 message 为 null。

   6. 令 message type 为 null。

   7. 令 cdm 为由此对象的 cdm instance 值所表示的 CDM 实例。

   8. 使用 cdm 执行下列步骤：

      1. 如果在 origin 中不存在针对 sanitized session ID 的存储数据，则以 false 解析 promise 并中止这些步骤。

      2. 如果存储的会话的 session type 与当前本对象的 MediaKeySession 的 session type 不同，则以新建的 TypeError 拒绝 promise。

      3. 令 session data 为在 origin 下为 sanitized session ID 存储的数据。此数据 MUST NOT 包含来自其它 origin 的数据或与 origin 无关的数据。

      4. 如果存在一个在任一 Document 中尚未被 closed 且表示该 session data 的 MediaKeySession 对象，则以 QuotaExceededError 拒绝 promise。

         注

         换言之，如果在任何浏览上下文中已存在针对该 sanitized session ID 的未关闭持久会话，则不要创建新会话。

      5. 加载 session data。

      6. 如果 session data 指示了该会话的某个 expiration time，则将 expiration time 设为该到期时间。

      7. 如果需要发送消息，则执行下列步骤：

         1. 令 message 为基于 session data 生成的消息。

         2. 令 message type 为该消息的适当 MediaKeyMessageType。

   9. 排队一个任务（Queue a task） 来运行下列步骤：

      1. 如果前述任何步骤失败，则以适当的 error name 拒绝 promise。

      2. 将 sessionId 属性设为 sanitized session ID。

      3. 将此对象的 callable 值设为 true。

      4. 如果已加载的会话包含有关任何密钥的信息（存在 known keys），则对 session 运行 Update Key Statuses 算法，提供每个密钥的 key ID 及相应的 MediaKeyStatus。

         如果确定某密钥的状态需要额外处理，可使用 "status-pending"。一旦对一个或多个密钥的额外处理完成，再次运行 Update Key Statuses 算法并提供实际状态。

      5. 在 session 上运行 Update Expiration 算法，提供 expiration time。

      6. 用 true 解析 promise。

      7. 如果 message 非 null，则在 session 上运行 Queue a "message" Event 算法，提供 message type 和 message。

9. 返回 promise。

update()

向 CDM 提供消息（包括许可证）。

response 参数包含要提供给 CDM 的消息。其内容依赖于 Key System，且 MUST NOT 包含可执行代码。

当调用此方法时，用户代理 MUST 运行以下步骤：

1. 如果此对象的 closing or closed 值为 true，则返回一个以 InvalidStateError 拒绝的 promise。

2. 如果此对象的 callable 值为 false，则返回一个以 InvalidStateError 拒绝的 promise。

3. 如果 response 是空数组，则返回一个以新建的 TypeError 拒绝的 promise。

4. 令 response copy 为 response 参数内容的副本。

5. 令 promise 为一个新的 promise。

6. 并行运行下列步骤：

   1. 令 sanitized response 为对 response copy 经验证和/或清理后的版本。

      注

      用户代理在将响应传递给 CDM 之前应对其进行彻底验证。这可能包括验证字段值在合理范围内、剥离无关数据或字段、预解析、清理和/或生成完全清理后的版本。用户代理应检查字段的长度和值是否合理。未知字段应被拒绝或移除。

   2. 如果前一步失败，或 sanitized response 为空，则以新建的 TypeError 拒绝 promise。

   3. 令 message 为 null。

   4. 令 message type 为 null。

   5. 令 session closed 为 false。

   6. 令 cdm 为由此对象的 cdm instance 值所表示的 CDM 实例。

   7. 使用 cdm 执行下列步骤：

      1. 如果 sanitized response 的格式在任何方面无效，则以新建的 TypeError 拒绝 promise。

      2. 处理 sanitized response，并按下列列表中首个匹配条件的规定执行：

         如果 sanitized response 包含许可证或密钥

         注

         这包括初始许可证、更新许可证以及许可证续订消息。

         处理 sanitized response，并按下列列表中首个匹配条件的规定执行：

         如果 sessionType 为 "temporary" 且 sanitized response 未指定应存储其包含的会话数据（包括任何许可证、密钥或类似会话数据）

         处理 sanitized response，但不存储任何会话数据。

         如果 sessionType 为 "persistent-license" 且 sanitized response 包含可持久化的许可证

         处理 sanitized response，并存储 sanitized response 中包含的许可证/密钥及相关会话数据。此类数据 MUST 以仅能由此对象的 origin 访问的方式存储。

         否则

         以新建的 TypeError 拒绝 promise。

         另见 会话存储与持久化。

         每个会话的状态信息（包括密钥） MUST 以这样一种方式存储：关闭一个会话不会影响其它会话中可观察到的状态，即使这些会话包含重叠的 key ID。

         注

         当 sanitized response 包含密钥和/或相关数据时，cdm 很可能在内存中按 key ID 存储该密钥和相关数据。

         注

         会话内部的替换算法依赖于 Key System。

         注

         建议 CDM 实现支持每个 MediaKeySession 对象的标准且合理的最小密钥数目（包含标准替换算法），以及标准且合理的最小 MediaKeySession 对象数目。这使得在用户代理之间能够实现合理数量的密钥轮换算法，并可能在涉及同一元素中多路流（例如自适应流、不同音视频轨道）使用不同密钥的用例中减少播放中断的可能性。

         如果 sanitized response 包含 许可证销毁记录 的确认且 sessionType 为 "persistent-license"

         运行下列步骤：

         1. 关闭 key session 并清除与此对象关联的 所有 存储会话数据，包括 sessionId 和 许可证销毁记录。

            注

            随后的对 load() 的调用，若使用此对象的 sessionId 值，将会失败，因为该会话 ID 不再有存储的数据。

         2. 将 session closed 设为 true。

         否则

         处理 sanitized response，但不存储任何会话数据。

         注

         例如，sanitized response 可能包含将用于生成另一个 message 事件的信息。在这种情况下，无需验证其内容是否与 sessionType 匹配。

      3. 如果需要发送消息，执行下列步骤：

         1. 令 message 为该消息。

         2. 令 message type 为该消息的适当 MediaKeyMessageType。

   8. 排队一个任务（Queue a task） 来运行下列步骤：

      1. 如果 session closed 为 true：

         在此对象上以原因 "release-acknowledged" 运行 Session Closed 算法。

         否则：

         运行下列步骤：

         1. 如果此对象的 CDM 对该对象已知的密钥集合变化或任何密钥的状态发生变化，则对 session 运行 Update Key Statuses 算法，提供每个已知密钥的 key ID 及相应的 MediaKeyStatus。

            如果确定某密钥的状态需要额外处理，可使用 "status-pending"。一旦额外处理完成，再次运行 Update Key Statuses 算法并提供实际状态。

         2. 如果会话的 expiration time 发生变化，则在 session 上运行 Update Expiration 算法，提供新的到期时间。

         3. 如果前述任一步骤失败，则以新的 DOMException（其 name 为相应的 error name） 拒绝 promise。

         4. 如果 message 非 null，则在 session 上运行 Queue a "message" Event 算法，提供 message type 和 message。

      2. 用 undefined 解析 promise。

7. 返回 promise。

close()

表示应用不再需要该会话，且 CDM 应释放与会话关联的任何资源并关闭该会话。已持久化的数据不应被释放或清除。

注

当请求被处理完毕时，返回的 promise 将被解析；当会话关闭时，closed 属性的 promise 将被解析为 "closed-by-application"。

当调用此方法时，用户代理 MUST 运行以下步骤：

1. 如果此对象的 closing or closed 值为 true，则返回一个解析为 undefined 的 promise。

2. 如果此对象的 callable 值为 false，则返回一个以 InvalidStateError 拒绝的 promise。

3. 令 promise 为一个新的 promise。

4. 将此对象的 closing or closed 值设为 true。

5. 并行运行下列步骤：

   1. 令 cdm 为由此对象的 cdm instance 值所表示的 CDM 实例。

   2. 使用 cdm 关闭与此对象关联的 key session。

      注

      关闭 key session 会导致销毁任何未被显式存储的许可证和密钥。

   3. 排队一个任务（Queue a task） 来运行下列步骤：

      1. 用 undefined 解析 promise。

      2. 在此对象上以原因 "closed-by-application" 运行 Session Closed 算法。

6. 返回 promise。

remove()

移除与该会话关联的所有许可证和密钥。对于 持久会话类型，其它会话数据将在释放消息确认被 update() 处理后按每种会话类型的定义被清除。

当调用此方法时，用户代理 MUST 运行以下步骤：

1. 如果此对象的 closing or closed 值为 true，则返回一个以 InvalidStateError 拒绝的 promise。

2. 如果此对象的 callable 值为 false，则返回一个以 InvalidStateError 拒绝的 promise。

3. 令 promise 为一个新的 promise。

4. 并行运行下列步骤：

   1. 令 cdm 为由此对象的 cdm instance 值所表示的 CDM 实例。

   2. 令 message 为 null。

   3. 令 message type 为 null。

   4. 使用 cdm 执行下列步骤：

      1. 如果有任何许可证和/或密钥与该会话相关联：

         1. 销毁与该会话关联的许可证和/或密钥。

            注

            这意味着无论许可证和/或密钥是在内存中、持久存储中或两者中，都将被销毁。

         2. 按下列列表中与此对象的 session type 值相对应的条目执行步骤：

            "temporary"

            继续执行下列步骤。

            "persistent-license"

            1. 令 record of license destruction 为表示此对象所代表许可证的 许可证销毁记录。

            2. 存储该 record of license destruction。

            3. 令 message 为包含或反映该 record of license destruction 的消息。

   5. 排队一个任务（Queue a task） 来运行下列步骤：

      1. 在 session 上运行 Update Key Statuses 算法，为会话中的所有 key ID 提供 "released" 的 MediaKeyStatus 值。

      2. 在 session 上运行 Update Expiration 算法，提供 NaN。

      3. 如果前述任一步骤失败，则以新的 DOMException（其 name 为相应的 error name） 拒绝 promise。

      4. 令 message type 为 "license-release"。

      5. 用 undefined 解析 promise。

      6. 如果 message 非 null，则在 session 上运行 Queue a "message" Event 算法，提供 message type 和 message。

5. 返回 promise。

MediaKeyStatusMap 对象是一个只读映射， 将 key IDs 映射到关联密钥的当前状态。

密钥的状态与该密钥当前是否正在被使用以及与媒体数据无关。

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

MediaKeyStatus 枚举定义如下：

MediaKeyMessageEvent 对象用于 message 事件。

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

MediaKeyMessageType 定义如下：

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

方法通过拒绝返回的 promise，并抛出 简单异常 [WEBIDL] 或 DOMException 来报告错误。下列 [WEBIDL] 中定义的 简单异常 和 DOMException 名称 会在算法中使用。算法中指定的原因会列在每个名称旁边，但这些名称 MAY 也可用于其他原因。

本节提供了与算法互补的会话存储与持久化概述。

除 存储与持久化 的要求外，下列要求也适用。

如果对本对象的 session type 运行 Is persistent session type? 算法结果为 false，则用户代理和 CDM MUST NOT 在任何时候持久化与该会话相关的记录或数据。这包括许可证、密钥、许可证销毁记录，以及 Session ID。

本节剩余内容适用于 Is persistent session type? 算法返回 true 的会话类型。

CDM SHOULD NOT 在首次调用 update() 前存储会话数据（包括 Session ID）。具体来说，CDM SHOULD NOT 在 generateRequest() 算法期间存储会话数据。这可确保应用知晓会话的存在，并知道需要最终移除它。

与会话相关的 所有 数据在会话被清除时 MUST 被清除，例如在处理 update() 时收到 许可证销毁记录确认。参见 持久数据。

CDM MUST 确保某个会话的数据只存在于一个未被 closed 的 MediaKeySession 对象中，无论在哪个 Document。换言之，当已经存在一个由 generateRequest() 创建且仍活动的对象，或已通过 load() 加载到另一个对象中时，针对该 sessionId 的 MediaKeySession 的 load() MUST 失败。只有所有曾经表示该会话的对象都已 closed 时，会话才 MAY 被再次加载。

应用在使用 Is persistent session type? 算法返回 true 的类型创建会话后，SHOULD 之后通过先用 remove() 启动移除过程，然后确保移除过程（可能涉及消息交换）成功完成来删除存储的数据。CDM MAY 也会酌情移除会话，但应用 SHOULD NOT 依赖此行为。

支持持久化存储时参见 10. 安全 和 11. 隐私 以获取更多考虑事项。

mediaKeys 类型为 MediaKeys，只读，可为 null

当前 media element 解密加密 媒体数据 时所用的 MediaKeys。

onencrypted 类型为 EventHandler

用于 encrypted 事件的事件处理器。所有 HTMLMediaElement 都 MUST 同时支持作为内容属性和 IDL 属性。

onwaitingforkey 类型为 EventHandler

用于 waitingforkey 事件的事件处理器。所有 HTMLMediaElement 都 MUST 同时支持作为内容属性和 IDL 属性。

setMediaKeys()

提供用于播放时解密媒体数据的 MediaKeys。

注

在播放过程中清除或替换关联的 MediaKeys 对象的支持属于实现质量问题。在许多情况下会导致不良的用户体验或 promise 被拒绝。

当调用此方法时，用户代理 MUST 运行以下步骤：

1. 如果此对象的 attaching media keys 值为 true，则返回一个以 InvalidStateError 拒绝的 promise。

2. 如果 mediaKeys 与 mediaKeys 属性是同一个对象，则返回一个解析为 undefined 的 promise。

3. 将此对象的 attaching media keys 值设为 true。

4. 令 promise 为一个新的 promise。

5. 并行运行下列步骤：

   1. 如果以下条件全部成立：

      • mediaKeys 不为 null，

      • mediaKeys 所代表的 CDM 实例已被其他媒体元素使用，

      • 用户代理无法与当前元素一起使用它，

      则将此对象的 attaching media keys 值设为 false，并以 QuotaExceededError 拒绝 promise。

   2. 如果 mediaKeys 属性不为 null，则运行以下步骤：

      1. 如果用户代理或 CDM 不支持解除关联，则将 attaching media keys 设为 false，并以 NotSupportedError 拒绝 promise。

      2. 如果当前无法解除关联，则将 attaching media keys 设为 false，并以 InvalidStateError 拒绝 promise。

         注

         例如，某些实现可能不允许在播放期间解除关联。

      3. 停止使用 CDM 实例（由 mediaKeys 属性表示）来解密 媒体数据，并解除与媒体元素的关联。

      4. 如果前述步骤失败，则将 attaching media keys 设为 false，并以合适的 错误名 拒绝 promise。

   3. 如果 mediaKeys 不为 null，则运行以下步骤：

      1. 将 mediaKeys 所代表的 CDM 实例与媒体元素关联，以用于解密 媒体数据。

      2. 如果前述步骤失败，运行以下步骤：

         1. 将 mediaKeys 属性设为 null。

         2. 将 attaching media keys 设为 false。

         3. 以新的 DOMException（其 name 为合适的 错误名）拒绝 promise。

      3. 排队一个任务，在该媒体元素上运行 Attempt to Resume Playback If Necessary 算法。

   4. 将 mediaKeys 属性设为 mediaKeys。

   5. 将 attaching media keys 设为 false。

   6. 用 undefined 解析 promise。

6. 返回 promise。

MediaEncryptedEvent 对象用于 encrypted 事件。

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

用户代理实现者 MUST 确保 CDMs 不得访问任何对使用本规范功能播放受保护媒体并非合理必要的信息、存储或系统能力。具体而言，CDM SHALL NOT：

• 访问网络资源（本地或远程），除非通过用户代理并且本规范明确允许。

• 访问存储（例如磁盘或内存），除非为使用本规范功能播放受保护媒体的合理需要。

• 访问用户数据，除非是 CDM 状态或 持久化数据。

• 访问硬件组件或设备，除非为使用本规范功能播放受保护媒体的合理需要。

用户代理实现者可使用各种技术来满足上述要求。例如，自行实现 CDM 的用户代理实现者可以将上述要求作为该组件的设计要求。使用第三方 CDM 的用户代理实现者可以确保其在受限环境（例如“沙箱”）中执行，从而无法访问被禁止的信息和组件。

与 CDM 之间的所有消息与通信（例如 CDM 与许可证服务器之间）MUST 通过用户代理传递。CDM MUST NOT 发起直接的带外网络请求。除 Direct Individualization 所述外，所有消息与通信 MUST 通过应用程序并使用本规范定义的 API 传递。具体而言，所有包含应用、origin 或内容特定信息，或发送到由应用指定或基于其 origin 的 URL 的通信 MUST 通过这些 API。包括所有许可证交换消息在内。

持久化数据包括由 CDM 或代表 CDM 由用户代理存储的、在 MediaKeys 对象销毁后仍然存在的所有数据。具体包括任何标识符（包括 Distinctive Identifier(s)）、许可证、密钥、key ID 或 许可证销毁记录，这些由 CDM 或代表 CDM 的用户代理存储。

暴露给应用或可被应用推断出的值（例如通过其被 CDM 使用）可能被用来识别客户端或用户，无论这些值是否被设计为标识符。本节定义了避免或至少缓解此类问题的要求。关于 Identifiers 有额外要求。

实现中使用标识符（尤其是 Distinctive Identifier(s) 或 Distinctive Permanent Identifier(s)）会带来隐私问题。本节定义了避免或至少缓解这些问题的要求。Values Exposed to the Application 中的要求同样适用于暴露给应用的标识符。

标识符，尤其是 Distinctive Identifiers，有时通过称为 individualization 或 provisioning 的流程生成或获取。由此产生的标识符 MUST 满足 non-associable by applications 要求，并且对它们的 使用 MUST 仅在来自单一配置文件的单一 origin的范围内暴露。该过程 MAY 被重复执行，例如在标识符被 清除 之后。

该过程 MUST 由 用户代理直接执行 或 通过应用执行。两种 individualization 类型的机制、流程和限制不同，下面的各节对其作了说明。采用哪种方法取决于 CDM 的实现以及对本规范要求的应用，尤其是下文所述的要求。

实现 MUST 在每个 MediaKeySession 对象中支持多个密钥。

实现 MUST 支持在播放期间在密钥之间无缝切换。这包括同一 MediaKeySession 中的密钥以及位于不同 MediaKeySession 对象中的密钥。

本节定义了本规范实现所支持的内容（media resource）的属性。

"org.w3.clearkey" 密钥系统 使用明文（未加密）的密钥来解密源内容。不需要额外的客户端侧内容保护。该 密钥系统 在下文描述。

{
  "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 和 Key System 实现必须将 media data、Initialization Data、传入 update() 的数据、许可证、 密钥数据，以及应用提供的所有其他数据视为不受信任的内容和潜在攻击向量。它们应当使用适当的防护措施来减轻任何相关的威胁，并在解析、解密等处理此类数据时谨慎。User Agents 应该 在将数据传递给 CDM 之前验证数据。

实现不得向应用返回会影响程序控制流的活动内容或被动内容。

User Agents 负有为用户提供安全浏览网络方式的责任。该责任适用于 User Agents 使用的任何功能，包括第三方功能。User agent 实现者必须从 Key System 实现者处获取足够的信息，以使其能够正确评估与集成该 Key System 的安全影响。User agent 实现者 必须确保 CDM 实现提供和/或支持足够的控制，以便 user agent 能够为用户提供安全保障。User agent 实现者 必须 确保 CDM 实现能够并且会在发现安全脆弱性时快速且积极地进行更新。

利用未完全沙箱化和/或使用平台特性的 CDM 实现，攻击者可能访问操作系统或平台特性、提升权限（例如以 system 或 root 身份运行），以及/或访问驱动、内核、固件、硬件等。这类特性、软件和硬件可能没有针对敌对软件或基于 Web 的攻击进行健壮性编写，并且可能不会像 user agent 那样频繁获得安全修复。CDM 实现中缺乏、稀少或缓慢的安全修复更新会增加风险。此类 CDM 实现及暴露它们的 UA 在所有安全领域都必须特别谨慎，包括解析 所有数据。

如果 user agent 选择支持无法被充分沙箱化或无法以其他方式加固的 Key System 实现，则 user agent 应该在加载或调用该实现之前确保用户已充分获知并/或给予明确同意。

关于 EME 和 Key Systems 披露的信息的关切分为两类： (a) 关于非特指的信息的担忧，尽管这些信息并不具体但仍可能促成对用户代理或设备的指纹识别；以及 (b) 可能被直接用于 用户追踪 的与用户相关的信息。

恶意应用可能通过检测或枚举所支持的 Key Systems 列表及相关信息来为用户或用户代理创建指纹。如果没有提供适当的 origin 保护，这可能包括检测已访问过的站点以及为这些站点存储的信息。尤其是，Key Systems 必须 不在 origins 之间共享密钥或其他数据。

User agents 可能支持一种旨在保持用户匿名和/或确保不在客户端保留浏览活动记录的操作模式（例如私密浏览）。对于使用这些模式的用户，上述各节讨论的隐私问题可能尤为令人关注。

支持此类模式的 user agent 实现者 应该 仔细考虑在这些模式下是否应禁用对 Key Systems 的访问。例如，这些模式 可以 禁止创建支持或使用 MediaKeySystemAccess 对象，这些对象支持或使用 persistentState 或 distinctiveIdentifier（无论是作为 CDM 实现的一部分，还是因为应用将其标记为 "required"）。如果实现不禁止此类创建，则在允许使用之前，应该 向用户告知其对这些模式预期隐私属性的影响和潜在后果。

本规范中定义的 API 仅在安全的 origins 上支持，从而保护前述各节中讨论的信息。标识符也按 Encrypt Identifiers 中规定的方式进行加密。

应用（包括其使用的服务器）应该 对所有包含或涉及 CDM 的数据或消息的流量使用安全传输，这包括但不限于来自 message 事件传出的所有数据，以及传递给 update() 的数据。

所有 user agents 必须 正确处理混合内容 [MIXED-CONTENT]，以避免在用户代理或应用希望强制执行安全 origin 和传输时暴露于不安全的内容或传输。