fuchsia.media.drm

PROTOCOLS

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.

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

NameType

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
result ContentDecryptionModule_SetServerCertificate_Result

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.

Request

NameType
session_type LicenseSessionType
license_session request<LicenseSession>

Response

NameType
session_id 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 string
license_session request<LicenseSession>

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 request<fuchsia.media/StreamProcessor>

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 string

Response

NameType
key_status KeyStatus

GetSupportedEncryptionModes

Queries for the list of supported encryption modes.

The common encryption modes include 'cenc', 'cbc1', 'cens', or 'cbcs'.

  • response encryption_modes a list of the supported encryption modes.

Request

NameType

Response

NameType
encryption_modes vector<string>

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.

OnReady

Indicates that the LicenseSession has successfully initialized.

This is always the first message sent by the LicenseSession.

Response

NameType

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.

  • request init_data container-specific data that is used to generate a LicenseMessageType.REQUEST LicenseMessage.
  • error an Error indicating the reason for failure.

Request

NameType
init_data LicenseInitData

Response

NameType
result LicenseSession_GenerateLicenseRequest_Result

GenerateLicenseRelease

Inititiates the release process for the license session.

This will cause the LicenseSession 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.

Request

NameType

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
result LicenseSession_ProcessLicenseResponse_Result

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 request<fuchsia.media/StreamProcessor>

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

OnKeysChanged

Provides updated key status information.

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

Response

NameType
key_info vector<KeyInfo>

Provisioner

Defined in fuchsia.media.drm/provisioning.fidl

A protocol for exchanging messages pertaining to the establishment of a provisioning certificate.

GetStatus

Gets the current status of provisioning for this service instance.

  • response status indicates whether the service instance is sufficiently provisioned.

Request

NameType

Response

NameType
status ProvisioningStatus

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
result Provisioner_SetServerCertificate_Result

GenerateProvisioningRequest

Generates a provisioning request for this service instance.

If the underlying DRM system requires provisioning for individual providers (the owner of the service instance), then this method can be used to generate ProvisioningRequests. This message must be routed to the provisioning server by the client and the server's response must be routed back to ProcessProvisioningResponse.

  • response request a ProvisioningRequest message to be provided to a provisioning server in order to receiving a provisioning certificate.

Request

NameType

Response

NameType
request ProvisioningRequest

ProcessProvisioningResponse

Updates the Provisioner with a message from the provisioning server.

Not all underlying DRM systems will require provisioning for individual providers. If they do, this method will carry the provisioning message to the service instance so that it may persistently store the provider certificate.

  • request response a ProvisioningResponse from the provisioning server. It should contain the provisioning certificate.
  • error an Error indicating the reason for failure.

Request

NameType
response ProvisioningResponse

Response

NameType
result Provisioner_ProcessProvisioningResponse_Result

RemoveProvisioning

Removes all provider based provisioning for this service instance.

Any active ContentDecryptionModules on this service instance that relied on this provisioning will be closed, as they will no longer be usable without it. This does not impact any factory provisioning.

Request

NameType

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

CreateContentDecryptionModule

Creates a new ContentDecryptionModule.

  • request cdm the server endpoint of the ContentDecryptionModule.

Request

NameType
cdm request<ContentDecryptionModule>

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 and Provisions will remain active.

CreateContentDecryptionModule

Creates a new ContentDecryptionModule.

The ContentDecryptionModules created will share their persistent state, but will not share active sessions.

  • request cdm the server endpoint of the ContentDecryptionModule.

Request

NameType
cdm request<ContentDecryptionModule>

CreateProvisioner

Creates a new Provisioner.

There can only be one active Provisioner for each service instance.

  • request provisioner the server endpoint of the Provisioner.

Request

NameType
provisioner request<Provisioner>

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.

CreateContentDecryptionModule

Creates a new ContentDecryptionModule.

The ContentDecryptionModules created will share their persistent state, but will not share active sessions.

  • request cdm the server endpoint of the ContentDecryptionModule.

Request

NameType
cdm request<ContentDecryptionModule>

STRUCTS

ContentDecryptionModule_SetServerCertificate_Response

generated

NameTypeDescriptionDefault

LicenseSession_GenerateLicenseRequest_Response

generated

NameTypeDescriptionDefault

LicenseSession_ProcessLicenseResponse_Response

generated

NameTypeDescriptionDefault

LicenseInitData

Defined in fuchsia.media.drm/license_session.fidl

