Protected HTTP streaming

Configure protected HTTP Dynamic Streaming (PHDS)

Use Flash Media Server 4.5 to serve live and on-demand protected content to Flash Player and AIR over HTTP without using a DRM License Server. When Flash Media Server packages the content, it generates the license and embeds it into the DRM metadata of the content stream. This feature is called Protected HTTP Dynamic Streaming (PHDS). In addition to encrypting content, PHDS also supports SWF verification for HTTP Dynamic Streaming.

The F4F packaging process for on-demand and live PHDS generates a license, embeds it in the DRM metadata, and delivers it with the media. Flash Player 11 and AIR 3 clients can retrieve the license from the content stream, which eliminates communication between the client and a License Server.

The Flash Media Server installer generates credentials, certificates, and policy files to the rootinstall/phds directory. The installer also creates a common-key.bin file in the /phds directory. You can change the content of this file or create a new common key file. To create a common key file (common-key.bin), which is used to derive the Content Encryption Key, use the Scramble tool. See Scramble tool.

Policy files

Use the following policy files to generate licenses for on-demand and live PHDS (FMS 4.5.1 includes four new policy files to support output protection):

Policy name

Description

phds_24hr_policy.pol

24 Hour limited policy

anonymous; 24 hours limited license caching.

This is the default policy. Users can start playback within 24 hours of the time the content was packaged. Users can continue watching the content until the end of the content (users may pause content).

The 24 hours window starts when the DRM metadata is generated.

phds_policy.pol

Unlimited policy

anonymous; not use license chaining; unlimited license caching; and binding to the Shared Domain is permitted

This policy allows playback at any time.

phds-24hr-OPBestEffort.pol

(FMS 4.5.1)

24 Hours Limited / Best Effort Output Protection Policy

Set in the same way as the 24 Hours Limited / No Output Protection Policy policy with an additional restriction to use hardware content protection, if available. Users are still able to playback media if the client hardware doesn't support Output Protection. If the client hardware supports Output Protection but it is disabled, Flash Player returns DRM Run Time Error: 3342 (NoDigitalProtectionAvail).

phds-OPBestEffort.pol

(FMS 4.5.1)

Unlimited / Best Effort Protection Policy

Set in the same way as the Unlimited / No Output Protection Policy policy with an additional restriction to use hardware content protection, if available. Users arestill able to playback media if the client hardware doesn't support Output Protection. If the client hardware supports Output Protection, but it is disabled, Flash Player returns DRM Run Time Error: 3342 (NoDigitalProtectionAvail).

phds-24hr-OPRequired.pol

(FMS 4.5.1)

24 Hours Limited / Required Output Protection Policy

Set in the same way as the 24 Hours Limited / No Output Protection Policy policy with an additional restriction to use hardware content protection. Users cannot playback media if the client hardware doesn't support Output Protection. If the client hardware doesn't support Output Protection or if it supports Output Protection, but it is disabled, Flash Player returns DRM Run Time Error: 3342 (NoDigitalProtectionAvail).

phds-OPRequired.pol

(FMS 4.5.1)

Unlimited / Required Output Protection Policy

Set in the same way as the Unlimited / No Output Protection Policy policy with an additional restriction to use hardware content protection. Users cannot playback media if the client hardware doesn't support Output Protection. If the client hardware doesn't support Output Protection or if it supports Output Protection but, it is disabled, Flash Player returns DRM Run Time Error: 3342 (NoDigitalProtectionAvail).

The simple unlimited policy is not intended for a regular use. It is provided as a temporary work around in case there is an issue with the network. When media is cached on network devices between Flash Media Server and Flash Player, clients may receive expired policy data from the network instead of the expected media from the server. If media that was generated with the 24 hours policy is cached for more than 24 hours the player does not allow playback. Switch to the unlimited PHDS policy as a temporary solution until the network configuration is fixed and the caches are flushed. This solution allows you to distribute media with lower protection instead of not distributing the media. After switching to the Unlimited Policy, flush the caches to allow the unlimited license to propagate to clients.

Live Protected HTTP Dynamic Streaming

Configure PHDS for live streaming at the following levels:

  • Application—rootinstall/applications/livepkgr/Application.xml

  • Event—rootinstall/applications/livepkgr/events/_definst_/liveevent/Event.xml

Application-level and event-level configurations for live PHDS

Both the Application.xml file and the Event.xml file have a ContentProtection container that holds the live PHDS configuration settings. In Application.xml, the container is located under //Application/HDS/Recording/ContentProtection. In Event.xml, the container is located under //Event/Recording/ContentProtection.

Element

Default

Description

Recording/ContentProtection

"allow" in Application.xml

"false" in Event.xml

Container element for content protection configurations.

In Application.xml, set the enabled attribute to "true" to enable content protection, "false" to disable content protection, or "allow" to allow settings in the Event.xml file to override the ContentProtection section of the Application.xml file.

When enabled="allow", the server uses none of the settings in the ContentProtection section of the Application.xml file. If a ContentProtection section is not specified in Event.xml, content protection is disabled because the default value is "false" in Event.xml.

In Event.xml, set the enabled attribute to "true"or "false".

Recording/ContentProtection/ProtectionScheme

None

Possible values are phds and FlashAccessV2. For PHDS, use phds.

Recording/ContentProtection/PHDS

None

Container for PHDS encryption settings.

Recording/ContentProtection/PHDS/CommonKeyFile

None

A relative path to the common-key.bin file containing a base key used (along with the content ID) to generate the final content encryption key.

This file is generated during installation to rootinstall/phds/common-key.bin.

If you define the CommonKeyFile in the Application.xml file, the server looks for the file in rootinstall/phds.

If you define the CommonKeyFile in the Event.xml file, the server looks for the file relative to the event folder.

Recording/ContentProtection/PHDS/PlaybackExpiration

