FairPlay Streaming

Programming Guide

 Developer
Contents
About FairPlay Streaming ....................................................................................................................6
At a Glance ...........................................................................................................................................................................6
A Key Security Module Wraps a Key for Delivery .........................................................................................8
An FPS-Aware Playback App Asks the Key Security Module for a Key ...............................................8
FPS Sends Content Keys Securely ......................................................................................................................8
Content Server Delivers the Content Stream ..............................................................................................10
FairPlay Streaming SDK Contents .....................................................................................................................10
See Also ...............................................................................................................................................................................10
Programming the Key Security Module .........................................................................................11
Overview of Processing Steps ....................................................................................................................................11
Cryptographic Formula Syntax ..................................................................................................................................11
SPC and CKC Messages .................................................................................................................................................12
TLLV Block Structure...............................................................................................................................................12
The SPC Message .............................................................................................................................................................14
The SPC Payload ......................................................................................................................................................14
Session Key and Random Value Block ............................................................................................................17
Session Key and Random Value Integrity Block .........................................................................................18
Protocol Version Blocks .........................................................................................................................................18
Constructing the CKC Message .................................................................................................................................21
CKC Payload ...............................................................................................................................................................21
Encrypting the Content Key ...............................................................................................................................22
Returning SPC Blocks in the CKC Payload ....................................................................................................23
Encrypting the CKC Payload...............................................................................................................................23
Understanding the TLLVs...................................................................................................................25
Capabilities ........................................................................................................................................................................25
Device Info Support .......................................................................................................................................................27
Kext Deny List ...................................................................................................................................................................28
Device Identity .................................................................................................................................................................29
Security Level Support ..................................................................................................................................................31
HDCP Enforcement.........................................................................................................................................................34
Renting and Leasing the Content Key ............................................................................................35

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 2 of 66
 Content Key Expiration .................................................................................................................................................35
Video Rental ..............................................................................................................................................................35
Secure Lease .............................................................................................................................................................35
TLLV for Rental and Lease ............................................................................................................................................35
Establishing the Rental and Lease Period .............................................................................................................36
Simultaneous Renting and Leasing .........................................................................................................................37
O ine FairPlay Streaming .................................................................................................................39
Preloading O ine Keys ........................................................................................................................................40
O ine Rental Support ........................................................................................................................43
Storage and Playback Expiry ..............................................................................................................................43
O ine Key ..................................................................................................................................................................43
Sync ..............................................................................................................................................................................44
Testing the Key Security Module .....................................................................................................47
Developing an FPS-Aware App ........................................................................................................48
Identifying Your FPS App with an Application Certi cate .............................................................................48
Integrating FPS with the iOS Decryption Process .............................................................................................48
Integrating FPS in Safari ...............................................................................................................................................49
EME Message Exchange .......................................................................................................................................49
Requesting a Content Key from the Key Server .................................................................................................50
Processing the Key Server’s Response....................................................................................................................50
Con guring AirPlay Mode ............................................................................................................................................51
Interpreting Error Messages ........................................................................................................................................51
Manually Fetching FPS Error Messages..................................................................................................................52
Formatting and Encrypting Streams ..............................................................................................54
Preparing Content for FPS ...........................................................................................................................................54
Including Initialization Vectors (IV) in Playlists....................................................................................................54
Using FPS Options with the Media File Segmenter ..........................................................................................55
Using ALLOWED-CPC in playlist to improve tier selection ............................................................................56
Using the FPS SDK and Tools ............................................................................................................58
FairPlay Streaming SDK Contents .............................................................................................................................58
Testing the Key Security Modules ............................................................................................................................58
Verifying your SPC processing in your KSM .................................................................................................58
Verifying your CKC creation in your KSM ......................................................................................................60
Debugging KSM ..............................................................................................................................................................63

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 3 of 66
ffl
ffl
ffl
fi
ffl
fi
Document Revision History ..............................................................................................................64

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 4 of 66
 Figures

Figure 1-1 FPS exchanges .....................................................................................................................................................8

Figure 1-2 FPS information ow .........................................................................................................................................9
Figure 2-1 TLLV block structure ........................................................................................................................................12
Figure 5-1 O ine playback..................................................................................................................................................40
Figure 5-2 Persistent key request ......................................................................................................................................41
Figure 8-1 FPS information ow ......................................................................................................................................50
Listing 8-1 Manually fetching FPS errors .......................................................................................................................52
Listing 9-1 Adding FPS to an HLS Playlist .....................................................................................................................54
Listing 9-2 Media File Segmenter command..............................................................................................................55
Listing 9-4 Adding ALLOWED-CPC to an HLS Playlist ..............................................................................................56
Listing 10-1 Parsing the SPC ..............................................................................................................................................59
Listing 10-2 Validating the CKC ........................................................................................................................................60

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 5 of 66
ffl
fl
fl
About FairPlay Streaming
Apple FairPlay Streaming (FPS) securely delivers keys to:

• Apple mobile devices (iOS-based, iPadOS-based, watchOS-based, and visionOS-based).

• Apple TV.

• Safari on macOS, iPadOS and iOS.

This will enable playback of encrypted video content. This content is delivered over the Web using HTTP
Live Streaming (HLS) technology.

For simplicity, these devices will collectively be referred to as “Apple devices” throughout the remainder
of this document.

Note that FPS also delivers keys to FPS-enabled TVs and STBs via AirPlay protocol.
FPS protects the delivery of keys that decrypt streamed audio and video media. An Apple device can
securely acquire a key from a content provider's key server. The operating system uses the key to
decrypt the media before playback.

FPS key delivery o ers the following features and behaviors:

• AES 128-bit content keys generated by the key server.

• Every key is known only to the key server and to the Apple device.
• When playback is stopped, the key for the Apple device is permanently discarded from memory.
• The key server can specify the duration of the key's validity for the Apple device.
• Protection of MPEG-2 le formats.
FPS allows the device to stop playback based on expiration information sent with the content key. Using
FPS on an Apple device ensures secure key transmission and secure use for media decryption.

At a Glance
As an approved Apple FPS developer, you implement FPS by writing code to run on your key server and
in your playback app, so that both recognize FPS messages. When an Apple device plays a media stream
with a playlist containing an FPS-speci c tag, the operating system asks the app to obtain the
decryption key. To do so, the app calls an API that invokes FPS, causing the operating system to prepare
an encrypted request for the key for that media. When the app sends the request to the server, the FPS
code on the server wraps the required key in an encrypted message and sends it to the app. The app
then asks the operating system to unwrap the message and decrypt the stream, so the Apple device can
play the media.

The implementation process requires three programming tasks:

• Writing a Key Security Module that is installed in a key server's software. This module exchanges
messages with the Apple device during the FPS process.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 6 of 66
ff
fi
fi
 • Adding code to make an Apple device playback app FPS-aware. The app communicates with a
server that can deliver the key to decrypt the content, such as a movie. Figure 1-1 shows an FPS
system including an FPS-aware playback app.
• Creating the formatting and encryption software for the media content server. This software
prepares the encrypted content stream according to the Apple HTTP Live Streaming (HLS)
speci cation.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 7 of 66
fi
Figure 1-1 FPS exchanges

A Key Security Module Wraps a Key for Delivery

The Key Security Module (KSM) implements FPS algorithms that can interpret an encrypted key request
message from an Apple device and create an encrypted response containing the key for the speci ed
media. You must write code for the key server enabling those algorithms.

An FPS-Aware Playback App Asks the Key Security Module for a Key
A FPS-aware playback app uses an operating system programming interface to obtain the encrypted
request for the key, send it to the KSM, and receive the key for the media asset decryption. Your app will
also need code supporting user interactions.

FPS Sends Content Keys Securely

An FPS messaging session delivers a content key to the player app. Typically, the session proceeds as
follows:
1. The app asks the operating system to play speci c content identi ed by a URL.
2. The operating system accesses the content and checks its playlist.
3. An attribute in the playlist identi es the content as encrypted by a content key obtainable
through FPS.
4. The operating system informs the app that the content is encrypted using FPS.
5. The app asks the operating system to prepare an FPS message that requests the content key.
6. The operating system delivers an encrypted Server Playback Context (SPC) message to the app.
7. The app sends the SPC to a key server that contains a KSM.
8. The KSM decrypts the SPC and gets the requested content key from the key server.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 8 of 66
fi
fi
fi
fi
 9. The KSM wraps the content key inside an encrypted content key context (CKC) message, which it
sends to the app.
10. The app delivers the CKC to FPS software integrated in the operating system, which then uses it
to decrypt the media content, as described below.
These steps move information between FPS modules as shown in Figure 1-2.

Figure 1-2 FPS information ow

After the FPS software receives the CKC, it extracts the content key and provides the key to the OS. The
OS uses the key to decrypt and play the content requested in step 1 of Figure 1-2.
The streaming media playlist contains a list of versions of FPS that the key server supports. The
operating system discerns and lists the mutually recognized FPS versions in the operating system’s
encrypted key request. The key server then picks which version to use.

Throughout this process, the app and the server can communicate through any transport link chosen by
the app developer.

The content streams in conformance with the HLS protocol, using H.264 video and audio formats.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 9 of 66
fl
Content Server Delivers the Content Stream
The content server delivers the formatted and encrypted content stream to the Apple device. Only the
Apple device, using keys delivered by FPS, can decrypt the stream and recover its content.

FairPlay Streaming SDK Contents

The FairPlay Streaming SDK from Apple is provided in two parts:

Part 1. The FairPlay Streaming Server SDK contains a reference implementation of the Key Security
Module, a client sample, a speci cation and a set of test vectors. The test vectors can help establish and
test the Key Security Module.

Part 2. The FPS Deployment Package contains the D Function and speci cation along with instructions
on how to generate the FairPlay Streaming Certi cate, private key and Application Secret key (ASk).

An FPS transaction round-trip between the server Key Security Module and a client requires both parts.
The content owner must request the FPS Deployment Package materials to complete the Key Security
Module for production deployment.

See Also
The following documents contain speci cations and instructions that supplement the material in this
programming guide:

• See HTTP Live Streaming Overview for general guidance on Apple streaming technology used
with FairPlay Streaming.
• See MPEG-2 Stream Encryption Format for HTTP Live Streaming for information on the
FairPlay Streaming media formats.
• See HTTP Live Streaming Protocol for the IETF Internet-Draft of the HLS speci cation.
• See the following industry standards, relevant to FPS:
• Information technology—generic coding of moving pictures and associated audio
information: Systems is the ITU-T Recommendation H.222.0 document, also published as
ISO/IEC International Standard 13818-1:2013.
• Advanced video coding for generic audiovisual services is the ITU-T Recommendation
H.264 document, also published as ISO/IEC International Standard 14496-10:2014.
• Information technology—Coding of audio-visual objects—Part 3: Audio is the ISO/IEC
International Standard 14496-3:2009.
• Digital Audio Compression Standard (AC-3) is the Advanced Television Systems Committee
(ATSC) standard A/52:2012.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 10 of 66
fi
fi
fi
fi
fi
Programming the Key Security Module
The Key Security Module (KSM) is the part of FairPlay Streaming (FPS) technology that resides in the
software of a content provider’s key server. Its code must run on the server platform and implement the
algorithms described in this chapter.

The KSM serves as a liaison between the playback app and the Apple device. The initial message from
app to Apple device contains the server playback context (SPC). The Apple device’s operating system
parses the SPC and generates the content key context (CKC). The KSM encrypts and delivers the content
key to the Apple device. The Apple device uses the content key to decrypt the FPS media sent from the
content server. Requesting a Content Key from the Key Server describes this SPC exchange.

