加密媒体扩展

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 中， 该对象由 MediaKeySystemAccess 的 getConfiguration() 方法返回。

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

受支持的初始化数据类型 名称列表。如果列表为空，或包含一个或多个与所有其他成员一起受支持的值 （由算法确定），则认为此对象的初始化数据类型 能力受支持。序列中的值不得为空字符串。

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

受支持的音频类型和能力对列表。如果列表为空，或包含一个或多个与所有其他 成员一起受支持的值（由算法确定），则认为此 对象的音频能力受支持。当值之间存在 冲突时，将选择较早的值。空列表表示 不支持音频能力。在这种情况下， videoCapabilities 元素不得为空。

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

受支持的视频类型和能力对列表。如果列表为空，或包含一个或多个与所有其他 成员一起受支持的值（由算法确定），则认为此 对象的视频能力受支持。当值之间存在 冲突时，将选择较早的值。空列表表示 不支持视频能力。在这种情况下， audioCapabilities 元素不得为空。

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

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

当此成员为 "not-allowed" 时， 实现绝不能在与从此配置创建的任何对象相关联的任何 操作中使用 可区别标识符或可区别永久标识符。

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

是否要求具备持久化状态的能力。这包括会话数据和任何 其他类型的状态。

当此成员为 "not-allowed" 时， CDM 绝不能持久化任何与 应用或此对象的 Document 的 源相关的状态。

注

就此成员而言，持久化状态不包括由密钥系统 实现控制的持久化唯一 标识符（可区别 标识符）。distinctiveIdentifier 独立地 反映此要求。

当不支持持久化 状态时，只能创建 "temporary" 会话。

注

对于 "temporary" 会话， 存储状态的需要和能力是密钥系统实现特定的，并且可能随所使用的 特性而变化。

注

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

sessionTypes 类型为 sequence<DOMString>

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

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

实现不应向此字典添加成员。如果添加成员， 它们必须是 MediaKeysRequirement 类型，并且建议它们具有 "optional" 的默认值，以支持最广泛的 应用和客户端组合。

此字典绝不能用于向 CDM 传递状态或数据。

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

为了让此对象表示的能力被视为受支持， contentType 绝不能为空字符串，并且其整个 值，包括所有编解码器，都必须与 robustness 一起受支持。

keySystem 类型为 DOMString，只读

标识正在使用的密钥系统。

getConfiguration()

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

返回的对象是第一个可满足的 MediaKeySystemConfiguration 配置的非严格子集（加上任何隐含默认值），该配置传递给 requestMediaKeySystemAccess() 调用，而该调用返回的 promise 以此对象 resolve。它不包含未在该单一配置中指定的能力值 （隐含默认值除外），因此可能不会反映 密钥系统实现的所有能力。配置中的所有值 可以以任意组合使用。类型为 MediaKeysRequirement 的成员反映 该能力是否为任意组合所要求。它们不会具有 "optional" 值。

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

1. 返回此对象的 configuration 值。

   注

   这会导致每次调用此方法时，都从 configuration 创建并初始化一个新对象。

   注

   如果应用没有给出 encryptionScheme， 累积的 configuration 必须 仍然包含一个值为 null 的 encryptionScheme 字段，以便 polyfill 可以在不指定具体值的情况下检测用户代理对该 字段的支持。

createMediaKeys()

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

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

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 值所表示的 密钥系统实现。

   5. 令 instance 为此对象的 cdm implementation 值所表示的密钥系统 实现的新实例。

   6. 使用 configuration 初始化 instance，以启用、禁用和/或选择 密钥系统特性。

   7. 如果 use distinctive identifier 为 false，则阻止 instance 使用 可区别标识符和可区别永久标识符。

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

   9. 如果前面的任何步骤失败，则以一个新的 DOMException 拒绝 promise，其名称为适当的错误 名称。

   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 resolve promise。

3. 返回 promise。

createSession()

返回一个新的 MediaKeySession 对象。

注

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

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

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

   注

   如果此对象的 persistent state allowed 值为 false，则 是持久会话类型吗？ 算法返回 true 的 sessionType 值会失败。

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

   注

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

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()

返回给定 MediaKeysPolicy 的 MediaKeyStatus。