24Hours

The protection policy. The policy determines the duration within which content playback is available. Possible values are 24Hours and Unlimited.

Recording/ContentProtection/PHDS/VideoEncryptionLevel

2

The level of encryption for the content (0-low,1-medium,2-high). Lower settings mean "partial encryption", where a subset of the samples (like video keyframes) are encrypted. This can improve playback performance on the client, since there will be fewer frame to decrypt.

Recording/ContentProtection/PHDS/UpdateInterval

60

The frequency at which the server generates the drm metadata, in minutes.

Recording/ContentProtection/PHDS/OutputProtection

None

The required hardware Output Protection of media on the client. Possible values are None, BestEffort, and Required.

Configure live PHDS at the application level

The following example enables and configures PHDS in the Application.xml file. These settings apply to every live event configured for this application.

<Application> 
    <StreamManager> 
        <Live> 
            <AssumeAbsoluteTime>true</AssumeAbsoluteTime> 
        </Live> 
    </StreamManager> 
     
    <HDS> 
        <Recording> 
            <FragmentDuration>4000</FragmentDuration> 
            <SegmentDuration>360000</SegmentDuration> 
            <ContentProtection enabled="true"> 
                <ProtectionScheme>PHDS</ProtectionScheme> 
                <PHDS> 
                    <CommonKeyFile>common-key.bin</CommonKeyFile> 
                </PHDS> 
            </ContentProtection> 
        </Recording> 
    </HDS> 
     
</Application>

When you configure CommonKeyFile in the Application.xml file, the server looks for the file in the rootinstall/phds directory.

Configure live PHDS at the event level

The following is an example of an Application.xml file that allows PHDS and tells the server to look for configurations in the Event.xml file for each live event:

<Application> 
    <StreamManager> 
        <Live> 
            <AssumeAbsoluteTime>true</AssumeAbsoluteTime> 
        </Live> 
    </StreamManager> 
     
    <HDS> 
        <Recording> 
            <ContentProtection enabled="allow"> 
                <ProtectionScheme>PHDS</ProtectionScheme> 
            </ContentProtection> 
        </Recording> 
    </HDS> 
     
</Application>

The following Event.xml file configures PHDS for a single live event:

<Event> 
    <EventID>liveevent</EventID> 
    <Recording> 
        <FragmentDuration>4000</FragmentDuration> 
        <SegmentDuration>360000</SegmentDuration> 
        <ContentProtection enabled="true"> 
            <ProtectionScheme>PHDS</ProtectionScheme> 
            <PHDS> 
                <CommonKeyFile>common-key.bin</CommonKeyFile> 
                <VideoEncryptionLevel>2</VideoEncryptionLevel> 
            </PHDS> 
        </ContentProtection> 
    </Recording> 
</Event>

In this case, copy the common-key.bin file from the rootinstall/phds directory to the rootinstall/applications/livepkgr/events/_definst_/liveevent directory.

On-demand Protected HTTP Dynamic Streaming

Configure PHDS for on-demand streaing at the following levels:

Server—rootinstall/Apache2.2/conf/httpd.conf

Stream—create a jit.conf file and copy it to the same directory as the content.

To configure PHDS at the stream level, in the httpd.conf file, set EncryptionScope to content to allow settings in jit.conf files to override settings in the httpd.conf file.

Server level configurations for on-demand PHDS

Configure the following directives for the jithttp_module in the Apache httpd.conf file:

Directive

Default value

Description

EncryptionScope

None

Possible values are content and server.

When the value is content, PHDS configuration settings in the jit.conf file override settings in the httpd.conf. file.

When the value is server, the server uses configuration settings in the httpd.conf file.

PHDSCommonKeyFile

phds/common-key.bin

This file is generated during installation.

A common key used to protect content at this location.

PHDSPlaybackExpiration

24Hours

The duration within which content playback is available. Possible values are 24Hours and Unlimited

PHDSOutputProtection

None

The required hardware Output Protection of media on the client. Possible values are None, BestEffort, and Required.

PHDSVideoEncryptionLevel

2

The level of encryption for the content (0-low,1-medium, 2-high). Lower settings provide partial encryption. A subset of the samples (like video keyframes) are encrypted. Partial encryption can improve playback performance on the client, because there are fewer frames to decrypt.

ProtectionScheme

None

A string determining the type of protection. For PHDS, use phds.

Stream-level configuration settings for on-demand PHDS

Element

Default value

Description

//manifest/hds:content-protection enabled

None

To enable content for protection with Flash Access or PHDS, set the enabled attribute to "true".

//manifest/hds:content-protection/hds:protection-scheme

None

The type of protection. For PHDS, use phds.

//manifest/hds:content-protection/hds:phds/hds:common-key-file

phds/common-key.bin

Path to a common key file generated when the server installs. The file contains a16-byte/128-bit random key. This path can be absolute or relative to the jit.conf file.

//manifest/hds:content-protection/hds:phds/hds:video-encryption-level

2

The level of encryption for the content (0-low,1-medium,2-high).

Lower settings provide partial encryption. A subset of the samples (like video keyframes) are encrypted.

Partial encryption can improve playback performance on the client because there are fewer frames to decrypt.

//manifest/hds:content-protection/hds:phds/hds:playback-expiration

24Hours

The protection policy. The policy determines the duration within which content playback is available. Possible values are 24Hours and Unlimited.

//manifest/hds:content-protection/hds:phds/hds:output-protection

None

The required hardware Output Protection of media on the client. Possible values are None, BestEffort, and Required.

Configure on-demand PHDS at the server level

The simplest way to configure on-demand PHDS is to uncomment two lines in the Apache httpd.conf file:

<IfModule jithttp_module> 
<Location /hds-vod> 
    HttpStreamingJITPEnabled true 
    HttpStreamingContentPath "../webroot/vod" 
    JitFmsDirPath ".." 
    Options -Indexes FollowSymLinks 
 