Overview of Processing Steps

Table 2-1 summarizes a typical sequence of actions that a server and its KSM might perform to support
FPS.

Table 2-1 Typical server program steps

Step Server action

1 Receive an SPC message from an app running on an Apple device and parse it. See The SPC
Message.

2 Check the SPC's certi cate hash value against the AC. See Identifying Your FPS App with an
Application Certi cate and Table 2-3.

3 Decrypt the SPC payload. See SPC Payload Decryption.

4 Verify that the Apple device is using a supported version of FPS software. See Protocol
Version Blocks.

5 Decrypt the session key and random value block in the SPC payload. See Decrypting the
[SK...R1] Payload.

6 Check the integrity of the SPC message. See Session Key and Random Value Integrity Block.

7 Encrypt the content key. See Encrypting the Content Key.

8 Assemble the contents of the CKC payload. See Table 2-11.
9 Encrypt the CKC payload. See Encrypting the CKC Payload.
10 Construct the CKC message and send it to the app on the Apple device. See Table 2-10.

Cryptographic Formula Syntax

This chapter uses the following conventions to formulate cryptographic processes:

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 11 of 66
fi
fi
 • Square brackets denote an encrypted value. For example, [Info] means that the plaintext
value Info is encrypted.
• e(Info)K denotes the encryption of the plain text value Info, using the key K. The convention
may also specify the encryption algorithm: RSA e(Info)K indicates the use of RSA encryption,
whereas AES_CBCIV e(Info)K indicates the use of AES encryption in cipher block chaining
(CBC) mode with an initialization vector (IV).
• Similarly, d(Info)K denotes the decryption of the encrypted value Info using the key K, and
AES_ECB d(Info)K indicates the use of AES decryption in electronic codebook (ECB) mode.
For an example of this syntax, see SPC Payload Decryption.

SPC and CKC Messages

The SPC message that the playback app sends to the key server, and the CKC message that the KSM
generates in reply, have these common characteristics:
• Messages consist of a xed-length header followed by a variable-length payload.
• Payload is encrypted; in the SPC, part of the header is encrypted as well.
• The payloads in both the SPC and the CKC are divided into structures called tag-length-length-
value (TLLV) blocks. This data layout is described in TLLV Block Structure.
• TLLV blocks are tightly packed into the payload elds, but the blocks are located in random
sequence.
• TLLV blocks are locatable in each payload by searching for their unique 8-byte tags, which begin
each block. For each tag value, only one block with that tag can exist in an SPC or CKC message.
• The contents of TLLV blocks and all other FPS data structures are in cleartext AES format.
• All numeric elds in the SPC, CKC, and TLLVs are stored in network (big-endian) order.

TLLV Block Structure

All TLLV blocks use the basic structure shown in Figure 2-1. The elds in this structure are in Table 2-2.

Figure 2-1 TLLV block structure

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 12 of 66
fi
fi
fi
fi
 Table 2-2 TLLV block elds

Field content Byte range Description

Tag 0-7 A sequence of bytes that is unique within an SPC or CKC

payload.

Block length 8-11 The number of bytes in the value plus padding elds of the
TLLV (following the tag, block length, and value length
elds). The block length must be lled out to a multiple of
16 bytes by extending the padding eld.

Value length 12-15 The number of bytes in the value eld. This number may be
any amount, including 0x0000.

Value 16 . . . k The payload of the TLLV, starting with byte 16 of the block.

Padding k+1 . . . n A eld that begins with the next byte after the value eld
(padding_size) (byte k+1). It must ll out the TLLV to a multiple of 16 bytes,
but may be randomly extended in increments of 16 bytes.
Thus the following relation holds:
padding_size = block_length - value_length

The padding eld must contain random values, not all 0x00
or 0xFF bytes.

Note: An SPC message may contain reserved TLLV blocks with tag values not covered in this
documentation. Such blocks should be ignored by the KSM.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 13 of 66
fi
fi
fi
fi
fi
fi
fi
fi
fi
fi
 The SPC Message
Con gure the key server so that it delivers to its KSM every SPC message that the Apple device
generates. Each SPC message is a container with a header of xed-length elds and a variable-length
data payload, as listed in Table 2-3. A sample SPC message is included in the FPS development support
package; see Using the FPS SDK and Tools.

Table 2-3 SPC container structure

Field content Byte range Description

SPC version 0-3 The version number of the SPC. The version number
covered by this programming guide is 0x00000001.

Reserved 4-7 Reserved for Apple; ignore these bytes.

SPC data 8-23 A CBC initialization vector that has a unique value for each
initialization SPC message. See SPC Payload Decryption.
vector (IV)

Encrypted 24-151 The key for decrypting the SPC payload. This key is itself
AES-128 key encrypted, using RSA public key encryption with Optimal
Asymmetric Encryption Padding (OAEP), as described in
SPC Payload Decryption.

Certi cate hash 152-171 The SHA-1 hash value of the encrypted Application
Certi cate, which identi es the private key of the developer
that generated the SPC. See Identifying Your FPS App with
an Application Certi cate.

SPC payload 172-175 The number of bytes in the encrypted SPC payload.
length Because the payload consists of blocks whose lengths are
multiples of 16 bytes, this number is a multiple of 16.

SPC payload 176 . . . n A variable-length set of TLLV blocks, as described in TLLV

Block Structure. The whole payload is AES-128 encrypted
using the encrypted key contained in bytes 24-151 of the
SPC message. The minimum set of TLLV blocks that the KSM
must extract from this payload is speci ed in SPC Payload
Contents.

The SPC Payload

The SPC payload begins at byte 176 of the SPC message and runs for the byte length speci ed by the
value of the SPC payload length eld (bytes 172-175). The SPC payload must be decrypted as speci ed in
SPC Payload Decryption. Read about the decrypted value in SPC Payload Contents.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 14 of 66
fi
fi
fi
fi
fi
fi
fi
fi
fi
fi
fi
 SPC Payload Decryption
Decrypt the payload of the SPC message, which begins at byte 176, using the AES-128 cryptography
standard with a cipher block chaining (CBC) mode of operation. The rst block of the chain contains the
CBC initialization vector (IV) contained in bytes 8-23 of the SPC message.

Obtain the key for the AES decryption of the SPC payload (called SPCK) by decrypting bytes 24-151 of
the SPC message using the RSA cryptography standard with Optimal Asymmetric Encryption Padding
(OAEP). The key for the RSA decryption of the SPCK is the server's RSA private key. An example of such a
key is in the FPS developer support package; see Using the FPS SDK and Tools.

In cryptographic formula syntax, decrypting the payload of the SPC consists of the following two
decryption processes:

SPCK = RSA_OAEP d([SPCK])Prv where

[SPCK] represents the value of SPC message bytes 24-151.
Prv represents the server's private key.

SPC payload = AES_CBCIV d([SPC data])SPCK where

[SPC data] represents the remaining SPC message bytes beginning at byte 176 (175 + the
value of SPC message bytes 172-175).
IV represents the value of SPC message bytes 8-23.

SPC Payload Contents

The decrypted SPC payload contains two TLLV types:

• De ned TLLVs listed in Table 2-4

• Unde ned TLLVs
Any TLLV must appear only once in the SPC payload. TLLVs cannot be repeated in the same SPC payload.

Table 2-4 TLLV blocks in the SPC payload

TLLV content Tag value Description

[SK...R1] 0x3d1a10b8bffac2ec A combination of values that the KSM will use to encrypt
the content key and the CKC payload. Parse and decrypt
this block as described in Session Key and Random
Value Block. Return the R1 value to FPS in the payload of
the CKC message, as described in CKC Payload.

[SK...R1] integrity 0xb349d4809e910687 A 16-byte value used to check the integrity of the
contents of the [SK...R1] block. See Session Key and
Random Value Integrity Block.

Anti-replay (AR) 0x89c90f12204106b2 A 16-byte value used in the encryption of the CKC
seed payload. See Encrypting the CKC Payload.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 15 of 66
fi
fi
fi
TLLV content Tag value Description
R2 0x71b5595ac1521133 A 21-byte value used in decrypting the payload of the
[SK...R1] block. See Decrypting the [SK...R1] Payload.

Tag return 0x19f9d4e5ab7609cb A TLLV block that contains zero or more concatenated 8-
request byte values, each of which is the tag for a di erent TLLV
block in the SPC. Retrieve and return all of the TLLV as is
in the CKC payload. See Returning SPC Blocks in the CKC
Payload.

Asset ID 0x1bf7f53f5d5d5a1f A content provider ID that tells the key server which
content needs to be decrypted. The playback app may
generate this value, or the FPS implementer may create
it. Its length can range from 2 to 200 bytes, inclusive. The
asset ID content is padded to a multiple of 16 bytes,
regardless of the original length.

Transaction ID 0x47aa7ad3440577de An 8-byte value that identi es the current FPS

transaction. The KSM does not need to process this
information.

Protocol versions 0x67b8fb79ecce1a13 A concatenation of 4-byte values identifying the Apple

supported device-supported versions of FPS. See Protocol Version
Blocks.

Protocol version 0x5d81bcbcc7f61703 A 4-byte value that identi es the version of FPS that the
used Apple device is using for this FPS transaction. See
Protocol Version Blocks.

Streaming 0xabb0256a31843974 A single 8-byte value. See Table 2-5.

indicator

Media playback 0xeb8efdf2b25ab3a0 Media playback information for rental and lease. See
state TLLV for Rental and Lease.

Capabilities 0x9c02af3253c07fb2 Apple device capabilities. See Capabilities.

Device Identity 0x94c17cd676c69b59 Client device information. See Table 3-6.

Table 2-5 Streaming indicator values

Value Description
0xabb0256a31843974 AirPlay will send content to an Apple TV box.

0x5f9c8132b59f2fde An Apple digital AV adapter will send content.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 16 of 66
fi
fi
ff
 Value Description
Any other value The requesting device plays back the content.

Session Key and Random Value Block

The SPC delivers these two values in a single TLLV block called the [SK...R1] block:

• The 16-byte session key, SK, which is used to encrypt the content key as described in Encrypting
the Content Key.

• A 44-byte random number, R1, which is used in the encryption of the CKC payload as described
in Encrypting the CKC Payload. These bytes are also returned to the Apple device in the CKC
payload, as shown in Table 2-11.

The structure of the whole [SK...R1] block, including its tag and length elds, is listed in Table 2-6.
Decrypt the payload contained in this block as described in Decrypting the [SK...R1] Payload.

Table 2-6 [SK...R1] TLLV block

Field content Byte range Description

TLLV tag 0-7 An 8-byte value of 0x3d1a10b8bffac2ec.

Total length 8-11 The total length of this TLLV block in bytes. The amount
of padding at the end of the block, if any, determines the
total length. It must be a multiple of 16 and greater than
127.

Value length 12-15 The length of the content of this TLLV block in bytes,
0x00000070 (decimal 112). The content consists of the
initialization vector and payload elds.

Initialization 16-31 A 16-byte CBC initialization vector used in decrypting the

vector (IV) next 96 bytes; see Decrypting the [SK...R1] Payload.

Payload 32-127 The 96-byte payload of the block. Decrypt this payload as
described in Decrypting the [SK...R1] Payload to yield its
contents.

Padding 128-n Random values to ll out the TLLV to a multiple of 16

bytes. See the description of the Padding eld in Table
2-2.

Decrypting the [SK...R1] Payload

