# Encrypted Media: Encryption Scheme Query

## Draft Community Group Report, 1 January 1970

This version:
  https://wicg.github.io/encrypted-media-encryption-scheme/
Editors:
  Joey Parrish (Google Inc.)
Participate:
  Git Repository.
  File an issue.
Version History:
  https://github.com/wicg/encrypted-media-encryption-scheme/commits

Copyright © 1970 the Contributors to the Encrypted Media: Encryption Scheme Query Specification, published by the Web Platform Incubator Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

## Abstract

This is an extension to the W3C Encrypted Media Extensions specification, to be integrated into EME vNext. The API will allow authors to query support for specific encryption schemes in the CDM.

## Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

## 1. MediaKeySystemMediaCapability dictionary extension

    partial dictionary MediaKeySystemMediaCapability {
      DOMString? encryptionScheme = null;
    };

The `encryptionScheme` field indicates an encryption scheme required by the application in combination with the other fields of the `MediaKeySystemMediaCapability` dictionary. A value which is null or not present indicates to the user agent that no specific encryption scheme is required by the application, and therefore any encryption scheme is acceptable.

NOTE: Applications that are aware of this field should always specify a value. See § 4 Application Notes for details.

NOTE: If `encryptionScheme` is not present, the `encryptionScheme` field of the `MediaKeySystemMediaCapability` object returned from `MediaKeySystemAccess`.`getConfiguration()` must be present and set to the default value of null. This enables detection of this feature in polyfills for user agents which do not support this field. See also § 5 Polyfills and Backward Compatibility.

NOTE: The empty string is distinct from null or not present, and so would be treated as an unrecognized encryption scheme.

Well-known values for `encryptionScheme` are:

- cenc: The "cenc" mode, defined in ISO 23001-7:2016, section 4.2a. AES-CTR mode full sample and video NAL subsample encryption.

- cbcs: The "cbcs" mode, defined in ISO 23001-7:2016, section 4.2d. AES-CBC mode partial video NAL pattern encryption. For video, the spec allows various encryption patterns.

- cbcs-1-9: The same as "cbcs" mode, but with a specific encrypt:skip pattern of 1:9 for video, as recommended in ISO 23001-7:2016, section 10.4.2.

NOTE: The document WebM Encryption defines WebM encryption to be equivalent to and compatible with the "cenc" encryption mode defined in ISO 23001-7:2016.

A registry should be created for encryption schemes, and the existing format registry should be updated with respect to encryption schemes. <https://github.com/wicg/encrypted-media-encryption-scheme/issues/#9>

## 2. Algorithm Extensions

In the `Get Supported Capabilities...` algorithm, the following changes should be made:

1. In the loop that begins with "For each requested media capability in requested media capabilities", the user agent MUST run the following steps at the beginning of the loop:

   1. Let encryption scheme be requested media capability’s `encryptionScheme` member.

   2. If encryption scheme is non-null and is not recognized or not supported by the user agent, continue to the next iteration.

2. In the step that says "If the user agent and implementation definitely support playback of encrypted media data for the combination of container, media types, robustness and local accumulated configuration in combination with restrictions", the user agent MUST replace the condition with the following condition:

   1. If the user agent and implementation definitely support playback of encrypted media data for the combination of container, media types, robustness, encryption scheme, and local accumulated configuration in combination with restrictions...

## 3. Clear Key Requirements

`Clear Key` implementations MUST support the cenc scheme at a minimum, to ensure interoperability for users of this common key system.

## 4. Application Notes

Applications that are aware of the `encryptionScheme` field should always specify the encryption scheme(s) they require, since different encryption schemes are generally incompatible with one another. It is unrealistic for an application to be accepting of "any" encryption scheme, but the default of null and the interpretation of null as "any" provide backward compatibility for unaware applications and a path to a polyfill for older user agents. See also § 5 Polyfills and Backward Compatibility.

Applications may specify multiple encryption schemes in separate configurations, or in multiple capabilities of the same configuration.

The user agent only selects one configuration. So if different encryption schemes are specified in separate configurations, the application will be given back a configuration containing only one encryption scheme.

If different encryption schemes appear in the same configuration, the user agent’s accumulated configuration will contain the supported subset of the capabilities specified by the application. The configuration returned from `getConfiguration()` may therefore contain more than one encryption scheme.