# Uncomment the following directives to enable encryption 
# for this location. 
   EncryptionScope server 
   ProtectionScheme phds 
</Location> 
</IfModule>

When a media player request content from the /webroot/vod folder, it is protected. For example, request the following URL from the sample video player:

http://localhost:8134/hds-vod/sample1_1500kbps.f4v.f4m

To verify that the content is protected, enter the same URL into the address bar of a web browser. The XML response contains a <drmAdditionalMetadata> element like the following:

 <?xml version="1.0" encoding="UTF-8" ?> 
- <manifest xmlns="http://ns.adobe.com/f4m/1.0"> 
  <id>sample1_1500kbps.f4v</id> 
  <streamType>recorded</streamType> 
  <duration>114.61450000000001</duration> 
  <bootstrapInfo profile="named" id="bootstrap3628">AAABq2Fic3QAAAAAAAA</bootstrapInfo> 
  <drmAdditionalHeader drmContentId="sample1_1500kbps.f4v" id="drmMetadata9839">AgARfEFkZGl0aW9uYWxIZWFkZXIDAAp</drmAdditionalHeader> 
- <media streamId="sample1_1500kbps.f4v" url="sample1_1500kbps.f4v" bootstrapInfoId="bootstrap3628" drmAdditionalHeaderId="drmMetadata9839"> 
  <metadata>AgAKb25NZXRhRGF0</metadata> 
  </media> 
  </manifest>
Note: The <bootstrapInfo>, <drmAdditionalHeader>, and <metadata> information has been abridged for readability.

The following example adds a new Location directive. Request that include /phds serve protected content. If you use the default /hds-vod Location directive, requests that use /hds-vod serve unprotected content. This configuration doesn’t define PHDSPlaybackExpiration, PHDSVideoEncryptionLevel, or PHDSCommonKeyFile, but relies on their default values:

LoadModule jithttp_module modules/mod_jithttp.so 
<IfModule jithttp_module> 
 
<Location /phds> 
    HttpStreamingJITPEnabled true 
    HttpStreamingContentPath "../webroot/vod" 
    JitFmsDirPath ".." 
    Options -Indexes FollowSymLinks 
    EncryptionScope server 
    ProtectionScheme phds 
</Location>

Configure on-demand PHDS at the stream level

The following httpd.conf file sets EncryptionScope to content. This setting tells the server that configuration settings in the jit.conf file override settings in the httpd.conf file. Use this setting to configure PHDS for individual sets of media.

LoadModule jithttp_module modules/mod_jithttp.so 
<IfModule jithttp_module> 
<Location /jit_phds> 
    HttpStreamingJITPEnabled true 
    HttpStreamingContentPath "../webroot/jit_phds" 
    JitFmsDirPath ".." 
    Options -Indexes FollowSymLinks 
    EncryptionScope content 
</Location>

The following is the accompanying jit.conf file, which is in the same directory as the on-demand media files (/webroot/jit_phds):

<?xml version="1.0" encoding="utf-8"?> 
<manifest xmlns="http://ns.adobe.com/f4m/1.0" xmlns:hds="http://ns.adobe.com/hds-package/1.0> 
 
    <frame-rate>29.97</frame-rate> 
    <frames-per-keyframe-interval>60</frames-per-keyframe-interval> 
    <hds:content-protection enabled="true"> 
        <hds:protection-scheme>phds</hds:protection-scheme> 
            <hds:phds> 
                <hds:common-key-file>C:\Program Files\Adobe\Flash Media Server 4.5\phds\common-key.bin</hds:common-key-file> 
                <hds:video-encryption-level>0</hds:video-encryption-level> 
                <hds:playback-expiration>unlimited</hds:playback-expiration> 
            </hds:phds> 
    </hds:content-protection> 
 
</manifest>

SWF verification for Protected HTTP Dynamic Streaming

SWF verification prevents authorized SWF files from accessing content. To use SWF verification, you must enable Protected HTTP Dynamic Streaming.

Create a list of "authorized SWF files, called a whitelist. These files are specified in the embedded license and sent to the client inside the DRM metadata. On the client, SWF verification is enforced by Flash Access inside of Flash Player and AIR.

To create the whitelist, use Whitelist tool (rootinstall/tools/Whitelist).

Workflow

  1. Enable PHDS.

  2. Use the whitelist tool to generate a whitelist of authorized SWF files. The whitelist file can have any name. It must have the .whitelist or .airwhitelist extension. See Whitelist tool.

  3. Copy the whitelist to the server.

  4. Enable SWF verification and indicate the location of the whitelist in the following locations:

    • (Live)—Application.xml or Event.xml

    • (On-demand)—httpd.conf or jit.conf

  5. Publish a stream to the livepkgr application on Flash Media Server.

  6. Request a stream from an OSMF media player. The syntax of the request URL does not change for SWF verification.

    The server embeds the SWF hashes from the whitelist into the .drmmeta file when recording starts. Flash Player attempts to verify the SWF hash during DRM authentication.

  7. (Live) The server looks for the whitelist in the following order:

    1. The application folder. (The default application for live HTTP streaming is rootinstall/applications/livepkgr).

    2. A path in the /SWFVerification/WhitelistFolder element of Application.xml

    3. A path in the /SWFVerification/WhitelistFolder element of Event.xml

  8. (On-demand) The server looks for the whitelist in the httpd.conf/jit.conf file in the same folder as the on-demand content.

If the hashes don’t match, Flash Player throws an runtime error (3310) and the OSMF media player stops requesting fragments.

SWF verification configurations for live PHDS

To enable SWF verification for live PHDS, enable PHDS at the application level (Application.xml) or the event level (Event.xml). In the Apache httpd.conf file, set EncryptionScope to content. See Configure protected HTTP Dynamic Streaming (PHDS).