To recover the SK and the R1 value, the KSM must decrypt the payload of the block listed in Table 2-6,
using AES-128 decryption with cipher block chaining (AES_CBC). The KSM must use the initialization
vector (IV) contained in bytes 16-31 of the [SK...R1] block (see Table 2-6) to initialize the rst block of the
AES_CBC chain.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 17 of 66
fi
fi
fi
fi
fi
Obtain the DASk by following the instructions in D Function Computation Guide, a separate document
that provides instructions on calculating the DASk. The computation of the DASk requires input of the
R2 block contents and the application secret key (ASk). The DASk value di ers for each SPC request.

In cryptographic formula syntax, decrypt the payload of the [SK...R1] block using the following process:

DASk = D(R2, ASk) where

R2 represents the contents of the R2 block in the SPC payload.

ASk represents the playback app's secret key.
D represents the function described in D Function Computation Guide.

Payload = AES_CBCIV d([[SK...R1] payload])DASk where

IV represents the value of [SK...R1] block bytes 16-31.

[[SK...R1] payload] represents the value of [SK...R1] block bytes 32-127.
SK and R1 are integrity numbers that represent elds in payload.

Table 2-7 Decrypted [SK...R1] payload

Field content Byte range Description

Session key (SK) 0-15 A 16-byte value used in the encryption of the content key. See
Encrypting the Content Key.

HU 16-35 A 20-byte value that represents the anonymized unique ID of the

playback device. However, if the value of the streaming indicator TLLV
(Table 2-4) in the SPC payload is 0x5f9c8132b59f2fde, then this value
represents the ID of the Apple digital AV adapter and should not be
used for device management (see Table X-Y).

R1 36-79 A 44-byte random number used in the encryption of the CKC payload
and returned to the Apple device in the CKC payload. See Encrypting
the CKC Payload.

Integrity bytes 80-95 16 bytes used to check the integrity of this SPC message, as explained
in Session Key and Random Value Integrity Block.

Session Key and Random Value Integrity Block

The [SK...R1] integrity block contains a 16-byte value that is used to check the integrity of the SPC. The
KSM should compare the SPC contents with the 16-byte integrity number value in bytes 80-95 of the
decrypted [SK...R1] payload; see Table 2-7. If the two numbers are not identical, the SPC is not valid and
the KSM should reject it.

Protocol Version Blocks

The integrated FPS code in each Apple device uses two TLLV blocks in the SPC (listed in Table 2-4) to tell
the KSM about the device versioning.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 18 of 66
fi
ff
 • The protocol versions supported block lists all the versions of FPS that the Apple device
supports.
• The protocol version used block identi es the one version that the Apple device is using for the
current transaction.
The purpose of sending versioning information in the SPC is to ensure that the key server and the Apple
device are using the same version of FPS, and that it is the latest version that they both support.

The streaming content’s playlist contains a list of the FPS versions that the key server supports for that
content. As a good practice, your KSM should compare this list with the list of FPS versions in the
protocol versions supported block. The protocol version used block should contain the ID of the most
recent version common to both platforms. If the Apple device is not using the most recent common
version, the app may be trying to attack FPS security. If there is no common version, the Apple device
should not have generated an SPC and the KSM should reject the transaction.

Table 2-8 displays some recommended version con gurations.

Note: Versioning should be decided between the server and the Apple device. The playback app should
never contain embedded version information.

Table 2-8 Version con gurations that follow good practices

Server Apple device SPC information

Version 1 Version 1 Used = 1

Supported = 1

Versions 1 and 2 Version 1 Used = 1

Supported = 1

Versions 1 and 2 Versions 1 and 2 Used = 2

Supported = 1 and 2

Version 2 Versions 1 and 2 Used = 2

Supported = 1 and 2

Table 2-9 displays other con gurations that do not follow good practices and why these con gurations
should be avoided.

Table 2-9 Version con gurations that do NOT follow good practices

Server Apple device SPC information Implications

Version 1 Versions Used = 1 The server veri es the version used and uses
1 and 2 Supported = 1 and 2 version 1. However, a newer version of FPS is
available, so the server should be updated.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 19 of 66
fi
fi
fi
fi
fi
fi
fi
Server Apple device SPC information Implications
Version 2 Version 1 Used = 1 A mismatch exists between the FPS version on
Supported = 1 the Apple device and on the server; reject the
SPC.

Versions Versions Used = 1 An app may have tried to exploit the server by
1 and 2 1 and 2 Supported = 1 and 2 forcing it to use an old version of FPS.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 20 of 66
Constructing the CKC Message
The KSM must respond to every SPC message by returning a corresponding CKC message to the Apple
device that sent it. Each CKC message is a container with a header of xed-length elds and a variable-
length data payload, as listed in Table 2-10. The FPS Developer Support Package packaged with the SDK
contains a sample CKC message.

Table 2-10 CKC container structure

Field content Byte range Description

CKC version 0-3 The version number of the CKC. The version number
covered by this programming guide is 0x00000001.

Reserved 4-7 Reserved by Apple; ignore these bytes.

CKC data initialization 8-23 A random 16-byte initialization vector, generated by the
vector KSM, that has a unique value for each CKC message. The
vector assists in initializing the rst block of the AES_CBC
chain, as described in Encrypting the CKC Payload.

CKC payload length 24-27 The number of bytes in the encrypted CKC payload.
Because the payload consists of blocks whose lengths are
multiples of 16 bytes, this number is a multiple of 16.

CKC payload 28 . . . n A variable-length set of contiguous TLLV blocks, as

described in CKC Payload. The CKC payload is AES-128
encrypted as described in Encrypting the CKC Payload.

CKC Payload
The KSM uses the session key (SK) to encrypt the content key. The payload of a CKC message contains
the content key that the Apple device uses to decrypt the media for playback.

Table 2-11 lists the TLLV blocks in the CKC payload. The order of these blocks should be random.

Table 2-11 Contents of the CKC payload

TLLV content Tag value Description

Encrypted CK 0x58b38165af0e3d5a Mandatory. A TLLV block containing a content

initialization vector and a 16-byte encryption of the
content key provided by the server. See Encrypting the
Content Key.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 21 of 66
fi
fi
fi
 TLLV content Tag value Description
R1 0xea74c4645d5efee9 Mandatory. A TLLV block containing the 44-byte R1 value
that the KSM receives in the SPC payload. See Session
Key and Random Value Block.

Content key 0x47acf6a418cd091a A TLLV that speci es the period of validity of the content
duration key. This TLLV may be present only if the KSM receives an
SPC with a Media Playback State TLLV. See Establishing
the Rental and Lease Period.

Blocks speci ed The CKC must return, unchanged, the TLLV blocks that
by a tag return the SPC requested in a tag return request. See Returning
request SPC Blocks in the CKC Payload.

Required Security 0x644cb1dac0313250 An optional TLLV, that speci es the minimum required
Level Security Level of the client device. See Security Level
Support.

O ine Key 0x6375d9727060218c Support for o ine playback. See O ine Rental support.

HDCP 0x2e52f1530d8ddb4a An optional TLLV that speci es whether HDCP

enforcement enforcement is required. The absence of this TLLV
enforces HDCP Type 0. See Table 3-12.

Because all the blocks listed above are padded to multiples of 16 bytes, the CKC payload as a whole does
not require further padding.

Encrypting the Content Key

The content provider creates the content key that is used to decrypt the media on the Apple device. The
provider must encrypt this key using AES-128 encryption before placing it into the CKC payload. The
session key that FPS sent to the KSM in the SPC payload serves as the encryption key.
In crypto-formula syntax, encrypting the content key consists of the following process:

[CK] = AES_ECB e(CK)SK where

CK is the content key provided by the key server.
SK is the content of the session key block from the SPC payload.

The encrypted content key must be 16 bytes long. It becomes the content of the content key TLLV,
shown in Table 2-12, which is encrypted and made part of the CKC payload (see Table 2-11). The CKC
payload is further encrypted as described in Encrypting the CKC Payload.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 22 of 66
ffl
fi
ffl
fi
fi
fi
ffl
Table 2-12 Content Key TLLV

Field name Byte range Description

TLLV tag 0-7 An 8-byte value of 0x58b38165af0e3d5a.

Total length 8-11 The total length of this TLLV block in bytes. The total
length is determined by the amount of padding at the
end of the block, if any; it must be a multiple of 16 and
greater than 31.

Value length 12-15 The length of the content of this TLLV block in bytes,
0x00000020 (decimal 32).

Initialization vector 16-31 A 16-byte CBC initialization vector used in AES encryption
(IV) and decryption of audio and video assets.

Content key (CK) 32-47 The 16-byte content key encrypted using the SK.
Padding 48-n Random values that ll out the TLLV to a multiple of 16
bytes. See the description of the Padding eld in Table
2-2.

Returning SPC Blocks in the CKC Payload

The SPC payload contains a tag return request. This TLLV contains a list of the tags of other TLLVs. The
KSM must return those TLLVs (unaltered, with original tag and contents) at the end of the payload of the
CKC.

Encrypting the CKC Payload

The CKC blocks that the KSM encrypted form the CKC payload. The blocks include the following, in
random order:

• An encrypted content key TLLV block containing the 16-byte encrypted content key, as
described in Encrypting the Content Key.
• The R1 TLLV block from the SPC payload; see Session Key and Random Value Block.
• All TLLV blocks from the SPC payload that must be returned in the CKC payload, as described in
Returning SPC Blocks in the CKC Payload.
To encrypt the CKC payload, compute the AR_key value by taking the rst 16 bytes of an SHA-1 digest
of the R1 value sent in the payload of the SPC; see Session Key and Random Value Integrity Block. That
AR_key value is then used as a key to encrypt the AR seed obtained from the SPC payload (see Table
2-4).

The resulting encrypted AR seed is the key that encrypts the CKC data section using AES-128 with cipher
block chaining (CBC). The KSM generates the CKC data initialization vector, sent to the Apple device in
bytes 8-23 of the CKC message, shown in Table 2-10.

In cryptographic formula syntax, encrypting the payload of the CKC consists of the following process.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 23 of 66
fi
fi
fi
AR_key = first 16 bytes of SHA-1(R1) where
R1 represents the content of R1 block from the SPC payload.
[AR] = AES_ECB e(AR Seed)AR_key where
AR Seed represents the content of AR seed block from the SPC payload.
[CKC data] = AES_CBCIV e([CK] block, R1 block, Requested SPC blocks)[AR]
where
IV represents the random initialization vector generated by the KSM.
[CK] block represents the TLLV block containing the encrypted content key.
R1 block represents the R1 block from the SPC payload.
Requested SPC blocks represents the TLLV blocks listed in an SPC tag return
request.
[CKC data] represents the CKC payload.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 24 of 66
 Understanding the TLLVs
Capabilities
The Capabilities TLLV communicates features supported by the Apple device to KSM. The Capabilities
TLLV is part of the SPC sent to the KSM.

Table 3-1 Capabilities TLLV

Field name Byte range Description

TLLV tag 0-7 An 8-byte value of 0x9c02af3253c07fb2.

Total length 8-11 The total length of this TLLV block in bytes. The amount of
padding at the end of the block, if any, determines the
total length. It must be a multiple of 16 and greater than
31.

Value length 12-15 The length of the content of this TLLV block in bytes,
0x00000010 (decimal 16).

Capabilities bits 16-23 An 8-byte eld containing capability bits 64-127. See Table
(high) 3-2.

24-31 An 8-byte eld containing capability bits 0-63. See Table

Capabilities bits (low) 3-2.

Padding 32-n Random values that ll out the TLLV to a multiple of 16

