Starboard Module Reference: drm.h

Provides definitions that allow for DRM support, which are common between Player and Decoder interfaces.

Macros

kSbDrmSystemInvalid

An invalid SbDrmSystem.

kSbDrmTicketInvalid

A ticket for callback invocations initiated by the DRM system.

Enums

SbDrmEncryptionScheme

Encryption scheme of the input sample, as defined in ISO/IEC 23001 part 7.

Values

  • kSbDrmEncryptionSchemeAesCtr
  • kSbDrmEncryptionSchemeAesCbc

SbDrmKeyStatus

Status of a particular media key. https://www.w3.org/TR/encrypted-media/#idl-def-mediakeystatus

Values

  • kSbDrmKeyStatusUsable
  • kSbDrmKeyStatusExpired
  • kSbDrmKeyStatusReleased
  • kSbDrmKeyStatusRestricted
  • kSbDrmKeyStatusDownscaled
  • kSbDrmKeyStatusPending
  • kSbDrmKeyStatusError

SbDrmSessionRequestType

The type of the session request. https://www.w3.org/TR/encrypted-media/#idl-def-mediakeymessagetype

Values

  • kSbDrmSessionRequestTypeLicenseRequest
  • kSbDrmSessionRequestTypeLicenseRenewal
  • kSbDrmSessionRequestTypeLicenseRelease
  • kSbDrmSessionRequestTypeIndividualizationRequest

SbDrmStatus

The status of session related operations. Used by SbDrmSessionUpdateRequestFunc, SbDrmSessionUpdatedFunc, and SbDrmServerCertificateUpdatedFunc to indicate the status of the operation. https://w3c.github.io/encrypted-media/#error-names

Values

  • kSbDrmStatusSuccess
  • kSbDrmStatusTypeError
  • kSbDrmStatusNotSupportedError
  • kSbDrmStatusInvalidStateError
  • kSbDrmStatusQuotaExceededError

  • kSbDrmStatusUnknownError

    The kSbDrmStatusUnknownError can be used when the error status cannot be mapped to one of the rest errors. New error codes (if needed) should be added before kSbDrmStatusUnknownError.

Typedefs

SbDrmServerCertificateUpdatedFunc

A callback to notify the caller of SbDrmUpdateServerCertificate() whether the update has been successfully updated or not.

Definition

typedef void(* SbDrmServerCertificateUpdatedFunc) (SbDrmSystem drm_system, void *context, int ticket, SbDrmStatus status, const char *error_message)

SbDrmSessionClosedFunc

A callback for signalling that a session has been closed by the SbDrmSystem.

Definition

typedef void(* SbDrmSessionClosedFunc) (SbDrmSystem drm_system, void *context, const void *session_id, int session_id_size)

SbDrmSessionKeyStatusesChangedFunc

A callback for notifications that the status of one or more keys in a session has been changed. A pointer to an array of all keys key_ids of the session and their new status will be passed along. Any keys not in the list are considered as deleted.

number_of_keys is the number of keys.

key_ids is a pointer to an array of keys.

key_statuses is a pointer of a vector contains the status of each key.

Definition

typedef void(* SbDrmSessionKeyStatusesChangedFunc) (SbDrmSystem drm_system, void *context, const void *session_id, int session_id_size, int number_of_keys, const SbDrmKeyId *key_ids, const SbDrmKeyStatus *key_statuses)

SbDrmSessionUpdateRequestFunc

A callback that will receive generated session update request when requested from a SbDrmSystem. drm_system will be the DRM system that SbDrmGenerateSessionUpdateRequest() was called on. context will be the same context that was passed into the call to SbDrmCreateSystem().

status is the status of the session request.

type is the status of the session request.

error_message may contain an optional error message when status isn't kSbDrmStatusSuccess to provide more details about the error. It may be NULL if status is kSbDrmStatusSuccess or if no error message can be provided.

ticket will be the same ticket that was passed to SbDrmGenerateSessionUpdateRequest() or kSbDrmTicketInvalid if the update request was generated by the DRM system.

session_id cannot be NULL when ticket is kSbDrmTicketInvalid, even when there was an error generating the request. This allows Cobalt to find and reject the correct Promise corresponding to the associated SbDrmGenerateSessionUpdateRequest().

Definition

typedef void(* SbDrmSessionUpdateRequestFunc) (SbDrmSystem drm_system, void *context, int ticket, SbDrmStatus status, SbDrmSessionRequestType type, const char *error_message, const void *session_id, int session_id_size, const void *content, int content_size, const char *url)

SbDrmSessionUpdatedFunc

A callback for notifications that a session has been added, and subsequent encrypted samples are actively ready to be decoded. drm_system will be the DRM system that SbDrmUpdateSession() was called on. context will be the same context passed into that call to SbDrmCreateSystem().

ticket will be the same ticket that was passed to SbDrmUpdateSession().

status is the status of the session request.