Configure SWF verification for live HDS at the application level (Application.xml) or at the event level (Event.xml).

In Application.xml, SWFVerification is located at //Application/HDS/Recording/ContentProtection/PHDS/SWFVerification.In Event.xml, SWFVerification is located at //Event/Recording/ContentProtection/PHDS/SWFVerification.

Element

Description

Default

/SWFVerification

The container for SWF verification configuration. To enable SWF verification, set the enabled attribute to "true".

"false"

/SWFVerification/WhiteListFolder

A path to the folder containing the whitelist. The folder can contain more than one whitelist file.

The path can be absolute or relative. A relative path in the Application.xml file is relative to the application folder. A relative path in the Event.xml file is relative to the event folder. Backwards relative paths are not supported for security reasons.

This configuration is optional. If no value is given, the server looks in the application folder of the live event.

The application folder of the live event. The default application for HTTP streaming is rootinstall/applications/livepkgr.

Configure the following settings in the Apache httpd.conf file to configure cache control for the bootstrap, fragment, manifest and drmmeta responses:

  • HttpStreamingBootstrapMaxAge

  • HttpStreamingFragMaxAge

  • HttpStreamingF4MMaxAge

  • HttpStreamingDrmmetaMaxAge

For detailed information about each configuration, see Configure live and on-demand HTTP Streaming at the server level (httpd.conf).

SWF verification configurations for on-demand PHDS

SWF verification is configured under PHDS. To enable SWF verification, enable PHDS. You can enable on-demand PHDS at the server level (httpd.conf) or at the stream level (jit.conf). To enable SWF verification at the stream level, set EncryptionScope to content at the server level. See Configure protected HTTP Dynamic Streaming (PHDS).

Configure SWF verification for on-demand PHDS at the server level (httpd.conf) or at the stream level (jit.conf).

Use the following elements to enable and configure SWF verification in the httpd.conf file:

Element

Description

Default

PHDSSWFVerification

The container for SWF verification configuration. To enable SWF verification, set the enabled attribute to "true".

"false"

PHDSSWFWhiteListFolder

Optional setting to specify where the SWF whitelist can be found. The folder can contain more than one whitelist files.

This can be overridden by jit.conf if the Apache configuration is overridable.

This configuration is optional. If no value is given, the server looks in the folder containing the jit.conf file.

The folder containing the media.

Use the following elements to enable and configure SWF verification in the jit.conf file. Copy the jit.conf file to the same directory as the on-demand media.

Element

Description

Default

//manifest/hds:content-protection/hds:phds/hds:swf-verification

The container for SWF verification configuration. To enable SWF verification, set the enabled attribute to "true".

"false"

//manifest/hds:content-protection/hds:phds/hds:swf-verification/hds:swf-whitelist-folder

A path to the folder containing the whitelist. The folder can contain more than one whitelist file.

The path can be absolute or relative. A relative path is relative to the folder containing the jit.conf file. Backwards relative paths are not supported for security reasons.

This configuration is optional. If no value is given, the server looks in the folder containing the jit.conf file.

The folder containing the media.

Whitelist tool

Use the whitelist tool to generate a list of verified SWF and AIR files. The server uses the whitelist to perform SWF verification for Flash Player and AIR applications.

The whitelist tool takes SWF files, AIR certificate files, and AIR signature files and creates a SHA256 hash for each file. The tool writes the hashes as Base64 encoded text to one or more text files and outputs the text files. The text files use the filename extensions .whitelist and .airwhitelist.

The whitelist tool is located in the following directory:

rootinstall/tools/Whitelist

Use the following command line syntax to run the whitelist tool:

whitelist --in <file|dir> [--outDir <output dir>] [--out <output file>] [--version]

The following table lists the command line options and arguments for the whitelist tool:

Option

Optional

Description

--in <file|dir>

No

A SWF file, an AIR signature file, or an AIR certificate file. A directory containing SWF files. The dir parameter does not support AIR files.

To specify multiple files or directories, use multiple --in options.

For SWF files, the tool outputs a file with the extension .whitelist. For AIR signature and certificate files, the tool outputs a file with the extension .airwhitelist.

--log <file|dir>

Yes

An existing directory path where default whitelist.properties file is present or the full path name to the properties file. Customize logging in the .properties file.

The whitelist tool supports log4j Apache logging. By default, logging messages are routed to the console. To reroute them, use the --log option.

--out <output file>

Yes

The name for the .whitelist file and the .airwhitelist file. If --out is not specified, creates .whitelist and .airwhitelist files for each .swf file and .xml file.

If --out is specified, --outDir is ignored and the file is saved to the directory the tool is being run from.

--outDir <outputdir>

Yes

Creates an output directory and saves the .whitelist file to the directory.

If --outDir is not specified, the .whitelist files and .airwhitelist files are created in the directory the tool is being run from. If --outDir is a relative path, it is relative to the directory the tool is being run from.

--version

Yes

Prints the SWF verification version number in the .whitelist file.

The following table lists examples of running the whitelist tool:

Example

Result

whitelist --in foo.swf --in bar.swf

Creates a foo.swf.whitelist and a bar.swf.whitelist in the current directory.

whitelist --in signature.xml --in bar.swf

Creates signature.xml.airwhitelist and bar.swf.whitelist in the current directory.

whitelist --in foo.swf --in mydir

In this example, mydir is a directory containing bar.swf.

Creates a foo.swf.whitelist and a bar.swf.whitelist in the current directory.

whitelist --in signature.xml --in mydir

In this example, mydir is a directory containing bar.swf.

Creates a signature.xml.airwhitelist and a bar.swf.whitelist in the current directory.

whitelist --in foo.swf --in bar.swf --outDir outputdir