## 5. Polyfills and Backward Compatibility

Omission of `encryptionScheme` is supported only to maintain backward compatibility for applications that are unaware of this field. Applications should always specify the encryption scheme(s) they require. See also § 4 Application Notes.

Applications which do not specify `encryptionScheme` will get the same behavior they did before this feature existed: encryption scheme will not be considered during `requestMediaKeySystemAccess()`, and they will have to make assumptions about which encryption scheme(s) the user agent supports.

User agents which implement this specification will always have an `encryptionScheme` field in the `MediaKeySystemMediaCapability` object returned from `MediaKeySystemAccess`.`getConfiguration()`, even if the field is not present in the `MediaKeySystemMediaCapability` object given by the application. This enables a polyfill to be written which detects the lack of `encryptionScheme` to determine whether or not a browser supports it.

If the user agent does not support the `encryptionScheme` field, a polyfill can use assumptions about the encryption scheme(s) supported by various user agents to emulate this specification and reject `MediaKeySystemMediaCapability` objects which specify (assumed) unsupported schemes. Note that these are the same assumptions already made by existing applications. A polyfill would allow an application to offload those assumptions. The application could then always use the `encryptionScheme` field to specify their needs using a standard API.

Publish and link to a polyfill for this feature. <https://github.com/wicg/encrypted-media-encryption-scheme/issues/#13>

Any user agent which deprecates support for an existing encryption scheme could introduce backward compatibility issues for older applications which do not use this new feature. Appropriate communication with developers will be necessary to ensure that applications are updated in a timely manner ahead of any such deprecation. The need for good communication around deprecations is not unique to this proposal.

## 6. Security and Privacy Considerations

This specification does not introduce any security-sensitive information or APIs.

### 6.1. Fingerprinting

This extension offers an additional field an application can use to determine the device’s decryption capabilities. This does not increase the fingerprint surface by much, since decryption capabilities are generally the same for any given user agent and operating system. This extension simply offers applications a way to avoid hard-coding this knowledge.

### 6.2. User Consent

Fingerprinting concerns are mitigated by the fact that this new field is part of the `requestMediaKeySystemAccess()` API, which may require user consent. User agents that would require user consent in order to access the CDM will therefore require user consent to make use of this new field.

## 7. Examples

    function tryTwoEncryptionSchemesInSeparateConfigurations(keySystem) {
      // Query two configurations with different encryption schemes.
      // Only one will be chosen by the user agent.

      return navigator.requestMediaKeySystemAccess(keySystem, [
        { // A configuration which uses the "cenc" encryption scheme
          videoCapabilities: [{
            contentType: 'video/mp4; codecs="avc1.640028"',
            encryptionScheme: 'cenc',
          }],
          audioCapabilities: [{
            contentType: 'audio/mp4; codecs="mp4a.40.2"',
            encryptionScheme: 'cenc',
          }],
          initDataTypes: ['keyids'],
        },

        { // A configuration which uses the "cbcs-1-9" encryption scheme
          videoCapabilities: [{
            contentType: 'video/mp4; codecs="avc1.640028"',
            encryptionScheme: 'cbcs-1-9',
          }],
          audioCapabilities: [{
            contentType: 'audio/mp4; codecs="mp4a.40.2"',
            encryptionScheme: 'cbcs-1-9',
          }],
          initDataTypes: ['keyids'],
        },
      ]);
    }

    function tryTwoEncryptionSchemesInOneConfiguration(keySystem) {
      // Query one configuration with two different encryption schemes.
      // The user agent will eliminate any capabilities object it cannot support,
      // so the accumulated configuration may contain one encryption scheme or both.

      return navigator.requestMediaKeySystemAccess(keySystem, [{
        videoCapabilities: [
          { // A capability object which uses the "cenc" encryption scheme
            contentType: 'video/mp4; codecs="avc1.640028"',
            encryptionScheme: 'cenc',
          },
          { // A capability object which uses the "cbcs-1-9" encryption
            // scheme
            contentType: 'video/mp4; codecs="avc1.640028"',
            encryptionScheme: 'cbcs-1-9',
          },
        ],
        audioCapabilities: [
          { // A capability object which uses the "cenc" encryption scheme
            contentType: 'audio/mp4; codecs="mp4a.40.2"',
            encryptionScheme: 'cenc',
          },
          { // A capability object which uses the "cbcs-1-9" encryption
            // scheme
            contentType: 'audio/mp4; codecs="mp4a.40.2"',
            encryptionScheme: 'cbcs-1-9',
          },
        ],
        initDataTypes: ['keyids'],
      }]);
    }

## Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with `class="example"`, like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with `class="note"`, like this:

Note, this is an informative note.

## Index

### Terms defined by this specification

- cbcs, in §1
- cbcs-1-9, in §1
- cenc, in §1
- encryptionScheme, in §1

https://www.w3.org/TR/encrypted-media/#clear-key Referenced in:

- 3. Clear Key Requirements

https://www.w3.org/TR/encrypted-media/#get-supported-capabilities-for-audio-video-type Referenced in:

- 2. Algorithm Extensions

https://www.w3.org/TR/encrypted-media/#dom-mediakeysystemaccess Referenced in:

- 1. MediaKeySystemMediaCapability dictionary extension
- 5. Polyfills and Backward Compatibility

https://www.w3.org/TR/encrypted-media/#dom-mediakeysystemmediacapability Referenced in:

- 1. MediaKeySystemMediaCapability dictionary extension (2)
- 5. Polyfills and Backward Compatibility (2) (3)

https://www.w3.org/TR/encrypted-media/#dom-mediakeysystemaccess-getconfiguration Referenced in:

- 1. MediaKeySystemMediaCapability dictionary extension
- 4. Application Notes
- 5. Polyfills and Backward Compatibility

https://www.w3.org/TR/encrypted-media/#navigator-extension:-requestmediakeysystemaccess()Referenced in:

- 5. Polyfills and Backward Compatibility
- 6.2. User Consent

https://www.w3.org/TR/html51/semantics-embedded-content.html#media-data Referenced in:

- 2. Algorithm Extensions (2)

https://heycam.github.io/webidl/#idl-DOMString Referenced in:

- 1. MediaKeySystemMediaCapability dictionary extension

https://heycam.github.io/webidl/#dfn-present Referenced in:

- 1. MediaKeySystemMediaCapability dictionary extension (2) (3) (4)
- 5. Polyfills and Backward Compatibility

https://heycam.github.io/webidl/#dfn-present Referenced in:

- 1. MediaKeySystemMediaCapability dictionary extension (2) (3) (4)
- 5. Polyfills and Backward Compatibility

### Terms defined by reference

- [encrypted-media] defines the following terms:
  - Clear Key
  - Get Supported Capabilities...
  - MediaKeySystemAccess
  - MediaKeySystemMediaCapability
  - getConfiguration()
  - requestMediaKeySystemAccess()
- [html51] defines the following terms:
  - media data
- [WebIDL] defines the following terms:
  - DOMString
  - not present
  - present

## References

### Normative References

[ENCRYPTED-MEDIA]
  David Dorwin; et al. Encrypted Media Extensions. 18 September 2017. REC. URL: https://www.w3.org/TR/encrypted-media/
[HTML51]
  Steve Faulkner; et al. HTML 5.1 2nd Edition. 3 October 2017. REC. URL: https://www.w3.org/TR/html51/
[RFC2119]
  S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WebIDL]
  Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

## IDL Index

    partial dictionary MediaKeySystemMediaCapability {
      DOMString? encryptionScheme = null;
    };

## Issues Index

A registry should be created for encryption schemes, and the existing format registry should be updated with respect to encryption schemes. <https://github.com/wicg/encrypted-media-encryption-scheme/issues/#9> ↵
Publish and link to a polyfill for this feature. <https://github.com/wicg/encrypted-media-encryption-scheme/issues/#13> ↵
#dom-mediakeysystemmediacapability-encryptionscheme Referenced in:

- 1. MediaKeySystemMediaCapability dictionary extension (2) (3) (4)
- 2. Algorithm Extensions
- 4. Application Notes
- 5. Polyfills and Backward Compatibility (2) (3) (4) (5) (6)

#cenc Referenced in:

- 3. Clear Key Requirements