Sie sind auf Seite 1von 112
PROD-336 VCAS: OMI Integration Guide PROD-336 VCAS: OMI Integration Guide SW Version 3.8 Confidential ©

PROD-336 VCAS: OMI Integration Guide

© 2015 Verimatrix, Inc. ALL RIGHTS RESERVED

Notice: No part of this publication may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, or stored in a database or retrieval system for any purpose without the express written permission of Verimatrix, Inc.

Verimatrix, Inc. reserves the right to make changes to this document at any time without notice and assumes no responsibility for its use. Verimatrix, Inc. products and services can only be ordered under the terms and conditions of Verimatrix, Inc.'s applicable agreements. All of the features described in this document may not be currently available. Refer to the most recent product announcement or contact Verimatrix, Inc. for information on feature and product availability.

The information contained in this document is provided AS-IS without warranty of any kind. Verimatrix reserves the right to make changes to this document and its implementation without any obligation to notify the recipient of this document. Nothing in this document shall create a warranty, either express or implied, and nothing herein shall alter the terms and conditions set forth in the applicable confidentiality and license agreement(s) for use of the Verimatrix confidential information or products.

Verimatrix and the Verimatrix logo are registered trademarks and service marks of Verimatrix, Inc.

All other trademarks, service marks, company names or logos are properties of their respective owners. Mention of third-party products is for informational purposes only and constitutes neither an endorsement nor a recommendation. Verimatrix, Inc. assumes no responsibility with regard to the performance or use of these products.

Verimatrix, Inc. 6059 Cornerstone Court West San Diego, CA 92121-3713 Telephone: +1.858.677.7800 Fax: +1.858.677.7804

Table of Contents

Preface

i

 

About This Document

i

Who Should Use This Document

i

What's Changed in This Document

i

Related Documents

i

Overview

1

OMI

Communications

3

OMI

Entities

4

Networks

4

Devices

4

Domains

6

Entitlements

6

Entitlement Entities

8

OMI Entitlement Model

12

On-screen Messages

13

OMI Web Services

15

 

Administration Management Service

16

Configuration Management Service

17

Content Management Service

19

Device Management Service

22

Domain Management Service

24

Entitlement Management Service

25

Messaging Service

27

Integrating with the OMI

29

APIs Available for Each Network

33

Implementing Specific Use Cases

41

 

Defining Networks

41

Querying Network Configurations

43

Defining Content

45

Defining

a

Broadcast

Channel

48

Defining

a

Broadcast

PPV Event

49

Defining Video on Demand

50

Creating Packages

51

Preparing Packages for Specific DVB Use Cases

54

Defining Devices

 

56

Implementing Hybrid Devices

60

Allowing Multiple SMS to Share the Same Device

61

Pairing a STB and Smartcard

61

Joining

Devices

 

64

Defining Entitlements

65

Entitling a Device or Domain to a Package

65

Forcing Entitlement Changes

67

Defining Policies

 

68

Defining Common Policy-based Business Models

70

Auditing Data with List Queries

 

71

Iterating Through a List

71

Querying for an Individual Record

72

Defining Output Controls

 

73

Enabling VideoMark

75

Implementing Fingerprinting

77

Defining On-Screen Messages

79

Defining

Trigger Messages

84

Defining

Preloaded Messages

85

Removing a Network

 

87

OMI Change History

 

88

VCAS 3.8

88

Operations

88

New Operations

 

88

Changed Operations

89

Deprecated Operations

89

Removed Operations

89

Data Types

89

New Data Types

 

89

Changed Data Types

90

Deprecated Data Types

90

Removed Data Types

91

VCAS 3.7

91

Operations

91

New Operations

91

Changed Operations

92

Deprecated Operations

92

Removed Operations

92

Data Types

92

New Data Types

92

Changed Data Types

93

Deprecated Data Types

94

Removed Data Types

94

VCAS 3.6

94

Operations

95

New Operations

95

Changed Operations

95

Deprecated Operations

95

Removed Operations

95

Data Types

95

New Data Types

95

Changed Data Types

95

Deprecated Data Types

96

Removed Data Types

96

VCAS 3.5

97

Operations

97

New Operations

97

Changed Operations

97

Deprecated Operations

97

Removed Operations

98

Data Types

98

New Data Types

98

Changed Data Types

98

Deprecated Data Types

98

Removed Data Types

98

VCAS 3.4

99

Operations

99

Data Types

99

New Data Types

99

Changed Data Types

99

Deprecated Data Types

99

Removed Data Types

99

VCAS 3.3

100

Operations

100

New Operations

100

Changed Operations

100

Deprecated Operations

100

Removed Operations

100

Data Types

101

New Data Types

101

Changed Data Types

101

Deprecated Data Types

101

Removed Data Types

101

APIs Removed and Replaced by OMI

102

Certificate Revocation List Service

102

Real-Time Encryption Service

103

Verimatrix Pre-Processor Service

103

Preface

About This Document

This document provides an overview of the Operator Management Interface (OMI), outlines common use cases, and describes the entities (data types, web services, messages) available through this interface.

Use this document when creating your interface between your Subscriber Management System (SMS) and VCAS.

Who Should Use This Document

Users of this document are those trying to integrate their SMS to VCAS. Readers are expected to have:

Working knowledge of network concepts

General knowledge of VCAS

Understanding of programming concepts

Understanding of SOAP

Completed Verimatrix University

What's Changed in This Document

The following information has been added or revised for this version of the document.

 

SECTION

DESCRIPTION OF CHANGE

All

This document has been completely rewritten for 3.8.

Related Documents

In addition to this document, the following documents may also be useful when using VCAS:

PROD-300 VCAS: OMI API Reference. Provides detailed information on the available OMI APIs including functional descriptions, data structure definitions, and returned error codes.

VCAS Multi-network Revenue Security Overview. Provides an overview of VCAS Platform and the available VCAS solutions. This document can be found on the Verimatrix Partner Portal.

PROD-00 VCAS: Installation Guide. Provides instructions for installing the Red Hat Enterprise Linux (RHEL) operating system and Oracle database, and for installing and performing base configuration for the VCAS Platform and VCAS solutions.

PROD-102 VCAS for IPTV and DVB Hybrid: Configuration Guide. Provides instructions on how to configure the VCAS for IPTV and the VCAS for DVB solutions in the same environment.

