media/mojo/interfaces/content_decryption_module.mojom

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   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.interfaces;
   6
   7 import "media/mojo/interfaces/decryptor.mojom";
   8
   9 // Transport layer of media::MediaKeys::Exception (see media/base/media_keys.h).
  10 // This is used for ContentDecryptionModule (CDM) promise rejections.
  11 // Note: This can also be used for session errors in prefixed API.
  12 enum CdmException {
  13   NOT_SUPPORTED_ERROR,
  14   INVALID_STATE_ERROR,
  15   INVALID_ACCESS_ERROR,
  16   QUOTA_EXCEEDED_ERROR,
  17   UNKNOWN_ERROR,
  18   CLIENT_ERROR,
  19   OUTPUT_ERROR
  20 };
  21
  22 // Transport layer of media::CdmKeyInformation::KeyStatus (see
  23 // media/base/cdm_key_information.h). This is used for indicating the status
  24 // of a specific key ID.
  25 enum CdmKeyStatus {
  26   USABLE,
  27   INTERNAL_ERROR,
  28   EXPIRED,
  29   OUTPUT_RESTRICTED,
  30   OUTPUT_DOWNSCALED,
  31   KEY_STATUS_PENDING
  32 };
  33
  34 // Transport layer of media::CdmConfig (see media/base/cdm_config.h).
  35 struct CdmConfig {
  36   bool allow_distinctive_identifier;
  37   bool allow_persistent_state;
  38   bool use_hw_secure_codecs;
  39 };
  40
  41 // Transport layer of media::CdmPromise (see media/base/cdm_promise.h).
  42 // - When |success| is true, the promise is resolved and all other fields should
  43 //   be ignored.
  44 // - When |success| is false, the promise is rejected with |exception|,
  45 //   |system_code| and |error_message|.
  46 struct CdmPromiseResult {
  47   bool success;
  48   CdmException exception;
  49   uint32 system_code;
  50   string? error_message;
  51 };
  52
  53 // Transport layer of media::CdmKeyInformation (see
  54 // media/base/cdm_key_information.h). It is used to specify a key_id and it's
  55 // associated status.
  56 struct CdmKeyInformation {
  57   array<uint8> key_id;
  58   CdmKeyStatus status;
  59   uint32 system_code;
  60 };
  61
  62 // See media::MediaKeys::MessageType
  63 enum CdmMessageType {
  64   LICENSE_REQUEST,
  65   LICENSE_RENEWAL,
  66   LICENSE_RELEASE
  67 };
  68
  69 // An interface that represents a CDM in the Encrypted Media Extensions (EME)
  70 // spec (https://w3c.github.io/encrypted-media/). See media/base/media_keys.h.
  71 interface ContentDecryptionModule {
  72   // See media::MediaKeys::SessionType.
  73   enum SessionType {
  74     TEMPORARY_SESSION,
  75     PERSISTENT_LICENSE_SESSION,
  76     PERSISTENT_RELEASE_MESSAGE_SESSION
  77   };
  78
  79   // See media::EmeInitDataType.
  80   enum InitDataType {
  81     UNKNOWN,
  82     WEBM,
  83     CENC,
  84     KEYIDS
  85   };
  86
  87   // Sets ContentDecryptionModuleClient. Must be called before any other calls.
  88   SetClient(ContentDecryptionModuleClient client);
  89
  90   // Initializes the CDM. |cdm_id| will later be used to locate the CDM at the
  91   // remote side. If initialization failed (e.g. |key_system| or |cdm_config| is
  92   // not supported), |result.success| will be false.
  93   Initialize(string key_system, string security_origin, CdmConfig cdm_config,
  94              int32 cdm_id) => (CdmPromiseResult result);
  95
  96   // Provides a server certificate to be used to encrypt messages to the
  97   // license server.
  98   SetServerCertificate(array<uint8> certificate_data)
  99       => (CdmPromiseResult result);
 100
 101   // Creates a session with the |init_data_type|, |init_data| and |session_type|
 102   // provided. If |result.success| is false, the output |session_id| will be
 103   // null.
 104   CreateSessionAndGenerateRequest(SessionType session_type,
 105                                   InitDataType init_data_type,
 106                                   array<uint8> init_data)
 107       => (CdmPromiseResult result, string? session_id);
 108
 109   // Loads the session associated with |session_id| and |session_type|.
 110   // Combinations of |result.success| and |session_id| means:
 111   //   (true, non-null) : Session successfully loaded.
 112   //   (true, null) : Session not found.
 113   //   (false, non-null): N/A; this combination is not allowed.
 114   //   (false, null) : Unexpected error. See other fields in |result|.
 115   LoadSession(SessionType session_type, string session_id)
 116       => (CdmPromiseResult result, string? session_id);
 117
 118   // Updates a session specified by |session_id| with |response|.
 119   UpdateSession(string session_id, array<uint8> response)
 120       => (CdmPromiseResult result);
 121
 122   // Closes the session specified by |session_id|.
 123   CloseSession(string session_id) => (CdmPromiseResult result);
 124
 125   // Removes stored session data associated with the active session specified by
 126   // |session_id|.
 127   RemoveSession(string session_id) => (CdmPromiseResult result);
 128
 129   // Retrieves the |decryptor| associated with this CDM instance.
 130   GetDecryptor(Decryptor&? decryptor);
 131 };
 132
 133 // Session callbacks. See media/base/media_keys.h for details.
 134 interface ContentDecryptionModuleClient {
 135   OnSessionMessage(string session_id, CdmMessageType message_type,
 136                    array<uint8> message, string legacy_destination_url);
 137
 138   OnSessionClosed(string session_id);
 139
 140   OnLegacySessionError(string session_id, CdmException exception,
 141                        uint32 system_code, string error_message);
 142
 143   OnSessionKeysChange(string session_id, bool has_additional_usable_key,
 144                       array<CdmKeyInformation> key_information);
 145
 146   // Provide session expiration update for |session_id|.
 147   // |new_expiry_time_sec| is the number of seconds since epoch (Jan 1, 1970).
 148   OnSessionExpirationUpdate(string session_id, double new_expiry_time_sec);
 149 };