error_message may contain an optional error message when status isn't kSbDrmStatusSuccess to provide more details about the error. It may be NULL if status is kSbDrmStatusSuccess or if no error message can be provided. succeeded is whether the session was successfully updated or not.

Definition

typedef void(* SbDrmSessionUpdatedFunc) (SbDrmSystem drm_system, void *context, int ticket, SbDrmStatus status, const char *error_message, const void *session_id, int session_id_size)

SbDrmSystem

A handle to a DRM system which can be used with either an SbDecoder or an SbPlayer.

Definition

typedef struct SbDrmSystemPrivate* SbDrmSystem

Structs

SbDrmEncryptionPattern

Encryption pattern of the input sample, as defined in ISO/IEC 23001 part 7.

Members

  • uint32_t crypt_byte_block
  • uint32_t skip_byte_block

SbDrmKeyId

Members

  • uint8_t identifier

    The ID of the license (or key) required to decrypt this sample. For PlayReady, this is the license GUID in packed little-endian binary form.

  • int identifier_size

SbDrmSampleInfo

All the optional information needed per sample for encrypted samples.

Members

  • SbDrmEncryptionScheme encryption_scheme

    The encryption scheme of this sample.

  • SbDrmEncryptionPattern encryption_pattern

    The encryption pattern of this sample.

  • uint8_t initialization_vector

    The Initialization Vector needed to decrypt this sample.

  • int initialization_vector_size

  • uint8_t identifier

    The ID of the license (or key) required to decrypt this sample. For PlayReady, this is the license GUID in packed little-endian binary form.

  • int identifier_size

  • int32_t subsample_count

    The number of subsamples in this sample, must be at least 1.

  • constSbDrmSubSampleMapping* subsample_mapping

    The clear/encrypted mapping of each subsample in this sample. This must be an array of subsample_count mappings.

SbDrmSubSampleMapping

A mapping of clear and encrypted bytes for a single subsample. All subsamples within a sample must be encrypted with the same encryption parameters. The clear bytes always appear first in the sample.

Members

  • int32_t clear_byte_count

    How many bytes of the corresponding subsample are not encrypted

  • int32_t encrypted_byte_count

    How many bytes of the corresponding subsample are encrypted.

Functions

SbDrmCloseSession

Clear any internal states/resources related to the specified session_id.

drm_system must not be kSbDrmSystemInvalid. session_id must not be NULL.

Declaration

void SbDrmCloseSession(SbDrmSystem drm_system, const void *session_id, int session_id_size)

SbDrmCreateSystem

Creates a new DRM system that can be used when constructing an SbPlayer or an SbDecoder.

This function returns kSbDrmSystemInvalid if key_system is unsupported.

Also see the documentation of SbDrmGenerateSessionUpdateRequest() and SbDrmUpdateSession() for more details.

key_system: The DRM key system to be created. The value should be in the form of "com.example.somesystem". All letters in the value should be lowercase and will be matched exactly with known DRM key systems of the platform. Note the key system will be matched case sensitive. For more details, refer to https://w3c.github.io/encrypted-media/#dfn-key-system-s

context: A value passed when any of this function's callback parameters are called.

update_request_callback: A function that is called every time after SbDrmGenerateSessionUpdateRequest() is called.

session_updated_callback: A function that is called every time after SbDrmUpdateSession() is called.

key_statuses_changed_callback: A function that can be called to indicate that key statuses have changed.

server_certificate_updated_callback: A function that is called to report whether the server certificate has been successfully updated. It is called once and only once. It is possible that the callback is called before the function returns.

session_closed_callback: A function that can be called to indicate that a session has closed. If NULL is passed for any of the callbacks (update_request_callback, session_updated_callback, key_statuses_changed_callback, server_certificate_updated_callback, or session_closed_callback), then kSbDrmSystemInvalid must be returned.

Declaration

SbDrmSystem SbDrmCreateSystem(const char *key_system, void *context, SbDrmSessionUpdateRequestFunc update_request_callback, SbDrmSessionUpdatedFunc session_updated_callback, SbDrmSessionKeyStatusesChangedFunc key_statuses_changed_callback, SbDrmServerCertificateUpdatedFunc server_certificate_updated_callback, SbDrmSessionClosedFunc session_closed_callback)

SbDrmDestroySystem

Destroys drm_system, which implicitly removes all keys installed in it and invalidates all outstanding session update requests. A DRM system cannot be destroyed unless any associated SbPlayer or SbDecoder has first been destroyed.

All callbacks are guaranteed to be finished when this function returns. As a result, if this function is called from a callback that is passed to SbDrmCreateSystem(), a deadlock will occur.

drm_system: The DRM system to be destroyed. Must not be kSbDrmSystemInvalid.

Declaration

void SbDrmDestroySystem(SbDrmSystem drm_system)

SbDrmGenerateSessionUpdateRequest

Asynchronously generates a session update request payload for initialization_data, of initialization_data_size, in case sensitive type, extracted from the media stream, in drm_system's key system.

