fuchsia.media.drm

Added: 7

PROTOCOLS

ClearKey

Defined in fuchsia.media.drm/services.fidl

A service hub providing access to the ClearKey key system. This key system is defined by the W3C Encrypted Media Extensions. It uses plain-text keys to decrypt the source.

If the client closes the ClearKey channel, derived ContentDecryptionModules will remain active.

W3C Encrypted Media Extensions: https://www.w3.org/TR/encrypted-media

AddDataStore

Adds a client data store to the KeySystem.

DRM systems generate data on behalf of clients as part of provisioning and license management. This data is only usable by the DRM system, but the client is the owner of the data. The client controls the lifetime of the data and can select which data set is to be used for a ContentDecryptionModule.

  • request data_store_id a client-assigned identifier for the data store. The identifier is scoped to the KeySystem channel. It is invalid for the client to provide NO_DATA_STORE or an already added data_store_id and the server should close the channel.
  • request data_store_params the parameters to be used for this data store.

Request

NameType
data_store_id uint32
data_store_params DataStoreParams

Response

NameType
payload KeySystem_AddDataStore_Result

CreateContentDecryptionModule2

Creates a new ContentDecryptionModule.

Creates a ContentDecryptionModule that will use the associated data store, if provided. If NO_DATA_STORE is provided for the data_store_id, then the created ContentDecryptionModule will only support LicenseSessions of LicenseSessionType.TEMPORARY type. If a data_store_id is provided, then the created ContentDecryptionModule will persist data to that data store. If the KeySystem requires a data store and NO_DATA_STORE was provided or the KeySystem does not support data stores and one was provided, then the server should close the cdm.

If the data_store_id does not exist, the cdm will be closed with a ZX_ERR_NOT_FOUND epitaph.

  • request data_store_id the data store that should be used by the ContentDecryptionModule.
  • request cdm the server endpoint of the ContentDecryptionModule.

Request

NameType
data_store_id uint32
cdm server_end<ContentDecryptionModule>

DestroyDataStoreAndConfirm

Destroys the client data store.

This method permanently removes this data store and all of its contents. All provisioning and license data will be removed and any active ContentDecryptionModule using this data store will be closed.

  • request data_store_id the client-assigned identifier for the data store to be removed. It is invalid for the client to provide NO_DATA_STORE or a data_store_id value that has not previously been added or has been previously destroyed.

Request

NameType
data_store_id uint32

Response

<EMPTY>

GetProperties

Get various static properties of the KeySystem implementation.

The properties include the capabilities and requirements of the KeySystem, such as whether the implementation is hardware-based or whether it requires client-provided data stores to operate.

  • response properties the properties of the KeySystem implementation.

Request

<EMPTY>

Response

NameType
properties KeySystemProperties

ContentDecryptionModule

Defined in fuchsia.media.drm/content_decryption.fidl

A protocol for managing content license sessions and providing decryption of media content. There may be zero to many active LicenseSessions associated with a ContentDecryptionModule, each with their own sets of keys.

From an EME client's perspective, this protocol has a 1:1 relationship with the MediaKeys object.

CreateDecryptor

Creates a Decryptor fuchsia.media/StreamProcessor to be used to decrypt content.

This decryptor would have access to the union of keys created by all the active sessions for this ContentDecryptionModule.

  • request params the parameters with which to create the decryptor.
  • request decryptor the server endpoint of the fuchsia.media/StreamProcessor.

Request

NameType
params DecryptorParams
decryptor server_end<fuchsia.media/StreamProcessor>

CreateLicenseSession

Creates a new session for the given type.

The session_id will be generated by the ContentDecryptionModule and can be used to reload the session after closing. If the session_type is not supported by the underlying DRM system, it will immediately close the license_session.

  • response session_id an identifier that can be used to reload the session later (if persistent).

Request

NameType
session_type LicenseSessionType
license_session server_end<LicenseSession>

Response

NameType
session_id SessionId

GetKeyStatusForHdcpVersion

Queries the status of a hypothetical key associated with an HDCP policy.