(padding_size) bytes. See the description of the Padding eld in Table
2-2.

The two capabilities bits elds are e ectively a 128-bit long value which is split into two 64-bit values for
ease of processing. Each capability bit indicates whether the Apple device supports a speci c feature.

Table 3-2 Features

Feature Capability bit Description

HDCP Enforcement 0 When set, indicates that the Apple device can enforce the
HDCP restrictions given in the HDCP Enforcement TLLV.
When not set, the device cannot guarantee the HDCP
restrictions given in the HDCP Enforcement TLLV, and
therefore it is not recommended to release keys requiring
HDCP Type 1 to the device. Regardless of the setting of this
bit, if the HDCP Enforcement TLLV is not present, the device
will enforce HDCP Type 0. See Table 3-13.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 25 of 66
fi
fi
fi
fi
ff
fi
fi
 Feature Capability bit Description
O ine Key 1 When set, indicates that the Apple device is capable of
handling and enforcing the O ine key TLLV. See the
document O ine Rental Support for FairPlay Streaming.

Secure Invalidation 2 When set, indicates that the Apple device is capable of
supporting secure invalidation requests.

O ine Key TLLV v2 3 When set, indicates that the Apple device can support O ine
Key TTLV version 2.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 26 of 66
ffl
ffl
ffl
ffl
ffl
 Device Info Support
FPS supports a Device Info TLLV in the SPC that reports the Apple device type and OS version.

Table 3-3 Device info TLLV

Field name Byte range Description

TLLV tag 0-7 An 8-byte value of 0xd43fc6abc596aae7.

Total length 8-11 The total length of this TLLV block in bytes. The amount of
padding at the end of the block, if any, determines this
length. It must be a multiple of 16 and greater than 31.

Value length 12-15 The length of the content of this TLLV block in bytes.

Apple device type 16-23 See Table 3-4.

24-27 Concatenation of 00 || major || minor || extra.
OS version

Version 28-31 TLLV version. Currently supported version is 1.

Padding 32-n Random values that ll out the TLLV to a multiple of 16
(padding_size) bytes. See the description of the Padding eld in Table
2-2.

Table 3-4 Device type

Device type eld Apple device type

“0x358c41b1ec78f599” Mac
“0xc1500767c86c1fae” AppleTV, FPS-enabled TV or STB
“0x8551fd5e31f479b3” iPhone, iPad, iPod

“0x5da86ac0c57155dc” Apple Watch

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 27 of 66
fi
fi
fi
Kext Deny List
macOS devices report the version of current “Kext Deny List” (KDL) loaded on the Apple device. If the
reported version is less than the latest published version, the server should treat the Apple device
Security Level as AppleBaseline.

As of May 2020 the latest KDL version is 32.

Table 3-5 Kext Deny List TLLV (included in the SPC sent to the server)

Field name Byte range Description

TLLV tag 0-7 An 8-byte value of 0x70eca6573388e329.

Total length 8-11 The total length of this TLLV block in bytes. The amount of
padding at the end of the block, if any, determines this
length. It must be a multiple of 16 and greater than 31.

Value length 12-15 The length of the content of this TLLV block in bytes.
KDL version 16-19 Kext Deny List version.
Padding 20-n Random values that ll out the TLLV to a multiple of 16
(padding_size) bytes.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 28 of 66
fi
Device Identity
Table 3-6 Device Identity TLLV

Field name Byte Description

range
TLLV tag 0-7 An 8-byte value of 0x94c17cd676c69b59.
Total Length 8-11 The total length of this TLLV block in bytes. The
length is determined by the amount of padding at the
end of the block, if any; this value must be a multiple
of 16 and greater than 32.
Value Length 12-15 The length of the content of this TLLV block in bytes.
Version 16-19 TLLV version.
Device Class 20-23 For example: Apple Mobile or Partner LivingRoom
(see below).
Vendor hash 24-31 8 byte value uniquely identifying device vendor.
Product hash 32-39 8 byte value uniquely identifying product.
FairPlay version REE 40-43 Version of FairPlay software running in REE/userland.

FairPlay version TEE 44-47 Version of FairPlay software running in TEE/kernel.

OS Version 48-51 OS version (Apple devices only).

Padding 52-n Random values to fill out the TLLV to a multiple of 16
bytes. See the description of the Padding field in Table
2-2 of FairPlay Streaming Programming Guide.

Device Class:

enum
{
kFPDIDeviceClassUnknown = 0,

// Apple devices
kFPDIDeviceClassAppleLiving = 1,
kFPDIDeviceClassAppleMobile = 2,
kFPDIDeviceClassAppleDesktop = 3,
kFPDIDeviceClassAppleSpatial = 4,
kFPDIDeviceClassAppleUnknown = 127,

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 29 of 66
 // Partner devices
kFPDIDeviceClassPartnerLiving = 128,
kFPDIDeviceClassPartnerUnknown = 255,

kFPDIDeviceClassMax = 255,
};

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 30 of 66
 Security Level Support
The Security Level of an Apple device provides information about the security robustness level of the
Apple device.

The SPC reports the Security Level of the Apple device in the Security Level Support TLLV. The Key
Security Module can enforce a policy based on this. For example, the Key Security Module can refuse to
deliver high-value assets (4K / HDR) to AppleBaseline or Baseline devices.
See Table 3-7 and Table 3-8.

Using the optional Required Security Level TLLV, the Key Security Module may indicate the minimum
required Security Level of the client device to allow playback of the requested asset.

AppleBaseline/Baseline Platforms will not play video content restricted to AppleMain/Main devices.

AppleBaseline, Baseline, AppleMain and Main Security Level should only be used for video content.
Audio content must use Audio Security Level.

These are further described in Table 3-9, Table 3-10, and Table 3-11.

Table 3-7 Security Level Report TLLV (included in the SPC sent to the server)

Field name Byte range Description

TLLV tag 0-7 An 8-byte value of 0xb18ee16ea50f6c02.

Total length 8-11 The total length of this TLLV block in bytes. The amount of
padding at the end of the block, if any, determines this
length. It must be a multiple of 16 and greater than 31.

Value length 12-15 The length of the content of this TLLV block in bytes.
Version 16-19 TLLV version. Currently supported version is 1.
Reserved 20-23 This eld is reserved
Security Level 24-31 Security Level of the Apple device.
See Table 8-2.

Reserved 32-35 This eld is reserved.

Padding 36-n Random values that ll out the TLLV to a multiple of 16
(padding_size) bytes

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 31 of 66
fi
fi
fi
 Table 3-8 Security Level

Name Value Notes

AppleBaseline/Baseline "0x32f0004966a5c4f8" Any platform that supports FairPlay streaming.

AppleMain/Main "0x4e7fd92421d588b4" Any platform that supports FairPlay Streaming

and guarantees enhanced content protection
robustness (su cient for studio 4K / HDR
playback).

Table 3-9 Required Security Level TLLV (included in the CKC sent by the server)

Field name Byte range Description

TLLV tag 0-7 An 8-byte value of 0x644cb1dac0313250.

Total length 8-11 The total length of this TLLV block in bytes. The amount of
padding at the end of the block, if any, determines this
length. It must be a multiple of 16 and greater than 31.

Value length 12-15 The length of the content of this TLLV block in bytes.
Version 16-19 TLLV version. Currently supported version is 1.
Reserved 20-23 This eld is reserved and should be set to 0.
Security Level 24-31 Security Level. See Table 8-4.

Padding 32-n Random values that ll out the TLLV to a multiple of 16

(padding_size) bytes.

Table 3-10

Name Value

Audio “0x17d99d574eed567d"

AppleBaseline/Baseline "0x32f0004966a5c4f8"

AppleMain/Main "0x4e7fd92421d588b4"

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 32 of 66
fi
ffi
fi
Table 3-11 FPS Error Messages Content-Protection violation

Message Description
-42811 The FPS library returns this error code when there is a Security Level violation.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 33 of 66
 HDCP Enforcement
High bandwidth Digital Content Protection (HDCP) is a digital rights protection method that provides a
secure connection between the source and the display by encrypting the audio/video stream to prevent
illegal copying of the content. Using the optional HDCP Enforcement TLLV, the requirement and version
of HDCP may be de ned.

Table 3-12 HDCP Enforcement TLLV

Field name Byte range Description

TLLV tag 0-7 An 8-byte value of 0x2e52f1530d8ddb4a.

Total Length 8-11 The total length of this TLLV block in bytes. The amount
of padding at the end of the block determines the total
length, which must be a multiple of 16 and greater than
32.

Value Length 12-15 The length of the content of this TLLV block in bytes,
0x00000010 (decimal 16).

HDCP requirement 16-31 A 16-byte eld containing the HDCP level values. See
Table 3-13.

Padding 32-n (padding_size) Random values to ll out the TLLV to a multiple of 16

bytes. See the description of the Padding eld in Table
2-2.

Table 3-13 HDCP level values

Value Description
0xEF72894CA7895B78 HDCP not required.

0x40791AC78BD5C571 HDCP Type 0 is required.

0x285A0863BBA8E1D3 HDCP Type 1 is required.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 34 of 66
fi
fi
fi
fi
Renting and Leasing the Content Key
FPS supports time-sensitive content keys. Renting and leasing set speci c limits on an app’s access to
FPS decryption keys. The server may associate a rental period with the media content and/or a lease
period with the Apple device. The server’s CKC response contains the validity duration of the content
key.

Content Key Expiration

FPS’s content key expiration creates two modes of time-sensitive exchange: video rental and secure
lease. These modes are used separately or together.

Video Rental
The content key is a rental type. FPS does not start the decryption if the content key has expired.
However, FPS continues the user experience if the content key expires during the playback. When
started again with an expired key, the Apple device declines the playback.

Secure Lease
The content key is a lease type. Typically, a content provider policy would restrict the number of
simultaneous playbacks (slots) for a user account. The server associates a slot to a device, and the server
delivers the content key with the expiration that represents the lease. The Apple device may request that
the key be renewed by the server before the lease expires. The server provides a new expiration time for
the content key, and playback continues uninterrupted. If the content key is not renewed, the Apple
device stops the playback when the lease expires. The server recognizes that playback has stopped and
frees the device slot.

This design ensures that a device is not orphaned (in a stale state) based on time rather than messaging
and garbage collection. The expiration triggers a server event to securely release the device slot. The
server knows playback stopped and frees the device slot as soon as the content key expires and the
PlayContent is discarded. Using the secure lease and the device identi cation, the server can implement
a robust solution for the management of simultaneous streams maintaining a seamless user experience.

TLLV for Rental and Lease

The SPC includes a speci c TLLV to provide the state of the media content playback. The key server uses
this TLLV to manage the rental period and the lease period. Details of the media playback state TLLV are
in Table 4-1.

Table 4-1 Media playback state TLLV

Field name Byte range Description

TLLV tag 0-7 An 8-byte value of 0xeb8efdf2b25ab3a0.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 35 of 66
fi
fi
fi
 Field name Byte range Description
Total Length 8-11 The total length of this TLLV block in bytes. The total length is
determined by the amount of padding at the end of the
block, if any; it must be a multiple of 16 and greater than 32.

Value Length 12-15 The length of the content of this TLLV block in bytes,
0x00000010 (decimal 16).

Creation Date 16-19 The time in seconds from Jan 1, 1970 to the time when the
SPC was created.

Playback State 20-23 The playback state of the Apple device at the time the SPC
was created. Possible values are listed in Table 4-2.

Session ID 24-31 An ID that represents the playback of a media content

