Package com.castlabs.android.drm

# Class DrmUtils

java.lang.Object
com.castlabs.android.drm.DrmUtils

public class DrmUtils extends Object
Utility class providing DRM-related functionality for the Android SDK. This class contains methods for handling DRM operations, including: - DRM scheme selection and validation - Key management and status checking - HTTP request execution for DRM operations - Header generation for various DRM schemes - Device security level detection

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `DrmUtils.HttpExecutorException`
  Exception thrown when HTTP execution fails.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static String`
  `PROD_DT_DASHBOARD_URL`
  The production DRM Today dashboard URL
  `static String`
  `STAGING_DT_DASHBOARD_URL`
  The staging DRM Today dashboard URL
  `static String`
  `TEST_DT_DASHBOARD_URL`
  The test DRM Today dashboard URL

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static String`
  `bytesToString(byte[] byteArray)`
  Converts byte array to String representation, used for debugging
  `static UUID`
  `cencFromPlayreadyKID(byte[] decode)`
  Creates a CENC UUID from the decoded playready KeyID
  `static UUID`
  `cencFromPlayreadyKID(String base64KID)`
  Creates a CENC UUID from a base 64 encoded playready key id
  `static CastlabsMediaDrm`
  `createMediaDrm(UUID uuid, boolean forceWidevineL3)`
  Creates a MediaDrm instance for the specified UUID.
  `static UUID`
  `createUuid(byte[] bytes)`
  Create a UUID from a byte array
  `static UUID`
  `createUuid(String base64)`
  Create a UUID from a encoded base64 String
  `static byte[]`
  `executeModifierPost(String url, byte[] data, Map<String,String> requestProperties, HashMap<String,List<String>> responseHeaders, int connectionTimeoutMs, int readTimeoutMs, int acquisitionTimeoutMs, SSLSocketFactory sslSocketFactory, List<ResponseModifier> responseModifiers, int responseType, Object tag)`
  Executes a POST request with response modifiers.
  `static Pair<byte[],Integer>`
  `executePost(Uri uri, byte[] data, Map<String,String> requestProperties)`
  Executes a POST request to the specified URI.
  `static Pair<byte[],Integer>`
  `executePost(String url, byte[] data, Map<String,String> requestProperties)`
  Executes a POST request with the given data and returns the response.
  `static Pair<byte[],Integer>`
  `executePost(String url, byte[] data, Map<String,String> requestProperties, Map<String,List<String>> responseHeaders, int connectTimeoutMs, int readTimeoutMs, int acquisitionTimeoutMs, SSLSocketFactory sslSocketFactory)`
  Executes a POST request.
  `static byte[]`
  `extractPsshData(UUID drmScheme, byte[] data)`
  Extract the atom data in a given PSSH box.
  `static byte[]`
  `generatePlayreadyHeader(byte[] initData, String licenseServerUrl)`
  Takes the raw bytes from a Widevine CENC header and generates a Playready Header Object
  `static byte[]`
  `generateWidvineCencHeader(byte[] keyId, String widevineProviderId, byte[] widevineContentId, String widevinePolicy)`
  Generates a Widevine CENC header
  `static byte[]`
  `generateWidvineCencHeader(UUID cencKeyId, byte[] contentId, String provider, String policy)`
  Generates a Widevine Header from a CENC UUID and a merchant.
  `static byte[]`
  `generateWiseplayHeader(byte[] initData, String licenseServerUrl)`
  Takes the raw bytes from a Widevine CENC header and generates a Wiseplay init data
  `static byte[]`
  `getBytes(UUID uuid)`
  Converts a UUID to bytes
  `static SecurityLevel`
  `getDeviceSecurityLevel(Drm drm)`
  Returns the security level supported by the current device and the given DRM if the devices supports the DRM.
  `static String`
  `getDrmTodayDashboardUrl(String licUrl)`
  Get the Dashboard URLs for the respective Lic urls
  `static String`
  `getDrmTodayIdFromResponseHeader(Map<String,List<String>> responseHeaders)`
  Takes a Hashmap of Response Headers returned by DrmToday and extracts the DrmToday Trace ID to log a url to analyze DRM Response details
  `static com.google.android.exoplayer2.drm.DrmInitData.SchemeData`
  `getFirstSchemeDataByUuid(com.google.android.exoplayer2.drm.DrmInitData drmInitData, UUID uuid)`
  Retrieves scheme data for a given DRM scheme, specified by its UUID.
  `static UUID`
  `getKIDFromPlayreadySchemeData(byte[] decode)`
  Takes a Playready Header Object and extracts the KID converted to CENC or null.
  `static UUID`
  `getKIDFromPlayreadySchemeData(com.google.android.exoplayer2.drm.DrmInitData.SchemeData schemeData)`
  Gets the KID (Key ID) from a PlayReady scheme data.
  `static UUID`
  `getKIDFromPlayreadySchemeData(String data)`
  Takes a Base64 encoded string representation of a Playready Header Object and extracts the KID converted to CENC or null.
  `static UUID`
  `getKIDFromWidevineHeader(byte[] wvHeader)`
  Gets the KID (Key ID) from a Widevine header.
  `static UUID`
  `getKIDFromWidevineSchemeData(com.google.android.exoplayer2.drm.DrmInitData.SchemeData schemeData)`
  Gets the KID (Key ID) from a Widevine scheme data.
  `static Set<Drm>`
  `getSupportedDRM()`
  Returns an unmodifiable Set of currently supported DRM based on the device and player plugins.
  `static boolean`
  `isDisabled(Drm drm, KeyStatus keyStatus)`
  Checks if a track with specified DRM and key status should be disabled.
  `static boolean`
  `isDisabled(KeyStatus keyStatus)`
  Checks if a track with specified key status should be disabled.
  `static boolean`
  `isDrmSupported(Drm drm)`
  Helper function.
  `static boolean`
  `isPlayreadyHeader(byte[] data)`
  Checks if the given data represents a Playready Header object.
  `static boolean`
  `isWidevineHeader(byte[] data)`
  Checks if the given data represents a Widevine Header object.
  `static Drm`
  `selectAudioDrm(Drm videoDrm, Drm audioDrm)`
  Select the best available DRM if no explicit DRM is specified.
  `static Drm`
  `selectAudioDrm(Drm videoDrm, Drm audioDrm, Set<Drm> excludeDrms)`
  Selects the appropriate audio DRM based on video DRM and exclusions.
  `static Drm`
  `selectBestDrm(Drm drm)`
  Select the best available DRM if no explicit DRM is specified.
  `static Drm`
  `selectBestDrmExcluded(Set<Drm> excludeDrms)`
  Selects the best available DRM from a set of DRMs, excluding specified ones.

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### STAGING_DT_DASHBOARD_URL

    @NonNull public static String STAGING_DT_DASHBOARD_URL
    The staging DRM Today dashboard URL

  - ### TEST_DT_DASHBOARD_URL

    @NonNull public static String TEST_DT_DASHBOARD_URL
    The test DRM Today dashboard URL

  - ### PROD_DT_DASHBOARD_URL

    @NonNull public static String PROD_DT_DASHBOARD_URL
    The production DRM Today dashboard URL