This aids clients in determining which content type to fetch prior to establishing a LicenseSession. For example, if the device would restrict output for HDCP 1.x, then the client can choose to fetch SD content rather than HD.

  • request hdcp_version a field containing the HDCP version to check, such as "1.2" or "2.0".
  • response key_status a field indicating what the status of a hypothetical key would be for this device if one could be licensed.

Request

NameType
hdcp_version HdcpVersion

Response

NameType
key_status KeyStatus

GetSupportedEncryptionSchemes

Queries for the list of supported encryption schemes.

This returns a list of the supported encryption schemes that the ContentDecryptionModule supports, such as 'cenc' or 'cbcs'. If the implementation supports passing unencrypted frames through decryption prior to license arrival, it should also report fuchsia.media.UNENCRYPTED as a supported scheme.

  • response encryption_schemes a list of the supported encryption schemes.

Request

<EMPTY>

Response

NameType
encryption_schemes vector<string>

LoadLicenseSession

Loads an existing session from storage using the given session_id.

If the session is not found, then the license_session will be closed.

  • request session_id contains an identifier of which session should be loaded from storage.
  • request license_session the server endpoint of the LicenseSession.

Request

NameType
session_id SessionId
license_session server_end<LicenseSession>

OnProvisioned

Indicates that the ContentDecryptionModule is provisioned.

In order to create LicenseSessions, a ContentDecryptionModule must be provisioned. A ContentDecryptionModule is not considered provisioned until it meets the requirements for the underlying DRM system. The DRM system may not require provisioning, may only require factory provisioning or may require both factory provisioning and service instance provisioning.

If the ContentDecryptionModule has already has sufficient provisioning, this event will be sent immediately upon creation. If the ContentDecryptionModule has its provisioning removed, then the server will close the channel and also close any active LicenseSessions or Decryptors.

If the DRM system does not require provisioning at all, this event should still be sent to notify the client that it can create LicenseSessions.

Response

<EMPTY>

SetServerCertificate

Sets the certificate to be used for encrypting outgoing messages.

  • request certificate a buffer containing the certificate to be used.
  • error an Error indicating the reason for failure.

Request

NameType
certificate vector<uint8>

Response

NameType
payload ContentDecryptionModule_SetServerCertificate_Result

KeySystem

Defined in fuchsia.media.drm/services.fidl

AddDataStore

Adds a client data store to the KeySystem.

DRM systems generate data on behalf of clients as part of provisioning and license management. This data is only usable by the DRM system, but the client is the owner of the data. The client controls the lifetime of the data and can select which data set is to be used for a ContentDecryptionModule.

  • request data_store_id a client-assigned identifier for the data store. The identifier is scoped to the KeySystem channel. It is invalid for the client to provide NO_DATA_STORE or an already added data_store_id and the server should close the channel.
  • request data_store_params the parameters to be used for this data store.

Request

NameType
data_store_id uint32
data_store_params DataStoreParams

Response

NameType
payload KeySystem_AddDataStore_Result

CreateContentDecryptionModule2

Creates a new ContentDecryptionModule.

Creates a ContentDecryptionModule that will use the associated data store, if provided. If NO_DATA_STORE is provided for the data_store_id, then the created ContentDecryptionModule will only support LicenseSessions of LicenseSessionType.TEMPORARY type. If a data_store_id is provided, then the created ContentDecryptionModule will persist data to that data store. If the KeySystem requires a data store and NO_DATA_STORE was provided or the KeySystem does not support data stores and one was provided, then the server should close the cdm.

If the data_store_id does not exist, the cdm will be closed with a ZX_ERR_NOT_FOUND epitaph.

  • request data_store_id the data store that should be used by the ContentDecryptionModule.
  • request cdm the server endpoint of the ContentDecryptionModule.

Request

NameType
data_store_id uint32
cdm server_end<ContentDecryptionModule>

DestroyDataStoreAndConfirm

Destroys the client data store.

This method permanently removes this data store and all of its contents. All provisioning and license data will be removed and any active ContentDecryptionModule using this data store will be closed.

  • request data_store_id the client-assigned identifier for the data store to be removed. It is invalid for the client to provide NO_DATA_STORE or a data_store_id value that has not previously been added or has been previously destroyed.

Request

NameType
data_store_id uint32