independently of its bit rates and content keys. When the user
closes and re-opens a movie, the Apple device generates a
new Session ID to identify the new instance.

Padding 32-n (padding_size) Random values to ll out the TLLV to a multiple of 16 bytes.
See the description of the Padding eld in Table 2-2.

Table 4-2 Apple device playback states

TLLV eld value Playback state

0xf4dee5a2 State 1: The Apple device is ready to start playing. The response CKC must contain
a valid content key.
0xa5d6739e State 2: The playback stream is playing or paused. The KSM must reply with a CKC
containing a rent/lease response TLLV, but it does not need to contain a valid
content key.

0x4f834330 State 3: The playback stream is playing, but the lease is about to expire. The
response CKC must contain a valid content key.

Establishing the Rental and Lease Period

When a KSM receives an SPC with a media playback state TLLV, the KSM may include a content key
duration TLLV in the CKC message that it returns. If the Apple device nds this type of TLLV in a CKC that
delivers an FPS content key, it will honor the terms of the rental or lease or both when the key is used.
Table 4-3 lists the elds of the rental and lease response TLLV.

Note: The app is unable to modify or overrule the rental and lease periods speci ed in the CKC.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 36 of 66
fi
fi
fi
fi
fi
fi
 Table 4-3 Content key duration TLLV

Field name Byte range Description

TLLV tag 0-7 An 8-byte value of 0x47acf6a418cd091a.

Total Length 8-11 The total length of this TLLV block in bytes. The amount of
padding at the end of the block, if any, determines this length. this
value must be a multiple of 16 and greater than 32.

Value Length 12-15 The length of the content of this TLLV block in bytes, 0x00000010
(decimal 16).

Lease Duration 16-19 The duration of the lease, if any, in seconds.

Rental Duration 20-23 The duration of the rental, if any, in seconds.
Key Type 24-27 The key type. Possible values are listed in Table 4-4.
Reserved 28-31 Reserved; set to a xed value of 0x86d34a3a.
Padding 32-n Random values to ll out the TLLV to a multiple of 16 bytes. See
(padding_size) the description of the Padding eld in Table 2-2.

Table 4-4 Rental and lease key types

TLLV eld value Type of rental or lease

0x1a4bde7e Content key valid for lease only.
0x3dfe45a0 Content key valid for rental only.
0x27b59bde Content key valid for both lease and rental.

See O ine FairPlay Streaming for additional rental and lease key types to support persistent keys.

Simultaneous Renting and Leasing

It is possible to combine a rental and a lease into one CKC. The combination of renting and leasing
follows these general rules:

• A rental period covers the initial delivery of a content key and the start of a stream. If the rental
period expires during playback, the stream continues to play until the media playback stops.
• A lease period covers the validity of the content key for media playback. If the lease period
expires during playback, the media playback stops.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 37 of 66
fi
ffl
fi
fi
fi
• In a combined renting and leasing arrangement, the mechanism by which leasing registers the
playback device may be used to limit the rental to that device only, as a leasing restriction
enforced by the KSM.
• If the lease expires before the end of the rental period, the key server should allow the lease to
be renewed.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 38 of 66
 O ine FairPlay Streaming
Note: O ine FairPlay Streaming (FPS) is an extension of o ine HTTP Live Streaming (HLS). This guide
describes how to build on top of the technologies to achieve an O ine FairPlay Streaming
solution. The term “HLS” is used to describe technology that is common to both FPS and HLS.

Apps can save HTTP Live Streaming assets onto Apple devices. This is known as O ine HLS. This new
capability allows users to download and store their HLS movies while they have access to a fast, reliable
network, and watch them later without a network connection.

O ine HLS is supported starting with the following OS versions:

• iOS: 10.0

• macOS: 10.15

• iPadOS: all versions

O ine HLS assets can be SAMPLE-AES encrypted. There are a few additional steps required for
downloading and managing encrypted O ine HLS assets to ensure the playability of downloaded assets
when no network connection is present.

When creating an AVURLAsset for use in downloading an O ine HLS asset, apps must install a
delegate to handle encryption keys. The persistent keys are not stored with downloaded HLS assets.
Instead, apps must store and manage persistent keys, using an AVAssetResourceLoader and a
delegate object implementing the AVAssetResourceLoaderDelegate protocol.The server may
enable an Apple device to persist the key either inde nitely or for the provided validity duration. To
enable persistence of the content key, the server’s CKC response shall contain a Content key duration
TLLV (TLLV tag 0x47acf6a418cd091a). See Table 4-3.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 39 of 66
ffl
ffl
ffl
ffl
ffl
fi
ffl
ffl
ffl
ffl
 Figure 5-1 O ine playback

Offline Playback with Persistent Bundle

CoreMedia/
App Server
AVFoundation

AVAssetResourceLoadingRequest

Retrieve persistent bundle from app container

finishLoading
[Persistent Bundle]

Preloading O ine Keys

Because an AVAssetDownloadTask can start while your app is background suspended, the
recommendation is to preload any content keys using -[AVContentKeySession
processContentKeyRequestWithIdentifier:initializationData:options:] or
AVAssetResourceLoader.preloadsEligibleContentKeys. However, AVFoundation will attempt
to load any resources requiring an AVContentKeySessionDelegate or
AVAssetResourceLoadingDelegate (HLS playlists with custom URL schemes and FPS keys) while
your app is still running. The Apple device must ensure that all the keys have been loaded before
starting a background download task on the AVURLAsset.

The nal policy decision as to which content keys can be persisted on the device belongs to the Key
Security Module vending the CKC. The server has the option to allow the Apple device to persist the key
either inde nitely, or for a speci ed duration. To enable persistence of the content key, the server’s CKC
response shall contain a Content key duration TLLV.

FairPlay Streaming on the Apple device does not start the decryption if the persisted content key has
expired. However, playback on the Apple device continues even if the content key expires during
playback.

Table 5-1 Rental and lease key types for persistence

TLLV eld value Type of rental or lease

0x3df2d9fb Content key can be persisted with unlimited validity duration.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 40 of 66
fi
fi
fi
ffl
ffl
fi
 TLLV eld value Type of rental or lease
0x18f06048 Content key can be persisted, and its validity duration is
limited to the “Rental Duration” value.

The diagram below shows the life cycle of a persistent key request.

Figure 5-2 Persistent key request

Persistent Key Request

CoreMedia/
App Server
AVFoundation

AVAssetResourceLoadingRequest

streamingContentKeyDataForApp
[AVAssetResourceLoadingRequestStreamingContentKeyRequestRequiresPersistentKey]

SPC

Requesting CKC (persistent)

with SPC

CKC (persistent)

persistentContentKeyFromKeyVendorResponse
[CKC (persistent)]

Persistent Bundle
Store to app container
(inc. certificate and version list)

finishLoading
[Persistent Bundle]

Table 6-2 FPS error messages for presistence

Message Description
-42799 FPS returns this error code when Apple issues a security update and the existing
persistent key format is no longer supported. In this case, the application must request a
new persistent key from the server.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 41 of 66
fi
-42800 FPS returns this error code when persistent key has expired. The server always has an
option to add a validity period for each key it issues for o ine playback. Once the validity
period is over, the Apple device will refuse to decrypt o ine content protected with such
key and indicate the error with this error code.
It is up to the application developers to decide whether to request a new key from the
server or treat this error condition as a permanent expiry; for example, a recorded
sporting event must not be playable after 48 hours and no key renewal is possible.
To use the best practice and achieve maximum exibility, always send a key-renewal
request to the server and let the server decide whether to allow the renewal.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 42 of 66
fl
ffl
ffl
 O ine Rental Support
Starting with iOS 11.0, FPS supports a new feature to enable o ine rental. This feature allows the server
to specify two expiration times for content. This “dual expiry” is similar to how the rental of iTunes movies
functions.

In iOS 12.2 and later, FPS supports relating multiple streams belonging to the same program. O ine Key
TTLV version 2 adds a new eld called Title ID. All sub-streams for a given program should have a
common Title ID. When the application requests the FairPlay Streaming component to create a Sync
SPC or invalidate a persistent key, FPS ensures that all persistent keys identi ed by the same Title ID
are invalidated. The updated Sync TLLV will include a list of all the invalidated Stream/Content IDs.
This eliminates the need to invalidate persistent keys on a one by one basis when multiple sub-streams
were downloaded for the program.

Note that FPS supports O ine Rental in all versions of iPadOS, and in macOS 10.15 and newer.

Storage and Playback Expiry

The server can use the new O ine Key TLLV (see below) to specify two di erent duration periods for the
downloaded content:

1. Storage duration (seconds). This speci es the maximum time the key stays valid prior to playback
being started. Measured from license acquisition time.
2. Playback duration (seconds). This speci es the maximum time the key stays valid after playback has
been started. Measured from the rst playback start time.
After content is downloaded and the content license is acquired, the app may report to the server the
remaining key validity duration using a Sync SPC (see below). This allows the server and the client to be
synchronized on when the license to play the downloaded asset will expire.

Example: A user rents a movie; the server sets the storage duration to 2,592,000 (30 days) and the
playback duration to 86,400 (24 hours). The user has up to 30 days to start watching the movie and 24
hours to nish watching it after starting the playback. If the app requests a Sync SPC to be created prior
to user starting playback, the “Duration to expiry” eld of the Sync TLLV will be set to 2,592,000 minus
the number of seconds passed since license was downloaded. The same SPC requested after playback
has started will contain a Sync TLLV with the “Duration to expiry” eld set to 86,400 minus the number of
seconds since playback was started.

O ine Key

Table 6-1 O ine Key TLLV

Field name Byte range Description

TLLV tag 0-7 An 8-byte value of 0x6375d9727060218c.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 43 of 66
ffl
ffl
fi
ffl
ffl
fi
ffl
fi
fi
fi
fi
ffl
fi
ff
fi
ffl
 Field name Byte range Description
Total length 8-11 The total length of this TLLV block in bytes. The total
length is determined by the amount of padding at the
end of the block, if any; it must be a multiple of 16 and
greater than 31.

Value length 12-15 The length of the content of this TLLV block in bytes.
Version 16-19 TLLV version. Currently supported version is 2. Supported
in iOS 12.2 and higher.

Reserved 20-23 This eld is reserved and must be set to 0.

Content ID 24-39 Unique content ID of the downloaded asset assigned by
(Stream ID in the server. This server receives this value in a Sync TLLV.
version2)

Storage duration 40-43 Asset storage validity duration in seconds. Starts at license
acquisition time. A value of zero means no limit.

Playback duration 44-47 Asset playback validity duration in seconds. Starts at asset
rst playback time. A value of zero means no limit.

Title ID 48-63 (Version 2 only) Unique ID common to all streams for the
ve content. The server receives this value in a Sync TLLV.

Padding 64-n Random values that ll out the TLLV to a multiple of 16

(padding_size) bytes. See the description of the Padding eld in Table
2-2.
The byte range
for version 1 is
48-n

To enable dual expiry for an asset, the KSM should add an O ine Key TLLV to the returned CKC.

Note: An O ine Key TLLV cannot be used in the same CKC payload as an already existing Content Key
Duration TLLV. If both of these TLLVs are in the CKC, the processing of the CKC stops and an Invalid CKC
error is returned.

Since the CKC cannot be interpreted by the app, the server should notify the app that the asset is using
dual expiry so that the app knows that a Sync SPC can be generated.

Sync
An app can obtain a Sync SPC via the method [AVContentKeySession
makeSecureTokenForExpirationDateOfPersistableContentKey:completionHandler:].

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 44 of 66
fi
fi
fi
ffl
fi
fi
ffl
 This method will fail unless the persistable content key was constructed from a CKC that included an