PROD-103 VCAS for Internet TV: Configuration Guide. Provides instructions on how to configure the VCAS for Internet TV solution.

PROD-107 VCAS for MultiRights: Configuration Guide. Provides instructions on how to configure the VCAS for MultiRights solution.

PROD-506 VCAS: GUI Users Guide. Describes how to use the VCAS GUI to manage and maintain content, devices, and entitlements within VCAS.

Chapter 1

Overview

The OMI is a unified interface that provides a "smart" adapter/translator between external systems. Operators use these systems to manage their operations and one or more sets of VCAS Conditional Access (CA) and Digital Rights Management (DRM) components that implement the details of revenue security across their networks. OMI provides a unified interface for headend deployments distributing content through different networks and different subscriber devices. As a result, the OMI simplifies headend integration and enables homogenous rights management for heterogeneous networks and devices.

The OMI supports external management systems such as SMS and/or middleware servers. In this document, these systems are called operations management systems (OMS). The overriding value proposition for operators and/or system integrators lies in the abstraction of the underlying conditional access system (CAS)/DRM "plumbing" of VCAS by using a single set of Application Programming Interfaces (APIs) into VCAS.

Using the OMI operators are able to:

Define and manage linear broadcast and video on demand (VOD) content

Define and manage subscriber devices

Define and manage subscriber entitlements and policies

Send messages to subscriber devices

The OMI provides a single point of VCAS communications with the external OMS. OMS-provided information, such as channel setup and entitlement data, are translated and formatted into objects based on the underlying format required by the network specific Content Security Manager (CSM). The OMI then communicates the entitlements and other information through internal interfaces, APIs, and protocols defined for each CAS/DRM server.

The following diagram provides an overview of the OMI and its various integration points.

an overview of the OMI and its various integration points. Figure 1: Overview of the OMI

Figure 1: Overview of the OMI Architecture

The OMI has two major tasks:

Managing diversity of the CAS

Isolating the OMS from the specifics of the CAS/DRM

Diversity refers to OMI's ability to manage different types of CAS while providing the same interface to the OMS. Currently, OMI supports the following CAS/DRM:

VCAS for DVB

VCAS for IPTV

VCAS for Internet TV

VCAS for MultiRights: PlayReady and Widevine

OMI Communications

OMI receives requests from one or more OMSes or from the VCAS GUI through its SOAP interface; OMI serves OMSes and the VCAS GUI through the same interface. SOAP is a form of Remote Procedure Call (RPC) protocol that uses XML as the encoding scheme and secure HTTP as the transport. The standardization body for SOAP is the World Wide Web Consortium (W3C). For more information about SOAP and associated specifications, visit http://www.w3.org/TR/soap.

The advantage of using a Web service to implement the interface between OMI and the OMS is the ubiquitous availability of SOAP toolkits for a wide variety of programming languages that transparently handle the syntax and semantics of the underlying protocols. These toolkits enable a quick turnaround when implementing a Web service server or client. Examples of such toolkits are:

Apache Axis2 (http://ws.apache.org/axis2)

JAX-WS toolkit that is part of the Java Platform, Standard and Enterprise edition

The SOAP toolkit that is part of Microsoft .NET framework

The OMI SOAP interface verifies the SMS/middleware system's credentials and the validity of the request. The request and the provided data pass to the data processor and validator, which validate the data and process the request. If the request contains data that requires persistence, the data processor stores it in the OMI database. Other requests can trigger particular actions for some or all of the served CAS and DRM systems. These actions are translated into the proprietary protocols used by these systems. After the execution of a request is completed, the OMI returns status information and eventually data to the requesting OMS. OMI can serve any number of OMSes and GUIs concurrently, as long as there are free connections available on the SOAP server.

If you are an application developer implementing an interface for the OMI Web services, you can build the interface using only the information found in this document and PROD-300 VCAS: OMI API Reference. However, Verimatrix recommends using the supplied OMI Web Services Description file (OMI.wsdl) along with the code generator of a SOAP toolkit to automatically generate the necessary code stubs. The OMI Web service is implemented through OMI as the server and the OMS as the client. For more information, see OMI Web Services (on page 15).

Web Services Description Language (WSDL) is a uniform language expressed in XML that describes Web services. While a WSDL is human readable due to its XML encoding, it can easily and preferably be processed by computer applications. All SOAP toolkits include a code generator that can create the stub code for the toolkit's SOAP implementation from a WSDL. After creating the stub code, application developers need only fill the stubs with application-specific code. Using a SOAP toolkit and a code generator simplifies the implementation process and shortens development time significantly.

Note

Verimatrix recommends a minimum of a 30 second timeout value between the OMS and the OMI.

OMI Entities

OMI entities are those components that are germane to all OMI functionality. These entities include:

Networks (on page 4): Generic object that describes CAS/DRM platforms

Devices (on page 4): Generic object that describes a physical subscriber device

Domains (on page 6): Optional. Arbitrary group of subscriber devices used to group devices across networks for entitlement and messaging

Entitlements (on page 6): Objects that define the rights that a subscriber has to a package of content items

Networks

The OMI organizes the different CAS/DRM platforms it manages into networks such as IPTV, Internet TV, DVB, and MultiRights. Within the OMI's logical representation of the CAS/DRM infrastructures the network is the top-level component. Devices, content, and events are associated with networks. These associations enable the OMI to correctly route events, messages, and entitlements to the correct CAS/DRM platform. An individual OMI deployment can support one of each type of available networks. For a list of the available network types, see "NetworkType" in PROD-300 VCAS: OMI API Reference.

The first action an OMI user performs is defining the networks. This is a one-time operation and is inherent in the architecture of the overall system.

Devices

Devices refer to uniquely identifiable subscriber devices that your system supports such as smartcards, set-top boxes (STB), mobile phones, Internet TV web home gateway, and PC/Mac. Each subscriber device must be associated with at least one network, and must be added to each network for which it will have access.

For wholesale/retail deployments, RSM and RKE devices must be configured to enable the retail-site to connect to the wholesale-site. For more details, refer to PROD-102 VCAS IPTV and DVB Hybrid: Configuration Guide.

Each device can have its own set of entitlements and messages or can be grouped in a domain ("Domains" on page 6) and inherit the same set of entitlements and messages for each device within the domain. Devices and/or domains are entitled to view packages (on page 11), with VCAS ensuring proper key delivery to the devices to enable decryption and viewing of the underlying content.

Device Pairing

For STBs on DVB networks, the OMI also provides the ability to "pair" smartcards and STBs. Pairing a STB with a smartcard restricts the use of the smartcard to only those STBs with which the smartcard is paired.

The pairing relationship depends on the hardware capabilities of the STB and can be either one-to-one or many-to-many. In the many-to-many scenario, a smartcard can be paired with multiple STBs, and a STB can be paired with multiple smartcards.

Device Joining

For STBs on DVB networks, the OMI also provides the ability to link one primary device to one or more secondary devices, providing automatic extension of entitlements granted to the primary device to the secondary devices.

Primary/secondary defines a business model, where multiple subscriptions can be bound to a single household by using a primary STB and additional secondary STBs, which must be interconnected using short range communication technology.

Smartcards can be dynamically defined to be secondary smartcards, working only together with a corresponding primary smartcard and in an environment, where the secondary and the primary smartcards are interconnected using a communication between the STBs.

Device Purse

DVB smartcard devices have a so-called "purse", which is a subscriber credit level for interactively purchasing PPV events by entering the device PIN using the subscriber’s remote control. This feature is comparable to the credit in a pre-paid business model. The credit is loaded onto the smartcard’s purse using a device command sent through the OMI. This credit can be used to purchase PPV events which were defined as so- called IPPV (impulse pay-per-view) events.

Available Device-based OMI Functionality

Through the OMI you can:

Add/edit/remove devices

Obtain a list of devices

Reset a device back to a non-provisioned state

Disable/enable a device (non-DVB only)

Verify a device (IPTV only)

Refresh device entitlements (DVB/IPTV only)

Define and manage STB/smartcard pairings (DVB only)

Obtain a list of STB and smartcard pairings (DVB only)

Join/unjoin devices to create a device hierarchy (DVB only)

Manage subscriber PINs (DVB only)

Manage device purses (DVB only)

Refresh device keys (DVB only)

Perform public authentication of a device (IPTV only)

Domains

Domains enable the grouping of individual devices to form a single addressable entity. All devices within a domain will receive any entitlements associated with the domain and will also receive any on-screen messages sent to that domain. A single domain can contain devices from different networks. A domain can contain shared devices; however, those domains cannot be shared among SMS systems.

Available Domain-based OMI Functionality

Through the OMI you can:

Add/remove/edit domains

Add/remove/edit the association of devices to domains

Obtain a list of domains

Obtain the list of devices associated with a domain

Obtain the list of domains to which a device is associated

Entitlements

Entitlements provide control over how subscribers consume content. They are necessary to enforce content owner rights and to link billing activities to playback functionality. An entitlement is always associated with a package, however, a package can contain an individual content item, an individual channel, a group of content items and/or channels, or just about any combination of assets. In addition, an entitlement can be assigned to an individual subscriber device or a domain.

Using the OMI, operators define the elements of their entitlements, such as what content (package/events) is included for what time frame, and then assign entitlements to subscriber devices or domains. When a subscriber tries to access content (such as a movie, sporting event, or specific channel) on a device connected to a two-way network such as IPTV or Internet TV, the associated CSM validates the subscriber's entitlement to the content with the OMI database. If the subscriber has access rights to the content (is entitled), then playback access is granted; if not, access to the content is denied.

Figure 2: Two-way Entitlement Flow If a subscriber tries to access content on a device

Figure 2: Two-way Entitlement Flow

If a subscriber tries to access content on a device connected to a one-way network such as DVB, access is only granted if the associated Broadcast Content Security Manager (BCSM) has pre-provisioned the device with the content specific keys and entitlements using the entitlement data forwarded to it from the OMI.

using the entitlement data forwarded to it from the OMI. Figure 3: One-way Entitlement Flow PROD-336

Figure 3: One-way Entitlement Flow

Entitlement Entities

Within the OMI there are a set of entities that define an entitlement and who has rights to those entitlements:

Content (on page 9): Describes on-demand or linear services media assets

Events (on page 11): Associates time parameters with any content item for a specific network

Packages (on page 11): Groups events into commercial products

Policies (on page 12): Defines licenses for MultiRights environments and links those licenses to entitlements

Some entities, such as content, devices, and events must be associated with a specific network. When adding content to the OMI, you must first add it to the OMI (addContent()) and then associate it with a specific network (addContentToNetwork()). If you try to create an event using content that has not been added to a network, you will receive an error.

When adding devices, you add the devices and assign them to a specific network using a single call (addDevices()). When adding events (addEvents()), you implicitly associate them with a specific network because the content you create them on has already been added to a network.

The following lists the general association between OMI and entitlement entities:

The OMI can contain one or more networks.

Devices are assigned to specific networks; if a device should be able to access multiple networks, it must be added to each network in which it will have entitlements.

Domains group one to "n" number of devices.

Content must be added to the OMI and then added to each network in which the content will be available.

Events contain a one-to-one relationship between a single piece of content on a specific network and a timeframe of availability.

Packages can contain one to "n" number of events.

Entitlements associate packages and devices or domains.

Policies define the type of access DRM subscriber devices have to content and are linked to entitlements to define their timeframe of availability.

The following diagram illustrates these associations:

The following diagram illustrates these associations: Content Content is a generic term in the OMI for

Content

Content is a generic term in the OMI for media assets, which can be linear real-time assets such as broadcast channels or static on-demand assets such as VOD movies. A single piece of content can be added to one or more networks but only needs to be added to VCAS one time.

Content is identified in two ways inside the OMI:

smsContentID: The unique name by which the content is referred to by the OMS.

NetworkContentID: The identifier that the CA/DRM system embeds in the encrypted media asset and that the reference subscriber devices use to retrieve the encryption key.

For IPTV linear content, this is the channel number. For VOD, the networkContentId is assigned by the VPP process and returned as part of the results data; so in essence it is ignored for IPTV VOD.

For InternetTV and MultiRights linear content and VOD, this is the resourceID passed by the encoder/packager.

For DVB linear content, this is the numeric DVB service ID used for this channel. For VOD, it is an arbitrary identifier used as the DVB network specific identification for the VOD content.

Each content object in the OMI requires the definition of at least one associated event object. While this may appear to be unnecessary for linear channels and VOD content, using events creates a richer description that allows more sophisticated business models to be built from the basic objects. This will become apparent as the use cases describe more complex scenarios.

Broadcast Pay-per-Channel

Broadcast pay-per-channel (PPC) represents the classic television channel that broadcasts content continuously for 24 hours a day and 7 days a week. Within the OMI realm, a broadcast PPC is defined by combining two entities:

The content

One event element per distribution network/CA

Broadcast Pay-per-View

Broadcast pay-per-view (PPV) allows viewers that are not currently subscribed to a broadcast PPC to view certain programs televised on that channel by ordering the PPV. A typical application is a major-league sports event that can generate additional revenue if extended beyond PPC customers to include PPV customers as well.

Note

PPV events are not valid for Internet TV or MultiRights content.

You define broadcast PPV by adding additional time-limited events to the broadcast PPC.

Video on Demand

VOD content is any static asset that subscribers can access and view for a specific period of time. Within the OMI realm, a VOD is defined by combining two entities:

The content

One event element per distribution network/CA

Available Content-based OMI Functionality

Through the OMI you can:

Add/remove content

Associate/disassociate content from a network

Obtain a list of the content on a network

Obtain the parameters for a specified content item

Obtain the parameters for a list of content items

IPTV/DVB VOD only. Obtain the encryption status for a specified content item

Events

Events specify the availability period for specific content, for a specific network. For VOD and DTV content, the time period should be infinite. For PPV, set the time periods to specify the start and end times of the PPV event. Events are ultimately grouped into packages for the purposes of entitling devices to the underlying content.

If an event is removed, its association to packages is removed automatically. This does not change any entitlements of devices or domains to packages with which the removed events were associated. However, removing the last event from a package leaves the package empty, rendering any existing entitlements meaningless.

For events on a DVB network you can also define a fingerprint message that should appear when the content associated with this event is viewed. In addition, you can specify the following for events in a DVB network:

Event price

Preview period

Non-purchase period

CI+ encryption mode

CI+ analog protection

Image constraints (downres HD to SD for analog output)

Redistribution control

Video mode

Content retention

VideoMark settings

Available Event-based OMI Functionality

Through the OMI you can:

Add/remove events (supports bulk operations)

Obtain a list of all events associate with a content item

Packages

The OMI uses events as the access points to a single piece of content on a particular network. However, an individual event only allows access to content for a single network and has no association with other events. Packages enable the grouping of events (one or more) to define comprehensive subscriber offerings.

Packages provide significant flexibility, providing an almost unlimited method in which content can be bundled into purchasable subscriber offerings. For example,

VOD events can be combined into movie packages, sports events can be sold individually or placed into a package that provides viewing rights for the entire season, content can be bundled into channels, and so on.

There are some restrictions however, for example, PPV and digital TV (DTV) (PPC) events cannot be mixed into one package. In addition, the underlying networks and CA systems may have technical limitations that prevent using certain combinations. In this case, the OMI rejects the package with an error condition.

Also, due to the nature of DVB addressing, there are limits on how many packages of a certain type that can be created. These limits depend on the configuration of the underlying DVB system. Packages that are not intended to be used on a DVB network can be flagged as such by providing the proper PackageParameters and have no such limits.

Available Package-based OMI Functionality

Through the OMI you can:

Add/modify/remove packages (supports bulk operations)

Add/remove events from a package

Obtain a list of all packages

Obtain a list of all events associated with a package

Obtain a list of all packages associated with an event

Policies

MultiRights only. Policies define the type of access that a device has to content when using a DRM such as PlayReady and Widevine. It defines the type of license to deliver to the subscriber device, whether that license can be persisted on the subscriber device, whether the license is renewable, and any type of access control imposed on the subscriber device when viewing the content such as copy controls and viewing limits.

Policies are linked to entitlements which provide the timeframe for which the policy is viable.

OMI Entitlement Model

The OMI uses a "push" operational model, which enables a data cache to be built in the VCAS entitlement subsystem. As a result, the majority of entitlement checks do not require real-time communication to an external source, such as an OMS.

In essence, VCAS provides a storage cache for SMS/middleware data on domains (devices, content, and entitlement information), which is maintained in a form fully optimized to support efficient queries. The entitlement interface also supports a direct way to perform necessary VCAS entitlement checks in real-time, supported by a series of methods to synchronize and maintain the cache with notifications of updates and changes to the entitlement or subscriber information. With this entitlement

model, the OMS offloads the requirement to perform real-time entitlement database checking to VCAS.

Unlike a "pull" model, where the external SMS/middleware is accessed by VCAS "on the fly" for real-time entitlement checks, the push model that the OMI uses significantly optimizes the response times for any of the various forms of entitlement checks by:

Eliminating data formatting and communication overhead

Maintaining a minimum structure of device related data that can be rapidly searched for the relevant information.

The improvement in the potential richness and efficiency of entitlement management is counterbalanced by the increase in complexity of managing a sometimes substantial cache of critical data.

Note

Verimatrix recommends a minimum of a 30 second timeout value between the middleware system and the OMI.

On-screen Messages

The OMI enables text-only messages to be sent to STB/TV devices connected to IPTV and DVB networks; messaging is not supported for Internet TV or MultiRights networks. These messages can be sent to an individual device, a domain, or to all devices on the specified network. Messages can be targeted to always display, only when a subscriber is viewing content contained in a specific package, or when they are viewing content not contained in a specified package. In addition, operators can control:

The positioning of a message on the screen

How long a message displays on the screen

Whether the message can be removed by the subscriber

Whether multiple messages can appear on the screen at the same time

CA-subsystem trigger messages

The OMI defines an abstract interface for on-screen messages. The OMI formats on- screen messages according to the encoding scheme defined in the charsetName parameter of the OnScreenMessage data structure before sending the message to a device. If this parameter is not specified, the system uses the default encoding scheme specified in the omi.messaging.encoding parameter of the omi.properties file.

In addition to "base" on-screen messaging, the OMI also provides the ability to send:

"Trigger" messages to DVB STB

Command messages to IPTV STB/TV devices

Diagnostic messages

"Preloaded" messages

Trigger Messages

DVB networks only. On-screen messages can be used to trigger various actions on a set-top box, such as:

Upgrading set-top box software

Rescanning all channels

Switching services

Enabling simple watermarking

Resetting subscriber PINs

Binding a device to a subscriber

Handling Emergency Alert System (EAS) events

It is up to the set-top box manufacturer to implement the triggers that the set-top box will handle. Any trigger that is not implemented should be ignored. For additional information on implementing trigger messages, see PROD-324 VCAS for DVB: Trigger Messages for Set-Top Boxes Reference.

Command Messages

IPTV networks only. Command messages enable operators to send command-type information (blobs) to a STB on an IPTV network. The payload of the command information is defined by the operator and any associated functionality must be implemented by the set-top box manufacturer. For additional information on this functionality, see "generateDeviceCommand" in PROD-300 VCAS: OMI API Reference.

Diagnostic Messages

DVB networks only. Diagnostic messages enable operators to send diagnostic information to message entities that displays when a particular event is viewed. The payload of the diagnostic message is defined by the operator and any associated functionality must be implemented by the set-top box manufacturer. For additional information on this functionality, see "diagnoseOSM" in PROD-300 VCAS: OMI API Reference.

Preloaded Messages

Preloaded messages enable operators to send messages to STBs that have permanent storage capabilities, and then later send another message to the STB to actually display the message. By pushing down preloaded messages to local device storage, operators can save bandwidth by sending down a simple "display message" which should use up less bandwidth.

In addition, preloaded messages can be used to send messages that are greater than 160 bytes, by sending multiple "message chunks" and then referencing all of those chunks in a single display message call. For additional information on this functionality, see "preloadMessage" and "generatePreloadedOSM" in PROD-300 VCAS: OMI API Reference.

OMI Web Services

The OMI is a collection of services that are organized by functionality. The following table describes the services that make up the OMI API.

OMI Web Services

WEB SERVICE

FUNCTIONALITY

Administration Management Service (on page 15)

Provides the APIs to sign on and off of the OMI and to modify user passwords.

Configuration Management Service (on page 17)

Provides the APIs to manage OMI networks.

Content Management Service (on page 18)

Provides the APIs to manage the content entities (content and events).

Device Management Service (on page 21)

Provides the APIs to manage subscriber devices such as set-top boxes, PCs, Android, iOS, and smartcards.

Domain Management Service (on page 24)

Provides the APIs to manage domains.

Entitlement Management Service (on page 24)

Provides the APIs to manage subscriber device entitlements to content.

Messaging Service (on page 26)

Provides the APIs to send messages to devices.

Administration Management Service

The Administration Management Service (AdminMgmtService) provides functionality for the administration of the OMI (for example, user log on and log off).

Administration Management Service APIs

API CALL

DESCRIPTION

signOn

Log on to the OMI

signOff

Log off from the OMI

addUser

Add a user to the OMI database

getUser

Retrieve the information for the specified user

modifyUser

Modify the information associated with an existing user

removeUser

Delete the specified user from the OMI database

getUserList

Return a list of users from the OMI database

getUserEventList

Return a list of user events from the OMI database

modifyPassword

Modify OMI/VCAS GUI user passwords

modifyUserPassword

Provides the ability for an administrator to modify another user's password.

getUserSecurity

Retrieve the security and session parameters defined in the OMI database

modifyUserSecurity

Modify the security and session data defined in the OMI

Configuration Management Service

The Configuration Management Service (ConfigurationMgmtService) provides functionality to manage the structural configuration of the OMI and the associated CAS/DRM. The term "structural configuration" refers to static system setup information that adapts the system to the operator's environment, provides default and fallback settings, and so on. Most of the configuration information is considered to be static during system runtime and changes to it will, in most cases, either require the entire system or parts of it to restart for the modifications to be applied.

The OMI organizes the different CAS/DRM platforms it manages into networks. A network is essentially responsible for delivering content to devices. It uses a Conditional Access or Digital Rights Management technology to protect the content during delivery from the headend to the device. The configuration of a network is static, however the association of devices and content to a network is dynamic and can be changed at any time even while the systems are operational.

Devices are associated with networks. Within the OMI this logical association represents the physical attachment of a device to a network, for instance a cable set- top box to a DVB network or a PC to an Internet TV network. If there are physical hybrid devices that can be attached to more than one physical network, for instance a set-top box with a DVB smartcard receiver and an IPTV receiver, then they are treated by the OMI as two different devices associated with two different networks, a DVB network and an IPTV network.

Content can be delivered through different networks at the same time. Hence, the OMI allows content to be associated with multiple networks.

The Configuration Management Service sets the stage for other services providing the necessary logical associations for the routing of events and entitlements.

Configuration Management Service APIs

API CALL

DESCRIPTION

addNetwork

Add a new network to the OMI

modifyNetwork

Modify the connection parameters for an existing network

removeNetwork

Remove a network from the OMI

getNetworkList

Retrieve a list of all networks defined in the OMI.

getNetworkDeviceList

Retrieve a list of all devices associated with a network

getNetworkContentList

Retrieve a list of all content associated with a network

PROD-336 VCAS: OMI Integration Guide

Page 17

API CALL

DESCRIPTION

getDeviceTypeLicenseData

Not available for DVB. Retrieve the subscriber device type data from the VCAS license

getGroupLicenseData

Not available for DVB. Retrieve group license information such as counts and limits

getLicenseGroups

Not available for DVB. Retrieve the subscriber device types associated with each group

getSystemAttributes

Retrieve a tree structure that contains license and VCAS version information

addSite

Reserved for future use

modifySite

Reserved for future use

removeSite

Reserved for future use

getSite

Reserved for future use

getSiteList

Reserved for future use

getHostList

Reserved for future use

getHostAttributes

Reserved for future use

getNetworkAttributes

Reserved for future use

modifyHostAttributes

Reserved for future use

Content Management Service

The Content Management Service (ContentMgmtService) provides functionality to manage content protected by the CAS.

The Content Management Service defines two entities:

Content

Events

There are two types of content:

Linear broadcast (also known as DTV)

VOD

Linear broadcast refers to content that is continuously distributed through channels of the network(s). For the purpose of the CA, broadcast content has no start and no end, although distribution starts at some point in time and can stop at another.

By tuning into a broadcast channel, a subscriber can only watch that part of broadcast content that is currently distributed. Content distributed earlier through this channel can be made available for viewing through other means, such as personal video recorder (PVR) and Catch-up TV.

VOD refers to content that has a finite duration and can be requested by subscribers for viewing at any time (on-demand).

The ContentMgmtService treats basic attributes of content, broadcast and VOD, uniformly across the different CA. Basic attributes, for instance, are ContentID, Description, and Tag (used for searching).

The ContentMgmtService defines a second entity called events. Events are not strictly content as such, but provide management for content usage. Events do not exist independently of content; they are always associated with a piece of content. Multiple events can be associated with the same underlying content.

Typical examples include:

A broadcast channel carrying a single program 24/7. An event is used to define this program as a PPC. Since the program is continuously broadcast, the event has no defined start and end times.

A broadcast channel that carries children's programming during the day and adult-only content during the night. Two alternating events are used to change the parental control level and restrict access to adult content to subscribers who explicitly paid for it.

A broadcast channel that, at a certain date and time, carries the transmission of a sports event that requires viewers to pay a special subscription to view it. An

event is used to delineate the time period and modify the access criteria defining a pay-per-view event.

A broadcast channel that continuously carries the latest movies in revolving order. These movies are available through PPV; however, the first 5 minutes of the movie can be viewed by anybody. Two events are used. One to entitle everyone to the first five minutes and one to only entitle subscribers who ordered the movie through PPV for the remaining time of the movie.

The Content Management Service defines events for particular delivery networks. Events may specify CA parameters for content protection by the CA associated with a particular network.

Content Management Service APIs

API CALL

DESCRIPTION

addContent

Add one or more content items

addContentToNetwork

Associate content to a specific network

modifyContentOnNetwork

Modify the ratingLevel, fingerprintMessage (DVB only), and EncryptionParameters (not for VOD) of content on a network.

For MultiRights networks cannot modify the ENCRYPTION_ALGORITHM or ENCRYPTION_TYPE parameters.

removeContent

Remove one or more content items

removeContentFromNetwork

Disassociate content from a network

addEvents

Add and modify one or more events

removeEvents

Remove one or more events

getContentList

Return a list of all content that matches the provided query

getContentEvents

Return a list of all events associated with content that matches the provided query

getContentOnNetwork

Retrieve the NetworkContent for the specified smsContentId

getNetworkContentTypeEncrypti

Return the encryption status for all ongoing encryption jobs identified by the smsNetworkContentId and networkContentType

onStatus

API CALL

DESCRIPTION

getNetworkContentIdList

Return a list of networkContent along with its associated encryption parameters for the specified NetworkContentId.

Only IPTV and DVB return the complete set ofdata; Internet TV and MultiRights only returns smsNetworkId, smsContentId, networkContentId, and networkContentType.

getNetworkContentEncryptionSt

IPTV and DVB only. Identify the NetworkContent that is to be queried for encryption status

atus

Device Management Service

The Device Management Service (DeviceMgmtService) provides functionality to manage subscriber devices such as set-top boxes, handheld devices, PCs, and smartcards.

Logical devices are attached to only one delivery network. Although devices and their operations are network dependent, the OMI defines a set of basic attributes for them that are independent from the delivery network. Most notably, this is the smsDeviceId, which must be unique within the realm of the OMI. This type of definition is a major advantage when it comes to entitling devices for content. The entitling entity, typically an OMS, does not require any intrinsic knowledge of what delivery network a particular device is connected. It is simply sufficient to specify the smsDeviceId in the entitlement and the OMI handles the entitlement transparently.

Device Management Service APIs

API CALL

DESCRIPTION

addDevices

Adds one or more devices.

addDevicePair

Pairs a set-top box with a smartcard.

checkDevicePair

Verifies the existence of the provided device pair.

clearDevices

IPTV and DVB only. Clears resident data from a device.

disableDevices

Disables one or more devices.

enableDevices

Not available for DVB. Enables one or more devices.

getDevice

Returns device information from the associated network when available.

DVB only returns a minimal subset of values:

smsDeviceId, smsNetworkId, deviceType, and networkDeviceId.

getDeviceList

Returns a list of devices associated with a SMS device ID.

getNetworkDeviceIdList

Allows for devices on IPTV systems to be searched using the specified filter data.

getSmartCardPairing

DVB only. Returns a list of all set-top boxes paired with the provided smartcard.

API CALL

DESCRIPTION

getSTBPairing

DVB only. Returns a list of all smartcards paired with the provided set-top box.

joinDevices

DVB only. Sets the purse on a device. Joins one or more secondary devices with a primary device in a dependency relationship.

modifyDevices

Modify the networkDeviceId, smsAuthenticator and videoMarkEnabled parameters for one or more devices.

refreshDeviceEntitleme

IPTV and DVB only. Refreshes/updates the entitlements sent to a device.

nts

refreshDeviceKeys

Sets the device group key(s) to the currently active group key(s).

removeDevicePair

DVB only. Removes pairing between a set-top box and a smartcard.

removeDevices

Removes one or more devices.

removeSmartCardDeviceP

DVB only. Removes pairing between a specified smartcard and all set-top boxes paired with it.

airing

removeSTBDevicePairing

DVB only. Removes pairing between the given set-top box and all smartcards paired with it.

resetDevicePins

DVB only. Resets all pins on a device to their factory defaults.

setDevicePins

DVB only. Sets all pins on a device.

setDevicePurse

DVB only. Sets the purse on a device.

unjoinDevices

DVB only. Disassociates one or more secondary devices from its dependency relationship with its primary device.

verifyDevice

IPTV only. Provides a means for authenticating a device.

setDeviceRegion

DVB only. Reserved for future use.

Domain Management Service

Domains group devices into logical entities that can be addressed for messaging and entitled for packages using the domain's ID (smsDomainId) instead of having to make multiple calls using individual device IDs (smsDeviceId). The Domain Management Service provides the necessary functions to manage domains.

You can use domains to group devices across delivery networks. For example, you can place all devices that belong to a particular subscriber in one domain, regardless of the delivery network. For example, placing an iPad, smart TV, STB, and PC that are all associated to the same subscriber, in a single domain.

Domain Management Service APIs

API CALL

DESCRIPTION

addDomains

Add one or more domains

modifyDomains

Modify the maxDevices, domainAddress, and timePeriodRule parameters for one or more domains

removeDomains

Remove one or more domains

addDomainDevices

Associate one or more devices with a domain

modifyDomainDevices

Modify the time frame that a device is associated with a domain

removeDomainDevices

Remove association between one or more devices and a domain

getDomainList

Return a list of domains matching the provided query

getDomainDeviceList

Return a list of all devices associated with a domain

getDeviceDomainList

Return a list of all domains associated with a device

Entitlement Management Service

The Entitlement Management Service (EntitlementMgmtService) provides functionality to manage subscriber and device entitlements to content.

The Entitlement Management Service defines two entities:

Entitlements

Policies

Domains and devices can be entitled to packages. An entitlement specifies a start date/time and an end date/time during which this entitlement is valid. During that time period, a domain/device is eligible to view a particular package. The event time period must overlap the entitlement time period in order for a device to receive the decryption keys.

In addition, the OMI also supports policies for MultiRights content. Policies support subscriber device-based content entitlement for devices using DRM such as PlayReady and Widevine.

Entitlement Management Service APIs

API CALL

DESCRIPTION

addPackages

Add one or more packages

modifyPackages

Modify the description parameter of one or more packages

removePackages

Remove one or more packages

getPackageList

Retrieve a list of packages starting with the specified package ID

getPackageEvents

Retrieve a list of all events contained in a package

getEventPackages

Retrieve a list of packages for an event matching the provided query

addEventsToPackage

Add one or more events to a package

removeEventsFromPackage

Remove one or more events from a package

addEntitlements

Add one or more entitlements

modifyEntitlements

Modify the time frame that an entitlement is valid for one or more entitlements

PROD-336 VCAS: OMI Integration Guide

Page 25

API CALL

DESCRIPTION

removeEntitlements

Remove one or more entitlements

removeAllEntitlements

Revoke all entitlements for one or more entitled entities, either devices or domains

getEntitlementList

Return a list of entitlements, starting from the first entitlement whose smsEntitlementId is greater than or equal to the provided search string

stopPreEntitlements

DVB only. End all pre-entitlements for one or more entitled entities (for example, devices)

getDeviceEntitlements

Retrieve all entitlements for devices matching the given query

getDomainEntitlements

Retrieve all entitlements for domains matching the given query

getRetailerEntitlements

Reserved for future use

addPolicy

MultiRights only. Add a single policy to the OMI

modifyPolicy

MultiRights only. Modify an existing policy

removePolicy

MultiRights only. Remove a policy from the OMI

getPolicy

MultiRights only. Return the data structure for a specified policy

getPolicyList

MultiRights only. Return a list of policy data structures greater than or equal to the specified policy ID

Messaging Service

IPTV and DVB only. The Messaging Service (MessagingService) provides functionality to send messages to devices on a network. These messages are addressable to a specific device, a group of devices, or all devices on a network. A MessageEntity contains specific addressing parameters that determine how a message request should be processed.

There are three types of messages:

Viewer messages which are for the subscriber and typically appear on the screen of the device.

Device messages which are for the device itself and trigger device functions such as a configuration change or a data request.

CA-subsystem messages which are addressed to the CA-subsystem operating in the device and trigger functions provided by the CA-subsystem.

Typically, subscribers are not aware of the device receiving and executing device and CA-subsystem messages.

The Messaging Service defines the following Web service messages.

Messaging Service APIs

API CALL

DESCRIPTION

generateOSM

IPTV and DVB. Create a generic on-screen message (OSM) for a particular device.

generatePackageOSM

DVB only. Create an OSM for a particular device to be displayed if the device has an active entitlement for the specified package.

deleteOSM

DVB only. Delete an OSM for a particular device.

diagnoseOSM

DVB only. Create a diagnostic OSM for a particular device to be displayed when events in a particular package are viewed.

generateDeviceCommand

IPTV only. Create a command message for a device.

preloadMessage

DVB only. Load a message into a device.

removePreloadedMessage

DVB only. Remove a previously loaded message from a device.

generatePreloadedOSM

IPTV and DVB. Create an on-screen message from a

PROD-336 VCAS: OMI Integration Guide

Page 27

API CALL

DESCRIPTION

 

preloaded message.

generatePreloadedPackageO

DVB only. Create an on-screen message from a preloaded message to be displayed if the device has an active entitlement for the specified package.

SM

Chapter 2

Integrating with the OMI

This section provides an overview of the API calls that are needed to perform a basic integration with the OMI. Details for ingesting specific types of content and managing devices are provided in Implementing Specific Use Cases (on page 41).

1. Before sending any API calls to the OMI, you must sign on to the OMI.

The signOn() call authenticates the user with the OMI, starts a session, and returns a session handle that must be included in all subsequent OMI API calls for the given session. A user can sign onto the OMI multiple times using the same username/password (UserLoginAttributes).

For more detailed information on the signOn() call, refer to "signOn" in PROD- 300 VCAS: OMI API Reference.

A session is limited by two timeouts:

An inactivity timeout that ends the session if the user does not interact with the OMI for the time period specified by the timeout.

A maximum session timeout that ends the session after the specified time period elapses after signing on.

A session also ends when the associated user signs off of the OMI.

The security functions behind the sign on process, including username/password and session management, are set up using the Admin GUI. An OMI user should have been configured during initial installation and configuration of VCAS. For details, refer to PROD-00 VCAS: Installation Guide.

2. After VCAS installation and initialization, the first action you perform is defining the initial network(s). This process only needs to occur one time, when you initially configure your system. Additional networks can be added at a later date as you expand your offering to support distribution to new devices.

Note

Only the first "super user" interaction with the OMI performs this action. All subsequent users should use a query call to request a network list (see below) and perform a simple verification on the list to confirm that network setup has been performed correctly.

The following diagram illustrates the general API call flow for adding network(s) to the OMI.

Figure 4: Adding Network(s) to the OMI For examples of the addnetwork() for specific networks,

Figure 4: Adding Network(s) to the OMI

For examples of the addnetwork() for specific networks, see Defining Networks (on page 41) and the topic "addNetwork" in PROD-300 VCAS: OMI API Reference.

3. Once the network(s) are defined, you can start adding other entities such as content, events, and packages to the OMI

The first of these entities to add is content. The addContent() call adds one or more content items to the OMI. This call does not actually add the actual physical content to the OMI, but rather adds references to the content within the OMI so subscriber entitlements can be generated. At this point the content is added to the OMI, but it is not associated to any network.

The addContentToNetwork() call associates a content item to a network (one call for every network to which you want to add the content).

Once the desired content is added to the OMI and to the desired network(s), use the addEvents() call to create events that define the availability period for the content, for a specific network. You can add events to multiple networks within a single call. You must create an event for each content item or the content item cannot be entitled to a subscriber.

Once you have defined the necessary events, use the addPackages() call to create groupings of events that can then be entitled to subscribers.

The following diagram illustrates the API flow for adding content and creating the events and packages that are necessary to create entitlements against those entities.

Note: You only need to call signOn() if your session has expired.

Figure 5: Adding Content to the OMI For more detail on the add content, events,

Figure 5: Adding Content to the OMI

For more detail on the add content, events, and packages calls, refer to the associated sections in Implementing Specific Use Cases (on page 41) and the associated API call details in PROD-300 VCAS: OMI API Reference.

4. Once the content entities are established, you can start adding subscriber devices (addDevices()) and the entitlements for those devices (addEntitlements()). Similar to content, devices are also associated to a network. If a device should be able to access content from multiple networks, you must add that device to each network for which it is able to access content. You can add a device to multiple networks with a single addDevices() call.

Optionally, if your system is configured for grouping of devices, you will also need to define a domain for the device group (addDomains()) and then associate the devices to the domain (addDomainDevices()).

The following diagram illustrates the OMI API call flow when adding devices and domains and then assigning entitlements to those devices/domains.

and then assigning entitlements to those devices/domains. Figure 6: Adding Devices and Entitlements to the OMI

Figure 6: Adding Devices and Entitlements to the OMI

For more information on the add devices, domains, and entitlements calls, refer to the associated sections in Implementing Specific Use Cases (on page 41) and the associated API call details in PROD-300 VCAS: OMI API Reference.

APIs Available for Each Network

The following tables map the OMI operations to their corresponding supported networks and describe any associated network or parameter dependencies. A check mark () indicates the OMI operation is supported, while a dash (—) indicates it is not supported.

Administration Management Service

API

 

NETWORKS

 

NOTES

DVB

IPTV

INTERNET

MULTI

 

TV

RIGHTS

signOn

signOff

addUser

getUser

modifyUser

removeUser

getUserList

getUserEventList

modifyPassword

modifyUserPassword

getUserSecurity

modifyUserSecurity

Configuration Management Service

API

NETWORKS

 

Notes

 

DVB

IPTV

INTERNET

MULTI

 

TV

RIGHTS

addNetwork

modifyNetwork

removeNetwork

getNetworkList

getNetworkDeviceList

getNetworkContentList

getDeviceTypeLicenseData

getGroupLicenseData

getLicenseGroups

getSystemAttributes

Only the noteAttributeTyp e VERSION and LICENSE parameters are currently supported.

Content Management Service

API

 

NETWORKS

 

NOTES

DVB

IPTV

INTERNET

MULTI

 

TV

RIGHTS

addContent

addContentToNetwork

API

 

NETWORKS

 

NOTES

DVB

IPTV

INTERNET

MULTI

 

TV

RIGHTS

modifyContentOnNetwork

For MultiRights networks cannot modify the ENCRYPTION_ALGOR ITHM or ENCRYPTION_TYPE parameters.

removeContent

addEvents

removeContentFromNetwork

removeEvents

getContentList

getContentEvents

getContentOnNetwork

getNetworkContentTypeEncry

VOD content only.

ptionStatus

getNetworkContentIdList

For Internet TV and MultiRights networks

 

this call only returns a subset of the network values:

smsNetworkId,

smsContentId,

networkContentId

,

networkContentTy

pe.

See PROD-300 VCAS: OMI API Reference for more details.

getNetworkContentEncryptio

VOD content only

nStatus

Device Management Service

API

 

NETWORKS

 

NOTES

DVB

IPTV

INTERNET

MULTI

 

TV

RIGHTS

addDevices

modifyDevices

removeDevices

enableDevices

disableDevices

getDevice

For DVB, only a subset of values is returned:

 

smsDeviceId,

smsNetworkId,

deviceType,

networkDeviceId.

getDeviceList

For DVB, only a subset of values is returned:

 

smsDeviceId,

smsNetworkId,

deviceType,

networkDeviceId.

getNetworkDeviceIdList

IPTV returns all values; all other networks return a minimal subset of values:

 

smsDeviceId,

smsNetworkId,

deviceType,

networkDeviceId.

clearDevices

API

 

NETWORKS

 

NOTES

DVB

IPTV

INTERNET

MULTI

 

TV

RIGHTS

refreshDeviceEntitlements

verifyDevice

resetDevicePins

setDevicePins

refreshDeviceKeys

setDevicePurse

Applies only to smartcard devices.

joinDevices

unjoinDevices

addDevicePair

Applies only to smartcard devices and base DVB STB devices.

removeDevicePair

Applies only to smartcard devices and base DVB STB devices.

removeSmartCardDevicePairi

Applies only to smartcard devices and base DVB STB devices.

ng

removeSTBDevicePairing

Applies only to smartcard devices and base DVB STB devices.

checkDevicePair

Applies only to smartcard devices and base DVB STB

API

 

NETWORKS

 

NOTES

DVB

IPTV

INTERNET

MULTI

 

TV

RIGHTS

 

devices.

getSmartCardPairing

Applies only to smartcard devices and base DVB STB devices.

getSTBPairing

Applies only to smartcard devices and base DVB STB devices.

Domain Management Service

API

 

NETWORKS

 

NOTES

DVB

IPTV

INTERNET

MULTI

 

TV

RIGHTS

addDomains

modifyDomains

removeDomains

addDomainDevices

modifyDomainDevices

removeDomainDevices

getDomainList

getDomainDeviceList

getDeviceDomainList

Entitlement Management Service

API

 

NETWORKS

 

NOTES

DVB

IPTV

INTERNET

MULTI

 

TV

RIGHTS

addPackages

modifyPackages

removePackages

getPackageList

getPackageEvents

getEventPackages