WebIDLdictionary MediaKeysPolicy {
    DOMString minHdcpVersion;
};

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

HDCP 策略由 minHdcpVersion 表示。如果 系统可以启用指定的 HDCP 版本或更高版本，则该策略会产生 "usable" 的 MediaKeyStatus。 [EME-HDCP-VERSION-REGISTRY] 提供从 minHdcpVersion 值 到 HDCP 规范的映射。

注

HDCP 状态的确定应当以与 CDM 在播放期间强制执行此类限制相同的方式进行。这样，应用 开发者可以获得合理提示，从而优化他们为开始播放而获取的内容。

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

1. 如果 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" resolve promise 并中止这些步骤。

   4. 用 "usable" resolve promise。

4. 返回 promise。

setServerCertificate()

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

对于使用此类证书的密钥系统，应用应当调用 setServerCertificate() 来显式设置服务器证书。 否则，许可证交换可能失败。

注

某些密钥系统也支持通过 排队一个 "message" 事件算法 从服务器请求证书。然而， 并非所有使用此类证书的密钥系统都支持这一点。

服务器证书内容特定于密钥系统。它绝不能包含 可执行代码。

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

1. 如果此对象的 cdm implementation 值所表示的密钥系统实现不支持服务器证书，则返回一个以 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 拒绝 promise，其名称为适当的错误 名称。

   4. 以 true 兑现 promise。

6. 返回 promise。

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

如果 MediaKeys 对象的 persistent state allowed 值为 false，则该对象的 cdm instance不得由于 对此对象或其创建的任何会话进行操作而持久化状态或 访问先前持久化的状态。

如果 MediaKeys 对象的 persistent state allowed 值为 true，则该对象的 cdm instance可以由于 对此对象或其创建的任何会话进行操作而持久化状态或访问 先前持久化的状态。

持久化数据必须始终以只有此对象的 Document 的 源可以访问它的方式存储。 此外，该数据必须只能由当前 浏览配置文件访问；其他浏览配置文件、用户代理和 应用绝不能 访问所存储的数据。见存储在 用户设备上的信息。

在支持持久性存储时，另请参见10. 安全和11. 隐私中的其他考虑事项。

sessionId 类型为 DOMString，只读

此对象及其关联密钥或许可证的会话 ID。

expiration 类型为 unrestricted double， 只读

会话中所有密钥的过期时间，或者如果不存在这样的 时间，或许可证明确永不过期，则为 NaN，具体由 CDM 确定。 此值可能在会话生命周期内发生变化，例如当某个操作触发 窗口的开始时。

closed 类型为 Promise<MediaKeySessionClosedReason>， 只读

表示对象因运行会话已关闭算法而变为已关闭的时间。此 promise 只能被 fulfilled，且永不会被拒绝。

keyStatuses 类型为 MediaKeyStatusMap， 只读

指向一个只读映射的引用，该映射把会话已知的密钥 ID映射到关联密钥的当前 状态。每个条目必须具有唯一的密钥 ID。

注

每当事件循环运转时，映射条目及其值都可能被更新。该 映射永远不会处于不一致或部分更新的状态，但如果两次访问之间 事件循环发生运转，则它可能在访问之间发生变化。密钥 ID 可能会作为 load() 或 update() 调用的结果而被添加。 密钥 ID 可能会作为移除 现有密钥知识（或用一组新密钥替换现有密钥集）的 update() 调用 的结果而被移除。如果密钥变得不可用，例如由于过期，则不会移除密钥 ID。相反，此类 密钥必须被赋予适当的状态，例如“expired”。

注

某些较旧的平台可能包含不暴露 密钥 ID 的密钥系统实现， 从而无法提供符合要求的用户代理实现。在 这种情况下，为了最大化互操作性，当非空列表 合适时（例如，当此对象表示的密钥会话可以包含 密钥时），该映射会填充为一个单独的键值对， 其中包含单字节密钥 ID 0，以及最适合此对象聚合状态的 MediaKeyStatus。

onkeystatuseschange 类型为 EventHandler

keystatuseschange 事件的 事件处理器。

onmessage 类型为 EventHandler

message 事件的 事件处理器。

generateRequest()