Response

<EMPTY>

GetProperties

Get various static properties of the KeySystem implementation.

The properties include the capabilities and requirements of the KeySystem, such as whether the implementation is hardware-based or whether it requires client-provided data stores to operate.

  • response properties the properties of the KeySystem implementation.

Request

<EMPTY>

Response

NameType
properties KeySystemProperties

LicenseSession

Defined in fuchsia.media.drm/license_session.fidl

A protocol for exchanging messages pertaining to the establishment of a media license and the encryption keys associated with it.

If the client closes the LicenseSession, any derived Decryptors will also be closed as the encryption keys will no longer be maintained.

CreateDecryptor

Creates a Decryptor fuchsia.media/StreamProcessor to be used to decrypt content.

This decryptor would be restricted to only having access to the keys maintained by this LicenseSession.

  • request params the parameters with which to create the decryptor.
  • request decryptor the server endpoint of the fuchsia.media/StreamProcessor.

Request

NameType
params DecryptorParams
decryptor server_end<fuchsia.media/StreamProcessor>

GenerateLicenseRelease

Initiates the release process for the license session.

This will cause the LicenseSession to destroy the license and/or keys associated with the session. If the session is temporary, the session will send the reply for this request once the license has been destroyed and then close the LicenseSession channel. If the session is persistent, the session will send the reply for this request once the license has been destroyed and then it will generate a license release type 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.

  • error an Error indicating the reason for failure.

Request

<EMPTY>

Response

NameType
payload LicenseSession_GenerateLicenseRelease_Result

GenerateLicenseRequest

Generates 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.

  • error an Error indicating the reason for failure.

Request

NameType
init_data LicenseInitData

Response

NameType
payload LicenseSession_GenerateLicenseRequest_Result

OnKeyStatesChanged

Provides updated key state information.

Some examples on when this might occur would be on license creation, expiration, renewal, or load of a persistent license session.

  • response key_states a list of the key_ids and their related KeyStatusCodes

Response

NameType
key_states vector<KeyState>

OnLicenseMessageGenerated

Provides a LicenseMessage that should be sent to the license server.

The client is responsible for transporting this message to the license server.

  • response request a message from the LicenseSession that the client should send to the license server.

Response

NameType
request LicenseMessage

OnReady

Indicates that the LicenseSession has successfully initialized.

This is always the first message sent by the LicenseSession.

Response

<EMPTY>

ProcessLicenseResponse

Updates 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.

  • request response a message from the license server to update the state of the LicenseSession.
  • error an Error indicating the reason for failure.

Request

NameType
response LicenseServerMessage

Response

NameType
payload LicenseSession_ProcessLicenseResponse_Result

PlayReady

Defined in fuchsia.media.drm/services.fidl

A service hub providing access to the PlayReady key system.

If the client closes the PlayReady channel, derived ContentDecryptionModules will remain active.

AddDataStore

Adds a client data store to the KeySystem.

DRM systems generate data on behalf of clients as part of provisioning and license management. This data is only usable by the DRM system, but the client is the owner of the data. The client controls the lifetime of the data and can select which data set is to be used for a ContentDecryptionModule.

  • request data_store_id a client-assigned identifier for the data store. The identifier is scoped to the KeySystem channel. It is invalid for the client to provide NO_DATA_STORE or an already added data_store_id and the server should close the channel.
  • request data_store_params the parameters to be used for this data store.

Request

NameType
data_store_id uint32
data_store_params DataStoreParams

Response

NameType
payload KeySystem_AddDataStore_Result

CreateContentDecryptionModule2

Creates a new ContentDecryptionModule.

Creates a ContentDecryptionModule that will use the associated data store, if provided. If NO_DATA_STORE is provided for the data_store_id, then the created ContentDecryptionModule will only support LicenseSessions of LicenseSessionType.TEMPORARY type. If a data_store_id is provided, then the created ContentDecryptionModule will persist data to that data store. If the KeySystem requires a data store and NO_DATA_STORE was provided or the KeySystem does not support data stores and one was provided, then the server should close the cdm.