Creates an outputdir/foo.swf.whitelist file and an outputdir/bar.swf.whitelist file.

whitelist --in signature.xml --in bar.swf --outDir outputdir

Creates an outputdir/signature.xml.airwhitelist file and an outputdir/bar.swf.whitelist file.

whitelist --in foo.swf --in mydir --out outputfile

In this this example, mydir is a directory containing bar.swf.

Creates an outputfile.whitelist file in the current directory containing hashes for foo.swf and mydir/bar.swf.

whitelist --in signature.xml --in mydir --out outputfile

In this this example, mydir is a directory containing bar.swf.

Creates a an outputfile.airwhitelist file containing hashes for signature.xml. Creates an outputfile.whitelist file contaning hashes for bar.swf. Both files are created in the current directory.

whitelist --in foo.swf --in mydir -out outputfile -outDir outputdir

This example, mydir is a directory containing bar.swf.

Creates an outputfile.whitelist in the current directory containing a hash for foo.swf and mydir/bar.swf.

Warning: When the --out option is specified, the tool ignores the --outDir option.

whitelist --in signature.xml --in mydir --out outputfile --outDir outputdir

In this example, mydir is a directory containing bar.swf.

Creates an outputfile.airwhitelist file that contains the hashes for signature.xml. Creates an outputfile.whitelist file that contains hashes for mydir/bar.swf. Both files are created in the current directory.

Warning: When the --out option is specified, the tool ignores the --outDir option.

whitelist --version

Displays "version 1.0".

If an input files has the same name as a previously input file, both files are added to the whitelist.

whitelist --in c:\myfolder\signature.xml --in c:\yourfolder\signature.xml --outDir c:\out\signature.xml

The following is the output:

# c:\myfolder\signature.xml 
XXXXXXXXXXXXXXXXXXXXXX 
# c:\yourfolder\signature.xml 
XXXXXXXXXXXXXXXXXXXXXXXXXXX

The following is the whitelist format for an individual hash:

# foo.swf 
PGfcEwgUKWScivIRucIwG5jT

The following is the whitelist format for an AIR file:

# C:\air\signatures.xml 
A167FBF93528C87BBCDAC2B8CD0829479DDA6912.2

The following is the whitelist format for multiple hashes when using the --out option:

# foo.swf 
PGfcEwgUKWScivIRucIwG5jT 
 
# bar.swf 
TcsQWLLi7h7WNjHqcLzzl0J15Srvdzkz2inCTKQLOHw= 
 
# mydir/bar.swf 
TcsQWLLi7h7WNjHqcLzzl0J15Srvdzkz2inCTKQLOHw=

Use encryption key rotation

Flash Media Server 4.5.1 supports Key Rotation for protected HTTP Dynamic Streaming when used with Flash Access 3.0. You can encrypt content packaged with FMS 4.5.1 using a set of keys. You can periodically change the encryption key and specify how often the content encryption key is to be changed. You can also specify the list of keys for encryption.

To enable the feature, you must add configuration options in the event.xml and manifest.xml files located in the event folder under the specific application directory (for example, applications/livepkgr/events/_definst_/event1).

Changes in event.xml

A new protection scheme "FlashAccessV3" is added to the ContentProtection element. This protection scheme includes the existing configuration parameters in the "FlashAccessV2" protection scheme and three additional (optional) configuration parameters to specify the required Key Rotation parameters.

The EnableKeyRotation element specifies whether Key Rotation is to be enabled for the event. You can add a KeyRotationFilePath element under the FlashAccessV3 tag to specify the path to a file containing custom rotation keys. The key file must contain a series of hexadecimal numbers, one per line. Each key must be 16 bytes long. Whitespace between the hexadecimal values is optional. These keys are used in order. Whenever the encryption key is changed, the subsequent key is used.

After the last key is used, FMS switches to the first key. The last parameter KeyRotationInterval specifies the frequency (in seconds) with which the encryption key must be changed. The default value for the parameter is 900 seconds (15 minutes). If a key rotation file is not specified, FMS uses an internal key generator. The key generator uses /dev/urandom on Linux and the function CryptGenRandom on Windows.

Note: KeyrotationFilePath and KeyRotationInterval are read only if the EnableKeyRotation tag is set to true. Otherwise they are ignored.
<Recording> 
    <ContentProtection enabled="true"> 
        <ProtectionScheme>FlashAccessV3</ProtectionScheme> 
        <FlashAccessV3> 
            <!-- All existing configuration parameters present in 
            "FlashAccessV2" protection scheme. --> 
            <!-- To specify whether the key rotation feature is enabled or not. 
            Values can be true or false. Default value is false --> 
            <EnableKeyRotation></EnableKeyRotation> 
            <!-- If Key Rotation is enabled --> 
            <!-- To specify the interval (in seconds) during which the same 
            rotation key will be used to encrypt content samples. Default value is 900 
            seconds--> 
            <KeyRotationInterval></KeyRotationInterval> 
            <!-- 
            To specify the file containing the rotation keys to be used. This 
            file will contain a sequence of rotated keys used to encrypt content. The keys 
            must be 16 bytes in length and specified as hexadecimal values (as shown 
            below). Whitespace between the hexadecimal values is optional. When multiple 
            keys are specified, the keys are cycled in the order they are specified. 
            The "KeyRotationFile" specified will contain the keys in the 
            following format: 
            01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 10 
            11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E 1F 20 
            --> 
            <KeyRotationFilePath></KeyRotationFilePath> 
        </FlashAccessV3> 
    </ContentProtection> 
</Recording>

Changes in manifest.xml

The manifest.xml file is present in the same directory as the event.xml ( inside the events folder ). This file is used by the HTTP module supplied with FMS to generate the .f4m file for any live stream. Here a ProtectionScheme is added to the element Drmmeta. You can set the tag EnableKeyRotation to true for it to generate the correct DRM metadata into the generated f4m file.

