EZDRM FairPlay Streaming (FPS) is a hosted service for protecting streams to iOS and Apple TV. Content owners encrypt streams with FairPlay DRM keys and deliver content to Apple devices with native support for the HTML 5 player in macOS Safari browsers or Safari 11.3 on iOS. Streams are packaged using a secure web call to the EZDRM Key Servers API. This article describes how to set up and use Wowza DRM with Wowza Streaming Engine™ media server software and EZDRM FairPlay DRM.
Download and install the EZDRM plugin for Wowza Streaming Engine
- Download the EZDRM Wowza Module Java plugin.
- Copy and paste the downloaded EzdrmWowzaModule.jar file into [wowza-install-dir]/lib.
- Restart Wowza Streaming Engine.
Create and configure an EZDRM DRM key file
For each Wowza Streaming Engine stream, the EZDRM Wowza plugin calls the DRM key(s) that correspond to the ContentID. Before streaming, create DRM key set (ContentID) entries in the EZDRM DRM-as-a-Service Key API for each stream. This is well suited to adaptive bitrate streaming.
Generate an EZDRM key
There are two ways to create DRM key files: by using the EZDRM Key Servers API or with a scripted curl web service call. In both cases you must provide the following information:
| Parameter | Value |
|---|---|
| U | Your EZDRM user name. |
| P | Your EZDRM password. |
| AssetID | (Optional) An AssetID if you want to encrypt a stream with an existing AssetID. All streams that use the same AssetID share one license. |
Request a DRM key with the EZDRM Key Servers API
- Use the advanced REST client (ARC) plugin for Chrome to open a session.
- In the left panel, select HTTP request.
- Change the Method to POST, and then enter the following request URL:
http://fps.ezdrm.com/api/keys?u=[ezdrm-account-username]&p=ezdrm-account-password]
Where [ezdrm-account-username] is your EZDRM user name and [ezdrm-account-password] is your EZDRM password.
Use the following URL to specify an AssetID in your request:
http://fps.ezdrm.com/api/keys/[AssetID]?u=[ezdrm-account-username]&p=ezdrm-account-password]
Where [AssetID] is an existing AssetID with which you want to associate the key, [ezdrm-account-username] is your EZDRM user name, and [ezdrm-account-password] is your EZDRM password.
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 where [AssetID] is an existing AssetID with which you want to associate the key, [ezdrm-account-username] is replaced with your EZDRM user name and [ezdrm-account-password] is replaced with the password associated with your EZDRM user name. You can also specify the ContentID for the value of C; if you don't specify a ContentID, you must use double quotation marks ("") to pass a blank value, as shown in the example script below.
curl -X POST 'http://fps.ezdrm.com/api/keys/[AssetID]?U=[ezdrm-account-username]&P=[ezdrm-account-password]' -d ' '
The following values in the EZDRM response must be used to create the key file and configure Wowza Streaming Engine to use the EZDRM module: FairPlay/KeyHEX and FairPlay/KeyUri.
Create an EZDRM FairPlay key file
Key files are text files with a .key file extension stored in the Wowza Streaming Engine [install-dir]/keys directory. Key files must be named in the format of [streamName].key. For example, to protect the stream myStream.mp4, the key file would be [install-dir]/keys/myStream.mp4.key.
Note: Each live stream and VOD asset must have a separate key file named [streamName].key.
Each key file must contain the following:
cupertinostreaming-aes128-method: SAMPLE-AES cupertinostreaming-aes128-url: [KeyUri] cupertinostreaming-aes128-key: [first-32-digits-of-KeyHEX] cupertinostreaming-aes128-iv: [last-32-digits-of-KeyHEX] cupertinostreaming-aes128-iv-include-in-chunklist: false cupertinostreaming-aes128-key-format: com.apple.streamingkeydelivery cupertinostreaming-aes128-key-format-version: 1
Where:
- [KeyUri] is the license URL for encryption. This is the KeyUri value in the EZDRM response.
- [KeyHEX] is the DRM encryption key in two forms: base-64 and HEX. The first 32 characters of the KeyHEX value in the EZDRM response are used for the cupertinostreaming -aes128-key value and the last 32 characters are used for the cupertinostreaming -aes128-iv value.
Configure the Wowza Streaming Engine stream and EZDRM module
Create and configure an application to ingest the source stream
- Use one of the following articles to create an application:
To set up DVR streaming, follow the live streaming instructions and then see Wowza nDVR overview.
- Use your player or the test players on the Video Test Players webpage to verify that you can play an unencrypted stream in the example Apple HLS player. The following is an example of the playback URL structure:
http://[address]:1935/[application-name]/[stream-name]/playlist.m3u8
Where [address] is the IP address or domain of your Wowza Streaming Engine server, [application-name] is the name of your streaming application, and [stream-name] is the name of your stream (myStream).
For nDVR, use the following playback URL structure:
http://[address]:1935/[application-name]/[stream-name]/playlist.m3u8?DVR
Add and configure the EZDRM module in Wowza Streaming Engine Manager
You must add the module to the application and then configure the module's properties.
Note: Access to the Properties and Modules tabs is limited to administrators with advanced permissions. For more information, see Manage credentials.
- In Wowza Streaming Engine Manager, click the Applications tab at the top of the page, and then click the name of your application the contents panel.
- On the application page Modules tab, click Edit, and then click Add Module.
- In the Add New Module dialog, enter the following information, and then click Add.
- Name: EZDRM
- Description: EZDRM
- Fully Qualified Class Name: com.ezdrm.wowza.EzdrmWowzaModule
- On the application page Properties tab, click HTTP Streamers Cupertino Settings in the Quick Links bar.
- In the HTTP Streamers Cupertino Settings section, click Edit.
- Click the check box next to cupertinoExtXVersion to enable the property, and then set the value to 7.
- Still on the application page Properties tab, click Custom in the Quick Links bar.
- In the Custom section, click Edit.
- Click Add Custom Property, specify the following settings in the Add Custom Property dialog box, and then click Add:
Path Name Type Value /Root/Application username String Your EZDRM user name. /Root/Application password String The password associated with the value provided for the username property. /Root/Application FPScontentID Boolean The AssetID for the DRM key(s) returned in the EZDRM response. /Root/Application ezdrmFPSUrl String Enter http://fps.ezdrm.com/Api/keys. This is the EZDRM Key API URL. /Root/Application cupertinoEncryptionAPIBased Boolean Set to true. /Root/Application debugFlag String (Optional) Enables logging in the Wowza Streaming Engine logs for troubleshooting. Set to true to enable logging. The default value is false. - Click Save and then restart the application.
Add and configure the EZDRM module in XML
Note: Skip this section if you configured the EZDRM module in Wowza Streaming Engine Manager. Editing the XML file directly is an alternative way to configure the module.
- Edit [install-dir]/conf/[application-name]/Application.xml and add the following <Module> as the last entry in the <Modules> list:
<Module> <Name>EZDRM</Name> <Description>EZDRM</Description> <Class>com.ezdrm.wowza.EzdrmWowzaModule</Class> </Module> - Edit [install-dir]/conf/[application-name/Application.xml and add the following properties to the application-level <Properties> container at the bottom of the file (be sure to get the correct <Properties> container; there are several in the Application.xml file):
Where [ezdrm-account-username] is your EZDRM user name, [ezdrm-account-password] is your EZDRM password associated with the specified use rname, and [ezdrm-AssetID] is the AssetID generated for the stream.<Property> <Name>username</Name> <Value>[ezdrm-account-username]</Value> <Type>String</Type> </Property> <Property> <Name>password</Name> <Value>[ezdrm-account-password]</Value> <Type>String</Type> </Property> <Property> <Name>ezdrmFPSUrl</Name> <Value>http://fps.ezdrm.com/Api/keys</Value> <Type>String</Type> </Property> <Property> <Name>cupertinoEncryptionAPIBased</Name> <Value>true</Value> <Type>Boolean</Type> </Property> <Property> <Name>FPSContentID</Name> <Value>[ezdrm-AssetID]</Value> <Type>String</Type> </Property> <Property> <Name>debugFlag</Name> <Value>true</Value> <Type>Boolean</Type> </Property>
- If you're delivering a live stream, start Wowza Streaming Engine and send the stream from your encoder to the server.
Test the DRM configuration
Test playback with encryption
- Log in to the EZDRM website.
- In the Members Area, click Widevine DRM Player and Playback Help. This provides information about creating a test player.
- On your test player webpage, enter the following URL into the Stream field and then click Connect:
http://[address]:1935/[application-name]/[stream-name]/playlist.m3u8
Where [address] is the IP address or domain of your Wowza Streaming Engine server, [application-name] is the name of your streaming application, and [stream-name] is the name of your stream (myStream).
For nDVR, use the following URL structure:
http://[address]:1935/[application-name]/[stream-name]/playlist.m3u8?DVR
Troubleshooting
If you see a message similar to the following in [install-dir]/logs/wowzastreamingengine_access.log, check that your EZDRM user name and password information is correct in Application.xml.
comment server WARN 200 - EZDRM.getFairPlayLicense[myApplication/_definst_]: EZDRM content key is not set.
comment server WARN 200 - EZDRM.onHTTPHLSFairPlayCreateVOD[myApplication/_definst_/sample.mp4]: Key request failed. ifFailFakeKey:false