NameTypeDescriptionDefault
type string 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

Defined in fuchsia.media.drm/license_session.fidl

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

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

LicenseServerMessage

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.

NameTypeDescriptionDefault
message fuchsia.mem/Buffer No default

KeyInfo

Defined in fuchsia.media.drm/license_session.fidl

NameTypeDescriptionDefault
key_id fuchsia.media/KeyId No default
status KeyStatus No default

Provisioner_SetServerCertificate_Response

generated

NameTypeDescriptionDefault

Provisioner_ProcessProvisioningResponse_Response

generated

NameTypeDescriptionDefault

ProvisioningRequest

Defined in fuchsia.media.drm/provisioning.fidl

A message originating from the Provisioner that the caller must route to the provisioning server.

NameTypeDescriptionDefault
default_provisioning_server_url string? An optional server to send the ProvisioningRequest to. This field is not required to be set and the client is not required to use it if one is provided. No default
message fuchsia.mem/Buffer No default

ProvisioningResponse

Defined in fuchsia.media.drm/provisioning.fidl

A message originating from the provisioning server that the caller must provide to Provisioner.ProcessProvisioningResponse.

NameTypeDescriptionDefault
message fuchsia.mem/Buffer No default

ENUMS

KeyStatus

Type: uint32

Defined in fuchsia.media.drm/content_decryption.fidl

NameValueDescription
USABLE 0
EXPIRED 1
RELEASED 2
OUTPUT_RESTRICTED 3
OUTPUT_DOWNSCALED 4
STATUS_PENDING 5
INTERNAL_ERROR 6

Error

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
TYPE 1 An error that occurs when the client provides invalid parameter data to the server, such as an invalid license response message.
NOT_SUPPORTED 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.
INVALID_STATE 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.
QUOTA_EXCEEDED 4 An error that occurs when a requested action would exceed allowable limits, such as attempting to load an already opened session.
INTERNAL 100 An internal, unexpected error that is not actionable by the client.
NOT_PROVISIONED 101 An error that occurs when the CDM is not usable because it requires additional provisioning.

LicenseSessionType

Type: uint32

Defined in fuchsia.media.drm/license_session.fidl

NameValueDescription
TEMPORARY 1 A session for which the license, keys, and record of the session are not persisted.
PERSISTENT_LICENSE 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().
PERSISTENT_USAGE_RECORD 3 A session for which the the record of the session will be persisted, but the keys and license will not be.

LicenseMessageType

Type: uint32

Defined in fuchsia.media.drm/license_session.fidl

NameValueDescription
REQUEST 1
RENEWAL 2
RELEASE 3

ProvisioningStatus

Type: uint32

Defined in fuchsia.media.drm/provisioning.fidl

NameValueDescription
NOT_PROVISIONED 1
PROVISIONED 2

TABLES

DecryptorParams

Defined in fuchsia.media.drm/content_decryption.fidl

OrdinalNameTypeDescription
1 require_secure_mode bool Requires the decryptor fuchsia.media/StreamProcessor to only output to secure buffers.
2 input_details fuchsia.media/FormatDetails Initial format details for the fuchsia.media/StreamProcessor.

UNIONS

ContentDecryptionModule_SetServerCertificate_Result

generated

NameTypeDescription
response ContentDecryptionModule_SetServerCertificate_Response
err Error

LicenseSession_GenerateLicenseRequest_Result

generated

NameTypeDescription
response LicenseSession_GenerateLicenseRequest_Response
err Error

LicenseSession_ProcessLicenseResponse_Result

generated

NameTypeDescription
response LicenseSession_ProcessLicenseResponse_Response
err Error

Provisioner_SetServerCertificate_Result

generated

NameTypeDescription
response Provisioner_SetServerCertificate_Response
err Error

Provisioner_ProcessProvisioningResponse_Result

generated

NameTypeDescription
response Provisioner_ProcessProvisioningResponse_Response
err Error

CONSTANTS

NameValueTypeDescription
ENCRYPTION_MODE_CENC cenc String
ENCRYPTION_MODE_CBC1 cbc1 String
ENCRYPTION_MODE_CENS cens String
ENCRYPTION_MODE_CBCS cbcs String
LICENSE_INIT_DATA_TYPE_CENC cenc String
LICENSE_INIT_DATA_TYPE_KEYIDS keyids String
LICENSE_INIT_DATA_TYPE_WEBM webm String
LICENSE_INIT_DATA_TYPE_HLS hls String