sdk/fidl/fuchsia.media/content_decryption.fidl - fuchsia - Git at Google

 // Copyright 2019 The Fuchsia Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.

 library fuchsia.media;

 using fuchsia.io;
 using fuchsia.mem;

 const uint32 KEY_ID_SIZE = 16;
 const uint32 MAX_INIT_DATA_SIZE = 16;

 // Encryption modes as defined by ISO 23001-7: Common encryption in ISO base
 // media file format files. These are defined as strings rather than enums so as
 // to not limit the types of encryption formats to just the set as defined by
 // the current Common Encryption standard.
 const string ENCRYPTION_MODE_CENC = "cenc";
 const string ENCRYPTION_MODE_CBC1 = "cbc1";
 const string ENCRYPTION_MODE_CENS = "cens";
 const string ENCRYPTION_MODE_CBCS = "cbcs";

 // Common initialization data formats. These are defined as strings rather than
 // enums so as to not limit the types a ContentDecryptionModule may support.
 const string LICENSE_INIT_DATA_TYPE_CENC = "cenc";
 const string LICENSE_INIT_DATA_TYPE_KEYIDS = "keyids";
 const string LICENSE_INIT_DATA_TYPE_WEBM = "webm";
 const string LICENSE_INIT_DATA_TYPE_HLS = "hls";

 enum LicenseSessionType {
     /// A session for which the license, keys, and record of the session are not
     /// persisted.
     TEMPORARY = 1;
     /// A session for which the license, keys, and record of the session will be
     /// persisted for offline use and can subsequently be loaded using
     /// LoadSession().
     PERSISTENT_LICENSE = 2;
     /// A session for which the the record of the session will be persisted, but
     /// the keys and license will not be.
     PERSISTENT_USAGE_RECORD = 3;
 };

 enum LicenseMessageType {
     REQUEST = 1;
     RENEWAL = 2;
     RELEASE = 3;
 };

 enum LicenseInitDataType {
     CENC = 0;
     KEYIDS = 1;
     WEBM = 2;
 };

 enum KeyStatus {
     USABLE = 0;
     EXPIRED = 1;
     RELEASED = 2;
     OUTPUT_RESTRICTED = 3;
     OUTPUT_DOWNSCALED = 4;
     STATUS_PENDING = 5;
     INTERNAL_ERROR = 6;
 };

 struct LicenseInitData {
     /// The type is a string that indicates the format of the accompanying init
     /// data. Common types include "cenc", "keyids", "webm", and "hls". CDMs may
     /// also define their own.
     string type;
     bytes:MAX_INIT_DATA_SIZE data;
 };

 /// LicenseMessage is for messages originating from the LicenseSession that the
 /// caller must route to the license server.
 struct LicenseMessage {
     LicenseMessageType type;
     fuchsia.mem.Buffer message;
 };

 /// LicenseServerMessage is for messages originating from the license server
 /// that the caller must provide to the LicenseSession via
 /// |ProcessLicenseServerMessage|.
 struct LicenseServerMessage {
     fuchsia.mem.Buffer message;
 };

 /// ProvisionMessage is for messages originating from the CDM that the caller
 /// must route to the provisioning server.
 struct ProvisionMessage {
     fuchsia.mem.Buffer message;
 };

 /// ProvisionServerMessage is for messages originating from the provisioning
 /// server that the caller must provide to the CDM via
 /// |ProcessProvisionServerMessage|.
 struct ProvisionServerMessage {
     fuchsia.mem.Buffer message;
 };

 struct KeyId {
     array<uint8>:KEY_ID_SIZE data;
 };

 struct KeyInfo {
     KeyId key_id;
     KeyStatus status;
 };

 table DecryptorParams {
     /// Requires the decryptor to only output to secure buffers.
     1: bool require_secure_mode;

     /// Initial format details for the StreamProcessor.
     2: FormatDetails input_details;
 };

 protocol LicenseSession {
     /// Generate a license request for a session based on the |init_data|. When
     /// the LicenseMessage has been created, the |OnLicenseMessageGenerated|
     /// event will be triggered with the message to be sent to the license
     /// server.
     GenerateLicenseRequest(LicenseInitData init_data);

     /// Inititiate the release process for the license session. This will cause
     /// the CDM to generate a LicenseMessage through the
     /// |OnLicenseMessageGenerated| event. The client must route that message
     /// to the license server and the server's response to
     /// |ProcessLicenseServerMessage|. Once the LicenseSession has received the
     /// license server's reply, it will close the LicenseSession channel as this
     /// session will no longer be usable.
     GenerateLicenseRelease();

     /// Update the LicenseSession with a message from the license server. All
     /// responses from license requests, renewals, and releases should be routed
     /// to the LicenseSession through this method.
     ProcessLicenseServerMessage(LicenseServerMessage message);

     /// Create a Decryptor StreamProcessor interface to be used to decrypt
     /// content.
     CreateDecryptor(DecryptorParams params, request<StreamProcessor> decryptor);

     /// The LicenseSession has generated a message to be sent to the license
     /// server. The client is responsible for transporting this message to the
     /// license server.
     -> OnLicenseMessageGenerated(LicenseMessage message);

     /// The LicenseSession has updated key status information.
     -> OnKeysChanged(vector<KeyInfo> key_info);
 };

 [FragileBase]
 protocol ContentDecryptionModule {
     /// Set the certificate to be used for encrypting outgoing messages.
     SetServerCertificate(bytes certificate);

     /// Create a new session for the given type. The |session_id| will be
     /// generated by the CDM and can be used to reload the session after
     /// closing.
     CreateLicenseSession(LicenseSessionType session_type,
                          request<LicenseSession> license_session)
         -> (string session_id);

     /// Load an existing session from persistent storage using the given
     /// |session_id|. If the session is not found, then the |license_session|
     /// will be closed.
     LoadLicenseSession(string session_id, request<LicenseSession> license_session);

     /// Update the CDM with a message from the provisioning server. Not all
     /// underlying CDM systems will require provisioning for individual
     /// providers. If they do, this method will carry the provisioning message
     /// to the CDM instance so that it may persistently store the provider
     /// certificate.
     ProcessProvisionServerMessage(ProvisionServerMessage message);

     /// Remove the persistent session data associated with the session without
     /// waiting for server acknowledgement. No LicenseMessage will be generated.
     /// If there is an active LicenseSession for this |session_id|, it will be
     /// closed.
     RemoveLicenseSessionData(string session_id);

     /// Check whether the device has been provisioned. Some CDM systems will be
     /// entirely provisioned at the time of device manufacturing, while others
     /// might require additional provisioning for a given content provider. This
     /// provisioning status will indicate whether the CDM is capable of
     /// generating license requests.
     IsProvisioned() -> (bool is_provisioned);

     /// Removes all provider based provisioning for this CDM instance. This does
     /// not impact any factory provisioning.
     RemoveProvisioning();

     /// Remove all persistent usage records for this CDM instance. Any
     /// associated license sessions will no longer be usable.
     RemoveUsageRecords();

     /// Query the status of a hypothetical key associated with an HDCP policy
     /// without setting up a license session. This aids clients in determining
     /// which content type to fetch prior to establishing. For example, if the
     /// device would restrict output for HDCP 1.x, then the client can choose to
     /// fetch SD content rather than HD.
     GetKeyStatusForHdcpVersion(string hdcp_version) -> (KeyStatus key_status);

     /// Query the CDM for the list of supported encryption modes, such as
     /// 'cenc', 'cbc1', 'cens', or 'cbcs'.
     GetSupportedEncryptionModes() -> (vector<string> encryption_modes);

     /// If the underlying CDM system requires provisioning for individual
     /// providers (the owner of the CDM instance), then it will generate a
     /// ProvisionMessage the first time a LicenseSession attempts to request a
     /// license. This message must be routed to the provisioning server by the
     /// client and the server's response provided to the CDM by calling
     /// |ProcessProvisionServerMessage|.
     -> OnProvisionMessageGenerated(ProvisionMessage message);
 };

 // There are two ways to create the desired ContentDecryptionModule. Which
 // method to use is dependent on how persistent storage should be provided to
 // the CDM. The preferred method to use is the per key system discoverable
 // interface. This method will rely on the componentmgr to create the CDM
 // instance's persistent storage for it. This provides isolation of the storage
 // location from the client.
 //
 // The second method is to use the discoverable ContentDecryptionModuleFactory
 // and request that it creates the CDM on the client's behalf. Using this method
 // requires the client to provide the storage to be used. This storage should be
 // isolated to distinct origins/providers.

 [Discoverable]
 protocol ClearKeyContentDecryptionModule {
     compose ContentDecryptionModule;
 };

 [Discoverable]
 protocol WidevineContentDecryptionModule {
     compose ContentDecryptionModule;
 };

 [Discoverable]
 protocol PlayReadyContentDecryptionModule {
     compose ContentDecryptionModule;
 };

 [Discoverable]
 protocol ContentDecryptionModuleFactory {
     /// The Factory interface should only be used if the client needs to inject
     /// the storage to be used by the CDM. The storage must be a unique location
     /// per origin/ provider.
     CreateClearKeyContentDecryptionModule(
         fuchsia.io.Directory data_directory,
         request<ClearKeyContentDecryptionModule> cdm);

     CreateWidevineContentDecryptionModule(
         fuchsia.io.Directory data_directory,
         request<WidevineContentDecryptionModule> cdm);

     CreatePlayReadyContentDecryptionModule(
         fuchsia.io.Directory data_directory,
         request<PlayReadyContentDecryptionModule> cdm);
 };
	// Copyright 2019 The Fuchsia Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.

	library fuchsia.media;

	using fuchsia.io;
	using fuchsia.mem;

	const uint32 KEY_ID_SIZE = 16;
	const uint32 MAX_INIT_DATA_SIZE = 16;

	// Encryption modes as defined by ISO 23001-7: Common encryption in ISO base
	// media file format files. These are defined as strings rather than enums so as
	// to not limit the types of encryption formats to just the set as defined by
	// the current Common Encryption standard.
	const string ENCRYPTION_MODE_CENC = "cenc";
	const string ENCRYPTION_MODE_CBC1 = "cbc1";
	const string ENCRYPTION_MODE_CENS = "cens";
	const string ENCRYPTION_MODE_CBCS = "cbcs";

	// Common initialization data formats. These are defined as strings rather than
	// enums so as to not limit the types a ContentDecryptionModule may support.
	const string LICENSE_INIT_DATA_TYPE_CENC = "cenc";
	const string LICENSE_INIT_DATA_TYPE_KEYIDS = "keyids";
	const string LICENSE_INIT_DATA_TYPE_WEBM = "webm";
	const string LICENSE_INIT_DATA_TYPE_HLS = "hls";

	enum LicenseSessionType {
	/// A session for which the license, keys, and record of the session are not
	/// persisted.
	TEMPORARY = 1;
	/// A session for which the license, keys, and record of the session will be
	/// persisted for offline use and can subsequently be loaded using
	/// LoadSession().
	PERSISTENT_LICENSE = 2;
	/// A session for which the the record of the session will be persisted, but
	/// the keys and license will not be.
	PERSISTENT_USAGE_RECORD = 3;
	};

	enum LicenseMessageType {
	REQUEST = 1;
	RENEWAL = 2;
	RELEASE = 3;
	};

	enum LicenseInitDataType {
	CENC = 0;
	KEYIDS = 1;
	WEBM = 2;
	};

	enum KeyStatus {
	USABLE = 0;
	EXPIRED = 1;
	RELEASED = 2;
	OUTPUT_RESTRICTED = 3;
	OUTPUT_DOWNSCALED = 4;
	STATUS_PENDING = 5;
	INTERNAL_ERROR = 6;
	};

	struct LicenseInitData {
	/// The type is a string that indicates the format of the accompanying init
	/// data. Common types include "cenc", "keyids", "webm", and "hls". CDMs may
	/// also define their own.
	string type;
	bytes:MAX_INIT_DATA_SIZE data;
	};

	/// LicenseMessage is for messages originating from the LicenseSession that the
	/// caller must route to the license server.
	struct LicenseMessage {
	LicenseMessageType type;
	fuchsia.mem.Buffer message;
	};

	/// LicenseServerMessage is for messages originating from the license server
	/// that the caller must provide to the LicenseSession via
	/// \|ProcessLicenseServerMessage\|.
	struct LicenseServerMessage {
	fuchsia.mem.Buffer message;
	};

	/// ProvisionMessage is for messages originating from the CDM that the caller
	/// must route to the provisioning server.
	struct ProvisionMessage {
	fuchsia.mem.Buffer message;
	};

	/// ProvisionServerMessage is for messages originating from the provisioning
	/// server that the caller must provide to the CDM via
	/// \|ProcessProvisionServerMessage\|.
	struct ProvisionServerMessage {
	fuchsia.mem.Buffer message;
	};

	struct KeyId {
	array<uint8>:KEY_ID_SIZE data;
	};

	struct KeyInfo {
	KeyId key_id;
	KeyStatus status;
	};

	table DecryptorParams {
	/// Requires the decryptor to only output to secure buffers.
	1: bool require_secure_mode;

	/// Initial format details for the StreamProcessor.
	2: FormatDetails input_details;
	};

	protocol LicenseSession {
	/// Generate a license request for a session based on the \|init_data\|. When
	/// the LicenseMessage has been created, the \|OnLicenseMessageGenerated\|
	/// event will be triggered with the message to be sent to the license
	/// server.
	GenerateLicenseRequest(LicenseInitData init_data);

	/// Inititiate the release process for the license session. This will cause
	/// the CDM to generate a LicenseMessage through the
	/// \|OnLicenseMessageGenerated\| event. The client must route that message
	/// to the license server and the server's response to
	/// \|ProcessLicenseServerMessage\|. Once the LicenseSession has received the
	/// license server's reply, it will close the LicenseSession channel as this
	/// session will no longer be usable.
	GenerateLicenseRelease();

	/// Update the LicenseSession with a message from the license server. All
	/// responses from license requests, renewals, and releases should be routed
	/// to the LicenseSession through this method.
	ProcessLicenseServerMessage(LicenseServerMessage message);

	/// Create a Decryptor StreamProcessor interface to be used to decrypt
	/// content.
	CreateDecryptor(DecryptorParams params, request<StreamProcessor> decryptor);

	/// The LicenseSession has generated a message to be sent to the license
	/// server. The client is responsible for transporting this message to the
	/// license server.
	-> OnLicenseMessageGenerated(LicenseMessage message);

	/// The LicenseSession has updated key status information.
	-> OnKeysChanged(vector<KeyInfo> key_info);
	};

	[FragileBase]
	protocol ContentDecryptionModule {
	/// Set the certificate to be used for encrypting outgoing messages.
	SetServerCertificate(bytes certificate);

	/// Create a new session for the given type. The \|session_id\| will be
	/// generated by the CDM and can be used to reload the session after
	/// closing.
	CreateLicenseSession(LicenseSessionType session_type,
	request<LicenseSession> license_session)
	-> (string session_id);

	/// Load an existing session from persistent storage using the given
	/// \|session_id\|. If the session is not found, then the \|license_session\|
	/// will be closed.
	LoadLicenseSession(string session_id, request<LicenseSession> license_session);

	/// Update the CDM with a message from the provisioning server. Not all
	/// underlying CDM systems will require provisioning for individual
	/// providers. If they do, this method will carry the provisioning message
	/// to the CDM instance so that it may persistently store the provider
	/// certificate.
	ProcessProvisionServerMessage(ProvisionServerMessage message);

	/// Remove the persistent session data associated with the session without
	/// waiting for server acknowledgement. No LicenseMessage will be generated.
	/// If there is an active LicenseSession for this \|session_id\|, it will be
	/// closed.
	RemoveLicenseSessionData(string session_id);

	/// Check whether the device has been provisioned. Some CDM systems will be
	/// entirely provisioned at the time of device manufacturing, while others
	/// might require additional provisioning for a given content provider. This
	/// provisioning status will indicate whether the CDM is capable of
	/// generating license requests.
	IsProvisioned() -> (bool is_provisioned);

	/// Removes all provider based provisioning for this CDM instance. This does
	/// not impact any factory provisioning.
	RemoveProvisioning();

	/// Remove all persistent usage records for this CDM instance. Any
	/// associated license sessions will no longer be usable.
	RemoveUsageRecords();

	/// Query the status of a hypothetical key associated with an HDCP policy
	/// without setting up a license session. This aids clients in determining
	/// which content type to fetch prior to establishing. For example, if the
	/// device would restrict output for HDCP 1.x, then the client can choose to
	/// fetch SD content rather than HD.
	GetKeyStatusForHdcpVersion(string hdcp_version) -> (KeyStatus key_status);

	/// Query the CDM for the list of supported encryption modes, such as
	/// 'cenc', 'cbc1', 'cens', or 'cbcs'.
	GetSupportedEncryptionModes() -> (vector<string> encryption_modes);

	/// If the underlying CDM system requires provisioning for individual
	/// providers (the owner of the CDM instance), then it will generate a
	/// ProvisionMessage the first time a LicenseSession attempts to request a
	/// license. This message must be routed to the provisioning server by the
	/// client and the server's response provided to the CDM by calling
	/// \|ProcessProvisionServerMessage\|.
	-> OnProvisionMessageGenerated(ProvisionMessage message);
	};

	// There are two ways to create the desired ContentDecryptionModule. Which
	// method to use is dependent on how persistent storage should be provided to
	// the CDM. The preferred method to use is the per key system discoverable
	// interface. This method will rely on the componentmgr to create the CDM
	// instance's persistent storage for it. This provides isolation of the storage
	// location from the client.
	//
	// The second method is to use the discoverable ContentDecryptionModuleFactory
	// and request that it creates the CDM on the client's behalf. Using this method
	// requires the client to provide the storage to be used. This storage should be
	// isolated to distinct origins/providers.

	[Discoverable]
	protocol ClearKeyContentDecryptionModule {
	compose ContentDecryptionModule;
	};

	[Discoverable]
	protocol WidevineContentDecryptionModule {
	compose ContentDecryptionModule;
	};

	[Discoverable]
	protocol PlayReadyContentDecryptionModule {
	compose ContentDecryptionModule;
	};

	[Discoverable]
	protocol ContentDecryptionModuleFactory {
	/// The Factory interface should only be used if the client needs to inject
	/// the storage to be used by the CDM. The storage must be a unique location
	/// per origin/ provider.
	CreateClearKeyContentDecryptionModule(
	fuchsia.io.Directory data_directory,
	request<ClearKeyContentDecryptionModule> cdm);

	CreateWidevineContentDecryptionModule(
	fuchsia.io.Directory data_directory,
	request<WidevineContentDecryptionModule> cdm);

	CreatePlayReadyContentDecryptionModule(
	fuchsia.io.Directory data_directory,
	request<PlayReadyContentDecryptionModule> cdm);
	};