Protect streams for iOS and Apple devices with EZDRM and the Wowza Streaming Cloud REST API

Playback of protected streams on iOS or Apple TV devices requires Apple's FairPlay DRM. You can access this DRM through our integration with EZDRM and configure stream encryption using the Wowza Streaming Cloud REST API.

You’ll use your EZDRM user name and password, as well as a FairPlay asset ID, to configure your stream for DRM protection with Wowza Streaming Cloud and EZDRM FairPlay DRM.

Tip: In addition to completing the steps in this topic, you might also want to use EZDRM Universal to protect streams on Google or Microsoft devices or players.

Video tutorial: Protect HLS live streams with EZDRM using FairPlay

Prerequisite

To protect streams in Wowza Streaming Cloud using EZDRM, you must have an EZDRM account, configured appropriately for the device types you want to stream to. For FairPlay, you'll need verification from Apple that you're approved to use FairPlay. Refer to EZDRM and their documentation for more information about EZDRM account setup.

Note: Because this solution involves navigating multiple service providers, we recommend engaging with Professional Services for assistance with setup. Contact 720.279.8163 or schedule a call.

Generate an EZDRM key

An EZDRM key contains the asset ID you’ll use to configure your stream for DRM protection.

This step assumes:

  • You do not already have an asset ID. If you have one, you can skip to Configure the stream for DRM protection.
  • You do not want to pass an existing asset ID in the key generation request. EZDRM allows for passing existing asset IDs, but you should refer the EZDRM KeyZ API guide on the EZDRM site for reasons why you’d want to and the correct syntax for the call should you choose to.
Note: We provide instructions for generating the EZDRM key for ease of use. However, EZDRM is third-party software and we recommend that you refer to the EZDRM KeyZ API guide on the EZDRM site for the most-up-to-date information.

There are two ways to create an EZDRM DRM key:

  • using the EZDRM Key Servers API
  • using a scripted curl web service call

In both cases, you’ll need to provide your EZDRM user name and password.

(Option 1) Request a DRM key with the EZDRM Key Servers API

  1. Use the advanced REST client (ARC) plugin for Chrome to open a session.
  2. In the left panel, select HTTP request.
  3. Change the Method to  POST, and then enter the following request URL:
    https://fps.ezdrm.com/api/keys?u=[ezdrm-account-username]&p=[ezdrm-account-password]

    Where:
    • [ezdrm-account-username] is your EZDRM user name
    • [ezdrm-account-password] is your EZDRM password

Make note of the following values in the response from EZDRM:

  • The AssetID. You'll use this to configure the stream protection in Wowza Streaming Cloud.
  • The LicensesUrl value. You'll use this when you playback a stream encrypted for FairPlay.

(Option 2) Request a DRM key with a curl script

Run the following curl script, or another scripted web service call, to retrieve the DRM values from the EZDRM web service:

curl -X POST 'https://fps.ezdrm.com/api/keys/?u=[ezdrm-account-username]&p=[ezdrm-account-password]' -d ' '

where:

  • [ezdrm-account-username] is your EZDRM user name
  • [ezdrm-account-password] is your EZDRM password
Note: The two quotation marks with a space between (' ') are required in place of passing the optional existing content ID. The call doesn’t work without it.

Make note of the following values in the response from EZDRM:

  • The AssetID. You'll use this to configure the stream protection in Wowza Streaming Cloud.
  • The LicensesUrl value. You'll use this when you playback a stream encrypted for FairPlay.

Configure the stream for DRM protection

To protect a stream using the EZDRM key you obtained in the previous step, you’ll need to set the following EZDRM properties on the transcoder using the Wowza Streaming Cloud REST API.

Note: Depending on your workflow, you might want to consider where these properties are and are not available:
  • They are not available in the user interface.
  • They are only available for transcoders. If you're using the live stream workflow, you set these properties on the transcoder for your live stream.
Section Key Value Description
ezdrm username string Your EZDRM user name
ezdrm password string Your EZDRM password
ezdrm fairPlayAssetId string The FairPlay asset ID you generated from EZDRM.
 