If the data_store_id does not exist, the cdm will be closed with a ZX_ERR_NOT_FOUND epitaph.

  • request data_store_id the data store that should be used by the ContentDecryptionModule.
  • request cdm the server endpoint of the ContentDecryptionModule.

Request

NameType
data_store_id uint32
cdm server_end<ContentDecryptionModule>

DestroyDataStoreAndConfirm

Destroys the client data store.

This method permanently removes this data store and all of its contents. All provisioning and license data will be removed and any active ContentDecryptionModule using this data store will be closed.

  • request data_store_id the client-assigned identifier for the data store to be removed. It is invalid for the client to provide NO_DATA_STORE or a data_store_id value that has not previously been added or has been previously destroyed.

Request

NameType
data_store_id uint32

Response

<EMPTY>

GetProperties

Get various static properties of the KeySystem implementation.

The properties include the capabilities and requirements of the KeySystem, such as whether the implementation is hardware-based or whether it requires client-provided data stores to operate.

  • response properties the properties of the KeySystem implementation.

Request

<EMPTY>

Response

NameType
properties KeySystemProperties

ProvisioningFetcher

Defined in fuchsia.media.drm/provisioning.fidl

Fetches provisioning from a server.

Some DRM systems require additional runtime provisioning (also known as individualization). This is a process by which a device receives DRM credentials (e.g. a certificate) to use for license acquisition for an individual content provider.

DRM systems use the ProvisioningFetcher to fetch the provisioning when the system determines that it is needed.

Fetch

Fetches provisioning from a server.

Called by the DRM system when it is in need of provisioning.

Request

NameType
request ProvisioningRequest

Response

NameType
response ProvisioningResponse

Widevine

Defined in fuchsia.media.drm/services.fidl

A service hub providing access to the Widevine key system.

If the client closes the Widevine channel, derived ContentDecryptionModules will remain active.

AddDataStore

Adds a client data store to the KeySystem.

DRM systems generate data on behalf of clients as part of provisioning and license management. This data is only usable by the DRM system, but the client is the owner of the data. The client controls the lifetime of the data and can select which data set is to be used for a ContentDecryptionModule.

  • request data_store_id a client-assigned identifier for the data store. The identifier is scoped to the KeySystem channel. It is invalid for the client to provide NO_DATA_STORE or an already added data_store_id and the server should close the channel.
  • request data_store_params the parameters to be used for this data store.

Request

NameType
data_store_id uint32
data_store_params DataStoreParams

Response

NameType
payload KeySystem_AddDataStore_Result

CreateContentDecryptionModule2

Creates a new ContentDecryptionModule.

Creates a ContentDecryptionModule that will use the associated data store, if provided. If NO_DATA_STORE is provided for the data_store_id, then the created ContentDecryptionModule will only support LicenseSessions of LicenseSessionType.TEMPORARY type. If a data_store_id is provided, then the created ContentDecryptionModule will persist data to that data store. If the KeySystem requires a data store and NO_DATA_STORE was provided or the KeySystem does not support data stores and one was provided, then the server should close the cdm.

If the data_store_id does not exist, the cdm will be closed with a ZX_ERR_NOT_FOUND epitaph.

  • request data_store_id the data store that should be used by the ContentDecryptionModule.
  • request cdm the server endpoint of the ContentDecryptionModule.

Request

NameType
data_store_id uint32
cdm server_end<ContentDecryptionModule>

DestroyDataStoreAndConfirm

Destroys the client data store.

This method permanently removes this data store and all of its contents. All provisioning and license data will be removed and any active ContentDecryptionModule using this data store will be closed.

  • request data_store_id the client-assigned identifier for the data store to be removed. It is invalid for the client to provide NO_DATA_STORE or a data_store_id value that has not previously been added or has been previously destroyed.

Request

NameType
data_store_id uint32

Response

<EMPTY>

GetProperties

Get various static properties of the KeySystem implementation.

The properties include the capabilities and requirements of the KeySystem, such as whether the implementation is hardware-based or whether it requires client-provided data stores to operate.

  • response properties the properties of the KeySystem implementation.

Request

<EMPTY>

Response

NameType
properties KeySystemProperties

STRUCTS

ContentDecryptionModule_SetServerCertificate_Response