基于 initData 生成许可证请求。如果算法成功且 promise 被兑现， 则始终会排队一个类型为 "license-request" 或 "individualization-request" 的 message。

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

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 值表示的密钥系统实现不支持将 initDataType 作为 初始化数据 类型，则返回一个以 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 版本。

       用户代理必须在将初始化 数据传递给 CDM 之前对其进行彻底验证。这包括验证 字段的长度和值是否合理，验证值是否在合理限制内， 并剥离无关、不受支持或未知的数据或字段。 建议用户代理预解析、清理 和/或生成初始化数据的完全清理版本。如果由 initDataType 指定的初始化 数据格式支持多个条目， 用户代理应该移除 CDM 不需要的条目。用户代理不得重新排序初始化 数据中的条目。

    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. 如果 cdm 不支持 sanitized init data， 则用 NotSupportedError 拒绝 promise。

       2. 按以下列表中 session type 值对应的步骤操作：

          "temporary"

          令 requested license type 为临时的 不可持久化 许可证。

          注

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

          "persistent-license"

          令 requested license type 为可持久化许可证。

       3. 令 session id 为唯一的会话 ID 字符串。

          如果在 session type 上运行是否为持久会话 类型？算法的结果为 true，则该 ID 必须在此对象的 Document 的源中随时间保持唯一，包括 跨 Document 和浏览会话。

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

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

             CDM cdm 不得使用任何未通过 sanitized init data 提供的流特定 数据，包括媒体 数据。

             CDM cdm 此时不应该 存储会话数据， 包括会话 ID。参见会话存储和 持久化。

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

          否则：

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

             在随后对 update() 的调用中，CDM 必须基于 sanitized init data 为 requested license type 生成许可证请求，该数据按 initDataType 解释。

          2. 令 message type 反映 message 的类型，即 "license-request" 或 "individualization-request"。

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

        1. 如果前述任一步骤因资源不足而失败，则用 QuotaExceededError 拒绝 promise。

        2. 如果前述任一步骤因任何其他原因失败，则用一个新的 DOMException 拒绝 promise，其名称为适当的错误名称。

        3. 将 sessionId 属性设置为 session id。

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

        5. 用 undefined 兑现 promise。

        6. 在 session 上运行排队一个 "message" 事件 算法，并提供 message type 和 message。

11. 返回 promise。

load()

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

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

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

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

3. 令此对象的 uninitialized 值为 false。

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

5. 如果在此对象的 session type 上运行是否为持久会话类型？ 算法的结果为 false，则返回一个以新创建的 TypeError 拒绝的 promise。

6. 令 origin 为此对象的 Document 的源。

7. 令 promise 为一个新的 promise。

8. 并行运行以下步骤：

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

      注

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

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

   3. 如果此对象的 Document 中存在一个尚未关闭的 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 存储的数据。此数据不得包含 来自其他源的数据或不与任何源关联的数据。

      4. 如果任何 Document 中存在一个尚未关闭的 MediaKeySession 对象，并且该对象表示 session data，则用 QuotaExceededError 拒绝 promise。

         注

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

      5. 加载 session data。

      6. 如果 session data 指示会话的过期 时间，则令 expiration time 为该过期时间。

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

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

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

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

      1. 如果前述任一步骤失败，则用适当的错误名称 拒绝 promise。

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

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

      4. 如果已加载会话包含有关任何密钥的信息（存在 已知密钥），则在 session 上运行更新 密钥状态算法，并提供每个密钥的密钥 ID 以及适当的 MediaKeyStatus。

         如果需要额外处理才能确定密钥状态， 则使用 "status-pending"。 一旦一个或多个密钥的额外处理完成， 再次运行更新 密钥状态算法，并使用实际状态。

      5. 在 session 上运行更新过期时间算法， 并提供 expiration time。

      6. 用 true 兑现 promise。

      7. 如果 message 不为 null，则在 session 上运行排队一个 "message" 事件 算法，并提供 message type 和 message。

9. 返回 promise。

update()

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