Note: Wowza Streaming Cloud does not validate the EZDRM values you specify in these properties. Make sure you enter the correct values.

You can configure the EZDRM properties when you create a transcoder or by updating an existing transcoder.

Tip: If you haven't used the Wowza Streaming Cloud REST API previously, consider reviewing About the Wowza Streaming Cloud REST API, specifically the information about using environment variables for the API and access keys.

Configure DRM when creating a new transcoder

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
   "transcoder": {
     "billing_mode": "pay_as_you_go",
     "broadcast_location": "us_west_california",
     "buffer_size": "4000",
     "delivery_method": "push",
     "name": " MyTranscoder",
     "protocol": "rtmp",
     "transcoder_type": "transcoded",
     "properties": [
      { 
        "key": "username", 
        "section": "ezdrm", 
        "value": "[your_ezdrm_username]" 
      }, 
      { 
        "key": "password", 
        "section": "ezdrm", 
        "value": "[your_ezdrm_password]" 
      }, 
      { 
        "key": "fairPlayAssetId", 
        "section": "ezdrm", 
        "value": "[asset_id_from_ezdrm]" 
      } 
     ]
   } 
}' "${WSC_HOST}/api/${WSC_VERSION}/transcoders"

Configure DRM on an existing transcoder

curl -X PATCH \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
    "transcoder": {
      "properties": [
        { 
          "key": "username", 
          "section": "ezdrm", 
          "value": "[your_ezdrm_username]" 
        }, 
        { 
          "key": "password", 
          "section": "ezdrm", 
          "value": "[your_ezdrm_password]" 
        }, 
        { 
          "key": "fairPlayAssetId", 
          "section": "ezdrm", 
          "value": "[asset_id_from_ezdrm]" 
        } 
     ]
   }
}' "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]"
 

(Optional) Block RTMP direct playback for enhanced security

Direct playback through RTMP is enabled by default, but you might want to block RTMP direct playback to ensure that only the devices and platforms intended to decrypt your stream can access it.

Configure RTMP playback when creating a new transcoder

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
   "transcoder": {
     "billing_mode": "pay_as_you_go",
     "broadcast_location": "us_west_california",
     "buffer_size": "4000",
     "delivery_method": "push",
     "name": " MyTranscoder",
     "protocol": "rtmp",
     "transcoder_type": "transcoded",
     "properties": [
      { 
        "section": "rtmp", 
        "key": "allowDirectPlayback", 
        "value": false 
      }
     ]
   } 
}' "${WSC_HOST}/api/${WSC_VERSION}/transcoders"

Configure RTMP playback on an existing transcoder

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
     "property": {
        "section": "rtmp", 
        "key": "allowDirectPlayback", 
        "value": false 
      } 
}' "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/properties"

Test playback with encryption

  1. Start your transcoder and your stream.
  2. Verify that the stream encryption works as you expect on an Apple device or service. To test your playback, you'll need a test player and some other information. The tips below are based on the user interface for https://developer-tools.jwplayer.com/stream-tester/ in Safari set to Fairplay:
    • File URL – The URL for your protected stream.
    • Certificate URL – Part of onboarding for your EZDRM account with FairPlay DRM. You'll need to generate a FairPlay certificate through an Apple Developer account and then post the resulting certificate on a publicly accessible endpoint. The URL to this endpoint is the value for this field.
    • Process SPC URL – Build this URL from the EZDRM response when you generated the asset ID. The format is https://[LicensesUrl]/[AssetID].
    Refer to the EZDRM Apple FairPlay DRM Setup  and EZDRM Testing Playback guides on the EZDRM site for information about how to deliver the FairPlay license and approve viewers, proxy URLs you’ll need for playback, and sample players.
  3. Stop your transcoder when your testing is complete.
Troubleshooting: If you experience playback issues on a Mac and you have an external monitor connected, there might be issues with the HDCP handhake. See macworld.com for more information. 

More resources