Defined in fuchsia.media.drm/content_decryption.fidl

<EMPTY>

KeySystem_AddDataStore_Response

Defined in fuchsia.media.drm/services.fidl

<EMPTY>

LicenseInitData

Defined in fuchsia.media.drm/license_session.fidl

FieldTypeDescriptionDefault
type LicenseInitDataType

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.

No default
data vector<uint8> No default

LicenseMessage resource

Defined in fuchsia.media.drm/license_session.fidl

A message originating from the LicenseSession that the caller must route to the license server.

FieldTypeDescriptionDefault
type LicenseMessageType No default
message fuchsia.mem/Buffer No default

LicenseServerMessage resource

Defined in fuchsia.media.drm/license_session.fidl

A message originating from the license server that the caller must provide to the LicenseSession via ProcessLicenseServerMessage.

FieldTypeDescriptionDefault
message fuchsia.mem/Buffer No default

LicenseSession_GenerateLicenseRelease_Response

Defined in fuchsia.media.drm/license_session.fidl

<EMPTY>

LicenseSession_GenerateLicenseRequest_Response

Defined in fuchsia.media.drm/license_session.fidl

<EMPTY>

LicenseSession_ProcessLicenseResponse_Response

Defined in fuchsia.media.drm/license_session.fidl

<EMPTY>

ProvisioningRequest resource

Defined in fuchsia.media.drm/provisioning.fidl

Message passed to a ProvisioningFetcher by a DRM system, to pass on to the provisioning server.

FieldTypeDescriptionDefault
default_provisioning_server_url fuchsia.url/Url

A suggested server to send the message to.

No default
message fuchsia.mem/Buffer

The DRM system specific provisioning request message body to be delivered to the provisioning server. The VMO must at least have the following rights: ZX_RIGHT_READ ZX_RIGHT_TRANSFER

No default

ProvisioningResponse resource

Defined in fuchsia.media.drm/provisioning.fidl

Message originating from the provisioning server that the ProvisioningFetcher must pass back to the DRM system.

FieldTypeDescriptionDefault
message fuchsia.mem/Buffer

The DRM system specific provisioning response message body received from the provisioning server. The VMO must at least have the following rights: ZX_RIGHT_READ ZX_RIGHT_TRANSFER

No default

ENUMS

Error strict

Type: uint32

Defined in fuchsia.media.drm/error.fidl

Standard error codes for DRM related protocols. Many of the error code names originate from the W3C Encrypted Media Extensions specification to cover common CDM exception cases.

W3C Encrypted Media Extensions: https://www.w3.org/TR/encrypted-media

NameValueDescription
1

An error that occurs when the client provides invalid parameter data to the server, such as an invalid license response message.

2

An error that occurs when a requested operation is not supported by the CDM, such as a license generation request with an unknown initialization data type.

3

An error that occurs when the CDM is not in a proper state to perform the requested operation, such as calling LicenseSession.GenerateLicenseRequest when the LicenseSession has already started the license release process.

4

An error that occurs when a requested action would exceed allowable limits, such as attempting to load an already opened session.

100

An internal, unexpected error that is not actionable by the client.

101

An error that occurs when the CDM is not usable because it requires additional provisioning.

KeyStatus strict

Type: uint32

Defined in fuchsia.media.drm/license_session.fidl

NameValueDescription
0

The key is currently usable for decryption.

1

The Key is no longer usable for decryption because it has expired.

2

The Key is no longer usable for decryption, but is still known to the CDM.

3

The Key has output restrictions that cannot currently be met and may be unusable for decryption.

4

The Key has output restrictions that cannot currently be met. The Key may be usable for decryption with lower quality content.

5

The Key is not yet known or usable for decryption.

6

The Key is not usable for decryption because of an internal error.

LicenseMessageType strict

Type: uint32

Defined in fuchsia.media.drm/license_session.fidl

NameValueDescription
1
2
3

LicenseSessionType strict

Type: uint32

Defined in fuchsia.media.drm/license_session.fidl

NameValueDescription
1

A session for which the license, keys, and record of the session are not persisted.

2

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

Requirement strict

Type: uint32

Defined in fuchsia.media.drm/properties.fidl