This function calls drm_system's update_request_callback function, which is defined when the DRM system is created by SbDrmCreateSystem. When calling that function, this function either sends context (also from SbDrmCreateSystem) and a populated request, or it sends NULL session_id if an error occurred.

drm_system's context may be used to route callbacks back to an object instance.

Callbacks may be called either from the current thread before this function returns or from another thread.

drm_system: The DRM system that defines the key system used for the session update request payload as well as the callback function that is called as a result of the function being called. Must not be kSbDrmSystemInvalid.

ticket: The opaque ID that allows to distinguish callbacks from multiple concurrent calls to SbDrmGenerateSessionUpdateRequest(), which will be passed to update_request_callback as-is. It is the responsibility of the caller to establish ticket uniqueness, issuing multiple requests with the same ticket may result in undefined behavior. The value kSbDrmTicketInvalid must not be used.

type: The case-sensitive type of the session update request payload. Must not be NULL.

initialization_data: The data for which the session update request payload is created. Must not be NULL.

initialization_data_size: The size of the session update request payload.

Declaration

void SbDrmGenerateSessionUpdateRequest(SbDrmSystem drm_system, int ticket, const char *type, const void *initialization_data, int initialization_data_size)

SbDrmGetMetrics

Get the metrics of the underlying drm system.

When it is called on an implementation that supports drm system metrics, it should return a pointer containing the metrics as a blob, encoded using url safe base64 without padding and line wrapping, with the size of the encoded result in size on return. For example, on Android API level 28 or later, it should return the result of MediaDrm.getPropertyByteArray("metrics"), encoded using url safe base64 without padding and line wrapping. On systems using Widevine CE CDM with oemcrypto 16 or later, it should return the metrics retrieved via Cdm::getMetrics(), encoded using url safe base64 without padding and line wrapping. The returned pointer should remain valid and its content should remain unmodified until the next time this function is called on the associated drm_system or the drm_system is destroyed.

When the metrics is empty on supported system, it should return a non-null pointer with size set to 0.

It should return NULL when there is no metrics support in the underlying drm system, or when the drm system implementation fails to retrieve the metrics.

drm_system must not be kSbDrmSystemInvalid. size must not be NULL.

Declaration

const void* SbDrmGetMetrics(SbDrmSystem drm_system, int *size)

SbDrmIsServerCertificateUpdatable

Returns true if server certificate of drm_system can be updated via SbDrmUpdateServerCertificate(). The return value should remain the same during the life time of drm_system.

drm_system: The DRM system to check if its server certificate is updatable. Must not be kSbDrmSystemInvalid.

Declaration

bool SbDrmIsServerCertificateUpdatable(SbDrmSystem drm_system)

SbDrmSystemIsValid

Indicates whether drm_system is a valid SbDrmSystem.

Declaration

static bool SbDrmSystemIsValid(SbDrmSystem drm)

SbDrmTicketIsValid

Indicates whether ticket is a valid ticket.

Declaration

static bool SbDrmTicketIsValid(int ticket)

SbDrmUpdateServerCertificate

Update the server certificate of drm_system. The function can be called multiple times. It is possible that a call to it happens before the callback of a previous call is called. Note that this function should only be called after SbDrmIsServerCertificateUpdatable is called first and returned true.

drm_system: The DRM system whose server certificate is being updated. Must not be kSbDrmSystemInvalid.

ticket: The opaque ID that allows to distinguish callbacks from multiple concurrent calls to SbDrmUpdateServerCertificate(), which will be passed to server_certificate_updated_callback as-is. It is the responsibility of the caller to establish ticket uniqueness, issuing multiple requests with the same ticket may result in undefined behavior. The value kSbDrmTicketInvalid must not be used.

certificate: Pointer to the server certificate data. Must not be NULL.

certificate_size: Size of the server certificate data.

Declaration

void SbDrmUpdateServerCertificate(SbDrmSystem drm_system, int ticket, const void *certificate, int certificate_size)

SbDrmUpdateSession

Update session with key, in drm_system's key system, from the license server response. Calls session_updated_callback with context and whether the update succeeded. context may be used to route callbacks back to an object instance. The key must not be NULL.

drm_system must not be kSbDrmSystemInvalid. ticket is the opaque ID that allows to distinguish callbacks from multiple concurrent calls to SbDrmUpdateSession(), which will be passed to session_updated_callback as-is. It is the responsibility of the caller to establish ticket uniqueness, issuing multiple calls with the same ticket may result in undefined behavior.

Once the session is successfully updated, an SbPlayer or SbDecoder associated with that DRM key system will be able to decrypt encrypted samples.

drm_system's session_updated_callback may called either from the current thread before this function returns or from another thread. The session_id must not be NULL.

Declaration

void SbDrmUpdateSession(SbDrmSystem drm_system, int ticket, const void *key, int key_size, const void *session_id, int session_id_size)