- ## Method Details

  - ### bytesToString

    @NonNull public static String bytesToString(@Nullable byte[] byteArray)
    Converts byte array to String representation, used for debugging
    Parameters:
      `byteArray` - The byte array
    Returns:
      String representation

  - ### isDisabled

    public static boolean isDisabled(@Nullable Drm drm, @Nullable KeyStatus keyStatus)
    Checks if a track with specified DRM and key status should be disabled.
    Parameters:
      `drm` - The DRM system to check
      `keyStatus` - The key status to check
    Returns:
      true if the track with specified `Drm` and `KeyStatus` is not playable and should be disabled, false otherwise

  - ### isDisabled

    public static boolean isDisabled(@Nullable KeyStatus keyStatus)
    Checks if a track with specified key status should be disabled.
    Parameters:
      `keyStatus` - The key status to check
    Returns:
      true if the track with specified `KeyStatus` is not playable and should be disabled, false otherwise

  - ### selectBestDrm

    @Nullable public static Drm selectBestDrm(@Nullable Drm drm)
    Select the best available DRM if no explicit DRM is specified.
    Parameters:
      `drm` - The source DRM
    Returns:
      The source DRM or the best available DRM if the source selection is `Drm.BestAvailable`

  - ### selectBestDrmExcluded

    @Nullable public static Drm selectBestDrmExcluded(@Nullable Set<Drm> excludeDrms)
    Selects the best available DRM from a set of DRMs, excluding specified ones.
    Parameters:
      `excludeDrms` - Set of DRMs to exclude from selection
    Returns:
      The best available DRM, or null if none available

  - ### selectAudioDrm

    public static Drm selectAudioDrm(@NonNull Drm videoDrm, @Nullable Drm audioDrm)
    Select the best available DRM if no explicit DRM is specified.
    Parameters:
      `videoDrm` - The video DRM system
      `audioDrm` - The video DRM system
    Returns:
      Selects the audio drm system based on the given selection and the device

  - ### selectAudioDrm

    @Nullable public static Drm selectAudioDrm(@NonNull Drm videoDrm, @Nullable Drm audioDrm, @NonNull Set<Drm> excludeDrms)
    Selects the appropriate audio DRM based on video DRM and exclusions.
    Parameters:
      `videoDrm` - The video DRM being used
      `audioDrm` - The audio DRM to use, or null for default
      `excludeDrms` - Set of DRMs to exclude from selection
    Returns:
      The selected audio DRM

  - ### executeModifierPost

    public static byte[] executeModifierPost(@NonNull String url, @Nullable byte[] data, @Nullable Map<String,String> requestProperties, @Nullable HashMap<String,List<String>> responseHeaders, int connectionTimeoutMs, int readTimeoutMs, int acquisitionTimeoutMs, @Nullable SSLSocketFactory sslSocketFactory, @Nullable List<ResponseModifier> responseModifiers, int responseType, @Nullable Object tag) throws IOException
    Executes a POST request with response modifiers.
    Parameters:
      `url` - The URL to send the request to
      `data` - The data to send in the request body
      `requestProperties` - Additional properties to include in the request
      `responseHeaders` - Map to store response headers
      `connectionTimeoutMs` - Connection timeout in milliseconds
      `readTimeoutMs` - Read timeout in milliseconds
      `acquisitionTimeoutMs` - Acquisition timeout in milliseconds
      `sslSocketFactory` - SSL socket factory for secure connections
      `responseModifiers` - List of response modifiers to apply
      `responseType` - Type of response expected
      `tag` - Optional object tag propagated to response modifiers
    Returns:
      The response data
    Throws:
      `IOException` - If an I/O error occurs

  - ### executePost

    @NonNull public static Pair<byte[],Integer> executePost(Uri uri, byte[] data, Map<String,String> requestProperties) throws IOException
    Executes a POST request to the specified URI.
    Parameters:
      `uri` - The URI to send the request to
      `data` - The data to send in the request body
      `requestProperties` - Additional properties to include in the request
    Returns:
      A pair containing the response data and status code
    Throws:
      `IOException` - If an I/O error occurs

  - ### executePost

    @NonNull public static Pair<byte[],Integer> executePost(String url, byte[] data, Map<String,String> requestProperties) throws IOException
    Executes a POST request with the given data and returns the response.
    Parameters:
      `url` - The URL to send the POST request to
      `data` - The data to send in the POST request
      `requestProperties` - Additional HTTP request properties to include
    Returns:
      A pair containing the response data and HTTP status code
    Throws:
      `IOException` - if an I/O error occurs during the request

  - ### executePost

    @NonNull public static Pair<byte[],Integer> executePost(String url, byte[] data, Map<String,String> requestProperties, @Nullable Map<String,List<String>> responseHeaders, int connectTimeoutMs, int readTimeoutMs, int acquisitionTimeoutMs, @Nullable SSLSocketFactory sslSocketFactory) throws IOException
    Executes a POST request.
    Parameters:
      `url` - The URL to connect to.
      `data` - The data to post. Null if there is no data to post.
      `requestProperties` - A map of request properties.
      `responseHeaders` - A map where response headers will be stored.
      `connectTimeoutMs` - The connection timeout in milliseconds.
      `readTimeoutMs` - The read timeout in milliseconds.
      `acquisitionTimeoutMs` - The acquisition timeout in milliseconds.
      `sslSocketFactory` - The SSL socket factory to use, or null to use the default.
    Returns:
      A pair containing the response body as a byte array and the response code.
    Throws:
      `IOException` - If an error occurs during the request.

  - ### generateWidvineCencHeader

    public static byte[] generateWidvineCencHeader(@NonNull UUID cencKeyId, @NonNull byte[] contentId, @NonNull String provider, @NonNull String policy)
    Generates a Widevine Header from a CENC UUID and a merchant. The key ID will be used for both keyID and contentID in the generated header.
    Parameters:
      `cencKeyId` - the CENC key ID
      `contentId` - the content ID
      `provider` - the provider
      `policy` - the policy
    Returns:
      The generated Widevine CENC header

  - ### cencFromPlayreadyKID

    public static UUID cencFromPlayreadyKID(String base64KID)
    Creates a CENC UUID from a base 64 encoded playready key id
    Parameters:
      `base64KID` - the base 64 encoded playready key ID
    Returns:
      Teh CENC UUID

  - ### cencFromPlayreadyKID

    public static UUID cencFromPlayreadyKID(byte[] decode)
    Creates a CENC UUID from the decoded playready KeyID
    Parameters:
      `decode` - the decoded playready key id
    Returns:
      The CENC UUID

  - ### getKIDFromPlayreadySchemeData

    public static UUID getKIDFromPlayreadySchemeData(String data)
    Takes a Base64 encoded string representation of a Playready Header Object and extracts the KID converted to CENC or null. See this Document for the spec and what data are expected.
    Parameters:
      `data` - the base64 encoded data
    Returns:
      The KIDs or null
    Throws:
      `IllegalArgumentException` - in case parsing fails

  - ### getDrmTodayIdFromResponseHeader

    @Nullable public static String getDrmTodayIdFromResponseHeader(@Nullable Map<String,List<String>> responseHeaders)
    Takes a Hashmap of Response Headers returned by DrmToday and extracts the DrmToday Trace ID to log a url to analyze DRM Response details
    Parameters:
      `responseHeaders` - HashMap of DrmToday's Response Headers
    Returns:
      The Trace ID for the Request

  - ### getDrmTodayDashboardUrl

    @Nullable public static String getDrmTodayDashboardUrl(@NonNull String licUrl)
    Get the Dashboard URLs for the respective Lic urls
    Parameters:
      `licUrl` - License URL for the content
    Returns:
      The Dashboard URL for the corresponding LIC url

  - ### getKIDFromPlayreadySchemeData

    @Nullable public static UUID getKIDFromPlayreadySchemeData(byte[] decode)
    Takes a Playready Header Object and extracts the KID converted to CENC or null. See this Document for the spec and what data are expected.
    Parameters:
      `decode` - the header object
    Returns:
      The KIDs or null
    Throws:
      `IllegalArgumentException` - in case parsing fails

  - ### getKIDFromPlayreadySchemeData

    @Nullable public static UUID getKIDFromPlayreadySchemeData(@NonNull com.google.android.exoplayer2.drm.DrmInitData.SchemeData schemeData)
    Gets the KID (Key ID) from a PlayReady scheme data.
    Parameters:
      `schemeData` - The PlayReady scheme data
    Returns:
      The KID UUID, or null if not found

  - ### generateWidvineCencHeader

    public static byte[] generateWidvineCencHeader(byte[] keyId, String widevineProviderId, byte[] widevineContentId, String widevinePolicy)
    Generates a Widevine CENC header
    Parameters:
      `keyId` - the keyID
      `widevineProviderId` - the provider
      `widevineContentId` - the content ID
      `widevinePolicy` - the policy
    Returns:
      The Widevine header

  - ### generatePlayreadyHeader

    @Nullable public static byte[] generatePlayreadyHeader(@NonNull byte[] initData, @NonNull String licenseServerUrl)
    Takes the raw bytes from a Widevine CENC header and generates a Playready Header Object
    Parameters:
      `initData` - The widevine cenc header raw data
      `licenseServerUrl` - The playready license server URL
    Returns:
      The Playready Header Object or null if the object could not be generated

  - ### generateWiseplayHeader

    @Nullable public static byte[] generateWiseplayHeader(@NonNull byte[] initData, @NonNull String licenseServerUrl)
    Takes the raw bytes from a Widevine CENC header and generates a Wiseplay init data
    Parameters:
      `initData` - The widevine cenc header raw data
      `licenseServerUrl` - The wiseplay license server URL
    Returns:
      The Wiseplay Header Object or null if the object could not be generated

  - ### extractPsshData

    @Nullable public static byte[] extractPsshData(@NonNull UUID drmScheme, @Nullable byte[] data)
    Extract the atom data in a given PSSH box. This method will return the original data if data is not a PSSH box.
    Parameters:
      `drmScheme` - The DRM scheme, i.e. `SdkConsts.WIDEVINE_UUID` or `SdkConsts.PLAYREADY_UUID`
      `data` - The PSSH box
    Returns:
      The data inside the given PSSH box or the original data if the data is not a PSSH box

  - ### getBytes

    public static byte[] getBytes(@NonNull UUID uuid)
    Converts a UUID to bytes
    Parameters:
      `uuid` - the UUID
    Returns:
      The UUID as bytes

  - ### createUuid

    public static UUID createUuid(@NonNull String base64)
    Create a UUID from a encoded base64 String
    Parameters:
      `base64` - base64 encoded UUID
    Returns:
      The UUID

  - ### createUuid

    public static UUID createUuid(byte[] bytes)
    Create a UUID from a byte array
    Parameters:
      `bytes` - the source bytes
    Returns:
      The UUID

  - ### getDeviceSecurityLevel

    @Nullable public static SecurityLevel getDeviceSecurityLevel(@Nullable Drm drm)
    Returns the security level supported by the current device and the given DRM if the devices supports the DRM. Returns `null` if the DRM is not supported. Please note that this method will always return `SecurityLevel.SOFTWARE` if the current API level is below 18.
    Parameters:
      `drm` - The drm system for which the security level is requested
    Returns:
      The security level supported for the given DRM or null if the DRM is not supported

  - ### getSupportedDRM

    public static Set<Drm> getSupportedDRM()
    Returns an unmodifiable Set of currently supported DRM based on the device and player plugins.
    Returns:
      plugins an unmodifiable Set of currently supported DRM based on the device and player plugins

  - ### isDrmSupported

    public static boolean isDrmSupported(Drm drm)
    Helper function. Checks if drm is supported in the platform.
    Parameters:
      `drm` - Drm to be checked
    Returns:
      if drm is supported on the device with the current plugin configuration.

  - ### getKIDFromWidevineHeader

    @Nullable public static UUID getKIDFromWidevineHeader(byte[] wvHeader)
    Gets the KID (Key ID) from a Widevine header.
    Parameters:
      `wvHeader` - The Widevine header data
    Returns:
      The KID UUID, or null if not found

  - ### getKIDFromWidevineSchemeData

    @Nullable public static UUID getKIDFromWidevineSchemeData(@NonNull com.google.android.exoplayer2.drm.DrmInitData.SchemeData schemeData)
    Gets the KID (Key ID) from a Widevine scheme data.
    Parameters:
      `schemeData` - The Widevine scheme data
    Returns:
      The KID UUID, or null if not found

  - ### isWidevineHeader

    public static boolean isWidevineHeader(byte[] data)
    Checks if the given data represents a Widevine Header object.
    Parameters:
      `data` - The data
    Returns:
      True if the given data represent a Widevine Header object

  - ### isPlayreadyHeader

    public static boolean isPlayreadyHeader(byte[] data)
    Checks if the given data represents a Playready Header object.
    Parameters:
      `data` - The data
    Returns:
      True if the given data represent a Playready Header object

  - ### createMediaDrm

    public static CastlabsMediaDrm createMediaDrm(UUID uuid, boolean forceWidevineL3) throws UnsupportedSchemeException, com.google.android.exoplayer2.drm.UnsupportedDrmException
    Creates a MediaDrm instance for the specified UUID.
    Parameters:
      `uuid` - The UUID of the DRM scheme
      `forceWidevineL3` - Whether to force Widevine L3
    Returns:
      A new CastlabsMediaDrm instance
    Throws:
      `UnsupportedSchemeException` - if the scheme is not supported
      `com.google.android.exoplayer2.drm.UnsupportedDrmException` - if DRM is not supported

  - ### getFirstSchemeDataByUuid

    @Nullable public static com.google.android.exoplayer2.drm.DrmInitData.SchemeData getFirstSchemeDataByUuid(@NonNull com.google.android.exoplayer2.drm.DrmInitData drmInitData, @NonNull UUID uuid)
    Retrieves scheme data for a given DRM scheme, specified by its UUID. Returns the first entry matched by UUID.
    Parameters:
      `drmInitData` - DRM init data to look into
      `uuid` - The DRM scheme's UUID.
    Returns:
      The initialization data for the scheme, or `null` if the scheme is not supported.