response 参数包含要提供给 CDM 的消息。 其内容是密钥系统特定的。它不得 包含可执行代码。

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

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 版本。

      注

      用户代理在将 response 传递给 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 中包含的许可证/密钥 以及相关会话数据。此类数据必须 以只有此对象的 Document 的源 能够访问的方式存储。

         否则

         用新创建的 TypeError 拒绝 promise。

         另见会话存储和 持久化。

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

         注

         当 sanitized response 包含密钥和/或 相关数据时，cdm 很可能会（在内存中）存储以密钥 ID 索引的密钥 及相关数据。

         注

         会话内的替换算法依赖于密钥 系统。

         注

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

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

         运行以下步骤：

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

            注

            之后用此对象的 sessionId 的值调用 load() 将会失败，因为 没有为该会话 ID 存储任何数据。

         2. 将 session closed 设置为 true。

         否则

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

         注

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

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

         1. 令 message 为该消息。

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

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

      1. 如果 session closed 为 true：

         在此对象上运行会话已关闭 算法，原因为 "release-acknowledged"。

         否则：

         运行以下步骤：

         1. 如果此对象的 CDM 已知密钥集合发生变化，或任何密钥的状态发生变化，则在 session 上运行更新密钥 状态算法， 并提供每个已知密钥的密钥 ID 以及适当的 MediaKeyStatus。

            如果需要额外处理才能 确定密钥状态，则使用 "status-pending"。 一旦一个或多个密钥的额外 处理完成，则再次运行 更新密钥 状态算法，并使用实际 状态。

         2. 如果会话的过期时间 发生变化，则在 session 上运行 更新 过期时间算法， 并提供新的过期时间。

         3. 如果前述任一步骤失败，则用一个新的 DOMException 拒绝 promise， 其名称为适当的 错误名称。

         4. 如果 message 不为 null，则在 session 上运行排队一个 "message" 事件算法，并提供 message type 和 message。

      2. 用 undefined 兑现 promise。

7. 返回 promise。

close()

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

注

当请求已被处理时，返回的 promise 会被兑现；当会话关闭时， closed 属性 promise 会以 "closed-by-application" 兑现。

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

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 关闭与此对象关联的密钥会话。

      注

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

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

      1. 用 undefined 兑现 promise。

      2. 在此对象上运行会话 已关闭算法，原因为 "closed-by-application"。

6. 返回 promise。

remove()

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

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

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. 排队 一个任务以运行以下步骤：

      1. 在 session 上运行更新密钥状态 算法， 并提供会话中所有密钥 ID 以及每个密钥对应的 "released" MediaKeyStatus 值。

      2. 在 session 上运行更新过期时间算法， 并提供 NaN。

      3. 如果前述任一步骤失败，则用一个新的 DOMException 拒绝 promise， 其名称为适当的错误名称。

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

      5. 用 undefined 兑现 promise。

      6. 如果 message 不为 null，则在 session 上运行排队一个 "message" 事件算法，并提供 message type 和 message。

5. 返回 promise。

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

密钥的状态独立于该密钥当前是否正在使用，也独立于媒体 数据。

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

这些方法通过使用简单异常 [WEBIDL] 或 DOMException 拒绝返回的 promise 来报告错误。算法中使用了以下来自 [WEBIDL] 的 简单 异常和 DOMException 名称。 算法中指定的原因列在每个名称旁边，尽管这些名称也可以 因其他原因使用。

本节提供会话存储和持久化的概述，以补充这些 算法。

除了存储和持久化中的要求外，还适用以下要求。

如果在此对象的 session type 上运行是否为持久会话类型？ 算法的结果为 false，则用户代理和 CDM 不得 在任何时候持久化该会话的记录或与该会话相关的数据。这包括 许可证、密钥、许可证销毁 记录，以及会话 ID。

本节其余部分适用于是否为持久会话类型？算法返回 true 的会话类型。

CDM 不应该存储会话数据，包括 会话 ID，直到 首次调用 update()。具体而言，CDM 不应该在 generateRequest() 算法期间存储会话数据。这 确保应用知道该会话，并知道它最终需要 移除该会话。

当会话被清除时，与该会话关联的所有数据必须被清除， 例如在 update() 中处理 许可证销毁记录 确认时。参见持久化 数据。

CDM 必须确保给定会话的数据 只存在于一个尚未在任何 Document 中关闭的 MediaKeySession 对象中。 换言之，当已经有一个 MediaKeySession 表示由 sessionId 参数指定的会话时，load() 必须失败， 这可能是因为通过 generateRequest() 创建它的对象仍处于活动状态，或者它已通过 load() 加载到另一个 对象中。只有曾表示该会话的所有对象都已关闭时，会话才可以再次加载。

