media/mojo/mojom/content_decryption_module.mojom

   1 // Copyright 2014 The Chromium Authors
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 module media.mojom;
   6
   7 import "media/mojo/mojom/decryptor.mojom";
   8 import "media/mojo/mojom/media_types.mojom";
   9 import "mojo/public/mojom/base/unguessable_token.mojom";
  10
  11 // See media::EmeInitDataType.
  12 [Native]
  13 enum EmeInitDataType;
  14
  15 // See media::CdmSessionType
  16 [Native]
  17 enum CdmSessionType;
  18
  19 // See media::CdmMessageType
  20 [Native]
  21 enum CdmMessageType;
  22
  23 // See media::CdmKeyInformation::KeyStatus
  24 enum CdmKeyStatus {
  25     USABLE,
  26     INTERNAL_ERROR,
  27     EXPIRED,
  28     OUTPUT_RESTRICTED,
  29     OUTPUT_DOWNSCALED,
  30     KEY_STATUS_PENDING,
  31     RELEASED,
  32 };
  33
  34 // See media::HdcpVersion
  35 [Native]
  36 enum HdcpVersion;
  37
  38 // See media::CdmConfig
  39 [Native]
  40 struct CdmConfig;
  41
  42 // Transport layer of media::CdmPromise (see media/base/cdm_promise.h).
  43 // - When |success| is true, the promise is resolved and all other fields should
  44 //   be ignored.
  45 // - When |success| is false, the promise is rejected with |exception|,
  46 //   |system_code| and |error_message|.
  47 struct CdmPromiseResult {
  48   // See media::CdmPromise::Exception
  49   [Native]
  50   enum Exception;
  51
  52   bool success;
  53   Exception exception;
  54   uint32 system_code;
  55   string error_message;
  56 };
  57
  58 // Transport layer of media::CdmKeyInformation (see
  59 // media/base/cdm_key_information.h). It is used to specify a key_id and it's
  60 // associated status.
  61 struct CdmKeyInformation {
  62   array<uint8> key_id;
  63   CdmKeyStatus status;
  64   uint32 system_code;
  65 };
  66
  67 // An interface that represents a CDM in the Encrypted Media Extensions (EME)
  68 // spec (https://w3c.github.io/encrypted-media/).
  69 // - Process Model: For security reason, the CDM is running in its own process
  70 // as the CDM contains untrusted code and handles arbitrary data. The exact
  71 // process model varies on various platforms. For example, on desktop, the CDM
  72 // runs in a CDM (utility) process. On Android, the CDM runs in the GPU process.
  73 // The client of the CDM is MojoCdm, which runs in the render process.
  74 // - Session ID: Passed as `session_id` in some methods, it is a unique string
  75 // identifier generated by the CDM that can be used to identify CDM sessions.
  76 // A ContentDecryptionModule can manage mutilple sessions per the EME spec. See
  77 // https://www.w3.org/TR/encrypted-media/#session-id.
  78 // - Also see media/base/content_decryption_module.h and media/mojo/README.md.
  79 interface ContentDecryptionModule {
  80   // Sets ContentDecryptionModuleClient. Must be called before any other calls.
  81   // Use associated interface to ensure ordering, e.g. events on the client
  82   // interface and promise fulfillment.
  83   SetClient(pending_associated_remote<ContentDecryptionModuleClient> client);
  84
  85   // Provides a server certificate to be used to encrypt messages to the
  86   // license server.
  87   SetServerCertificate(array<uint8> certificate_data)
  88       => (CdmPromiseResult result);
  89
  90   // Gets the key status if there's a hypothetical key that requires the
  91   // |min_hdcp_version|. Resolve the |promise| with the |key_status| after the
  92   // operation completes. Reject the |promise| if this operation is not
  93   // supported or unexpected error happened.
  94   GetStatusForPolicy(HdcpVersion min_hdcp_version)
  95       => (CdmPromiseResult result, CdmKeyStatus key_status);
  96
  97   // Creates a session with the |init_data_type|, |init_data| and |session_type|
  98   // provided. If |result.success| is false, the output |session_id| will be
  99   // empty.
 100   CreateSessionAndGenerateRequest(CdmSessionType session_type,
 101                                   EmeInitDataType init_data_type,
 102                                   array<uint8> init_data)
 103       => (CdmPromiseResult result, string session_id);
 104
 105   // Loads the session associated with |session_id| and |session_type|.
 106   // Combinations of |result.success| and |session_id| means:
 107   //   (true, non-empty) : Session successfully loaded.
 108   //   (true, empty) : Session not found.
 109   //   (false, non-empty): N/A; this combination is not allowed.
 110   //   (false, empty) : Unexpected error. See other fields in |result|.
 111   LoadSession(CdmSessionType session_type, string session_id)
 112       => (CdmPromiseResult result, string session_id);
 113
 114   // Updates a session specified by |session_id| with |response|.
 115   UpdateSession(string session_id, array<uint8> response)
 116       => (CdmPromiseResult result);
 117
 118   // Closes the session specified by |session_id|.
 119   CloseSession(string session_id) => (CdmPromiseResult result);
 120
 121   // Removes stored session data associated with the active session specified by
 122   // |session_id|.
 123   RemoveSession(string session_id) => (CdmPromiseResult result);
 124 };
 125
 126 // Session callbacks. The implementation is MojoCdm that runs in the render
 127 // process. The caller is the remote CDM (mojom::ContentDecryptionModule). See
 128 // comments above for more details on CDM process model and session ID.
 129 // Also see media/base/content_decryption_module.h and media/mojo/README.md.
 130 interface ContentDecryptionModuleClient {
 131   // Called when the CDM needs to queue a message event to the session object.
 132   // See http://w3c.github.io/encrypted-media/#dom-evt-message
 133   OnSessionMessage(string session_id, CdmMessageType message_type,
 134                    array<uint8> message);
 135
 136   // Called when the session specified by |session_id| is closed. Note that the
 137   // CDM may close a session at any point, e.g. in response to `CloseSession()`,
 138   // when the session is no longer needed, or when system resources are lost.
 139   // After `OnSessionClosed()` is called for a `session_id`, no methods in this
 140   // interface should be called with the same `session_id`.
 141   // See http://w3c.github.io/encrypted-media/#session-close
 142   OnSessionClosed(string session_id, CdmSessionClosedReason reason);
 143
 144   // Called when there has been a change in the keys in the session or their
 145   // status.
 146   // See http://w3c.github.io/encrypted-media/#dom-evt-keystatuseschange
 147   OnSessionKeysChange(string session_id, bool has_additional_usable_key,
 148                       array<CdmKeyInformation> keys_info);
 149
 150   // Called when the CDM changes the expiration time of a session.
 151   // See http://w3c.github.io/encrypted-media/#update-expiration
 152   // |new_expiry_time_sec| is the number of seconds since epoch (Jan 1, 1970).
 153   OnSessionExpirationUpdate(string session_id, double new_expiry_time_sec);
 154 };
 155
 156 // Context associated with the remote CDM, mostly to populate media::CdmContext.
 157 struct CdmContext {
 158   // An ID that can be used to locate the CDM at the remote side.
 159   mojo_base.mojom.UnguessableToken cdm_id;
 160
 161   // The remote Decryptor if the CDM implementation provides one.
 162   pending_remote<Decryptor>? decryptor;
 163
 164   // Whether MediaFoundationRenderer is required by the CDM.
 165   [EnableIf=is_win]
 166   bool requires_media_foundation_renderer;
 167 };
 168
 169 // Factory interface used for creating ContentDecryptionModule instances.
 170 interface CdmFactory {
 171   // Creates a CDM based on the `cdm_config` provided. The `key_system` in
 172   // `cdm_config` is a generic term for a decryption mechanism and/or content
 173   // protection provider. It should be a reverse domain name,
 174   // e.g. "com.example.somesystem". However, this call may be initiated by an
 175   // untrusted process (e.g. renderer), so the implementation must fully
 176   // validate `key_system` before creating the CDM. `cdm_config` also specifies
 177   // other properties of the CDM which may influence creation. Upon failure,
 178   // the returned `cdm` and `cdm_context` will be null, and `error_message`
 179   // will specify the error reason. Upon success, `cdm` and `cdm_context` will
 180   // be valid, and `error_message` will be empty.
 181   CreateCdm(CdmConfig cdm_config) =>
 182             (pending_remote<ContentDecryptionModule>? cdm,
 183              CdmContext? cdm_context,
 184              string error_message);
 185 };