However, the DRMMeta tag in manifest.xml is not mandatory. If the tag is not present, the DRM metadata is generated from the information specified in the event.xml file.

<manifest xmlns="http://ns.adobe.com/f4m/1.0" 
    xmlns:le="http://ns.adobe.com/liveevent/1.0"> 
    <le:Drmmeta id="drmMeta" drmContentId="live_event"> 
        <le:ProtectionScheme>FlashAccessV3</le:ProtectionScheme> 
        <le:FlashAccessV3> 
            <!-- All existing configuration parameters present in 
                "FlashAccessV2" protection scheme. --> 
            <!-- To specify whether the key rotation feature is enabled or not. 
                Values can be true or false. Default value is false --> 
            <le:EnableKeyRotation>false</le:EnableKeyRotation> 
        </le:FlashAccessV3> 
</le:Drmmeta>
Note: If key Rotation is enabled, the key change occurs only at the fragment boundaries.

Configure protected HTTP Live Streaming (PHLS)

Use Flash Media Server 4.5 to serve protected content over HTTP to devices that support Apple HTTP Live Streaming. This feature is called Protected HTTP Live Streaming (PHLS) and it provides real-time AES-128 wire encryption.

The Flash Media Server installer generates the required certificates and keys to the rootinstall/phls directory. To generate new keys, use the scramble tool. See Scramble tool.

Configure live Protected HTTP Live Streaming

Configure PHLS for live streaming at the following levels:

  • Server—rootinstall/Apache2.2/conf/httpd.conf

  • Application—rootinstall/applications/livepkgr/Application.xml

  • Event—rootinstall/applications/livepkgr/events/_definst_/liveevent/Event.xml

Server level configuration directives for live PHLS

The following table contains the directives for the hlshttp_module in the Apache httpd.conf file:

Directive

Default

Description

HLSEncryptionScope

Off

Defines the encryption scope. The following are possible values:

server —Apache encryption settings are applied to all content. The server ignores content-specific encryption configurations in Event.xml and Application.xml (live) and jit.conf (on-demand).

content —Apache encryption settings are ignored. The server uses encryption settings from Event.xml or Application.xml (live) or from jit.conf (on-demand).

Off —Encryption is off for the whole server.

HLSEncryptCipherKeyFile

None

The path of the default cipher key used to encrypt the content.

HLSEncryptKeyURI

None

The URI that the client uses to fetch the encryption key.

Application and event level configuration for live PHLS

Both the Application.xml file and the Event.xml file have an HLS container that holds the live PHLS configuration settings. In Application.xml, the container is located under //Application/HDS/HLS. In Event.xml, the container is located under //Event/HLS.

Element

Default

Description

/HLS

None

Container for content protection settings.

/HLS/Encryption

None

Set the enabled attribute to "allow" to allow PHLS configurations in the Event.xml file to override settings in the Application.xml file.

Set the enabled attribute to "true" to configure PHLS in the Application.xml file. These configurations apply to all live events in the application.

The default value of the enabled attribute in the Application.xml file is "allow". The default value in the Event.xml file is "false".

/HLS/Encryption/KeyFile

None

The path of the default cipher key used to encrypt the content.

/HLS/Encryption/KeyURI

None

The URI that the client uses to fetch the encryption key. See Serve encryption keys to the client.

Configure live PHLS at the server level

  1. Open the rootinstall/Apache2.2/conf/httpd.conf file and locate the hlshttp_module:

    <IfModule hlshttp_module> 
        ... 
    <Location /hls-live> 
        ...
  2. Uncomment the following:

    # Uncomment the following directives to enable encryption 
    # for this location: 
        HLSEncryptionScope server 
        HLSEncryptionCipherKeyFile "../phls/liveeventkey.bin" 
        HLSEncryptKeyURI "https://<ServerName>/hls-key/liveeventkey.bin"

    Substitute the fully qualified domain name of your Flash Media Server for the <ServerName> parameter.

  3. Follow the steps in Serve encryption keys to the client to configure the server to serve keys with or without SSL. These steps configure the /hls-key path in the HLSEncryptKeyURI directive.

  4. Open Flash Media Live Encoder and publish a stream with the following settings:

    • Format—H.264

    • Keyframe Frequency—4 seconds

    • FMS URL—rtmp://<server-name>/livepkgr

    • Stream—encryption?adbe-live-event=encryption

  5. Request the following URL from an iOS device:

    http://<servername>/hls-live/livepkgr/_definst_/encryption/encryption.m3u8

  6. To verify that the stream is encrypted, run the Apple Media Stream Validator Tool on the stream. See Technical Note TN2224.

Configure live PHLS at the application level

  1. Open the rootinstall/Apache2.2/conf/httpd.conf file and locate the hlshttp_module:

    <IfModule hlshttp_module> 
        ... 
    <Location /hls-live> 
        ...
  2. Uncomment the HLSEncryptionScope directive and set it to content:

    # Uncomment the following directives to enable encryption 
    # for this location: 
        HLSEncryptionScope content 
    #    HLSEncryptionCipherKeyFile "../phls/liveeventkey.bin" 
    #    HLSEncryptKeyURI "https://<ServerName>/hls-key/liveeventkey.bin"

    Substitute the IP address or DNS of your Flash Media Server for the <ServerName> parameter.

  3. Edit the Application.xml file in the rootinstall/applications/livepkgr folder to include the following:

    <Application> 
        <HDS> 
            <HLS> 
                <Encryption enabled="true"> 
                    <KeyFile>C:\Program Files\Adobe\Flash Media Server 4.5\phls\liveeventkey.bin</KeyFile> 
                    <KeyURI>http://<server-ip>/hls-key/liveeventkey.bin</KeyURI> 
                </Encryption> 
            </HLS> 
        </HDS> 
    </Application>
  4. Follow the steps in Serve encryption keys to the client to configure the server to serve keys with or without SSL. These steps configure the /hls-key path in the KeyURI directive.

  5. Open Flash Media Live Encoder and publish a stream with the following settings:

    • Format—H.264

    • Keyframe Frequency—4 seconds

    • FMS URL—rtmp://<server-name>/livepkgr

    • Stream—encryption?adbe-live-event=encryption

  6. Request the following URL from an iOS device:

    http://<servername>/hls-live/livepkgr/_definst_/encryption/encryption.m3u8

  7. To verify that the stream is encrypted, run the Apple Media Stream Validator Tool on the stream. See Technical Note TN2224.

