Processes EMM (Entitlement Management Message) More...

Data Structures
struct	EMB_ByteArray
	An array of bytes. More...

struct	EMB_HardwareFilter
	Hardware filter. More...

struct	EMB_GroupFilters
	Group hardware filters. More...

struct	EMB_Processor_MediaInfo
	Media info with content ids. More...

struct	EMB_Processor_Event
	Structure used as the base for all event structures. More...

struct	EMB_Processor_OpmNotificationEvent
	OPM Notification event. More...

struct	EMB_Processor_EplNotificationEvent
	EPL Notification event. More...

struct	EMB_Processor_GkoNotificationEvent
	GKO Notification event. More...

struct	EMB_Processor_EpdNotificationEvent
	EPD Notification event. More...

struct	EMB_Processor_EventListener

Typedefs
typedef struct SHI_Data	SHI_Data
	A SHI_Data object represents a typed data object. More...

typedef struct WSB_KeyManager	WSB_KeyManager
	A WSB_KeyManager object can be used to register (set) and get content keys for a playback session. More...

typedef struct EMB_Processor	EMB_Processor
	An EMB_Processor object represents information about processing an EMBB packet. More...

Enumerations
enum	EMB_Processor_EventType { EMB_PROCESSOR_EVENT_TYPE_EPL_ADDED, EMB_PROCESSOR_EVENT_TYPE_EPL_CHANGED, EMB_PROCESSOR_EVENT_TYPE_EPL_REMOVED, EMB_PROCESSOR_EVENT_TYPE_GKO_ADDED, EMB_PROCESSOR_EVENT_TYPE_GKO_CHANGED, EMB_PROCESSOR_EVENT_TYPE_GKO_REMOVED, EMB_PROCESSOR_EVENT_TYPE_EPD_ADDED, EMB_PROCESSOR_EVENT_TYPE_EPD_CHANGED, EMB_PROCESSOR_EVENT_TYPE_EPD_REMOVED, EMB_PROCESSOR_EVENT_TYPE_OPM }
	Identifiers for event types. More...

Functions
EMB_EXPORT EMB_Result	EMB_Processor_Create (EMB_Processor_EventListener listener, EMB_Processor **processor)
	Create EMB (Extended Marlin Broadband) processor to process EMM (Entitlement Management Message). More...

EMB_EXPORT EMB_Result	EMB_Processor_GetDeviceFilter (EMB_Processor processor, EMB_HardwareFilter device_filter)
	Get the filter suitable to set hardware filter to obtain EMMs targeting at the device. More...

EMB_EXPORT EMB_Result	EMB_Processor_GetGroupFilters (EMB_Processor processor, EMB_GroupFilters group_filters)
	Get the group filters suitable to set hardware filter(s) to obtain EMMs targeting at group(s). More...

EMB_EXPORT EMB_Result	EMB_Processor_ProcessPacket (EMB_Processor processor, EMB_ByteArray packet)
	Process incoming EMM of the following payload types: More...

EMB_EXPORT EMB_Result	EMB_Processor_EnableContent (EMB_Processor processor, EMB_Processor_MediaInfo media_info, WSB_KeyManager *key_manager)
	Enable content with the specified content id(s) to be ready for playback. More...

EMB_EXPORT EMB_Result	EMB_Processor_Destroy (EMB_Processor *processor)
	Destroys the EMB_Processor object. More...

Detailed Description

Processes EMM (Entitlement Management Message)

Typedef Documentation

◆ EMB_Processor

typedef struct EMB_Processor EMB_Processor

An EMB_Processor object represents information about processing an EMBB packet.

◆ SHI_Data

typedef struct SHI_Data SHI_Data

A SHI_Data object represents a typed data object.

◆ WSB_KeyManager

typedef struct WSB_KeyManager WSB_KeyManager

A WSB_KeyManager object can be used to register (set) and get content keys for a playback session.

Enumeration Type Documentation

◆ EMB_Processor_EventType

enum EMB_Processor_EventType

Identifiers for event types.

See also: EMB_Processor_Event

Enumerator
EMB_PROCESSOR_EVENT_TYPE_EPL_ADDED
EMB_PROCESSOR_EVENT_TYPE_EPL_CHANGED
EMB_PROCESSOR_EVENT_TYPE_EPL_REMOVED
EMB_PROCESSOR_EVENT_TYPE_GKO_ADDED
EMB_PROCESSOR_EVENT_TYPE_GKO_CHANGED
EMB_PROCESSOR_EVENT_TYPE_GKO_REMOVED
EMB_PROCESSOR_EVENT_TYPE_EPD_ADDED
EMB_PROCESSOR_EVENT_TYPE_EPD_CHANGED
EMB_PROCESSOR_EVENT_TYPE_EPD_REMOVED
EMB_PROCESSOR_EVENT_TYPE_OPM

Function Documentation

◆ EMB_Processor_Create()