O ine Key TLLV.

The app should send the resulting SPC to the KSM. The KSM should distinguish between Sync SPCs and
other SPCs. Any SPC may contain a Sync TLLV, so you need to check the Sync TLLV for validity. Valid Sync
TLLVs will have the Version eld set to 1 or 2. Any other value is invalid. A Sync SPC is one with a valid
Sync TLLV.

Table 6-2 Sync TLLV (version 1)

Field name Byte range Description

TLLV tag 0-7 An 8-byte value of 0x77966de1dc1083ad.

Total length 8-11 The total length of this TLLV block in bytes. The amount of
padding at the end of the block, if any, determines this
length. It must be a multiple of 16 and greater than 31.

Value length 12-15 The length of the content of this TLLV block in bytes.

Version 16-19 TLLV version. Currently supported version is 1.

Reserved 20-23 This eld is reserved and must be set to 0.

24-39 Unique content ID of the downloaded asset received in
Content ID O ine Key TLLV.

40-43 Remaining license validity time in seconds. It will be set to

Duration to expiry 0 if the license has expired, and to 0xFFFFFFFF if the
license doesn’t have an expiry date.

Padding 44-n Random values that ll out the TLLV to a multiple of 16

(padding_size) bytes. See the description of the Padding eld in Table
2-2.

Table 6-3 Sync TLLV (version 2)

Field name Byte range Description

TLLV tag 0-7 An 8-byte value of 0x77966de1dc1083ad.

Total length 8-11 The total length of this TLLV block in bytes. The amount of
padding at the end of the block, if any, determines this
length. It must be a multiple of 16 and greater than 31.

Value length 12-15 The length of the content of this TLLV block in bytes.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 45 of 66
ffl
ffl
fi
fi
fi
fi
 Field name Byte range Description
16-19 TLLV version. For Apple devices supporting O ine Rental,
Version the version is set to 2.

Reserved 20-23 This eld is reserved and must be set to 0.

24-31 The unique 64-bit server challenge generated by the
Server Challenge server.

32-39 64-bit integer containing the current ag setting. See the

Flags ag values in Table 6-4.

Title ID 40-55 The 128 bit title ID provided in the O ine Key TLLV.
55-59 Remaining license validity time in seconds. It will be set to
Duration to expiry 0 if the license has expired, and to 0xFFFFFFFF if the
license doesn’t have an expiry date.

60-63 The total number of invalidated records.

Records Invalidated

Invalidated Stream 64-X A concatenated array of invalidated Stream IDs.

IDs
Padding X+1-n Random values that ll out the TLLV to a multiple of 16
(padding_size) bytes. See the description of the Padding eld in Table
2-2.

The following table contains the possible values for the Flag eld:

Table 7-4 Sync TLLV Flag Field De nitions

Flag Capability Bit Description

KD_SYNC_SPC_FLAG_REPORT 0 The Apple device requested a sync.

KD_SYNC_SPC_FLAG_SECURE_INVALID 1 The Apple device requested a secure

ATION invalidation.

KD_SYNC_SPC_FLAG_SECURE_INVALID 2 The Apple device requested a “Delete all”

ATION_ALL operation.

KD_SYNC_SPC_FLAG_SUCCESS 16 The requested operation was successful.

KD_SYNC_SPC_FLAG_OBJ_NOT_FOUN 17 The provided persistent key was not found

D or is invalid.

KD_SYNC_SPC_FLAG_OBJ_EXPIRED 18 The provided persistent key is valid, but

expired by the time of the request.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 46 of 66
fl
fi
fi
fi
ffl
fl
fi
ffl
fi
Testing the Key Security Module
The FPS SDK includes a CKC veri cation tool, verify_ckc, with SPC and CKC test vectors. Use the
verify_ckc tool and test vectors to verify that the KSM implementation can produce a valid CKC. See
Using the FPS SDK and Tools.

Once you have a working KSM you can request the FPS Deployment Package at https://
developer.apple.com/contact/fps/ which contains the D Function, instructions about how to generate
your Application Certi cate and Application Secret key (ASk) values. You need these to test your KSM
implementation with an FPS client.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 47 of 66
fi
fi
Developing an FPS-Aware App
Any media playback app that runs on an Apple device can implement FPS. This chapter covers
programming required for an app to obtain content keys that decrypt FPS media.

Typically, playback apps provide a user interface for browsing and selecting the content to be streamed,
support user identi cation, and facilitate other user and content provider transactions. Additionally, an
FPS-aware playback app must establish two-way communication between the Apple device and a key
server to support FPS functions.

⚠ Warning: FPS cannot be run on iOS Simulator.

For general information about writing apps for Apple iOS devices, visit the Developer Center.

Identifying Your FPS App with an Application Certi cate

As part of registering an FPS playback app, you provide Apple with an X.509 Certi cate Signing Request
linked to your private key. In return, you receive an Application Certi cate encoded with the X.509
standard with distinguished encoding rules (DER). Bytes 152-171 of the SPC message contain a secure
hash algorithm (SHA-1) digest of that encoded certi cate.

Every playback app that uses FPS must nd the media’s key server and establish communication with
that server. When the Apple device and the key server can exchange messages, the app must send the
server an FPS-created SPC message. This message contains a hash of the Application Certi cate
identifying your private key.

The recommendations below help you ensure FPS security.

• Do not hard-code the Application Certi cate in the playback application.

• Verify that the hash value in bytes 152-171 of the SPC correctly identi es the private key of the
developer from which the module expects to receive SPC messages.
• Do not enforce the expiration date of the Application Certi cate within your app. FPS does not
enforce the expiration date.
In the code sample shown in the iOS FPS Client sample (included in the SDK), kTestAppCert contains
the Application Certi cate.

Integrating FPS with the iOS Decryption Process

To use FPS, the playback app must implement the AVAssetResourceLoaderDelegate protocol. For
each AVURLAsset subclass required by FPS, the app must create an appropriate object that implements
this protocol as the AVAssetResourceLoader delegate for that subclass. AVAssetResourceLoader
invokes this delegate to examine URL requests that the operating system cannot handle by itself,
including requests for content keys.

The app uses the resourceLoader property of the AVURLAsset subclass to obtain the instance of
AVAssetResourceLoader associated with the class. It uses the AVAssetResourceLoader method

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 48 of 66
fi
fi
fi
fi
fi
fi
fi
fi
fi
fi
fi
 -setDelegate:queue: to set the delegate and the dispatch queue on which
AVAssetResourceLoader will invoke the delegate.

Integrating FPS in Safari