使用是否为持久会话类型？算法返回 true 的类型创建会话的应用，应该随后移除已存储的数据，方法是先 使用 remove() 发起移除过程，然后确保 该移除过程成功完成，该过程可能涉及消息交换。CDM 也可以在适当时移除会话，但应用不应该依赖 这一点。

支持持久化存储时的其他考虑事项，参见10. 安全和11. 隐私。

mediaKeys 类型为 MediaKeys，只读，可空

在为此媒体元素解密加密媒体数据时使用的 MediaKeys。

onencrypted 类型为 EventHandler

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

onwaitingforkey 类型为 EventHandler

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

setMediaKeys()

提供在播放期间解密媒体数据时要使用的 MediaKeys。

注

在播放期间支持清除或替换关联的 MediaKeys 对象 是实现质量问题。在许多情况下，这会导致糟糕的用户 体验或被拒绝的 promise。

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

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 实例已被 另一个媒体元素使用

      • 用户代理无法将其与此元素一起使用

      则运行以下步骤：

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

         1. 令此对象的 attaching media keys 值为 false。

         2. 用 QuotaExceededError 拒绝 promise。

      2. 中止这些步骤。

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

      1. 如果用户代理或 CDM 不支持 移除关联，则运行 以下步骤：

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

            1. 令此对象的 attaching media keys 值 为 false。

            2. 用 NotSupportedError 拒绝 promise。

         2. 中止这些步骤。

      2. 如果当前无法移除该关联，则运行以下步骤：

         注

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

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

            1. 令此对象的 attaching media keys 值 为 false。

            2. 用 InvalidStateError 拒绝 promise。

         2. 中止这些步骤。

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

      4. 如果前一步失败，则运行以下步骤：

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

            1. 令此对象的 attaching media keys 值 为 false。

            2. 用适当的错误名称拒绝 promise。

         2. 中止这些步骤。

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

      1. 将由 mediaKeys 表示的 CDM 实例与 媒体元素关联，以解密媒体 数据。

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

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

            1. 将 mediaKeys 属性设置为 null。

            2. 令此对象的 attaching media keys 值 为 false。

            3. 用一个新的 DOMException 拒绝 promise，其名称 为适当的错误 名称。

         2. 中止这些步骤。

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

      1. 将 mediaKeys 属性设置为 mediaKeys。

      2. 令此对象的 attaching media keys 值为 false。

      3. 用 undefined 兑现 promise。

      4. 如果 mediaKeys 不为 null，则在媒体元素上运行必要时尝试 恢复播放算法。

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

用户代理实现者必须确保 CDM 不访问任何并非使用本规范特性播放受保护媒体 合理所需的信息、 存储 或系统能力。具体而言，CDM 不得：

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

• 访问存储（例如磁盘或内存），除非这是使用本规范特性播放 受保护媒体的合理所需。

• 访问除 CDM 状态和持久化数据以外的用户数据。

• 访问硬件组件或设备，除非这是使用本规范特性播放 受保护媒体的合理所需。

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

所有发往和来自 CDM 的消息和通信，例如 CDM 与 许可证服务器之间的通信，必须经由用户代理传递。CDM 不得发起直接的 带外网络请求。除直接个性化中描述的那些以外的所有消息和通信必须 通过本规范中定义的 API 经由应用传递。具体而言，所有 包含应用、源或 内容特定信息的通信，或者 发送到由应用指定或基于其源的 URL 的通信，必须通过 这些 API。这包括所有许可证交换消息。

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

暴露给应用或可由应用推断的值（例如通过 CDM 的使用）， 可能被用于标识客户端或用户，无论它们是否设计为 标识符。本节定义了避免或至少缓解此类问题的要求。对于标识符还有其他要求。

实现使用标识符，尤其是可区别 标识符或可区别永久标识符，会带来隐私 问题。本节定义了避免或至少缓解此类问题的要求。 暴露给应用的值的要求也适用于 暴露给应用的标识符。