Configure live PHLS at the event level

  1. Open the rootinstall/Apache2.2/conf/httpd.conf file and locate the hlshttp_module:

    <IfModule hlshttp_module> 
        ... 
    <Location /hls-live> 
        ...
  2. Uncomment the HLSEncryptionScope directive and set it to content:

    # Uncomment the following directives to enable encryption 
    # for this location: 
        HLSEncryptionScope content 
    #    HLSEncryptionCipherKeyFile "../phls/liveeventkey.bin" 
    #    HLSEncryptKeyURI "https://<ServerName>/hls-key/liveeventkey.bin"

    Substitute the IP address or DNS of your Flash Media Server for the <ServerName> parameter.

  3. Edit the Event.xml file in the rootinstall/applications/livepkgr/_definst_/encryption folder to include the following:

    <Event> 
            <HLS> 
                <Encryption enabled="true"> 
                    <KeyFile>C:\Program Files\Adobe\Flash Media Server 4.5\phls\liveeventkey.bin</KeyFile> 
                    <KeyURI>http://<server-ip>/hls-key/liveeventkey.bin</KeyURI> 
                </Encryption> 
            </HLS> 
    </Event>
  4. Follow the steps in Serve encryption keys to the client to configure the server to serve keys with or without SSL. These steps configure the /hls-key path in the KeyURI directive.

  5. Open Flash Media Live Encoder and publish a stream with the following settings:

    • Format—H.264

    • Keyframe Frequency—4 seconds

    • FMS URL—rtmp://<server-name>/livepkgr

    • Stream—encryption?adbe-live-event=encryption

  6. Request the following URL from an iOS device:

    http://<ServerName>/hls-live/livepkgr/_definst_/encryption/encryption.m3u8

  7. To verify that the stream is encrypted, run the Apple Media Stream Validator Tool on the stream. See Technical Note TN2224.

Configure on-demand Protected HTTP Live Streaming

Configure PHLS for on-demand streaing at the following levels:

Server—rootinstall/Apache2.2/conf/httpd.conf

Stream—create a jit.conf file and copy it to the same directory as the content.

Server level configurations for on-demand PHLS

Configure the following directives for the hlshttp_module in the Apache httpd.conf file:

Directive

Default

Description

HLSEncryptionScope

Off

Defines the encryption scope. The following are possible values:

server —Apache encryption settings are applied to all content. The server ignores content-specific encryption configurations in Event.xml and Application.xml (live) and jit.conf (on-demand).

content —Apache encryption settings are ignored. The server uses encryption settings from Event.xml or Application.xml (live) or from jit.conf (on-demand). Off —Encryption is off for the whole server.

HLSEncryptCipherKeyFile

None

The path of the default cipher key used to encrypt the content.

HLSEncryptKeyURI

None

The URI that the client uses to fetch the encryption key. See Serve encryption keys to the client.

Stream level configurations for on-demand PHLS

Configure the following elements in a jit.conf file in the same directory as the on-demand media:

Element

Default value

Description

//manifest/hds:encryption

None

The parent element for configuration. This element has with an enabled attribute. To enable content for protection with PHLS, set the enabled attribute to "true". The value is "false" by default.

//manifest/hds:encryption/hds:keyfile

None

The path of the default cipher key used to encrypt the content.

//manifest/hds:enecryption/hds:keyuri

None

The URI that the client uses to fetch the encryption key. See Serve encryption keys to the client.

Configure on-demand PHLS at the server level

To configure PHLS at the server level, set HLSEncryptionScope to server in the httpd.conf file. This configuration tells the server to use the settings in the httpd.conf file for all requests to this Location directive.

  1. Open the rootinstall/Apache2.2/conf/httpd.conf file and locate the hlshttp_module:

    <IfModule hlshttp_module> 
        ... 
    <Location /hls-vod> 
        ...
  2. Uncomment the following:

    # Uncomment the following directives to enable encryption 
    # for this location: 
        HLSEncryptionScope server 
        HLSEncryptionCipherKeyFile "../phls/vodkey.bin" 
        HLSEncryptKeyURI "https://<ServerName>/hls-key/vodkey.bin"

    Substitute the IP address or DNS of your Flash Media Server for the <ServerName> parameter.

  3. Follow the steps in Serve encryption keys to the client to configure the server to serve keys with or without SSL. These steps configure the /hls-key path in the HLSEncryptKeyURI directive.

  4. Request the following URL from an iOS device:

    http://<ServerName>/hls-vod/sample2_1000kbps.f4v.m3u8

  5. To verify that the stream is encrypted, run the Apple Media Stream Validator Tool on the stream. See Technical Note TN2224.

Configure on-demand PHLS at the stream level