EMB_EXPORT EMB_Result EMB_Processor_Create	(	EMB_Processor_EventListener	listener,
		EMB_Processor **	processor
	)

Create EMB (Extended Marlin Broadband) processor to process EMM (Entitlement Management Message).

Parameters

listener	An object that will receive various notification events during a EMB_Processor_ProcessPacket call.
processor	Address of a pointer that will be set to refer to the EMBB processor created.

◆ EMB_Processor_Destroy()

EMB_EXPORT EMB_Result EMB_Processor_Destroy ( EMB_Processor * processor )

Destroys the EMB_Processor object.

Parameters

processor An EMBB processor.

◆ EMB_Processor_EnableContent()

EMB_EXPORT EMB_Result EMB_Processor_EnableContent	(	EMB_Processor *	processor,
		EMB_Processor_MediaInfo *	media_info,
		WSB_KeyManager *	key_manager
	)

Enable content with the specified content id(s) to be ready for playback.

It searches for EPL/GKO to derive a MS3 license. Once it has the license, it will evaluate the license, enable the content to be ready for playback.

Specifically the details of the steps are as followed:

1) obtain a license for the specified content id(s)

In the case of using EPL/GKO:

a) lookup EPL with the request content id
b) lookup GKO that the EPL depends on if any
c) base64 encoded result of a) and result of b) if any as part of the
   business token in ms3h request URL
d) formulate the ms3h request URL pointing to XPCA internal MS3 Server
e) call WSB_PlaybackEnabler_ResolveUrl() with d) which triggers
   MS3_Client::GetSas() to
       i)   generate a nonce
       ii)  retrieve the Octopus public node
       iii) formulate the ms3h POST request body with i) and ii)
       iv)  POST the SAS request to XPCA internal MS3 Server
f) in either execution model with:
       - only SKB in TEE
       - with TEE porting kit
   XPCA internal MS3 Server
       i)  call XPCA SAS Builder (specifically
           WSB_Ms3EplSasBuilder::EplToSas() function) to build a SAS
           from EPL and dependent GKO (if any)
       ii) XPCA SAS Builder call OCT_KeyManager_GetKey() to obtain
           the Octopus private keys in SKB_SecureData type and uses it
           along with EPL, GKO (if needed), nonce, public Octopus node
           to build the SAS
   in the execution model with TEE porting kit, XPCA SAS Builder
   resides in TEE

2) perform the play action on the license obtained from 1) by calling WSB_PlaybackEnabler_PerformPlayAction()

3) call WSB_Config_ValidateActionResult() to check i) play action is granted ii) check the action result and handle all mandatory obligations and callbacks (we might need to provide a sample implementation of this function that can handles all the expected mandatory obligations and callbacks on the target platform)

4) accept action result to obtain content keys and supplies them to the internal key manager by calling WSB_PlaybackEnabler_AcceptActionResult()

Parameters

processor	An EMBB Processor.
media_info	A media information structure that contains content id(s) to be enabled for playback.
key_manager	For the execution model with only SKB in TEE, a key manager object that will be populated with content keys in SKB persistent export format. For the execution model with TEE porting kit, the key manager only exists in TEE so caller just need to pass in NULL for this argument.

◆ EMB_Processor_GetDeviceFilter()

EMB_EXPORT EMB_Result EMB_Processor_GetDeviceFilter	(	EMB_Processor *	processor,
		EMB_HardwareFilter *	device_filter
	)

Get the filter suitable to set hardware filter to obtain EMMs targeting at the device.

See ExpressPlay CA - Entitlement Management Messge (EMM) specification for more information.

For example, if the device's Octopus Node ID is

urn:marlin:organization:seacert:companya:8pusperso:00000702a2

the device target address in big-endian format is formulated with "companya" and "00000702a2" in hex byte array as

[0x63, 0x6f, 0x6d, 0x70, 0x61, 0x6e, 0x79, 0x61,
 0x00, 0x00, 0x07, 0x02, 0xa2]

table id used for device is 0x82

coeff is the following where x can be any value but won't be used for filtering purpose

[0x82,    x,    x,
 0x63, 0x6f, 0x6d, 0x70, 0x61, 0x6e, 0x79, 0x61,
 0x00, 0x00, 0x07, 0x02, 0xa2]

mask is

[0xff, 0x00, 0x00,
 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
 0xff, 0xff, 0xff, 0xff, 0xff]

mask controls which bits of the coeff are compared with the incoming EMMs first 16 bytes. On a binary value of 1 in the mask, the corresponding bits are compared. The hardware filter accepts the EMM if its first 16 bytes are equal to the coeff in all the tested bit positions.

Parameters

processor	An EMBB Processor.
device_filter	Address to the caller provided device filter structure to receive the device filter data.

◆ EMB_Processor_GetGroupFilters()