The FPS content that you author for iOS and Apple TV also plays in Safari starting on macOS 10.10.3, iOS
11.2, and iPadOS. Encrypted Media Extensions (EME) provide FPS support on Safari. Support for the
WebKit-pre xed EME speci cation (https://dvcs.w3.org/hg/html-media/raw- le/tip/encrypted-media/
encrypted-media.html) started on macOS 10.10.3, iOS 11.3, and iPadOS. Support for the Modern EME
speci cation (https://w3c.github.io/encrypted-media/) started on iOS 12.2, and macOS 10.14.4 and
greater. The EME extended HTMLMediaElement APIs manage the FPS process with secure message
exchanges analogous to FPS on iOS devices and Apple TV.

EME Message Exchange

For web pages in Safari, FPS supports a Key System identi ed by the string com.apple.fps.

You must create a Key Session to provide a context for message exchange with the Content Decryption
Module (CDM)/Key System. Per the EME speci cation, each Key Session is associated with a single
instance of Initialization Data provided in the createSession() call.

For FPS, this Initialization Data must be the following byte array.
AssetID + Certificate
In this expression, AssetId represents the byte array de ned in Table 2-4, Certificate represents the
Application Certi cate provided by Apple, and the + indicates concatenation of the two values. The
AssetId can be any string you choose.

Use the following events in your JavaScript for Safari to support FPS.

encrypted
The encrypted event nds the CDM, identi ed with the string com.apple.fps and allows for
creation of the keySession. The event triggers when a process requests playback of FPS protected
content.

message
The message event sends the SPC and obtains a CKC from the Key Server Module. The update()
function adds the CKC to the keySession.
keystatuseschange
The keystatuseschange event triggers when a change occurred in the keys in the session or their
status. See https://w3c.github.io/encrypted-media/#mediakeystatusmap-interface for more
information.

Apple provides samples in the FPS SDK, including a JavaScript implementation of the API for Safari on
macOS.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 49 of 66
fi
fi
fi
fi
fi
fi
fi
fi
fi
fi
Requesting a Content Key from the Key Server
When the operating system asks the app to provide a content key, as shown in Figure 8-1, the app
invokes the AVAssetResourceLoader delegate’s implementation of its
-resourceLoader:shouldWaitForLoadingOfRequestedResource: method. This method
provides the delegate with an instance of AVAssetResourceLoadingRequest, which accesses the
underlying NSURLRequest for the requested resource and support for responding to the request.

Figure 8-1 FPS information ow

When the request is for a content key, the app invokes the delegate -
[AVAssetResourceLoadingRequest
streamingContentKeyRequestDataForApp:contentIdentifier:options:error:] method.
This method obtains the SPC message from the operating system. Then the app sends the SPC to the
key server, as shown in Figure 8-1, using appropriate transport forms and protocols.

Processing the Key Server’s Response

The KSM constructs the CKC message containing the content key as described in Programming the Key
Security Module. The key server returns a CKC message in response to the app’s SPC message, as shown
in Figure 8-1. After receiving this message, the app sends it to the operating system by invoking the
AVAssetResourceLoadingRequest method -[AVAssetResourceLoadingRequest
finishLoading]. The device can now decrypt and play the content stream using HLS as summarized
in HTTP Live Streaming Overview.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 50 of 66
fl
 Con guring AirPlay Mode
When an Apple device is in AirPlay mode, FPS content will not play on an attached Apple TV unless
AirPlay playback is set to mirroring. The FPS-aware app must set the
usesExternalPlaybackWhileExternalScreenIsActive property of the AVPlayer object to TRUE
with code such as this:
// create AVPlayer object
player = [AVPlayer playerWithURL:movieURL];
// set the property to TRUE
player.usesExternalPlaybackWhileExternalScreenIsActive = TRUE;

Interpreting Error Messages

When -streamingContentKeyRequestDataForApp:contentIdentifier:error: fails, it
returns nil and sets the outError parameter to an instance of NSError that describes the failure. In
this case, invoke -finishLoadingWithError:, passing the resulting error.

If you want the application to report the error to the user at this stage of the process, use the
localizedDescription of NSError from
-streamingContentKeyRequestDataForApp:contentIdentifier:error:. You can access
another error instance through the NSUnderlyingErrorKey in the userInfo dictionary of the
NSError instance provided by
-streamingContentKeyRequestDataForApp:contentIdentifier:error:. This NSError
instance provides additional information of interest when debugging an application that tries to obtain
an SPC. It can contain one of the codes listed in Table 8-1.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 51 of 66
fi
 Table 8-1 FPS error messages

Message Description

-42656 Lease duration has expired.

-42668 The CKC passed in for processing is not valid.
-42672 A certi cate is not supplied when creating SPC.
-42673 assetId is not supplied when creating an SPC.

-42674 Version list is not supplied when creating an SPC.

-42675 The assetID supplied to SPC creation is not valid.
-42676 An error occurred during SPC creation.
-42679 The certi cate supplied for SPC creation is not valid.
-42681 The version list supplied to SPC creation is not valid.
-42783 The certi cate supplied for SPC is not valid and is possibly revoked.

-42803 O ine key is invalid.

Manually Fetching FPS Error Messages

The following code fetches an underlying error speci c to FPS.

Listing 8-1 Manually fetching FPS errors

NSError *topLevelError = nil;

NSData *requestData = [loadingRequest
streamingContentKeyRequestDataForApp:appID contentIdentifier:contentID
error:&topLevelError];
if (requestData == nil && topLevelError != nil)
{
NSError *underlyingError = [[topLevelError userInfo] objectForKey:
NSUnderlyingErrorKey];
if ([[underlyingError domain] isEqualToString:NSOSStatusErrorDomain])
{
NSInteger errorCode = [underlyingError code];
// check whether this errorCode is specific to FPS as listed in
Table 3-1.
}
}
2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.
Page 52 of 66
ffl
fi
fi
fi
fi
2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.
Page 53 of 66
Formatting and Encrypting Streams
You’ve seen how the KSM works and how to build an app to communicate with that KSM. Now that you
understand some aspects of FPS on the key server and the Apple device, take a look at the content that
streams between the two. FPS requires content formatting and encrypting in accordance with the HTTP
Live Streaming (HLS) and MPEG-2 stream encryption standards published in HTTP Live Streaming IETF
draft and MPEG-2 Stream Encryption Format for HTTP Live Streaming. This chapter helps you prepare
your FPS content for these standards.

Beyond this chapter, the following books provide instruction on formatting and encrypting streams.

• HTTP Live Streaming IETF draft details the media formatting required to send your content via
HTTP. The advantages of HLS and implementation instructions are provided in HTTP Live
Streaming Overview.
• MPEG-2 Stream Encryption Format for HTTP Live Streaming explains features of the MPEG-2
standard.

Preparing Content for FPS

As shown in Example Playlist Files for use with HTTP Live Streaming, HLS extends the m3u playlist
format with an EXT-X-KEY tag. FPS requires that this tag be included in the HLS playlist and that it
declare the following attributes:

• METHOD: The encryption method. SAMPLE-AES indicates AES-128_CBC unpadded encryption of

individual samples.
• URI: The path for obtaining the content key. An example is skd://key65, as shown in Listing
9-1.
• KEYFORMAT: A value of com.apple.streamingkeydelivery indicates a FPS key; identity
indicates the original key format of clear text 16-byte AES key.
• KEYFORMATVERSIONS: A list of key format versions separated by slashes. For example, 1/2
indicates support for either version 1 or version 2 of the key format.
The following listing shows a sample FPS EXT-X-KEY tag in a streaming playlist.

Listing 9-1 Adding FPS to an HLS Playlist

#EXT-X-KEY:METHOD=SAMPLE-AES,URI="skd://key65",
KEYFORMAT="com.apple.streamingkeydelivery",KEYFORMATVERSIONS="1"

Including Initialization Vectors (IV) in Playlists

There are a few important considerations that apply to the IV in an FPS m3u8 playlist.

• FPS does not support IVs listed in the EXT-X-KEY tag's IV attribute in an m3u8 playlist. The FPS-
aware app ignores any IV in the playlist. The Key Security Module only delivers the IV in the
content key context (CKC).

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 54 of 66
 • FPS does not support using IVs as media sequence numbers in a m3u8 playlist. AES encryption
and decryption of audio and video assets uses the IV delivered in the CKC.
• An EXT-X-KEY tag with a KEYFORMAT of identity without an IV attribute indicates that the
media sequence number should be used as the IV to decrypt a media segment. However, if
you specify a KEYFORMAT of com.apple.streamingkeydelivery to indicate an FPS key
(leaving out any IV), IVs are not used as media sequence numbers.
• For more information, see http://tools.ietf.org/html/draft-pantos-http-live-streaming.
• The Apple device doesn't make a key request for every segment in the playlist.
• For example, if an EXT-X-KEY tag is in the playlist along with three segments, the Apple
device requests the key just once. This means that your encryption system must encrypt the
three segments with the same IV.
• In a similar example, a playlist sequence includes the following items where the key lines
are identical. In this scenario, the second key line (with Key_0) is not necessary because the
Apple device requests the key only once.
• Key_0
• Segment_1
• Key_0
• Segment_2
• Some special circumstances do require key requests for every segment, such as when using
FPS through AirPlay or Digital AV Adaptors.

Using FPS Options with the Media File Segmenter

The following new FPS-speci c features are part of the mediafilesegmenter tool included with the
HTTP Live Streaming tools download.

• -P is the short form of --streaming-key-delivery. Either form indicates that the key le is
32 bytes long, where the rst 16 bytes is the content key and the second 16 bytes is the
initialization vector (IV). This option is necessary for
KEYFORMAT="com.apple.streamingkeydelivery" streaming.
• The option --encrypt-iv is incompatible with FPS.
• If an existing key le is supplied to --encrypt-key-file, it must be 32 bytes long. The rst
16 bytes hold the content key, and the second 16 bytes hold the IV. The segment /tmp/
key.bin in Listing 9-2 represents a 32-byte le.
• The --stream-encrypt option is necessary if the key is to be delivered via FPS.
Listing 9-2 uses the mediafilesegmenter command to produce an m3u8 playlist for use with FPS.

Listing 9-2 Media File Segmenter command

mediafilesegmenter --stream-encrypt --streaming-key-delivery --encrypt-key-

file=/tmp/key.bin --encrypt-key-url="skd://example/key" /tmp/source.mov

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 55 of 66
fi
fi
fi
fi
fi
fi
Using ALLOWED-CPC in playlist to improve tier selection

With “Security Level support”, platforms can be classi ed as follows.

Table 9-3 Platforms

CPC Label Devices that adhere to that CPC level

AppleBaseline Any Apple device that supports FairPlay Streaming.
AppleMain Any Apple device that supports FairPlay Streaming and guarantees enhanced
content protection robustness (su cient for studio 4K / HDR playback).

Baseline Any non-Apple device that supports FairPlay Streaming. For example, any
AirPlay 2–enabled smart TV.

Main Any non-Apple device that supports FairPlay Streaming and guarantees
enhanced content protection robustness (su cient for studio 4K / HDR
playback).

The optional ALLOWED-CPC attribute of the EXT-X-STREAM-INF tag indicates which Security Level the
stream requires. Leverage it to avoid requesting assets that the device will not be able to play because it
does not have the required Security Level.

See Listing 9-4 for an example that uses an ALLOWED-CPC attribute.

Listing 9-4 Adding ALLOWED-CPC to an HLS Playlist

#EXT-X-STREAM-INF:AVERAGE-BANDWIDTH=2266124,_AVG-
BANDWIDTH=2266124,BANDWIDTH=3752516,VIDEO-
RANGE=SDR,CODECS="avc1.64001f,mp4a.40.2",AUDIO="audio-stereo-160",FRAME-
RATE=23.976,HDCP-LEVEL=TYPE-0,RESOLUTION=1186x494,ALLOWED-
CPC="com.apple.streamingkeydelivery:AppleBaseline/Baseline"

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 56 of 66
ffi
ffi
fi
Downloading HTTP Live Streaming tools: You must log in to the iOS developer library to access the
HTTP Live Streaming tools download.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 57 of 66
 Using the FPS SDK and Tools
Apple provides registered FPS developers with a server software development kit (SDK) containing
reference materials, code, and tools to support FPS development. Optionally, registered developers may
obtain additional tools and test streams from Apple that support the creation and testing of encrypted
HLS streams. See http://developer.apple.com/streaming/ for those helpful downloads.

FairPlay Streaming SDK Contents

The FPS SDK contains the following items:

• This FairPlay Streaming Programming Guide.

• A KSM reference implementation written in C.
• A set of test streams.
• A sample iOS app demonstrating the implementation of an AVAssetResourceLoader
delegate to handle FPS key requests.
• A set of development keys.
• A CKC veri cation tool that contains SPC and CKC test vectors.
• A sample JavaScript implementation of FPS for Safari.

Testing the Key Security Modules

In order to perform testing of your KSM implementation, the FPS Server SDK package contains a number
of pre-generated SPC and CKC test vectors and a veri cation utility verify_ckc.

Note that you can only use this utility to test your KSM implementation when using the test values for
the private key and xed DASk value. You cannot use it to test your application, nor to validate CKCs
produced with your KSM implementation using production credentials.

1. Use the private key provided in the Development Certi cate and Private Key le in the pKeyPem
variable in the SKDServerUtils.c le

2. Use the DASk provided in the spc_internal_values_v2.txt le in the Verify CKC tool
(verify_ckc). Populate this value into spcData->DAS_k in the
SKDServer.c:SKDServerProcessEncrypted_SK_R1 function as a replacement for the
Dfunction.

3. Use the verify_ckc tool and test vectors to ensure the KSM can produce a valid CKC.

Make use of the SPC test vectors to simulate the client and exercise the KSM logic. The verify_ckc
command-line tool veri es CKCs that the KSM returns.

Verifying your SPC processing in your KSM

The verify_ckc utility parses the SPC and prints a report with the details about each TLLV present in
the SPC, as shown in Parsing the SPC.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 58 of 66
fi
fi
fi
fi
fi
fi
fi
fi
Listing 10-1 Parsing the SPC
$ ./verify_ckc -s SPC-CKC-Tests/FPS/spc1.bin
CKC/SPC Sanity Test v. 1.07
========================= Begin SPC Data ===============================
SPC container size 2688
SPC Encryption Key -
92 66 48 b9 86 1e c0 47 1b a2 17 58 85 1c 3d da
SPC Encryption IV -
5d 16 44 ea ec 11 f9 83 14 75 41 e4 6e eb 27 74
================ SPC TLLV List ================
[SK ... R1] Integrity Tag -- b349d4809e910687
Tag size: 0x10
Tag length: 0x40
Tag value:
54 a1 6b e0 13 7e f2 59 ab 3e 4f c7 96 90 82 5f

[SK ... R1] Tag -- 3d1a10b8bffac2ec

Tag size: 0x70
Tag length: 0x100
Tag value:
4f 45 d8 5c e2 62 73 10 1a 97 f3 30 81 c1 d0 4a
93 b2 dd 03 55 e3 63 72 9d 92 a4 5a 45 ce 8d 25
8b 0c 08 aa 65 1c 09 64 97 6b f0 94 4d 28 25 f3
ac 8d de 7e d2 31 4f a0 ef 3f b4 5b 97 a2 26 e8
c5 36 6d ef e5 f1 e1 2b d7 b7 21 98 a4 a8 f2 65
3a 0e f0 de 8c 37 a4 7c 3c 40 f0 12 e1 5c 8b 59
3d f1 2d 4b 01 60 3a 97 35 7e 6a e0 a1 1c a3 e3

AR Tag -- 89c90f12204106b2
Tag size: 0x10
Tag length: 0xd0
Tag value:
f3 c6 9d 1e 8c c4 27 5a 6d 32 86 d3 32 61 3e 13

R2 tag -- 71b5595ac1521133
Tag size: 0x15
Tag length: 0xb0
Tag value:
11 f7 be 61 2c a9 5e f5 e0 07 ce 51 89 6a e4 50
2c a3 d8 80 1b -- -- -- -- -- -- -- -- -- -- --

Asset ID Tag -- 1bf7f53f5d5d5a1f

Tag size: 0x12
Tag length: 0x80
Tag value:
aa bb cc dd ee ff aa bb cc dd ee ff aa bb cc dd
ee ff -- -- -- -- -- -- -- -- -- -- -- -- -- --

Transaction ID Tag -- 47aa7ad3440577de

Tag size: 0x08
Tag length: 0x70
Tag value:
14 73 e5 cc 53 e1 e5 d6 -- -- -- -- -- -- -- --

Return Request Tag -- 19f9d4e5ab7609cb

Tag size: 0x38
Tag length: 0x60
Tag value:
1b f7 f5 3f 5d 5d 5a 1f 47 aa 7a d3 44 05 77 de
f9 11 f0 4d a5 4b f5 99 ba 08 cc 74 da c9 17 6d
13 0d 99 4c b8 94 b9 e3 66 c8 23 f3 79 b8 7b b5
18 d4 2c 5f 8e 54 5a 4b -- -- -- -- -- -- -- --

DASk Value:
d8 7c e7 a2 60 81 de 2e 8e b8 ac ef 3a 6d c1 79

SPC SK Value:

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 59 of 66
 af b4 6e 7b f5 f3 15 96 c1 c6 76 dc 15 e1 4d c6

SPC [SK..R1] IV Value:

4f 45 d8 5c e2 62 73 10 1a 97 f3 30 81 c1 d0 4a

=========================== End SPC Data =================================

You can use this information when debugging your KSM implementation. For example you can print out
TLLVs decrypted by your KSM and compare these values against the data reported by verify_ckc
utility.

Verifying your CKC creation in your KSM

The verify_ckc utility can also check the validity of the CKC that your KSM created. Run the
verify_ckc utility as shown in Validating the CKC. Please note that in order to decrypt the CKC, you
must invoke the utility with both SPC and matching CKC les. For your reference, the package includes
the sample CKCs, which the verify_ckc utility can also use.

Listing 10-2 Validating the CKC

$ ./verify_ckc -s SPC-CKC-Tests/FPS/spc1.bin -c SPC-CKC-Tests/FPS/ckc1.bin

CKC/SPC Sanity Test v. 1.07
========================= Begin SPC Data ===============================
SPC container size 2688
SPC Encryption Key -
92 66 48 b9 86 1e c0 47 1b a2 17 58 85 1c 3d da
SPC Encryption IV -
5d 16 44 ea ec 11 f9 83 14 75 41 e4 6e eb 27 74
================ SPC TLLV List ================
[SK ... R1] Integrity Tag -- b349d4809e910687
Tag size: 0x10
Tag length: 0x40
Tag value:
54 a1 6b e0 13 7e f2 59 ab 3e 4f c7 96 90 82 5f

[SK ... R1] Tag -- 3d1a10b8bffac2ec

Tag size: 0x70
Tag length: 0x100
Tag value:
4f 45 d8 5c e2 62 73 10 1a 97 f3 30 81 c1 d0 4a
93 b2 dd 03 55 e3 63 72 9d 92 a4 5a 45 ce 8d 25
8b 0c 08 aa 65 1c 09 64 97 6b f0 94 4d 28 25 f3
ac 8d de 7e d2 31 4f a0 ef 3f b4 5b 97 a2 26 e8
c5 36 6d ef e5 f1 e1 2b d7 b7 21 98 a4 a8 f2 65
3a 0e f0 de 8c 37 a4 7c 3c 40 f0 12 e1 5c 8b 59
3d f1 2d 4b 01 60 3a 97 35 7e 6a e0 a1 1c a3 e3

AR Tag -- 89c90f12204106b2
Tag size: 0x10
Tag length: 0xd0

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 60 of 66
fi
 Tag value:
f3 c6 9d 1e 8c c4 27 5a 6d 32 86 d3 32 61 3e 13

R2 tag -- 71b5595ac1521133
Tag size: 0x15
Tag length: 0xb0
Tag value:
11 f7 be 61 2c a9 5e f5 e0 07 ce 51 89 6a e4 50
2c a3 d8 80 1b -- -- -- -- -- -- -- -- -- -- --

Asset ID Tag -- 1bf7f53f5d5d5a1f

Tag size: 0x12
Tag length: 0x80
Tag value:
aa bb cc dd ee ff aa bb cc dd ee ff aa bb cc dd
ee ff -- -- -- -- -- -- -- -- -- -- -- -- -- --

Transaction ID Tag -- 47aa7ad3440577de

Tag size: 0x08
Tag length: 0x70
Tag value:
14 73 e5 cc 53 e1 e5 d6 -- -- -- -- -- -- -- --

Return Request Tag -- 19f9d4e5ab7609cb

Tag size: 0x38
Tag length: 0x60
Tag value:
1b f7 f5 3f 5d 5d 5a 1f 47 aa 7a d3 44 05 77 de
f9 11 f0 4d a5 4b f5 99 ba 08 cc 74 da c9 17 6d
13 0d 99 4c b8 94 b9 e3 66 c8 23 f3 79 b8 7b b5
18 d4 2c 5f 8e 54 5a 4b -- -- -- -- -- -- -- --

DASk Value:
d8 7c e7 a2 60 81 de 2e 8e b8 ac ef 3a 6d c1 79

SPC SK Value:
af b4 6e 7b f5 f3 15 96 c1 c6 76 dc 15 e1 4d c6

SPC [SK..R1] IV Value:

4f 45 d8 5c e2 62 73 10 1a 97 f3 30 81 c1 d0 4a

=========================== End SPC Data =================================

=========================== Begin CKC Data =================================
AES IV value:
0x00000000000000000000000000000000

AR Key Value:

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 61 of 66
 0xcb0d802549396b9c8d636d5e64594cbe

CKC Data Length 768

CK Tag -- 58b38165af0e3d5a
Tag size: 0x20
Tag length: 0x20
Tag value:
d5 fb d6 b8 2e d9 3e 4e f9 8a e4 09 31 ee 33 b7
3d 56 43 97 87 8b 70 43 e1 54 31 f1 f8 6b c5 62

R1 Tag -- ea74c4645d5efee9
Tag size: 0x2c
Tag length: 0x40
Tag value:
27 52 00 8e 1c 11 e2 24 e8 eb 07 ee c4 a0 9d 17
44 0a 63 72 d5 dc 21 09 e5 50 ec ac 98 60 61 3f
8b 7a 8b e6 b4 5a 69 83 2d 9e 8c e7 -- -- -- --

Asset ID Tag -- 1bf7f53f5d5d5a1f

Tag size: 0x12
Tag length: 0x80
Tag value:
aa bb cc dd ee ff aa bb cc dd ee ff aa bb cc dd
ee ff -- -- -- -- -- -- -- -- -- -- -- -- -- --

Transaction ID Tag -- 47aa7ad3440577de

Tag size: 0x08
Tag length: 0x70
Tag value:
14 73 e5 cc 53 e1 e5 d6 -- -- -- -- -- -- -- --

MATCHED! Return Request Tag 1bf7f53f5d5d5a1f

MATCHED! Return Request Tag 47aa7ad3440577de
MATCHED! Return Request Tag f911f04da54bf599
MATCHED! Return Request Tag ba08cc74dac9176d
MATCHED! Return Request Tag 130d994cb894b9e3
MATCHED! Return Request Tag 66c823f379b87bb5
MATCHED! Return Request Tag 18d42c5f8e545a4b

Info: SPC and CKC R1 key values match.

Info: CKC decryption and parsing was successful.

=========================== End CKC Data =================================

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 62 of 66
Debugging KSM
The verify_ckc utility helps you debug your KSM implementation by printing all the TLLVs included in
the CKC.

For example, you can inspect the CK Tag TLLV (58b38165af0e3d5a), which contains the Content Key
encrypted with the session key, and compare it against values printed by your KSM. If you are using the
Server Reference Implementation, locate the Content Key and encrypted Content Key in SKDServer.c,
function SKDServerFillCKCData(), variable ckcData->ck. This variable contains the unencrypted
Content Key prior to calling SKDServerAESEncryptDecrypt(), and the encrypted Content Key after
this call is completed.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 63 of 66
 Document Revision History

This table describes the changes to FairPlay Streaming Programming Guide.

Date Notes

2023-08-10 Added kFPDIDeviceClassAppleSpatial device class support in Device

Identity TLLV (Table 3-6).

2022-12-01 Updated description of Version eld in Device Identity TLLV (Table 3-6).

2022-03-30 HDCP Enforcement TLLV description added in Table 3-12.

Device Identity TLLV description added in Table 3-6.

2021-06-11 Fixed an incorrect reference in the CKC version description in Table 2-10.

2021-03-10 Updated external links and renamed events in “Integrating FPS in Safari.”

2021-02-08 Updated copyright and legal information.

2020-11-05 Added intra-document links and performed a copy edit.

2020-05-05 Added ALLOWED-CPC description.

Added Security Level support.
Added Kext Deny List support.
Added Device Info support.

2019-07-11 Added enhanced O ine TLLV information to support grouping of sub-

streams for a particular program.

2017-08-21 Added Capabilities TLLV and sections on O ine FairPlay Streaming and
O ine Rental Support.

2015-09-15 Added macOS support and Lease/Rental Support features. Added

clari cation concerning the initialization vector (IV) in an FPS m3u8
playlist and behavior of the client when making key requests for
segments in a playlist.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 64 of 66
ffl
fi
ffl
fi
ffl
Date Notes

2015-06-08 New document that describes how to implement FairPlay Streaming

encryption in HTTP Live Streaming media.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 65 of 66

Apple Inc.
© 2023 Apple Inc.
All rights reserved.

AirPlay, Apple, the Apple logo, Apple TV,

Apple Watch, FairPlay, iPad, iPadOS,
iPhone, iPod, Mac, macOS, Safari,
watchOS, and visionOS are trademarks
of Apple Inc., registered in the U.S. and
other countries and regions.

IOS is a trademark or registered

trademark of Cisco in the U.S. and other
countries and regions and is used under
license.

No part of this publication may be

reproduced, stored in a retrieval system,
or transmitted, in any form or by any
means, mechanical, electronic,
photocopying, recording, or otherwise,
without prior written permission of Apple
Inc., with the following exceptions: Any
person is hereby authorized to store
documentation on a single computer or
device for personal use only and to print
copies of documentation for personal
use provided that the documentation
contains Apple’s copyright notice.
No licenses, express or implied, are
granted with respect to any of the
technology described in this document.
Apple retains all intellectual property
rights associated with the technology
described in this document. This
document is intended to assist
application developers to develop
applications only for Apple-branded
products.

Apple Inc.
One Apple Park Way
Cupertino, CA 95014

APPLE MAKES NO WARRANTY OR

REPRESENTATION, EITHER EXPRESS OR
IMPLIED, WITH RESPECT TO THIS
DOCUMENT, ITS QUALITY, ACCURACY,
MERCHANTABILITY, OR FITNESS FOR A
PARTICULAR PURPOSE. AS A RESULT,
THIS DOCUMENT IS PROVIDED “AS IS,”
AND YOU, THE READER, ARE ASSUMING
THE ENTIRE RISK AS TO ITS QUALITY AND
ACCURACY.

IN NO EVENT WILL APPLE BE LIABLE FOR

DIRECT, INDIRECT, SPECIAL, INCIDENTAL,
OR CONSEQUENTIAL DAMAGES
RESULTING FROM ANY DEFECT, ERROR
OR INACCURACY IN THIS DOCUMENT,
even if advised of the possibility of such
damages.
Some jurisdictions do not allow the
exclusion of implied warranties or liability,
so the above exclusion may not apply to
you.

2023-08-24 | Copyright © 2023 Apple Inc. All Rights Reserved.

Page 66 of 66