标识符，尤其是显著标识符，有时 通过称为个性化或配置的过程生成或获得。所得到的标识符必须 不可由应用关联，并且对它们的使用必须仅 暴露给来自单一配置文件的单一 来源。该过程可以执行多次，例如 在标识符被清除之后。

该过程必须由用户代理直接执行，或通过应用执行。两种个性化类型的机制、 流程和限制不同，如以下各节所述。使用哪种方法取决于 CDM 实现以及 本规范要求的应用，尤其是以下要求。

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

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

本节定义了本规范实现所支持的内容（媒体 资源）的属性。

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

用户代理和密钥系统实现必须将 媒体 数据、初始化数据、传递给 update() 的数据、许可证、 密钥数据以及应用提供的所有其他数据视为不可信内容和 潜在攻击向量。它们必须使用适当的防护措施来缓解任何 相关威胁，并注意安全地解析、解密等此类数据。用户代理应当 在将数据传递给 CDM 之前对其进行验证。

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

用户代理负责为用户提供安全的 Web 浏览方式。此 责任适用于用户代理使用的任何功能，包括 来自第三方的功能。用户代理实现者必须从密钥系统实现者处获取 足够的 信息，使其能够恰当地评估与密钥系统集成的安全影响。用户代理实现者 必须确保 CDM 实现提供和/或支持 足够的控制能力，以便 用户代理为用户提供安全性。用户代理实现者必须 确保 CDM 实现在出现安全漏洞时能够且将会被快速、主动地更新。

利用未完全沙盒化和/或使用平台 特性的 CDM 实现，可能允许攻击者访问 OS 或平台功能、提升权限 （例如，以 system 或 root 身份运行），和/或访问驱动程序、内核、固件、硬件等。 此类功能、软件和硬件可能并未被编写为能够抵御恶意 软件或基于 Web 的攻击，并且可能不会通过安全修复进行更新，尤其是 与用户代理相比。CDM 实现中安全 漏洞修复更新缺失、不频繁或缓慢会增加风险。此类 CDM 实现以及暴露它们的 UA 必须在 安全性的所有方面格外谨慎，包括解析所有数据。

如果用户代理选择支持一个无法被充分沙盒化或以其他方式保护的密钥系统实现， 则用户代理应该在加载或调用它之前确保用户已被充分告知和/或给出明确同意。

关于 EME 和密钥系统披露信息的顾虑分为 两类：(a) 关于非特定信息的顾虑，尽管这些信息仍可能有助于 对用户代理或设备进行指纹识别；以及 (b) 可直接用于用户跟踪的 用户特定信息。

恶意应用可能能够通过检测或枚举所支持的 密钥系统列表及相关信息，对用户或用户代理进行指纹识别。 如果未提供适当的源保护，这可能包括检测已访问的站点以及为这些站点存储的信息。 特别是，密钥系统 必须不在不同源之间共享密钥或其他数据。

本规范中的若干特性会暴露可能对指纹识别略有贡献的能力信息：

• encryptionScheme 成员（属于 MediaKeySystemMediaCapability） 会揭示某个密钥系统 支持哪些加密方案。此信息主要由该密钥系统本身决定， 因此除了应用选择的密钥系统已隐含的信息之外，增加的信息很少。

• getStatusForPolicy() 会揭示是否可以强制执行指定的 HDCP 策略。 这反映当前连接的显示链能力，并且如果用户重新配置显示器， 可能会在会话期间发生变化。

用户代理可以支持一种旨在保护用户匿名性和/或确保浏览活动记录不会 持久化到客户端的操作模式（例如私密浏览）。前几节讨论的隐私顾虑 对使用此类模式的用户而言可能尤其令人担忧。

支持此类模式的用户代理实现者应当仔细考虑 是否应在这些模式中禁用对密钥系统的访问。例如，此类模式 可以禁止创建支持或使用 MediaKeySystemAccess 对象， 这些对象支持或使用 persistentState 或 distinctiveIdentifier （无论是作为 CDM 实现的一部分，还是因为应用指明它们为 "required"）。如果实现不禁止此类创建， 则它们应当在允许使用之前，告知用户此类模式的预期隐私属性所面临的影响和潜在后果。

本规范中定义的 API 仅在安全源上受支持，从而保护前几节讨论的信息。 标识符还会按加密标识符中的规定进行加密。

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

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