NameValueDescription
1
2
3

TABLES

DataStoreParams resource

Defined in fuchsia.media.drm/services.fidl

OrdinalFieldTypeDescription
data_directory fuchsia.io/Directory

Directory into which this data store should write persistent provisioning and licenses, or their proxy. This field is required.

provision_server_certificate vector<uint8>

Certificate to use for encrypting provisioning messages. This field is optional.

provisioning_fetcher ProvisioningFetcher

The client endpoint of the ProvisioningFetcher to be used when this data store requires provisioning. If the DRM system requires data store provisioning, then this field is required to be set. Otherwise, it is optional.

DecryptorParams

Defined in fuchsia.media.drm/content_decryption.fidl

OrdinalFieldTypeDescription
require_secure_mode bool

Requires the decryptor fuchsia.media/StreamProcessor to only output to secure buffers.

input_details fuchsia.media/FormatDetails

Initial format details for the fuchsia.media/StreamProcessor.

KeyState

Defined in fuchsia.media.drm/license_session.fidl

OrdinalFieldTypeDescription
key_id fuchsia.media/KeyId
status KeyStatus

KeySystemProperties

Defined in fuchsia.media.drm/properties.fidl

OrdinalFieldTypeDescription
features Features

Various flags indicating supported features of the KeySystem. This field is required.

data_store_requirement Requirement

Indicates the data store requirements of the KeySystem.

See KeySystem.ContentDecryptionModule2 for implications of different values. This field is required.

license_session_types vector<LicenseSessionType>

Indicates the supported license session types. This field is required and the list must not be empty.

init_data_types vector<string>

Indicates the supported init data types. This field is required and the list must not be empty.

encryption_schemes vector<string>

Indicates the supported encryption schemes. This field is required and the list must not be empty.

UNIONS

ContentDecryptionModule_SetServerCertificate_Result strict

Defined in fuchsia.media.drm/content_decryption.fidl

OrdinalVariantTypeDescription
response ContentDecryptionModule_SetServerCertificate_Response
err Error

KeySystem_AddDataStore_Result strict

Defined in fuchsia.media.drm/services.fidl

OrdinalVariantTypeDescription
response KeySystem_AddDataStore_Response
err Error

LicenseSession_GenerateLicenseRelease_Result strict

Defined in fuchsia.media.drm/license_session.fidl

OrdinalVariantTypeDescription
response LicenseSession_GenerateLicenseRelease_Response
err Error

LicenseSession_GenerateLicenseRequest_Result strict

Defined in fuchsia.media.drm/license_session.fidl

OrdinalVariantTypeDescription
response LicenseSession_GenerateLicenseRequest_Response
err Error

LicenseSession_ProcessLicenseResponse_Result strict

Defined in fuchsia.media.drm/license_session.fidl

OrdinalVariantTypeDescription
response LicenseSession_ProcessLicenseResponse_Response
err Error

BITS

Features strict

Type: uint32

Defined in fuchsia.media.drm/properties.fidl

NameValueDescription
1

All key management and crypto operations are performed in a hardware based trusted execution environment. If not set, a software implementation is used.

2

Decrypted data can be written to hardware secure buffers.

CONSTANTS

NameValueTypeDescription
LICENSE_INIT_DATA_TYPE_CENC cenc String
LICENSE_INIT_DATA_TYPE_HLS hls String
LICENSE_INIT_DATA_TYPE_KEYIDS keyids String
LICENSE_INIT_DATA_TYPE_WEBM webm String
MAX_HDCP_VERSION_SIZE 16 uint32
MAX_LICENSE_INIT_DATA_TYPE_SIZE 100 uint32
MAX_SESSION_ID_SIZE 512 uint32
NO_DATA_STORE 0 uint32

A sentinel value for use with KeySystem.CreateContentDecryptionModule2 to create a ContentDecryptionModule without a client data store.

ALIASES

NameValueDescription
EncryptionScheme string
HdcpVersion string[MAX_HDCP_VERSION_SIZE]
LicenseInitDataType string[MAX_LICENSE_INIT_DATA_TYPE_SIZE]
SessionId string[MAX_SESSION_ID_SIZE]