To configure individual sets of media, in the httpd.conf file, set HLSEncryptionScope to content. This setting tells the server that configuration settings in the jit.conf file override settings in the httpd.conf file.

  1. To configure live PHLS at the stream level, open the rootinstall/Apache2.2/conf/httpd.conf file and locate the hlshttp_module:

    <IfModule hlshttp_module> 
        ... 
    <Location /hls-vod> 
        ...
  2. Uncomment HLSEncryptionScope and set it to content:

    # Uncomment the following directives to enable encryption 
    # for this location: 
        HLSEncryptionScope content 
    #    HLSEncryptCipherKeyFile 
    #     HLSEncryptKeyURI
  3. Create a jit.conf configuration file and copy it to the same directory as the on-demand media files.

    <hds:hls> 
        <hds:encryption enabled="true"> 
        <hds:keyfile>../phls/content.key</hds:keyfile> 
        <hds:keyuri>https://<server-name>/hls-key/content.key</hds:keyuri> 
        </hds:encryption> 
    </hds:hls>
  4. Follow the steps in Serve encryption keys to the client to configure the server to serve keys with or without SSL. These steps configure the /hls-key path in the /hds:keyuri element.

  5. Copy the vodkey.bin file from rootinstall/phls to rootinstall/webroot/keys.

  6. Request the following URL from an iOS device:

    http://<servername>/hls-vod/sample2_1000kbps.f4v.m3u8

  7. To verify that the stream is encrypted, run the Apple Media Stream Validator Tool on the stream. See Technical Note TN2224.

Serve encryption keys to the client

The following PHLS configurations specify the path the client uses to fetch the encryption key:

  • HLSEncryptKeyURI

  • //manifest/hds:hls/hds:encryption/hds:keyuri

  • //Application/HDS/HLS/Encryption/KeyURI

  • //Event/HLS/Encryption/KeyURI

For both on-demand and live PHLS, serve encryption keys to the client through the Apache HLS module. The module unscrambles the key before serving the request.

You can enable client authentication over SSL to ensure that key files are served securely. A reference configuration file and the Apple CA bundle are installed to the following locations:

rootinstall/Apache2.2/conf/httd-hls-secure.conf

rootinstall/phls/certs/ca

The httpd-hls-secure.conf file demonstrates how to configure a virtual host at the default SSL port with client authentication enabled for the location /hls-key with cipher key hosting enabled. However, this is only a reference configuration. To guarantee authentication for a production system, customize the configuration for your deployment.

Note: The SSL certificate presented by the iOS client must be current. If the client presents an expired certificate, client authentication fails and an error message displays to the user (on the client). iOS clients with older iOS installations may encounter this problem.

Serve key files with SSL client authentication

  1. Uncomment the following lines in the Apache httpd.conf file:

    "#LoadModule ssl_module" 
    "#Include conf/httpd-hls-secure.conf"
  2. Customize the SSL properties in the rootinstall/Apache2.2/conf/httpd-hls-secure.conf file based on the deployment. This customization includes getting an SSL certificate from a recognized CA.

    Important: The SSL certificate generated for the server must have a CN that is a FQDN (Fully Qualified Domain Name), even in a test environment. If not, the iOS client may not present its client certificate and client authentication fails. If client authentication fails, the key file is not served and the iOS client crashes. This is a known Apple bug.
  3. Restart Apache.

Serve key files without SSL

  1. Add the following to the Apache httpd.conf file under the line <IfModule hlshttp_module>:

    <Location /hls-key> 
        HLSEncryptHostCipherKey true 
        HLSFmsDirPath ".." 
        HLSEncryptKeyRepository "../phls" 
    </Location>

    The Location path can be any value. Point the HLSEncryptKeyRepository directive to the location of the keys. The keys are in the rootinstall/phls folder by default.

  2. Restart Apache.

Use the following parameters in the Apache httpd.conf file to configure key hosting:

Parameter

Description

Default value

HLSEncryptHostCipherKey

Enable (true) or disable (false) cipher key hosting from this location.

false

HLSEncryptKeyRepository

The path of the folder that contains the key file.

None

Use live PHDS and PHLS together

Publishing one set of streams to Flash Media Server for delivery with live PHLS and PHDS requires special configuration.

When PHDS is enabled, the server ingests a stream and packages it into encrpypted F4F data. However, PHLS requires unencrypted data as its source. It’s not possible to take the encrypted F4F data and encrypt it again for PHLS.

To deliver protected content to Flash Player/AIR and iOS devices, configure your encoder to publish to two different applications, one for HDS and one for HLS.

  1. Create two copies of the livepkgr application. Name them “livepkgr_hds” and “livepkgr_hls”.

  2. Configure the httpd.conf files as follows:

    1. For PHDS, use the following Location directive:

      <Location /hds-live> 
          HttpStreamingEnabled true 
          HttpStreamingLiveEventPath "../applications/livepkgr_hds" 
          HttpStreamingContentPath "../applications/livepkgr_hds" 
          HttpStreamingURLSandboxLevel "App" 
          HttpStreamingF4MMaxAge 2 
          HttpStreamingBootstrapMaxAge 2 
          HttpStreamingFragMaxAge -1 
          Options -Indexes FollowSymLinks 
      </Location>
    2. For PHLS use the following Location directive:

      <Location /hls-live> 
          HttpStreamingEnabled true 
          HttpStreamingLiveEventPath "../applications/livepkgr_hls" 
          HttpStreamingContentPath "../applications/livepkgr_hls" 
          HttpStreamingURLSandboxLevel "App" 
          HttpStreamingF4MMaxAge 2 
          HttpStreamingBootstrapMaxAge 2 
          HttpStreamingFragMaxAge -1 
          Options -Indexes FollowSymLinks 
      </Location>
    3. Restart Apache.

  3. Publish streams from Flash Media Live Encoder to the livepkgr_hds and livepkgr_hls applications. Use the stream name livestream%i?adbe-live-event=liveevent.

  4. The request URLs are:

    • (PHDS) http://<serveruri>/hds-live/_definst_/<liveevent>.f4m

    • (PHLS) http://<serveruri>/hls-live/_definst_/<liveevent>.m3u8

    Because the directive HttpStreamingURLSandboxLevel is set to "App", the request URL doesn’t use the application name.