EMB_EXPORT EMB_Result EMB_Processor_GetGroupFilters	(	EMB_Processor *	processor,
		EMB_GroupFilters *	group_filters
	)

Get the group filters suitable to set hardware filter(s) to obtain EMMs targeting at group(s).

See ExpressPlay CA - Entitlement Management Messge (EMM) specification for more information.

A group ID is 13 bytes in big-endian format consists of a reserve byte of 0x00 followed by 12 bytes (96 bits) of group mask, each bit represents a group. The group IDs are distributed over the range of 13 EMM tables that provide a range of group IDs from 0 to 1247

table_id 0x83 for group ID [   0 to   95]
table_id 0x84 for group ID [  96 to  191]
table_id 0x85 for group ID [ 192 to  287]
table_id 0x86 for group ID [ 288 to  383]
table_id 0x87 for group ID [ 384 to  479]
table_id 0x88 for group ID [ 480 to  575]
table_id 0x89 for group ID [ 576 to  671]
table_id 0x8a for group ID [ 672 to  767]
table_id 0x8b for group ID [ 768 to  863]
table_id 0x8c for group ID [ 864 to  959]
table_id 0x8d for group ID [ 960 to 1055]
table_id 0x8e for group ID [1056 to 1151]
table_id 0x8f for group ID [1152 to 1247]

(Example 1)

if the group ID is 223

table ID for this group is 0x85

the target address for this group in hex byte array is

[0x00,
 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x80, 0x00, 0x00, 0x00]

group_filters->use_table_count is 1

group_filters->filters[2].coeff is the following where x can be any value but won't be used for filtering purpose

[0x85,    x,    x,
 0x00,
 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x80, 0x00, 0x00, 0x00]

group_filters->filters[2].mask is

[0xff, 0x00, 0x00,
 0xff,
 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0x7f, 0xff, 0xff, 0xff]

(Example 2)

if the group IDs are 0, 95, 96, 1000

table ID for this set of groups are 0x83 (group 0, 95), 0x84 (group 96), 0x8d (group 1000)

the target address for group IDs 0 and 95 in hex byte array is

[0x00,
 0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01]

the target address for group ID 96 in hex byte array is

[0x00,
 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01]

the target address for group ID 1000 in hex byte array is

[0x00,
 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00]

group_filters->use_table_count is 3

group_filters->filters[0].coeff for groups IDs 0 and 95 is the following where x can be any value but won't be used for filtering purpose

[0x83,    x,    x,
 0x00,
 0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01]

group_filters->filters[0].mask is

[0xff, 0x00, 0x00,
 0xff,
 0x7f, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xfe]

group_filters->filters[1].coeff for groups ID 96 is the following where x can be any value but won't be used for filtering purpose

[0x84,    x,    x,
 0x00,
 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01]

group_filters->filters[1].mask is

[0xff, 0x00, 0x00,
 0xff,
 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xfe]

group_filters->filters[10].coeff for groups ID 1000 is the following where x can be any value but won't be used for filtering purpose

[0x8d,    x,    x,
 0x00,
 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00]

group_filters->filters[10].mask is

[0xff, 0x00, 0x00,
 0xff,
 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xfe, 0xff, 0xff, 0xff, 0xff, 0xff]

The mask controls which bits of the coeff are compared with the incoming EMMs first 16 bytes. On a binary value of 1 in the mask, the corresponding bits are compared. The hardware filter accepts the EMM if its first 16 bytes are equal to the coeff in all the tested bit positions.

If the returned group_filters->use_table_count is equal to 0, then the device does not belong to any group and no group filters need to be set.

Parameters

processor	An EMBB Processor.
group_filters	Address to the caller provided group filters structure to receive the group filters data.

◆ EMB_Processor_ProcessPacket()

EMB_EXPORT EMB_Result EMB_Processor_ProcessPacket	(	EMB_Processor *	processor,
		EMB_ByteArray *	packet
	)

Process incoming EMM of the following payload types:

EPL (MS3 (Marlin Simple Secure Streaming) Extended Persistent License)
GKO (Group Key Object)
CMD (Command)
OPM (Operator Message)
EPD (Entitlement Package Definition)

Ignore EMM with EMM ID that exits in the EMB Storage and has not expired. Store EPL and GKO in EMB Storage, replacing them as per spec. EMB Storage encapsulates EMB Store (where EPLs and GKOs are stored) and Wasabi LicenseStore (where MBBs are stored).

Parameters

processor	An EMBB processor.
packet	Packet data to be processed.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ EMB_Processor

◆ SHI_Data

◆ WSB_KeyManager

Enumeration Type Documentation

◆ EMB_Processor_EventType

Function Documentation

◆ EMB_Processor_Create()

◆ EMB_Processor_Destroy()

◆ EMB_Processor_EnableContent()

◆ EMB_Processor_GetDeviceFilter()

◆ EMB_Processor_GetGroupFilters()

◆ EMB_Processor_ProcessPacket()