DECE Coordinator API Specification Inter… · dece coordinator api specification (draft) dece...

DECE Confidential

DECE Coordinator API Specification Version 0.13925

DECE COORDINATOR API SPECIFICATION(DRAFT)

DECE Coordinator API Specification

Working Group: Technical Working Group

THE DECE CONSORTIUM ON BEHALF OF ITSELF AND ITS MEMBERS MAKES NO

REPRESENTATION OR WARRANTY, EXPRESS OR IMPLIED, CONCERNING THE

COMPLETENESS, ACCURACY, OR APPLICABILITY OF ANY INFORMATION

CONTAINED IN THIS SPECIFICATION. THE DECE CONSORTIUM, FOR ITSELF

AND THE MEMBERS, DISCLAIM ALL LIABILITY OF ANY KIND WHATSOEVER,

EXPRESS OR IMPLIED, ARISING OR RESULTING FROM THE RELIANCE OR USE

BY ANY PARTY OF THIS SPECIFICATION OR ANY INFORMATION CONTAINED

HEREIN. THE DECE CONSORTIUM ON BEHALF OF ITSELF AND ITS MEMBERS

MAKES NO REPRESENTATIONS CONCERNING THE APPLICABILITY OF ANY

PATENT, COPYRIGHT OR OTHER PROPRIETARY RIGHT OF A THIRD PARTY TO

THIS SPECIFICATION OR ITS USE, AND THE RECEIPT OR ANY USE OF THIS

SPECIFICATION OR ITS CONTENTS DOES NOT IN ANY WAY CREATE BY

IMPLICATION, ESTOPPEL OR OTHERWISE, ANY LICENSE OR RIGHT TO OR

UNDER ANY DECE CONSORTIUM MEMBER COMPANY’S PATENT, COPYRIGHT,

TRADEMARK OR TRADE SECRET RIGHTS WHICH ARE OR MAY BE ASSOCIATED

WITH THE IDEAS, TECHNIQUES, CONCEPTS OR EXPRESSIONS CONTAINED

HEREIN.

DECE Confidential 7-Apr-15 | P a g e 2


DRAFT: SUBJECT TO CHANGE WITHOUT NOTICE© 2009

Revision History

Version Date By Description0.04 Alex

Deacon1st distributed version

0.042 3/24/09 Craig Seidel

Added identifier section


Added new sections 8 and 11. Old sections 8 and 9 are 9 and 10 respectively.


Updated to match DECE Technical Specification Parental Controls v0.5


Removed Section 9 (redundant with 8)


Made various corrections. Added Stream messages as example. There may still be some inconsistencies between the schema and the document.

0.069-0.070

4/16/09 Craig Seidel et al

Incorporated Steam from Hank and Chris, and reorganized document. Updated table from Alex.


Move things around so each section is more self-contained

0.077 5/20/09 Craig Seidel, Ton Kalker

Cleaned up identifiers, bundles and other constructs. Added ISO Burning. Changed name of doc.


Same as 0.077 but with changes incorporated.


Extracted metadata to separate spec. Updated streamsAdded Account management, standard response definitions. Fixed bundle.


Finished 1st draft of Rights

0.092-.096 Craig Seidel

Lots of changes. (tracked)

0.100 Craig Seidel

Baseline without changes tracked

0.102 9/4 Craig Seidel

Adminstrative: Put data after functions. Fixed organization.

0.103-106 9/4-9/7 Craig Seidel

Updated Bundles and ID Mapping

0.107-0.111

9/8 Craig Seidel

Added login information, Added metadata functions, variety of fixes.

0.114-115 9/18- Craig Seidel

Added linked LASP, partial node management, a few corrections

116 9/25 Craig Changed namespace: om: to dece:



Seidel117 9/25 Craig

SeidelAdded Node functions

118-118 9/27 Craig Seidel

Finished LLASP binding and Rights Locker opt-in. [CHS: not sure this belongs in account. Possibly goes to Rights Locker and Stream sections.]

-121 9/29 Craig Seidel

Added a bit on license, started adding DRM

0.122 9/23 Craig Seidel

1st pass at DRM Client complete

0.125 9/30 Craig Seidel, Alex Deacon

Lots of fixes. Incorporated Alex’s authentication material.


“Accepted changes” for whole document—clean start.


Partial fix to account. Incorporated Hank’s comments (biggest changes in Rights Locker)


Updated some DRM/Device info.


Updated bundle to incorporate Compound Objects from metadata spec.

0.139 11/17/09 Suneel Marthi

Updated 2.4 and 5.0



TODO List:

• Sections

o License (explain how it works): TBD?

o Authentication functions (especially login): Alex?

o Need Burn info : Jim T?

• Other

o Write “How it works from ecosystem standpoint” intro to each section.

o Add priv level for all User accessible API’s.

o Fix function summaries (deleted for now)

o Test interfaces (assume this is a byproduct of Node authorization, test Nodes

access a different database.)

o Interfaces for initial load of system, particularly metadata. Is this in scope?

o Customer Support APIs



Contents

Document Description..................................................................................................................7Communications Security..........................................................................................................12DECE API Overview..................................................................................................................35Identifiers...................................................................................................................................36Login.......................................................................................................................................... 46Assets: Metadata, ID Mapping and Bundles..............................................................................51Rights........................................................................................................................................ 65License Acquisition....................................................................................................................81Domain and DRMClient.............................................................................................................82Stream....................................................................................................................................... 93Node/Account Bind Functions..................................................................................................102Account....................................................................................................................................110User and User Group...............................................................................................................125Device Interface.......................................................................................................................149Other........................................................................................................................................150Error......................................................................................................................................... 151Caching and Subscriptions......................................................................................................153



Document Description

1.1 Scope

This document describes the Coordinator data model and API.

It is envisioned that the Coordinator implementer will make changes to this specification to

improve implementability and to provide a better interface to other Roles.

The APIs are written in terms of other Roles, such as DSPs, LASPs, Retailers, Content

Providers, User Interface and Customer Support. User Interface and Customer Support are

part of the broader definition of Coordinator, an therefore APIs are designed to model behavior

rather than to specify implementation. [CHS: I’m currently removing CS and will figure out what

to do with UI next.]

1.2 Document Conventions

1.3 Document Organization

This document is organized as follows:

• Introduction—Provides background, scope and conventions

• [TBS]

1.4 Document Notation and Conventions

1.4.1 Notations

[CHS: I’m reluctant to put this in here because it’s mostly redundant given this is an API spec..

Ultimately, this should be a web-based resource and this formal language would be

inappropriate. Anyhow, it’s not strictly followed in this spec, so on way or another it needs to be

addressed.]

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”,

“SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be

interpreted as described in [RFC2119]. That is:

“MUST”, “REQUIRED” or “SHALL”, mean that the definition is an absolute requirement of the specification.

“MUST NOT” or “SHALL NOT” means that the definition is an absolute prohibition of the specification.



“SHOULD” or “RECOMMENDED” mean that there may be valid reasons to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.

“SHOULD NOT” or “NOT RECOMMENDED” mean that there may be valid reasons when the particular behavior is acceptable, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.

“MAY” or “OPTIONAL” mean the item is truly optional, however a preferred implementation may be specified for OPTIONAL features to improve interoperability.

Terms defined to have a specific meaning within this specification will be capitalized, e.g.

“Track”, and should be interpreted with their general meaning if not capitalized.

Normative key words are written in all caps, e.g. “SHALL”

1.4.2 XML Conventions

XML is used extensively in this document to describe data. It does not necessarily imply that

actual data exchanged will be in XML. For example, JSON may be used equivalently. It is

currently TBD what data format will be used and how it will be documented going forward.

This document uses tables to define XML structure. These tables may combine multiple

elements and attributes in a single table. Although this does not align with schema structure, it

is much more readable and hence easier to review and to implement.

Although the tables are less exact than XSD, the tables should not conflict with the schema.

Such contradictions should be noted as errors and corrected.

1.4.2.1 Naming Conventions

This section describes naming conventions for DECE OMC XML attributes, element and other

named entities. The conventions are as follows:

• Names use initial caps, as in InitialCaps.

• Elements begin with a capital letter, as in InitialCapitalElement.

• Attributes begin with a lowercase letter, as in InitiaLowercaseAttribute.



• XML structures are formatted as Courier New, such as dece:rightstoken

• Names of both simple and complex types are followed with “-type”

1.4.2.2 General Structure of Element Table

Each section begins with an information introduction. For example, “The Bin Element describes

the unique case information assigned to the notice.”

This is followed by a table with the following structure.

The headings are

• Element—the name of the element.

• Attribute—the name of the attribute

• Definition—a descriptive definition. The definition may define conditions of usage or

other constraints.

• Value—the format of the attribute or element. Value may be an XML type (e.g., “string”)

or a reference to another element description (e.g., “See Bar Element”). Annotations for

limits or enumerations may be included (e.g.,” int [0..100]” to indicate an XML int type

with an accepted range from 1 to 100 inclusively)

The 1st header of the table is the element being defined here. This is followed by attributes of

this element. Then it is followed by child elements. All child elements must be included.

Simple child elements may be full defined here (e.g., “Title” , “ “, “Title of work”, “string”), or

described fully elsewhere (“POC”, “ “, “Person to contact in case there is a problem”, “See POC

Element”). In this example, if POC was to be defined by a complex type would be handled

defined in place (“POC”, “ “, “Person to contact in case there is a problem”, “POC Complex

Type”)

Optional elements and attributes are shown in italics.

Following the table is as much normative explanation as appropriate to fully define the element.

Examples and other informative descriptive text may follow.

1.5 Normative References

DECE Architecture

DECE Metadata Specification



DECE Coordinator XML Schema

DECE Metadata XML Schema

[CHS: Various rights and policies]

[RFC4646] Philips, A, et al, RFC 4646, Tags for Identifying Languages, IETF, September, 2006.

http://www.ietf.org/rfc/rfc4646.txt

[RFC4647] Philips, A, et al, RFC 4647, Matching of Language Tags, IETF, September, 2006.


[RFC4346]

RFC3986 – http://tools.ietf.org/html/rfc3986

RFC 3987 – http://tools.ietf.org/html/rfc3987

[RFC5280]

[ISO8601] ISO 8601:2000 Second Edition, Representation of dates and times, second edition,

2000-12-15.

[RFC2119]

[ISO639] ISO 639-2 Registration Authority, Library of Congress.

http://www.loc.gov/standards/iso639-2

[ISO3166-1] Codes for the representation of names of countries and their subdivisions -- Part 1:

Country codes, 2007. [CHS: not sure if we want 2006 version or 2007 Corrigenda]

[ISO3166-2] ISO 3166-2:2007Codes for the representation of names of countries and their

subdivisions -- Part 2: Country subdivision code

1.6 Informative References

• [TBS]

1.7 General Notes

All time are UTM unless otherwise stated.

An unspecified cardinality (“Card.”) is “1”.


http://www.loc.gov/standards/iso639-2%20

http://tools.ietf.org/html/rfc3987





1.8 Customer Support Considerations

The Customer Support (CS) APIs are not defined as Customer Support is current defined as an

integral function to the Coordinator.

However, the data models include provisions for element management. For example, most

elements contain a ‘Status’ element defined as “dece:ElementStatus-type”. This determines the

current state of the element (active, deleted, suspended or other) as well as history of changes.

These are included to allow required behavior to be specified.

If CS becomes an external Role, then APIs will need to be defined to implement this behavior.



Communications Security

As much of the data in the DECE ecosystem is sensitive and private in nature all

communications between entities in the architecture must ensure data privacy, integrity and

end-point authenticity. There are two major styles of communication defined. The first are the

communications between non-Coordinator Nodes (e.g. Retailers, LASPs, DSPs) and the

Coordinator. The second are the communications between the User, or devices on behalf of

the User, and the DECE hosted User Interface associated with the Coordinator. 1

This section defines a secure communications framework that includes details on the proper

identification, authentication, authorization and end-to-end messaging protocols. The

framework is based on the use of the TLS [RFC4346] protocol and further defines specifics on

identification and authorization using industry standard security technologies. At a high level the

TLS protocol enables a client and server to communicate across an insecure network and has

been designed to prevent eavesdropping, tampering, and message forgery of communications

while also providing for end point authentication and encryption.

1.9 Authentication

Accurate and secure identification and authentication of DECE Nodes and DECE Users is

required to ensure controlled access to all DECE resources and data.

1.9.1 Node Authentication

Nodes MUST be identified via a TLS server certificate issued by a DECE approved Certificate

Authority as defined in Section Error: Reference source not found. The certificate MUST

conform to [RFC 5280].

The identity and the fully qualified domain name (FQDN) of the organization associated with the

owner of the Node MUST be included in the certificates Subject Distinguished Name (DN) and

at a minimum MUST contain the following DN attributes:

• Common Name (CN): <FQDN of the server associated with the Node>

• Organization (OU): <Registered Business name of the organization>

• Country (C): <Country of organization>

1 Note that communication between the User and the Retailer and communication between the

Retailer or LASP and DSP are out of scope of this specification.



Additional identifying Subject DN attributes, such as the Organizational Unit (OU), State (ST),

and Locality (L) MAY be included.

[AD: Suggest we agree on the EV Cert profile as defined by cabforum.org]

1.9.1.1 DECE Approved Certificate Authorities

All nodes MUST obtain an Extended Validation [www.cabforum.org] TLS server certificate from

an approved EV CA.

[CA list TBD – Ideally we would point to a CABForum page that listed these CA’s]

1.9.2 User Authentication

Users MUST be identified by a unique username and password pair managed by the

Coordinator. The username MUST be an email address that is not already associated with

another DECE User. Email addresses must be validated. [CHS: This is assumed to be an

email to a User with a link to confirm.]

Coordinator managed passwords must be defined using best practices for security. A set of

rules might contain:

• MUST contain both upper and lower case characters (e.g., a-z, A-Z)

• MUST be at least eight (8) alphanumeric characters long

• MUST include at a minimum one numeric character (e.g. 0-9)

• MAY include the following non-alpha numeric characters - !@#$%^&*()_+|~-=\`{}

[]:";'<>?,./)

• MUST NOT be based on personal information or information associated with the Users

Account (e.g. First name, last name, username, the account friendly name, etc.)2

1.10Node Authentication and Authorization

Once properly identified and authenticated, entities must be authorized to ensure and enable

access to sensitive information based on the DECE authorization policies. As with

2 [SANS Password Policy - http://www.sans.org/resources/policies/Password_Policy.pdf]



authentication, this specification defines different methods to authorize DECE Nodes and DECE

Users.

1.10.1 Node Authentication

[CHS: We recently changed the model, but the document has not been updated. Nodes must

be authenticated, however, once authenticated the Node’s Roles are used to determine

functions that may be performed by the Node.]

1.10.2 Node Authorization

Node authorization is enabled by an access control list implied by Role structure called a Role

Assertion. The Role Assertion is a statement by the DECE Role Authority that a particular entity

implementing the functionality behaves according to the normative definition of a specific Role.

A Node is said to posses a given Role if the DECE Role Authority has asserted that the Node

has the given Role as an attributein the Coordinator database. Typically, the DECE Role

Authority makes the assertion based on a demonstration that the Node implementation:

• Complies to a technical specification for that Role, including interfaces exposed or

invoked and events published or consumed

• Satisfies compliance and robustness requirements defined for that Role by an

Ecosystem.

1.10.2.1 The Role Assertion

Once approved all Nodes will be assigned a DECE identifier by the DECE Naming Authority, as

defined in <Section X.X>. This identifier will be mapped to a Fully Qualified Domain Name

(FQDN) that is present in the associated Node certificate. The mapping between the identifiers

and FQDNs is be managed by the Coordinator. The list of approved Nodes creates an inclusion

list that the Coordinator MUST use to authorize access to all Coordinator resources and data.

Access to any Coordinator interface by a DSP or LASPNode whose identity is not on the

inclusion MUST be rejected.

The Role Assertion is defined by the following XML

[XML TBD. CHS: There might be something useful in NodeInfo-type.]



1.10.2.2 Including the Role Assertion in the TLS Message

[Details TBD]

Role Assertions are included in all intra-node communications.

1.10.2.3 Validating the Role Assertion

Upon receipt of an incoming request from a Node, the receiving Node must first authenticate the

Nodes identity (e.g., the node certificate) and once authenticated then ascertain that the Node is

properly authorized by validating the signature on the role assertion and ensuring that the Node

identity in the role assertion matches the identity of the Node making the request.

1.11User Authorization

Once properly authenticated via their username and password, DECE Users are authorized to

access DECE data and services based on two authorization attributes:

First, each User is assigned an authorization level. The ecosystem defines the following three

authorization levels

• Basic-Access User:

o May associate their Retail accounts with their Account.

o May view content associated with their Rights Locker in accordance with their parental control settings.

• Controlled-Access User:

o Inherits all Basic-Access User permissions.

o May initiate an authenticated Dynamic LASP Session.

o May add or remove Users for their User Group.

o May add or remove Devices for their Domain.

• Full-Access User:

o Inherits all Controlled-Access User permissions.

o May set the Privilege Level for each User in their User Group.

o May set the Parental Control Level for each User in their User Group.

o May associate or disassociate a Linked LASP Account with their Account.

Second, each User is assigned a set of parental control settings

1) Their authorization level a defined in Section Error: Reference source not found; and



2) Their parental control settings as described in Section Error: Reference source not

found.

1.12 User Delegated Authorization

There are many scenarios where a DECE Node, such as a Retailer or LASP, is interacting with

the Coordinator on behalf of a User. In order to properly control access to user data while

providing a simple yet secure experience for the user authorization will be explicitly delegated

by the user to the node using the OAuth [OAuth] protocol.

[Lots of OAuth details here]

1.13User Delegated Authorization

There are many scenarios where a DECE Node, such as a Retailer or LASP, is interacting with

the Coordinator on behalf of a User. In order to properly control access to user data while

providing a simple yet secure experience for the user authorization will be explicitly delegated

by the user to the node using the OAuth [OAuth] protocol.

1.13.1 OAuth Protocol

The OAuth protocol enables websites or applications (Consumers) to access Protected

Resources from a web service (Service Provider) via an API, without requiring Users to disclose

their Service Provider credentials to the Consumers.

An example use case is allowing a DECE Retailer (the Consumer), to access the RightsLocker

for a DECE account stored on the Coordinator (the Service Provider) without requiring Users to

provide their Coordinator credentials to the Retailer.

OAuth does not require a specific user interface or interaction pattern, nor does it specify how

Service Providers authenticate Users, making the protocol ideally suited for cases where

authentication credentials are unavailable to the Consumer.

1.13.2 OAuth Protocol Definitions

• Service Provider: DECE Coordinator that allows access via OAuth.

• User: An individual who has an account with the Coordinator.

• Consumer: A Retailer or LASP that uses OAuth to access the Coordinator on behalf of

the User.



• Protected Resource(s): Data controlled by the Coordinator, which a Retailer or LASP

can access through authentication.

• Consumer Key: A value used by the Retailer/LASP to identify itself to the Coordinator.

• Consumer Secret: A secret used by the Retailer/LASP to establish ownership of the

Consumer Key. This would the Private Key assigned to the Consumer by a DECE

approved Certificate Authority when using RSA-SHA1 signature mechanism.

• Request Token: A value used by the Retailer/LASP to obtain authorization from the

User, and exchanged for an Access Token.

• Access Token: A value used by the Retailer/LASP to gain access to the Protected

Resources on behalf of the User, instead of using the User's Coordinator credentials.

• Token Secret: A secret used by the Retailer/LASP to establish ownership of a given

Token (only if using HMAC-SHA1 signature method). This would not be applicable when

using RSA-SHA1 signature method.

1.13.3 DECE OAuth Protocol Extensions

The following parameters would be implemented as part of Coordinator Service Provider in

addition to the OAuth Protocol parameters outlined in Section [REF]:

• Token Scope: the Coordinator resource or URI the Retailer/LASP (Consumer) wants

access to.

• Token UserId: The ID the user has used to log into the Retailer/LASP. This would be

used for binding the user’s Retailer account to the Coordinator Account.

PreConditions:

The Retailer/LASP (Consumer) would need to register with the Coordinator and must be issued

a TLS server certificate issued by a DECE approved Certificate Authority.

1.13.4 Assumptions

• A Request Token is valid for upto 1 hour (or any time as defined by Coordinator policy)

for it to be exchanged with an Access Token.

• An Access Token is valid for up to 24 hrs (to be determined by policy) before it expires.



• An Access Token can only be used to access the resource defined by the scope of the

access token and the ParentalControl Rights of the user who has authorized the token.

1.13.5 OAuth Endpoint URLs:

Coordinator (Service Provider) would need to specify the below 3 endpoint URLs to the Retailer

to acquire an OAuth Access token:

• Request Token URL – This is the URL that a Consumer would invoke for fetching an

unauthorized Request token.

• User Authorization URL – The URL used to obtain User authorization for Consumer

access and for authorizing the Request Token fetched via the previous URL

• Access Token URL: The URL used to exchange the User-authorized Request Token

with an Access Token.

1.13.6 OAuth Authorization Process:

• The Consumer makes a signed request to fetch an initial OAuth Request Token.

• The Service Provider returns an unauthorized OAuth Request Token.

• The Consumer redirects the User to the appropriate OAuthAuthorizeToken URL.

• The User authorizes the Request Token and is

• The User authorizes the Request Token and is redirected by the Consumer to the

callback URL that is specified.

• The Consumer sends a signed request to exchange the Authorized Request Token for

an Access Token.

• The Consumer uses the Access Token to access the protected resources on the

Coordinator.

• The scope of the Access Token determines the resources on Coordinator that are

accessible to the Consumer.

The OAuth Service Provider would be implemented as part of the Coordinator interface and

exposes the endpoint URLs (see Section [REF]) for OAuth Authorization.



1.13.7 Fetching a Request Token

PreConditions:

• User has successfully logged into the Retailer (Consumer).

• Consumer is registered with DECE Coordinator and has a TLS server certificate issued

by a DECE approved Certificate Authority.

Behavior:

The Consumer makes a HTTP POST request to the Request Token endpoint URL specified in

Section 2.4.1.5 and includes the following required parameters in the request OAuth HTTP

Authorization Header. This would be a signed request (as described in Section [REF]) using

RSA-SHA1 signature method. The following parameters need to be in the Authorization Header

of the HTTP POST request to fetch a Request Token.

Parameter Description

oauth_consumer_key (required) key used by the Consumer to register with Coordinator

oauth_nonce_(required) unique string that is generated by Jersey REST API for every request that is made

oauth_signature_method

(required) this would be ‘RSA-SHA1’ for DECE

oauth_timestamp(required) is a unique integer and expressed in number of milliseconds since Jan 1, 1970

oauth_version (optional) defaults to the value ‘1.0’

dece_oauth_scope(required) URL for the protected resource on the Service Provider that the Consumer wants to access.

oauth_signature(required) string generated using the reference signature method (See Signing Requests in Section 2.4.1.10 below)

dece_oauth_userId

(required) id used by the User to sign into the Consumer and would be bound to the Users’ Coordinator account when the access token is granted.

oauth_callback(required) URL that the Service Provider redirects the User to following User Request Token Authorization.

Example below puts them in the Authorization header.



authorization=OAuth oauth_signature="ofcSo4D79lz3WkK1FzUY5wKQUng%3D", oauth_nonce="95bc0287-8b16-4756-a74d-9f568424375d", oauth_signature_method="RSA-SHA1", oauth_consumer_key="verisign", dece_scope_url=" http%3A%2F%2Flocalhost%3A9090%2FDeceOauth%2Fphoto", oauth_timestamp="1257792017"

Request Token Response:

If the request for a request token is successful, Coordinator responds with an HTTP 200 OK

message containing an OAuth request token and a token "secret" in the response body. In

addition the Coordinator (Service Provider) would also return an

oauth_callback_confirmed=true. This is to confirm to the Consumer that the Coordinator has

received the callback value.

A token request may be rejected by the Coordinator if the request is malformed. If the request is

not successful, Coordinator returns the following error:

• HTTP 400 Bad Request: in the case of an unsupported or missing parameter, an

unsupported oauth_signature_method, or other error in the request format or content.

Sample response

Below is an example of an OAuth request token returned in the response body. At this point, the

request token cannot be used to request data from the Coordinator; it must be authorized by the

Coordinator Authorization service.

oauth_token=9d8269aa080948cda8db623275fe0642&oauth_token_secret= e79cc465ec6b476680b952930a05d2b5&oauth_callback_confirmed=true

The request token that’s been returned is unauthorized and needs to be authorized by the user

before it can be exchanged for an access token.

1.13.8 Request Token Authorization

PreConditions:

An unauthorized Request Token has been successfully fetched (see Section [REF])

Behavior:

(i) Consumer directs the User to the Coordinator

In order for the Consumer to be able to exchange the Request Token for an Access Token, the

Consumer must obtain approval from the User by directing the User to the Coordinator. The



Consumer constructs an HTTP GET request to the Coordinator's User Authorization URL

(specified in Section [REF]) with the following parameters:

oauth_token: The Request Token obtained in Section [REF].

Once the request URL has been constructed the Consumer redirects the User to the URL via

the User's web browser.

(ii) Coordinator authenticates the User and obtains consent to authorize the

Request token

Coordinator verifies the User's identity and asks for consent as detailed below:

• Coordinator first verifies the User's identity before asking for consent by asking the User

to sign into Coordinator.

• Coordinator presents to the User information about the Consumer requesting access.

The information includes the Protected Resources the Consumer wants access to, and

the User’s Id on the Consumer (for Binding).

• The User must grant or deny permission for the Coordinator to give the Consumer

access to the Protected Resources on behalf of the User. If the User denies the

Consumer access, Coordinator will not allow access to the Protected Resources.

(iii) Coordinator directs the User back to the Consumer:

After the User authenticates with the Coordinator and grants permission for Consumer access,

the Consumer is notified that the Request Token has been authorized and ready to be

exchanged for an Access Token. If the User denies access, the Consumer will be notified that

the Request Token has been revoked.

To make sure that the User granting access is the same User returning back to the Consumer

to complete the process, the Coordinator would generate a verification code which is an un-

guessable value passed to the Consumer via the User and is REQUIRED to complete the

process.

If the Consumer provided a callback URL (using the oauth_callback parameter specified in

Section 2.4.1.7), the Coordinator uses it to constructs an HTTP request, and directs the User's

web browser to that URL with the following parameters added:

oauth_token: The Request Token the User authorized or denied.

oauth_verifier: The verification code.



dece_oauth_userId: Id used by the user to sign into the Consumer (for Binding).

This is returned unmodified back to the Consumer.

Below is a sample request for Request Token Authorization:

GET

http://localhost:9090/DeceOAuth/authorizeToken?oauth_token=9d8269aa080948cda8db623275fe0642&dece_oauth_userId=testUser

Below is a sample response that is returned when the User authorizes a Request token and a

callback URL has been provided:

http://localhost:9090/DeceOAuth/index.jsp?oauth_token=9d8269aa080948cda8db623275fe0642&oauth_verifier=a6f6b70605b748af8baf4cad5359bdbe

1.13.9 Fetching an Access Token

PreConditions:

• User has successfully logged into the Retailer (Consumer).

• User has authorized a Request Token obtained by the Consumer (see Sections 2.4.1.7

and 2.4.1.8) which is ready to be exchanged for an Access Token.

Behavior:

The Consumer makes a HTTP POST request to the Access Token endpoint URL specified in

Section 2.4.1.4 and includes the following required parameters in the request OAuth HTTP

Authorization Header. This would be a signed request (as described in Section 2.4.1.10) using

RSA-SHA1 signature method. The following parameters need to be in HTTP headers to fetch

an access token:

Parameter Description

oauth_consumer_key (required) key used by the Consumer to register with Coordinator

oauth_nonce_(required) unique string that is generated by Jersey REST API for every request that is made

oauth_signature_method (required) would be ‘RSA-SHA1’ for DECE






oauth_timestamp (required) is a unique integer and expressed in number of milliseconds since Jan 1, 1970

oauth_version (optional) defaults to the value ‘1.0’

oauth_signature(required) string generated using the reference signature method (See Signing Requests in Section 2.4.1.10 below)

dece_oauth_userId(required) id used by the User to sign into the Consumer and would be bound to the Users’ Coordinator account when the access token is granted.

oauth_token(required) the Request token authorized by the User during ‘Authorizing a Request Token’ step (see Section 2.4.1.8)

oauth_verifier(required) the Verifier string returned during Request Token Authorization (see Section 2.4.1.8)

Below is a Sample Request for fetching an Access Token:

authorization=OAuth oauth_token="9d8269aa080948cda8db623275fe0642", oauth_signature="Z8K0f4GbT1BM17EuIWdNXwLmfoY%3D", oauth_nonce="9b4f586c-e123-4aba-a402-99186c45e2e1", oauth_signature_method="RSA-SHA1", oauth_consumer_key="verisign", oauth_timestamp="1257875297", oauth_verifier=" a6f6b70605b748af8baf4cad5359bdbe ", dece_oauth_userId="testUser"

Access Token Response:

If the request for an access token is successful, Coordinator responds with an HTTP 200 OK

message containing an OAuth access token.

A token request may be rejected by the Coordinator if the request is malformed. If the request is

not successful, Coordinator returns the following error:

• HTTP 400 Bad Request: in the case of an unsupported or missing parameter, an

unsupported oauth_signature_method, or the request token has not been authorized.

Sample response

Below is an example of an OAuth access token returned in the response body. At this point, the

access token can be used to request data from the Coordinator.

oauth_token=9d8269aa080948cda8db623275fe0642

The request token that’s been returned is unauthorized and needs to be authorized by the user

before it can be exchanged for an access token.



1.13.10 Signing OAuth requests

All calls requesting or using an OAuth token must be signed. This includes calls to

<BaseURL>/dece/requestToken,, <BaseURL>/dece/accessToken, and all requests made to

Coordinator resources. This section describes how a signature is generated for the requests.

The OAuth extension that is part of the Jersey REST API supports all of the 2 signature

mechanisms viz. PLAINTEXT, HMAC-SHA1 and RSA-SHA1. It also does normalization of the

Request Parameters as specified in Section 9.1.1 of the OAuth Core1.0 Revision A specification

(http://oauth.net/core/1.0a#sig_norm_param).

Each request must specify the signature method in use (oauth_signature_method). For DECE,

this would always be ‘RSA-SHA1’. All consumers must have been registered with the

Coordinator and must have been issued a TLS security certificate by a DECE approved

Certificate Authority.

• Construct a signature "base string", which consists of a concatenation of three request

elements:

o The HTTP request method.

o The base URL the request is being sent to.

o A normalized string of the parameters in the request (excluding the

oauth_signature parameter). This includes parameters sent in the request header

or body, as well as query parameters added to the request URL. To normalize

the string, the parameters are sorted using lexicographical byte value ordering.

• Generate an oauth _signature using one of the following sequences:

o Use the private key corresponding to the certificate issued by a DECE approved

Certificate Authority during registration with Coordinator.

1.13.11 Nonce and Timestamp

A nonce is a random string, uniquely generated for each request. The Coordinator (Service

Provider) would need to validate the Nonce values to ensure that a nonce value has not

previously been used to avoid replay attacks on the Service Provider. The Service Provider

would need to maintain a repository of all nonces and the timestamp when they were issued to

check if a nonce value had been used before.



1.14End to End Message Security

[This ties all of the above together.]

A single interaction between DECE nodes consists of a synchronous messaging roundtrip (one

request and one response) between a requesting node and a responding node that exposes a

DECE-defined interface. All interfaces defined by the Ecosystem are based on REST [REST]

principals. All messages pass through a secure communications layer designed to protect and

deliver each message.

As shown in Error: Reference source not found, the application layer functionality provided by

the node, together with the secure communication layer components, comprise a node. Nodes

in DECE rely on standard networking infrastructure for delivery of messages; the DECE layers

simply add DECE specific trust and security properties.

Communication between all nodes MUST use client and server authenticated TLS [RFC4346].

All communication between the User and the Coordinator MUST be over server authenticated

TLS [RFC4346].

Users MUST be authenticated using HTTP Basic Auth [RFC2617].

End-to-end message confidentiality and integrity functions are provided by the use of TLS [TLS].



Intra-node communication is based on mutually authenticated TLS using node certificates plus

the addition of the Role Assertion The requesting node asserts its identity and the responding

node verifies that (a) the identity is asserted by a mutually trusted naming authority, (b) that the

roles asserted in the authorization layer were asserted about the node identified, and (c) that the

communication provably originates from the node asserting its identity.

All communications between the DECE User and the DECE UI role is protected by server-side

TLS authentication and HTTP Basic Authentication of the user.

1.15Resource Oriented API (REST)

The DECE Services are resource oriented HTTP services. All requests to the service target a

specific resource with a fixed set of requests methods. The set of methods supported by a

specific resource depends on the resource being requested and the identity of the requestor.

1.16Terminology

Resources – Data entities that are the subject of a request submitted to the server. Every http

message received by the service is a request for the service to perform a specific action

(defined by the method header) on a specific resource (identified by the URI path)

Resource Identifiers – All resources in the DECE ecosystem can be identified using a URI3 or

an IRI4. Before making requests to the service, clients supporting IRIs should convert them to

URIs as per Section 3.1 of the IRI RFC. When an IRI is used to identify a resource, that IRI and

the URI that it maps to are considered to refer to the same resource.

Resource Groups – A Resource template defines a parameterized resource identifier that

identifies a group of resources usually of the same “type”. Resources within the same resource

group generally have the same semantics: same set of methods, same authorization rules,

same supported query parameters etc.

1.17Resource Requests

For all requests that cannot be mapped to a resource group, a 404 status code will be returned

in the response. Requests that map to a resource group but not to a valid resource based on

resource identifier will also result in a 404 response code. But the

3 RFC3986 – http://tools.ietf.org/html/rfc39864 RFC 3987 – http://tools.ietf.org/html/rfc3987





If a request is received for a method that the resource does not allow, a response code of 405

will be returned. In compliance with the HTTP RFC, the server will also include an “Allow”

header.

Authorization rules can be defined for each method in a resource group. If a request is received

that requires authorization the server will return a 401 response code. If the client is already

authenticated and the request is not permitted for the principal identified by the authentication

header, the server will also return a 401.

1.18Queries

Some resources will support or require query strings in the request. A query string implies a

filtering of a request based on a set of parameters and will generally be applied to resources

that represent multiple items. The method in the request will apply to the subset of items

selected by the query string.

Although the HTTP specification specifies the query string as an open string, query strings are

generally a of name value pair collection encoded using “application/x-www-form-urlencoded”

as defined in the HTML 4.01 specification5. Except where it is impractical, DECE will use this

encoding. In situations where Unicode characters need to be encoded, the definition in the

HTML 5 specification6 for UTF-8 character encoding will be used.

Query string variable names and valid value syntax will be defined for resources that support or

require them. If the query string contains data that is malformed either according to the

encoding rules above or according to syntax rules defined for values, a 400 response code will

be returned.

1.19Conditional Requests

DECE servers SHOULD support strong entity tags as defined in Section 3.1 of the HTTP/1.1

RFC. Servers must also support conditional request headers for use with entity tags (If-Match

and If-None-Match). Since none of the DECE web services have use range headers, the

If-Range header is not needed. These headers provide clients with a reliable way to avoid lost

updates and provide clients with an ability to perform “strong” cache validation.

Clients can (and are strongly encouraged to) use unreserved-checkout7 mechanisms to avoid

lost updates. This means:

5 http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.16 http://www.w3.org/TR/html5/forms.html#application-x-www-form-urlencoded-encoding-algorithm7 http://www.w3.org/1999/04/Editing/


http://www.w3.org/1999/04/Editing/

http://www.w3.org/TR/html5/forms.html#application-x-www-form-urlencoded-encoding-algorithm

http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1


• Using the If-None-Match header with GET requests and sending the entity tags of

any representations already in the client’s cache. For intermediary proxies that support

HTTP/1.1, clients should also send the Vary: If-None-Match header. The client

should handle 304 responses by using the copy indicated in its cache.

• Using If-None-Match: * when creating new resources, using If-Match with an

appropriate entity tag when editing resources and handling the 412 status code by

notifying users of the conflicts and providing them with options.

1.20Request Throttling

Requests from Non-Node clients in DECE are subject to rate limits. The rate limits will be

sufficiently high enough to not require well-behaved clients to implement internal throttling

however clients that don’t cache any data and consistently circumvent the cache with cache-

busting techniques may find themselves limited. In this case, clients will receive a 503 response

with a Reason-Phrase of “request-limit-exceeded”.

1.21Request Methods

The following methods are supported by DECE resources. Most resources support HEAD and

GET requests but not all resources support PUT, POST or DELETE. DECE servers do not

support the OPTIONS method

1.21.1 HEAD

To support cache validation in the presence of HTTP 1.0 proxy servers, all DECE resources

should support HEAD requests.

1.21.2 GET

A request with the GET method returns a representation of that resource. If the URL is not

recognized for any reason, a response code of 404 is returned. If the representation has not

changed and the request contained conditional headers supported by the server, a 304

response might be returned.

DECE does not currently support or require long-running GET requests that might need to

return a 202 response.



1.21.3 PUT and POST

PUT is used to create a resource or update a resource by completely replacing its definition.

POST is used to “add” or “append” to a resource. POST is sometimes also used to update a

resource without replacing its definitions. In general, a PUT request will be used in cases where

a client has control over the resulting resource URI. An example of this is when creating USER

accounts. A POST request is used when the resource being created is a subordinate resource

of another resource.

If the request results in a resource creation, the status code returned should be 201 otherwise

the status code should be 200 or 204. If the request does not require a response body the client

should be prepared to receive 204 as a status code.

The structure and encoding of the request depends on the resource. If the content-type is not

supported for that resource, the server will return a 415 status code. If the structure is invalid, a

status code of 400 will be returned. The server MUST return an explanation of the reason the

request is being rejected however this is not an explanation intended for end-users, clients that

receive 400 status codes should log them and treat them as bugs in either the client or the

server.

1.21.4 DELETE

The server will support the DELETE method on resources that can be deleted.

Sending the DELETE request might not necessarily delete the resource immediately in which

case the server will respond with a 202 response code (An example would be a delete that

required some other action or confirmation before removal). In compliance with the HTTP RFC,

the use of the 202 response code should also provide users with a way to track the status of the

delete request.

1.22Request Encodings

DECE services will support the same set of request encodings supported in response

messages, json and XML. The requested response content-type needn’t be the same as the

request content-type. For various resources, DECE Services may choose to broaden the set of

accepted request formats to suit additional clients. This will not necessarily change the set of

supported response types.8

8 An example of an additional request encoding that might end up being supported is multipart/form-data which is defined in the HTML 4.01 specification (http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2)





1.23Coordinator REST URL

For this version (1.0) of the specification the base URL for all API’s is

[baseURL] = https://<dece.domainname.com>/rest/v/1/0

All requests MUST include the Content-Type header with a value of “application/xml”.

<Hoop will find some text to add here regarding encoding of POSTS (utf8, url-encoding, etc?)>

1.24DECE Response Format

All responses are structured to include a choice of either success data or error data.

Generally, these are the form of a choice between an Error element defined as

dece:ResponseError-type or a response specific to that request. Error information is provided in

the section [REF] Errors.

In the case where there is no data provided in the response, the ResponseStandard element

SHALL be used.

Element Attribute Definition Value Card.

ResponseStandard

Success UNDEFINED xs:string (choice)

Error Error information dece:ResponseError-type

(choice)

If an HTTP status code other than 200 is returned, the system SHALL NOT return either

Success a response specific element.

[CHS: Does it make sense to return a success element and nothing else? Isn’t HTTP status

code 200 sufficient?]

1.25HTTP Status Codes

All responses from DECE servers will contain HTTP1.1 compliant status codes. This section

details intended meaning for these status codes and recommended client behavior.



1.25.1 Informational (1xx)

The current version of the service has no need to support informational status requests for any

of its resource types or resource groups.

1.25.2 Successful (2xx)

200 OK – This response message means the request was successfully received and

processed. For requests that changed the state of some resource on the server, the client can

safely assume that the change has been committed.

201 Created – For requests that result in the creation of a new resource, clients should expect

this response code instead of a 200 to indicate successful creation of the resource. The

response message MUST also contain a Location header field indicating the URL for the

created resource. In compliance with the HTTP specification, if the request requires further

processing or interaction to fully create the resource, a 202 response will be returned instead.

202 Accepted – This response code will be used in situations where the request has been

received but is not yet complete. This code will be sent by the server in response to any request

that is part of a workflow that is not immediate or not automated. Examples of situations where

this response code would be used are adding or deleting a device from a DECE account. All

DECE resource groups that will use this response code for a specific method will indicate this in

their description. In each case, a separate URL will be specified that can be used to determine

the status of the request.

203 Non-Authoritative Information – DECE will not return this header but it may be returned

by intermediary proxies

204 No Content – Clients should treat this response code the same as a 200 without a

response body. There may be updated headers but there will not be a body.

205 Reset Content – DECE doesn’t have a need for these response codes in its services.

206 Partial Content – DECE doesn’t use Range header fields in its metadata service

definitions.

1.25.3 Redirection (3xx)

Redirection status codes indicate that the client should visit another URL to obtain a valid

response for the request. W3C guidelines recommend designing URLs that don’t need changing

and thus don’t need redirection.

300 Multiple Choices – There are no plans to use this response code in DECE services



301 Moved Permanently – This response code will only be used for future versioning in DECE

services. It should not be returned in the current version.

302 Found – DECE will not use this response code instead, code 303 and 307 will be used to

respond to redirections if necessary

303 See Other, 307 Temporary Redirect – There are no current needs for moved resource

URIs DECE services. Clients wishing to be future proof should support these codes regardless.

304 Not Modified – Clients making conditional requests should handle this status code to

support caching of responses.

305 Use Proxy – If DECE chooses to use edge caching then unauthorized requests to the

origin servers might result in this status code. Clients should accessing DECE resources

through the documented URLs should not need to handle this code.

1.25.4 Client Error (4xx)

400 Bad Request – These errors are returned whenever the client sends a request that targets

a valid URI path but that cannot be processed due to malformed query string, header values or

body content. 400 requests can indicate syntactic or semantic issues with the request. A 400

error generally indicates a bug in a client or a server. The server MUST include a description of

the issue in the response body and the client should log the report. This description is not

intended to be end-user actionable and should be used to submit a support issue.

401 Unauthorized – A 401 request means a client is not authorized to access that resource.

The authorization rules around resources should be clear enough so that clients should not

need to make requests to resources they do not have permission to access and clients should

not make requests to resources that require an authorization header without providing one.

Since permissions can change over time it’s still possible for a 401 to be received as a result of

a race condition.

402 Payment Required, 403 Forbidden – These codes are not used by DECE.

404 Not Found – This code means that the resource targeted by the request is not understood

by the server.

405 Method Not Supported – This code is returned along with an Allows header when clients

make a request with a method that is not allowed. This status code indicates a bug in either the

client or the server implementation.

406 Not Acceptable – DECE will not respond with this response code. As is permitted by the



407 Proxy Authentication Required – The client does not

408 Request Timeout – The server might return this code in response to a request that took

too long to send. Clients should be prepared to respond to this although given the small payload

size of DECE request bodies, it is unlikely.

409 Conflict – For PUT, POST and DELETE requests,

410 Gone – DECE may choose to support this status code for resources that can be deleted.

After deleting a resource, a response code of 410 can be sent to indicate that the resource is no

longer available. While this is preferable to a status code of 404, it is not necessarily guaranteed

to be used.

411 Length Required, 416 Requested Range Not Satisfiable – DECE does not have any

need for range request header fields in its metadata APIs so there is no need to support these

codes.

412 Precondition Failed – This response should only be received when client send conditional

PUT, POST or DELETE requests to the server. Clients should notify the user of the conflict and

depending on the nature of the request, provide the user with options to resolve the conflict.

413 Request Entity Too Large, 414 Request-URI Too Long – DECE has no need for either of

these codes at the moment. There are no large request bodies or URI definitions defined in the

DECE service.

415 Unsupported Media Type – If the content-type header of the request is not understood,

this code will be returned by the server. This indicates a bug in the client.

417 Expectation Failed – DECE has no current need for this status code

1.25.5 Server Errors (5xx)

When the DECE service is unable to process a client request due to conditions on the server

side, there are various codes used to communicate this to the client. Additionally DECE will

provide a status log on a separate host that can be used to indicate service status.

500 Internal Server Error – If the server is unable to respond to a request for internal reasons,

this

501 Not Implemented – If the server does not recognize the requested method type, it may

return this response code. This is not returned for not supported method types. It is only

returned for unrecognized method types. Or for method types that are not supported at any

resource.



503 Service Unavailable - This response will be returned during planned service downtime.

The length of the downtime (if known) will be returned in a “Retry-After” header. A 503 code

might also be returned if a client exceeds request-limits (throttling).

502 Bad Gateway, 504 Gateway Timeout – The DECE service will not reply to responses with

this status code directly however clients should be prepared to handle a response with these

codes from intermediary proxies.

505 HTTP Version Not Supported – Clients that make requests with HTTP versions other than

1.1 may receive this message. DECE may change its response to this message in future

versions of the service but since the version number is part of the request, this will not affect

implementers of this specification.

1.26Bulk Requests

[CHS: Need to define how to make requests for multiple items (e.g., 1st 10 rights tokens, next 10

rights tokens, etc.]



DECE API Overview

[TBS]

This section defines the interfaces used in the DECE Architecture.

<New Interface Diagram based on Ton’s TBD>

Figure 1 - Interface Diagram

The following sections are organized via Roles. API’s listed in each section indicate which Role

is authorized to invoke the API at the Coordinator.



Identifiers

DECE requires the use of multiple types of identifiers. In most cases, the only requirement for

identifiers is that they be unique within DECE ecosystem. That is, two objects exchanged by

DECE components using DECE interfaces with only use the same ID if they refer to the same

entity. IDs often must be persistent. That is, the identified entity will always be referred to by

the same identifier.

1.27DECE Identifier Structure

DECE identifiers use the general structure of the “urn:” URI scheme as discussed in RFC 3986

(URN) and RFC 3305 with a “dece” namespace identifier (NID). However, for DECE, rather

than the fully articulated “urn:dece” we abbreviate to “dece:”. The basic structure for a DECE ID

is

<DECEID> ::= “dece:”<type>”:”<scheme>”:”<SSID>

• <type> is the type of identifier. These are defined in sections throughout the document

defining specific identifiers.

• <scheme> is either a DECE recognized naming scheme (e.g., “ISAN”) or “org:” non-

standard naming. These are specific to ID type and are therefore discussed in sections

addressing IDs of each type.

• <SSID> (scheme specific ID) is a string that corresponds with IDs in scheme <scheme>.

For example, if the scheme is “ISAN” then the <SSID> would be an ISAN number.

There is a special case where <scheme> is “org”. This means that the ID is assigned by a

recognized DECE organization within their own naming conventions. If <scheme> is “org” then

<SSID> ::= <organization><UID>

• <organization> is a name assigned by DECE to an organization.

• <UID> is a unique identifier assigned by the organization identified in <organization>.

Organizations may use any naming convention as long as it complies with RFC 3986

syntax.

When DECE assigns identifiers, <organization> is DECE and an ID would have the form:

“dece:”<type>”:org:dece”<UID>



Some sample identifiers are

• Organization ID: dece:org:org:dece:MYCOMPANY -- Note that this is an organization

defined ID with DECE being the assigning organization

• Content ID: dece:alid:ISAN:000000018947000000000000

• Content ID: dece:alid:org:MYSTUDIO:12345ABCDEF

o id-type Simple Type

The simple type dece:id-type is the basic type for all IDs. It is XML type xs:anyURI

All identifiers are case sensitive.

1.28ID Types and Assignment

1.28.1 Internal Coordinator Managed/Assigned Identifiers

Identifiers of this type are assigned by the Coordinator and represent a unique entity/resource

within the Ecosystem. These identifiers are used to build the Path value defined for each

interface.

1.28.2 Ecosystem Assigned Identifiers

These identifiers are manually assigned by DECE. That is, DECE administrative personnel

explicitly assign them in accordance with rules here and DECE policies. DRM and Profile

Identifiers will be assigned based on which DRM and profile are approved for use in the

Ecosystem. Retail, LASP and DSP identifiers uniquely identify organizations who have

executed the corresponding license agreements.

1.28.3 Content Identifiers

These are assigned by the content provider. These must be unique throughout the ecosystem.

1.28.4 ID Assignment

The following table shows the ID and their assignment method: Coordinator, Ecosystem or

Content

Category ID <type> Assignment

Organization/Role



Organization N/A Ecosystem

Role N/A Ecosystem

User/Account

AccountID accountid Coordinator

UserGroupID usergroupid Coordinator

UserID userid Coordinator

RightsLockerID rightslockerid Coordinator

RightsTokenID rightstokenid Coordinator

BurnRequestID burnrequestid Coordinator

StreamID streamid Coordinator

ProfileID profileid Coordinator

DRM/Device/Domain

DomainID domainid Coordinator

DRMClientID drmclientid Coordinator (Domain manager)

Content

AssetLogicalID alid Content Provider

AssetPhysicalID apid Content Provider

ContentID cid Content Provider

BundleID bid Content Provider

1.29Organization and Role Identifiers

This sections describes identifies associated with Organizations and Roles as defined

<<<reference>>>.

1.29.1 Organization IDs

Organizations are identified uniquely. These IDs are assigned as part of an organization

entering the DECE ecosystem.

IDs are two or more characters and numbers. They are case sensitive.

For example, “MyCompany” and “Best4You” are examples of Organizational ID.

Organizational IDs are used along with “org:” for other types of identifiers. For example:

dece:alid:MyCompany:ABCDEFG

Organization IDs are also used as part of Role IDs. For example,



dece:lasp:MyCompany

1.29.2 Role IDs

Role IDs have the form

“dece:”<role>“:”<organization ID>

• <role> is their role in the ecosystem: as listed under Role Identifiers [REF]

• <organization ID> is the organization’s assigned name as descrbed above.

For example,

dece:cp:MyCompany

1.30User and Account-related Identifiers

All these IDs are assigned by the Coordinator. <type> shall be in conformance with Table xyz

(above). The <ssid> of these IDs is at the discretion of the Coordinator. They must be unique

throughout the ecosystem.

• AccountID

• UserGroupID

• UserID

• RightsLockerID

• RightsTokenID

• BurnRequestID

• StreamHandle (specific to Account)

1.31Device and DRM Identifiers

• DomainID

• DRMClientID



1.31.1 DRM Name and DRM ID

A DRM name is a DECE assigned name for each DRM. That is, for each DRM, the name

comes from the following table: [CHS: Table will be defined once DRMs are approved.]

DRM DRM name

TBS

dece:drmID-type is a simple type that is of the form:

‘dece:drm:’<approved DRM name>

• where <approved DRM name> is from the table above .

1.31.2 DomainID

DomainIDs identify a Domain within for a given DRM.

DomainIDs are of the form

<Approved DRM name>:<DRM-specific Domain ID>

• <Approved DRM name> is a DRM Name

• <DRM-specific Domain ID> is a UTF-8 string whose form specific to the DRM.

1.31.3 DRMClientID

DRMClientIDs identify a DRM Client within one Domain.

DRMClientIDs are of the form

<Approved DRM name>:<DRM-specific DRMClient ID>

• <Approved DRM name> is a DRM Name

• <DRM-specific DRMClient ID> is a UTF-8 encodable string whose form is

specific to the DRM

1.32Content Identifiers

Content Identifiers are assigned by Content Providers, independent of the Coordinator.

However, they must be globally unique within the DECE ecosystem. The following scheme

provides flexibility in naming while maintaining uniqueness.



1.32.1 Asset Identifiers

DECE maintains several types of asset identifiers:

• An Asset Logical Identifier (ALID) denotes an abstract representation of a content item.

An ALID is referred to in a Rights Token, indicating the media object for which rights

have been obtained.

• Asset Physical Identifier (APID) refers to a physical entity (i.e., a Common Container)

that is associated with a logical asset. The APID is structured to be included in the

container. An APID is sufficient identification for a DRM system to determine a license

[CHS: is this true?]

The following describes the [current] assumptions for relationships between ALIDs, APIDs and

file names. If the assumptions change, the naming rules may also change

• An ALID is referred to in a Rights Token as the media object for which rights have been

obtained.

• The actual right is a ALID/profile pair.

• An ALID explicitly refers to one or more physical assets. That is, ALIDs map to one or

more APIDs.

• An ALID is retrievable from an APID for the purpose of rights verification.

1.32.1.1 ALID

Syntax: dece:alid:<scheme>:<SSID>

The following restrictions apply to the <scheme> and <SSID> part of an ALID:

• An ALID scheme may not contain the colon character

• An ALID SSID may have a colon character

• <ALID scheme> and <ALID SSID> shall be in accordance with the following table

Scheme Expected value for <SSID>

ISAN An <ISAN> element, as specified in ISO15706-2 Annex D.

UUID A UUID in the form 8-4-4-4-12



Scheme Expected value for <SSID>

URI A URI; this allows compatibility with TVAnytime and MPEG-21

Grid A Global Release identifier for a music video; exactly 18 alphanumeric characters

ISRC International Standard Recording Code for music videos; exactly 12 alphanumeric characters

Coral A Coral <Resource> element, as specified in Coral Core Architecture Specification, Version 4.0, §2.5.3

ISBN An ISBN, ISO 2108, http://www.isbn-international.org <<<we can draw from here for XML: http://www.xfront.com/isbn.html >>>

ISSN Serials. ISO 3297:1998.

ISTC Textual works. ISO 21047

ISMN Printed music, ISO 10957, http://ismn-international.org/

ISRC Master recordings, ISO 3901, http://www.ifpi.org/content/section_resources/isrc.html

ISWC Musical Works, http://www.cisac.org

Org <SSID> begins with the Organization ID of the assigning organization and follows with a string of characters that provides a unique identifier. The <ssid> must conform to RFC 2141 with respect to valid characters.

[CHS: This list is not comprehensive. Please provide other identifiers that are applicable to

DECE.]

1.32.1.2 APID

Syntax: dece:apid:<ALID scheme>:<ALID SSID>:<APID SSID>

Each APID is associated with an ALID and is derived from that ALID. An APID can easily be

parsed to retrieve the associated ALID. An APID is constrained as follows:

• Each APID is globally unique

• <ALID scheme> matches the scheme from the associated ALID

• <ALID SSID> matches the SSID from the associated ALID


http://www.cisac.org/

http://www.ifpi.org/content/section_resources/isrc.html

http://ismn-international.org/

http://www.xfront.com/isbn.html

http://www.isbn-international.org/


• <APID SSID> may not contain a colon character

o This constraint guarantees that the <APID SSID> can be parsed as the suffix of

an APID.

For example:

• ALID: dece:alid:org:MyCompany:ABCDEFG

APID: dece:apid:org:MyCompany:ABCDEFG:100

invalid APID: dece:apid:org:MyCompany:ABCDEFG:100:2 (extra colon)

• ALID: dece:alid:ISAN:000000018947000000000000

APID: dece:apid:ISAN:000000018947000000000000:A203

1.32.2 CID

Syntax: dece:cid:<scheme>:<ssid>

A CID points to Controller-required metadata. Each ALID must have an associated CID. CIDs

are not necessarily associated with an ALID. CIDs may refer to items such as shows or

seasons, even if there is no single asset for that entity.

1.32.3 Bundle Identifiers

Syntax: dece:bid:<org-id>:<ssid>

A bundle is either a logical asset or group of bundles. A bundle is represented as tree where the

leaves of the tree are logical assets. Each bundle has an associated CID, but only the leaves of

a bundle correspond to an APID. Bundles are typically defined by retailers. There are no

standard identifiers for bundles: the scheme type of a bundle must be “org” (see Section 1.34.1.)

Example:

• BID: dece:bid:org:MyCompany:1234ABC567

1.33Role Identifiers

DECE defines numerous roles:

• Controller (formerly OMC)

• Retailer



• LASP. LASPs comes as Dynamic LASPs or Linked LASPs. For the purposes of

identification, they are unique

• DSP

• DRMClient

In addition to these roles, the ecosystem has pseudo-roles. These need to be identified, but

they are extensions of the Controller:

• CS—Customer Support

• UI—User Interface to Controller. [CHS: This will subdivide into UI-Web and UI-other, but

not quite yet.]

• Metadata – Metadata provider. [CHS: At the moment, this doesn’t appear in the

document, but it probably should.]

The naming for roles is as follows:

dece:role:<role>

Syntax: dece:role:<role>

The <role> element corresponds to a DECE defined role as indicated in the table below:

Role <role>

ControllerCoordinat

or

cdtr

Retailer rtr

Linked LASP llp

Dynamic LASP dlp

DSP dsp

DRM Client cnt

Customer Support csp

User Interface usi

Example

• Dynamic LASP dece:role:dlp



1.34ID Types

IDs are defined in Section 7.

All id types are based on the simple type id-type which is xs:string.

Most IDs are described in the sections in which they apply (e.g., AccountID-type under Account)

1.34.1 OrgID types

ID types are

• dece:orgID-type: <any organization>. The value must be a DECE defined

organization

• dece:coordID-type: <An organization that is a Coordinator>. There is currently only

one Coordinator, but this included for symmetry. It also allows for a future distributed for

federated Coordinator model.

• dece:dspID-type:< an organization that is a DSP>

• dece:laspID-type: <an organization that is a LASP>

• dece:retailerID-type: <an organization that is a retailer>



Login

1.35Overview

Most APIs assume actions are being taken on behalf of a user. Except where noted, all account

actions require a valid login or actions SHALL not be allowed.

The Login mechanism is different depending on which entity is accessing Coordinator/UI

functions.

1.35.1 Nodes

Users provide credentials directly to Coordinator. The Node does not have access to the

credentials.

The User logs into the Coordinator in the context of a communication with a Node. Subsequent

communications with that Node are assumed to be on behalf of that User until either the session

is complete or the User logs off. [CHS: Need to better define sessions. What prevents Node

from action on behalf of the User indefinitely?]

The specific mechanism is not yet defined.

[CHS: Leaning towards OAuth, but needs to be worked out (Action: Alex)]

1.35.2 Web UI and Device Interface

The Web UI incorporates a typical web login process. The mechanism for login is HTTP Basic

Authentication. Note that communications with Users are TLS secured.

Devices that use a browser for Users to communicate with the Web UI use the same

mechanism.

Devices that use the Web Services Interface (i.e., REST) establish a secure channel using TLS

and use HTTP Basic Authentication to authenticate users. [CHS: I am assuming devices may

cache passwords, but we should probably say something explicitly in the Device Spec.]

1.36Login Functions

Function Name Path Method Roles Comments



1.37Overview

Most APIs assume actions are being taken on behalf of a user. Except where noted, all account

actions require a valid login or actions SHALL not be allowed.

The Login mechanism is different depending on which entity is accessing Coordinator/UI

functions.

1.37.1 Nodes

Nodes can access the Coordinator resources on behalf of a user using the OAuth Authorization

Protocol. This has been covered in detail in Section 2.4 (OAuth Protocol) of this document.

The steps involved in the OAuth authorization are:-

a) Node needs access to a protected resource in the Coordinator on behalf of a User and

makes a request to fetch a Request Token from the Coordinator.

b) Coordinator issues an unauthorized Request Token to the Node.

c) Node redirects the User to the Service Provider to authorize the Request Token.

d) User logs into the Coordinator by providing the user credentials and is redirected to an

authorization URL by the Coordinator where the User can either grant or deny access to the

Node.

e) When the User grants access to the Node, the unauthorized Request Token from (b) above

is marked as authorized by Coordinator.

f) Node then exchanges the Authorized Request token for an Access Token with the

Coordinator.

g) Node can then access the Coordinator protected resources on behalf of the user using this

access token.

Throughout the whole process as outlined above, the User would never have to share his

Coordinator credentials with the Node. An access token would be valid indefinitely (or a time

period as specified by Coordinator policy). A Node could reuse an Access Token to access the

protected resources indefinitely until either the token expires or the User revokes the token (this

would remove the binding between the user’s account in Coordinator and the user’s account on

the Node).

For subsequent access to the protected resources by the Node, the Node needs to provide the

access token to the Coordinator. Coordinator needs to ensure that the access token provided



by the Node is valid and the scope of the token is the specified resource that the Node is trying

to access.

If the access token has expired, Coordinator would display an appropriate message (like

‘Token Invalid’) with a HTTP response Status of 400 (Bad Request) to the Node.

If the scope of the access token is not the resource that the node wants to access, Coordinator

would display an appropriate message to the Node (like ‘Invalid Scope’) and return a HTTP

response status of 403 (Forbidden).

1.37.2 Web Portal and Device Portal Interface s

The Web Portal incorporates a typical web login process. The mechanism for login is HTTP

Basic Authentication. Note that communications with Users are TLS secured.

Devices that use a browser for Users to communicate with the Web UI use the same

mechanism.

Devices that use the Web Services Interface (i.e., REST) establish a secure channel using TLS

and use HTTP Basic Authentication to authenticate users.

To support BasicAuth, the Portal must use the Login function to the Coordinator.

[CHS: It’s not clear how access between the Portal and the Coordinator are controlled. Suneel

is investigating using a one time use OAuth for this interface in symmetry with other Roles.

Login() would then include the creation of the OAuth token whose lifespan would be until a

logou() occurs.]

1.38Login Functions

Function Name Path Method Roles Comments

Login() <BaseURL>/login?username=<username>&password=<password>

GET UI

Logout() <BaseURL>/logout?username-<username> GET UI

1.39Login()

Path: [BaseURL]/login?username=<username>&password=<password>

Method: GET



Roles: UI

Behavior:

User is trying to login to the Coordinator from the UI. The mechanism for login is HTTP Basic

Authentication.

a) The User presents his credentials in the UI.

b) UI would make a REST call to the Path specified appending the User’s credentials as

query parameters.

c) Coordinator fetches the User Credentials from the query parameters and returns a HTTP

Response code of 200 (OK) if successful or 400 (Bad Request) if the credentials are

invalid.

[Suneel: Not sure if we need to track the login/logout times in the Coordinator, if we do then

the Coordinator would make a record of the User login time.]

1.40Logout()

Path: [BaseURL]/logout?username=<username>

Method: GET

Roles: UI

Behavior:

User wants to logout of his UI session.

a) UI makes a REST call to the Path specified appending the User’s username as a query

parameter.

[Suneel: As is the case for login, if the Coordinator needs to maintain an audit of user

login/logout times then the Coordinator would make a record of the User logout time.]

1.41Login()

[TBD: Alex]



1.42Logout()

[TBD: Alex]



Assets: Metadata, ID Mapping and Bundles

1.43Metadata Functions

Metadata is described in DECE Metadata Specification. Functions to manipulate metadata are

here. All definitions are there.

Descriptive and technical metadata are inherent to Coordinator functions, particularly User

Interface.

It has also been expressed that the DECE architecture should include metadata services.

These are included as part of the broader definition of the Coordinator.

APIs are provided for posting and retrieving metadata. The primary V1 purpose for the

Metadata services is for the DECE User Interface. However, these APIs are available to other

roles as needed.

Metadata is created, updated and deleted by Content Publishers. Metadata may be retrieved

by UI, Retailers, LASPs and DSPs. Note that Devices can get metadata through the Device

Interface.

[CHS: Do we really plan on updating Metadata using REST? It is certainly doable, but it seems

like there should be more of a concept of ‘feed’]

1.43.1 MetadataBasicCreate(), MetadataPhysicalCreate(),

MetadataBasicUpdate(), MetadataPhysicalUpdate()

These functions use the same template. Metadata is either created or updated. Updates

consist of complete replacement of metadata—there is no provision for updating individual child

elements.

1.43.1.1 API Description

These functions all work off the same template. A single ID is provided in the URL and a

structure is returned describing the mapping.

1.43.1.2 API Details

Path:

[BaseURL]/Asset/Metadata/Basic

[BaseURL]/Asset/Metadata/Physical



Method: POST | PUT

Authorized Role(s): Content Publisher

Request Parameters: None

Request Body

Basic


AssetMDBasicCreate-

req

dece:AssetMDBasicData-type

Physical


AssetMDPhyGet-

resp

dece:AssetMDPhyData-type

Response Body: None

1.43.1.3 Behavior

In the case of Create (POST), the entry is added to the database as long as the ID (CID or

APID) is new.

In the case of Update (PUT) the entry matching the ID (CID or APID) exists.

1.43.1.4 Errors

[ID issues]

1.43.2 MetadataBasicGet(), MetadataPhysicalGet()







Path:

[BaseURL]/Asset/Metadata/Basic/{CID}

[BaseURL]/Asset/Metadata/Physical/{APID}

Method: GET

Authorized Role(s): Any?

Request Parameters:

{APID} is an Asset Physical ID

{CID} is a Content Identifier

Request Body: None

Response Body

Basic


AssetMDBasicGet-

resp

BasicMD Metadata dece:AssetMDBasic-type

(choice)

Error Error Response if error dece:ResponeError-type (choice)

Physical


AssetMDPhyGet-

resp

PhysicalMD Mapping dece:AssetMDPhy-type

(choice)



Error Error Response if error dece:ResponeError-type

(choice)

1.43.2.3 Behavior

The metadata that corresponds with the CID or APID is returned.

1.43.2.4 Errors

• Just ID issues

1.43.3 MetadataBasicDelete(), MetadataPhysicalDelete()

Allows Content Publisher to delete Basic and Physical Metadata


These functions all work off the same template. A single ID is provided in the URL and the

identified metadata is flagged as deleted.


Path:

[BaseURL]/Asset/Metadata/Basic/{CID}

[BaseURL]/Asset/Metadata/Physical/{APID}

Method: DELETE

Authorized Role(s): Content Publisher

Request Parameters:

{APID} is an Asset Physical ID

{CID} is a Content Identifier

Request Body: None

Response Body: None



1.43.3.3 Behavior

If metadata exists for the identifier (CID or APID), the identified metadata is flagged as deleted.

1.43.3.4 Errors

[ID issues]

1.44ID Mapping Functions

1.44.1 MapALIDtoAPIDCreate(),MapALIDtoAPIDUpdate()


These function creates a mapping between logical and physical for a given profile


Path:

[BaseURL]/Asset/Map/ALIDToAPID

Method: PUT | POST

Authorized Role(s): Content Provider

Request Parameters:

{Profile} is a profile from AssetProfile-type enumeration

Request Body:


AssetMapALIDtoAPID-

req

LPMap Mapping from Logical to Physical, based on profile

dece:AssetMapLP-type

1..n

Response Body: None



1.44.1.3 Behavior

When a POST is used, a mapping is created as long as the ALID is not already in a mapping for

the given profile.

When a PUT is used, the Coordinator looks for a matching ALID. If there is a match, the

mapping is replaced. If not, a mapping is created.

1.44.1.4 Errors

• POST

o Mapping already exists

• PUT

o Mapping does not already exist

1.44.2 MapALIDtoAPIDGet(), MapAPIDtoALIDGet()





Path:

[BaseURL]/Asset/Map/ALIDToAPID/{Profile}/{ALID}

[BaseURL]/Asset/Map/APIDToALID/{Profile}/{APID}

Method: GET

Authorized Role(s): Any?

Request Parameters:

{Profile} is the profile for which the mapping is indicated

{APID} is an Physical Asset ID

{ALID} is a Logical Asset ID



Request Body: None

Response Body

APID to ALID


AssetMapAPIDtoALID-

resp

LPMap Mapping from ALID to APID dece:AssetMapLC-type

APID to ALID


AssetMapAPIDtoALID-

resp

ALIDs that contain the APID md:AssetLogicalID

1.44.2.3 Behavior

When a POST is used, a Bundle is created. The ID is checked for uniqueness.

When a PUT is used, the Coordinator looks for a matching BundleID. If there is a match, the

Bundle is replaced.

1.44.2.4 Errors

• Mapping doesn’t exist.

1.45Bundle Functions

1.45.1 BundleCreate(), BundleUpdate()


BundleCreate is used to create a Bundle.


Path:



[BaseURL]/Asset/Bundle

Method: POST | PUT

Authorized Role(s): Content Publisher, Retailer?

Request Body

The request body this the same for both Create and Update.


BundleCreate-req dece:Bundle-type

Response Body: None

1.45.1.3 Behavior

When a POST is used, a Bundle is created. The ID is checked for uniqueness.

When a PUT is used, the Coordinator looks for a matching BundleID. If there is a match, the

Bundle is replaced.

1.45.1.4 Errors

Bad or duplicate BundleID.

1.45.2 BundleDelete()


BundleCreate is used to create a Bundle.


Path:

[BaseURL]/Asset/Bundle/{BundleID}

Method: DELETE

Authorized Role(s): Content Publisher, Retailer?

Request Parameters

{BundleID} is the identifier for the bundle to be deleted.



Request Body


BundleCreate-req dece:BundleData-type

Response Body: None

1.45.2.3 Behavior

The Status of the Bundle element is flagged as ‘deleted’.

1.45.2.4 Errors

Bad or nonexistent BundleID.

1.46Metadata

Definitions pertaining to metadata are part of the ‘md’ namespace defined the DECE Metadata

Specification [REF].

1.46.1 AssetMDPhy-type, AssetMDPhyData-type

Common metadata does not use the APID identifier, so this is added for Coordinator APIs

through the following element.


AssetMDPhyData-

type

Physical Metadata md:PAssetMetadata-type

(by extension)

ALID Asset Logical ID dece:AssetLogicalID-type


AssetMDPhy-

type

PhyData ALID Physical Metadata dece:AssetMDPhyDataType

Status Status dece:ElementStatus-type



1.46.2 AssetMDBasic-type, AssetMDBasicData-type


AssetMDBasicData-

type

Physical Metadata md:BasicMetadata-type

(by extension)


AssetMDBasic-

type

BasicData Basic Metadata dece:AssetMDBasicDataType

Status Status dece:ElementStatus-type

1.47Mapping Data

1.47.1 Mapping Logical Assets to Content IDs

Every Logical Asset maps to a single Content ID.

1.47.1.1 AssetMap LCMap -type definition

Mapping ALID to CID. Note that all ALIDs map 1:1 with CIDs.


AssetMapLCMap-

type

Logical Asset to Content ID map

ALID Asset Logical ID dece:AssetLogicalID-type

CID Content ID associated with Logical Asset

dece:ContentD-type



1.47.2 Mapping Logical to Physical Assets

A Logical Identifier maps to one or more Physical Assets for each available profile.

1.47.2.1 AssetMap LPMap -type definition

Map ALID to APID. There may be multiple APIDs associated with an ALID.

APIDs can map to multiple ALIDs, but this mapping is not supported directly.


AssetMapLPMap

-type

Asset logical to physical map

ALID Asset Logical ID for Physical Asset dece:AssetLogicalID-type

Profile Profile for Physical Asset dece:Assetprofile-type

APID ID of physical asset associated with ALID/Profile combination

dece:AssetPhysicalID-type

1..n

1.47.3 AssetKey-type

This element contains decryption information for a Physical Asset.


AssetKey-type

APID Asset Physical ID. dece:AssetPhysicalID-type

KeyInfo Key information in BLOB xs:base64Binary

1.47.3.1 AssetComponentLoc-type

This is a place holder.


AssetLoc-type

Location Location of asset metadata ]CHS: should this be 0..n?]

xs:anyURI 1..n



1.47.3.2 AssetComponentMetadataLoc-type

This is a place holder.


AssetMetadataLoc-

type

Location Location of asset files. xs:anyURI 1..n

1.47.3.3 AssetProfile-type

This simple time is xs:string enumerated to:

• “PD”

• “SD”

• “HD”

• “ISO”

1.48Bundle Data

1.48.1 Bundles

The Bundle defines the context of sale for assets. That is, when constructing a view of the

User’s Rights Locker, a Bundle reference in in the Rights Token provides information about how

the User saw the content when it was purchased. For example, if a User bought a “Best Of”

collection consisting of selected episodes, the Bundle would group the episodes as a “best-of”

group rather than by the conventional season grouping. The Bundle is informational to be used

at the discretion of the User Interface designer.

A bundle consist of a list of Content ID/ALID mappings (dece:AssetMapLC-type) and optionally

information to provide logical grouping to the Bundle in the form of composite objects

(md:CompObj-type).

In its simplest form, the Bundles is one or more CID to ALID mappings along with a BundleID

and a simple textual description. The semantics is that the bundle consists of the rights

associated with the ALID and described by the CIDs in the form of metadata. The Bundle refers

to existing Rights Tokens so there is no need to include Profile information—that information is

already in the token.



A bbundle users the Composite Object mechanism (md:CompObj-tyep) to create is a tree-

structured collection of logical assetsContent Identifiers, optionally with descriptions and

metadata. The Composite Object is defined in DECE Metadata.

The leaves in the tree refer to logical assets and have associated meta-data. An internal node in

the tree has only meta-data that is descriptive for all its children.

An example of a bundle would be a season of an episodic show “Big Sister”. This show has run

for 2 seasons, with the first season containing 25 episodes. The 25 episodes are assets so they

have Logical Asset IDs (ALIDs). All entries, including the show name, have a content ID (CID)

because there is metadata associated with all entries. This example shows that the episodes

are subordinate to the show. It is expected that the Controller will display “Big Sister” first and

allow the user to expand to seasons and episodes.

This allows for display in the context of the purchase. The Controller has the option of extracting

information from metadata for more sophisticated display.

1.48.1.1 Bundle-type definition


BundleData-type

BundleData Data for Bundle dece:BundleData-type

Status Status of element dece:ElementStatus-type



1.48.1.2 BundleData-type definition


BundleData-type

BundleID Unique identifier for bundle dece:BundleID-type

BundleDisplayName Human readable 1-line description of bundle

xs:string

language The language of the DisplayName

xs:language 0..1

Assets List of assets in Bundle dece:AssetMapLC-type 1..n

EntryCompObj Information about each asset component

dece:AssetComponentmd:CompObj-type

1..n

1.48.1.3 BundleEntry-type


BundleEntry-

type

DisplayName Human readable 1-line description of content entry

xs:string

CID Content ID reference (for metadata, etc.)

md:ContentID-type

ALID Asset Logical ID that defines the right included in the bundle. This is at the profile level.

md:AssetLogicalID-type

(choice)

Entry Information about each asset component

dece:AssetComponent-type

(choice)



Rights

1.49Rights Function Summary

[TBS]

1.50Rights Token, Rights Locker and Rights Functions

1.50.1 Behavior for all Rights APIs

Rights Lockers and Rights Tokens are only active if their Status (dece:ElementStatus-

typeCurrentStatus) is ‘active’. Rights lockers and tokens should behave as if they did not

exist for all calls made by all Roles other than Customer Support. For example, a call to retrieve

a rights locker will only return tokens that are active.

1.50.2 RightsTokenCreate


This API is used to add a right to right’s locker.

[CHS: I think the rights locker maps 1:1 with account, so there is no reason to address this at

the rights locker level. I should probably eliminate the RightsLockerID. Thoughts?]


Path:

[BaseURL]/Account/{AccountID}/RightsLocker/RightsToken

Method: POST

Authorized Role(s): Retailer, UI, CS

Request Body


RightsTokenCreate-

req

The request is a fully populated rights token. All required formation SHALL be included in the create request.

dece:RightsTokenData-type

Response Body




RightsTokenCreate-

resp

RightsTokenID If the token was created successfully, this contains the ID for the created rights token.

dece:RightsTokenID-type

(choice)

1.50.2.3 Behavior

This creates a Right for a given Logical Asset and Profile for a given Account. The Rights token

is associated both with the User and with the Retailer.

Once created, the Rights Token SHALL NOT be deleted, only flagged in the Status element

with a CurrentStatus of ‘deleted’. Modifications to the Rights Token SHALL be noted in the

History element of the Status Element.

1.50.2.4 Errors

• Invalid Rights combination [CHS: Need to decide if Coordinator has the rules and

enforces.]

o Invalid HD/SD/PD combination

o Burn rights where not applicable

• Missing or invalid PurchaseInfo

• Missing or invalid LicenseAcqLoc

• Missing or invalid TimeInfo

• Invalid ViewControl

• Unknown or invalid ALID

• Unknown or invalid BundleID

• Unknown or invalid CID



1.50.3 RightsTokenDelete()


This API changes a rights token to an inactive state. It does not actually remove the rights

token, but sets the status element to ‘deleted’.


Path

[BaseURL]/Account/{AccountID}/RightsLocker/RightsToken/{RightsTokenID}

Method: DELETE

Authorized Role(s): Retailer

Request Parameters

• RightsTokenID identifies the rights token being deleted

Request Body: None

Response Body: None

1.50.3.3 Behavior

Status is updated to reflect the deletion of the right. Specifically, the CurrentStatus element

within the Status element is set to ‘deleted’.

1.50.3.4 Errors

1.50.4 RightsDataGet(), RightsSummaryGet()

Rights may be obtained by APID or ALID. Summary only applies to APIDs because the

Summary structures do not support multiple APIDs returned.

If the request comes from a Retailer, the response differs depending on whether the Rights

Token was created by the Retailer making the request. Retailers with opt-in access are

provided only a limited view of the Rights Token.

[CHS: Rename: Summary has more than Data—seems backwards.]

[CHS: Consider expanding Summary to include multiple returns.]




This provides for the retrieval of Rights, as maintained in Rights tokens. This API is designed

for a simple retrieval of whether the User has certain Rights for this asset. RightsSummaryGet

also returns License Acquisition URLs.

Retrieval is constrained by the rights allowed to the retailer and the user who is making the

request. [CHS: Define under behavior]


Path

For rights by ALID

[BaseURL]/Account/{AccountID}/RightsData/ALID/{ALID}

For a rights by APID

[BaseURL]/Account/{AccountID}/Rights[Data|Summary]/APID/{APID}

Method: GET

Authorized Role(s): UIPortal, Retailer, LASP, DSP

Request Parameters:

• APID is an APID for which the requestor wishes to determine rights.

• ALID is an ALID for which the requestor wishes to determine rights.

Request Body: None

Response Body

When getting a rights token RightsTokenGet-resp is returned. When RightsTokenID is

requested, only one Rights Token will be returned. When ALID or APID are used zero or more

may be returned.


RightsDataGet-

resp

RightsData Access rights dece:RightsData-type (choice)



Error Error response on failure. dece:ResponseError-type

(choice)


RightsSummaryTokenGet-

resp

RightsSummary Access rights and license acquisition URLs

dece:RightsSummary-type

(choice)


(choice)

1.50.4.3 Behavior

A request is made for a Rights Token or a Rights Locker.

The request is made on behalf of a User.

Rights Token data is returned with the following conditions:

• Only Rights from Rights Token that are ‘active’ are included in the response

• Rights from Rights tokens not visible to the logged in user based on the

RightsViewControl elements are not included in the response.

• When requesting by ALID, Rights Tokens that contain the ALID for that Account are

included in the response.

• When requesting by APID, the function has the equivalence of mapping APIDs to ALIDs

and then querying by ALID. That is, Rights from Rights Tokens whose ALIDs match the

APID are included in the results.

• If the user has no Rights Token associated with the ALID or APID, the RightsAllowed

fields are all returned to indicate the User has no rights.

• If the user has one Rights Token associated with the ALID or APID, the RightsAllowed

fields are those from the Rights Token.



• If the user has multiple Rights Tokens associated with the ALID or APID, the Rights

Allowed element are the Union of those rights, on a Profile basis. If expressed as a

binary, a ‘true’ in any RightsToken’s RightsAllowed element the corresponding element

in the RightsAllow will be ‘true’. If expressed as an integer, the RightsAllowed element

will be the sum of the Rights Token Elements. For example, if two Rights Tokens exist

and their SD Profile indicates Stream and Download rights are granted, and BurnsLeft

for each is 1, the returned RightsAllowed element will indicate Stream and Download

rights are granted, and BurnsLeft is 2.

1.50.4.4 Errors

• Right locker not active

1.50.5 RightsTokenGet(), RightsLockerGet()

Get function works by TokenID, APID or ALID.


This provides for the retrieval of a Rights Token or a full rights locker.

Retrieval is constrained by the rights allowed to the retailer and the user who is making the

request. [CHS: Define under behavior]


Path

For a rights token by RightsTokenID


For a rights locker:

[BaseURL]/Account/{AccountID}/RightsLocker

For rights tokens by ALID

[BaseURL]/Account/{AccountID}/RightsToken/ALID/{ALID}

For a rights tokens by APID

[BaseURL]/Account/{AccountID}/RightsToken/APID/{APID}



Method: GET

Authorized Role(s): UI, Retailer, LASP, DSP

Request Parameters:

• RightsTokenID is the ID for the Rights Token being requested

• ALID identifies the Logical Asset that is contained in Rights Tokens that are to be

returned

• APID identifies the Physical Asset that corresponds with Logical Assets that in turn

correspond with Logical Assets contained in Rights Tokens that are to be returned

Request Body: None

Response Body

When getting a rights token RightsTokenGet-resp is returned. When RightsTokenID is

requested, only one Rights Token will be returned. When ALID or APID are used zero one or

more may be returned.

RightsData is a choice between RightsTokenData and RightsTokenDataLimited.


RightsTokenGet-resp

RightTokenDataRightsData Rights token data (no administrative data)

dece:RightsTokenData-typechoice of RightsTokenData and RightsTokenDataLimited

(choice with Error))1..n

RightsTokenDataLimited Rights Token data limited for opt-in Retailers and LASPs

dece:RightsTokenDataLimited-type

(choice)

RightsTokenData RightsTokenData dece:RightsTokenData-type (choice)

Error Error response on failure.

dece:ResponseError-type (choice with RightsData)



For a Rights Locker


RightsLockerGet-

resp

RightsLockerData Rights locker data, including a list of Rights Tokens

dece:RightsLockerData-type

(choice)


(choice)

1.50.5.3 Behavior

A request is made for a Rights Token or a Rights Locker.

The request is made on behalf of a User.

Rights Token data is returned with the following conditions:

• Only IDs rights tokens that are ‘active’ are returned.

• Rights tokens not visible to the logged in user based on the RightsViewControl elements

will not be returned.

• When requesting by ALID, Rights Tokens that contain the ALID for that Account are

returned. There may be zero or more

• When requesting by APID, the function has the equivalence of mapping APIDs to ALIDs

and then querying by ALID. That is, Rights Tokens whose ALIDs match the APID are

returned.

• Limited data is returned on Rights Tokens that were created by Retailers other than the

requestor.

1.50.5.4 Errors

• Right locker not active

• Requested rights token does not exist or is inactive.



1.50.6 RightsTokenUpdate()


This API allows selected fields of the Rights Token to be updated. The request looks the same

for each Role, but some updates are ignored for some roles.


Path


Method: PUT

Authorized Role(s): Retailer

Request Parameters None

Request Body


RightsTokenUpdate-

req

The request is fully populated rights token data.

dece:RightsTokenData-type

The update request SHALL match the current contents of the rights token except for the items

being updated..

Customer Support may update any element.

Retailers may only update rights token that were purchased through them (i.e., the RetailerID in

PurchaseInfo matches that retailer). Updates are made on behalf of a user, so only Rights

viewable by that User (i.e., ViewControl includes access rights allowing the User’s UserID) may

be updated by a Retailer.:

• BundleID [CHS: Not sure about this, but since the bundle mostly affects UI it shouldn’t

be too harmful. This might be nice if a bundle is expanded, for example, to include a

whole season.]

• RightsAllowed

• PurchaseInfo [CHS: I’m debating this one because it allows some rewriting of history. It

allows the retailers to fix mistakes without involving the ecosystem. I’m assuming



RetailerID changes are handled at the administration level, but we should talk about

whether this can be handled here. I’m inclined to 1) break it out as its own request, and

2) keep all previous versions {which should typically be none}.]

• ViewControl. If ViewControl does include the User who is currently logged in to make

this request, no modifications may be made to ViewControl.

If changes are made in fields for which changes are not allowed, no changes are made and an

error is returned.

Response Body: None

1.50.6.3 Behavior

The Rights token is updated. This is a complete replacement, so the update request must

include all data.

1.50.6.4 Errors

• Data changed in elements that may not be updated

1.51Rights Locker Data

1.51.1 RightsLockerID-type

This identifies a rights locker. It is coordinator assigned.

1.51.2 RightsLocker-type


RightsLocker-

type

dece:RightsLockerData-type

(by extension)

Status Status of rights locker dece:ElementStatus-type

1.51.3 RightsLockerData-type


RightsLockerData-



type

RightsLockerID Unique identifier for the rights locker dece:RightsLockerID-type

AccountID Account that owns rights locker dece:AccountID-type

RightsTokenID Reference to rights tokens that are contained in this locker.


0..n

1.51.4 Rights Token ID

This identifies a rights token. It is coordinator assigned.

RightsTokenID-type is a simple type of md:id-type.

[CHS: Do we want the token to contain the locker? I’m inclined not to do this as it gets messy if

the account is split up later.]

1.51.5 RightsToken-type


RightsToken-type

RightsTokenID Unique identifier for token. dece:RightsTokenID-type

Data Data associated with token. dece:RightsTokenData-type

LockerID In which right locker this belongs. [CHS: Is useful to cross reference backwards?]

dece:RightsLockerID-type

Status Status of the rights token including current status and history.

dece:ElementStatus-type

1.51.6 RightsAllowed-type

Defines right associated with logical asset.




RightsAllowed-

type

BurnsLeft How many burns left against this asset. [CHS: Note that Phase 1 limits burns to SD and to 1, this should accommodate growth.]

xs:int

Download Can this asset be downloaded? “TRUE” means yes.

xs:boolean

Stream Can this asset be streamed? “TRUE” means yes.

xs:boolean

1.51.7 RightsPurchaseInfo-type

This contains information about the purchase usable by the Coordinator. It also contains

information that can be passed to the retailer to allow the right to be matched to a purchase

transaction.


RightsPurchaseInfo-

type

RetailerID Retailer who executed transaction dece:RetailerID-type

RetailerTransaction Retailer-provided opaque identifier for the transaction. This information is returned to the retailer to allow the retailer to match the right to the purchase.

xs:string

PurchaseAccount Account associated with the original purchase. Note that this may change if the right is moved to a different account (e.g., account split)

dece:AccountID-type

PurchaseUser User who purchased right. dece:UserID-type

PurchaseTime Date and time of purchase transaction. xs:dateTime



1.51.8 RightsViewControl-type

DECE has a requirement that a purchaser has the option to ensure that they are the only who

can view the content. For V1, this is the only requirements. For future expansion, provisions for

an ACL are provided. CHS: I’m leaving this here for discussion. I believe a boolean is too

simple because it requires traversal back to the purchase information. It then becomes

impossible to assign ownership elsewhere. I believe we could keep it as an ACL but by policy

only populate one user in the inclusion list. Alternatively, we could keep one UserID.


RightsViewControl-

type

AccessList Access Control List for users who may view (inclusion) or not view (exclusion).

dece:UserAccessList-type

ExclusiveAccess UserID of single user who may view, download or steam this content.

dece:UserID-type

1.51.9 RightsLicAcqLoc-type

Provides location where DRM may acquire a license.


RightsLicAcqLoc-

type

DRM Which DRM location applies to. dece:drmID-type

Location Location for acquisition xs:anyURI

Preference Preferred location (low number being higher preference. More than one instance may have the same preference if the preference for the two is equal.

xs:int 0..1

1.51.10 RightsTokenData-type, RightsTokenDataLimited-type

RightsTokenData-type holds the key information for the rights token. RightsTokenDataLimited-

type is the proper subset that is accessible to Nodes who have opt-in status to read Rights

Locker.




RightsTokenDataLimited-

type

ALID Logical Asset ID for the right md:AssetLogicalID-type

CID Content ID referencing metadata md:ContentID-type

BundleID Identifies Bundle for the context of the purchase

md:BundleID-type

RightsData Enumeration of specific rights for each profile

dece:RightsData-type

TimeInfo Creation of right and modification history [CHS: need to decide how much history to track. Right now it’s just time of changes, but that is either too much info, or not enough.]

dece:timeinfo-type

PurchaseInfo dece:RightsPurchaeInf-type

RightsLicAcqLoc Information about where a DRM client may obtain a license. Must be at least one for each DRM. [CHS: min 3 now, but should increase if more DRMs added.]

dece:RightsAcqLoc-type 3..n

ViewControl Enumerates who may view the existence of the right (typically owner-only or everyone in account).

dece:RightsViewControl-type

0..1


RightsTokenData-

type

dece:RightsTokenDataLimited-type

(extension)



TimeInfo Creation of right and modification history [CHS: need to decide how much history to track. Right now it’s just time of changes, but that is either too much info, or not enough.]

dece:timeinfo-type

PurchaseInfo dece:RightsPurchaeInf-type

1.51.11 RightsData-type

RightsData-type holds the rights information for the rights token.


RightsData-type

RightsHD Enumeration of specific rights owned for the HD profile

dece:RightsAllowed-type

RightsSD Enumeration of specific rights owned for the SD profile


RightsPD Enumeration of specific rights owned for the PD profile


1.51.12 RightsSummary-type

This is used to support the API that gathers rights information.


RightsSummaryData-

type

RightsData Enumeration of specific rights owned for the HD profile

dece:RightsData-type

AcqLoc License Acquisition information dece:RightsAcqLoc-type



License Acquisition

The DECE Coordinator provides an interface to redirect license requests in a secure manner to

the appropriate license server.

There are many reasons for redirecting through the Coordinator, including

• Mapping license requests to DSPs based on information put into the rights token a time

of sale

• Allowing containers to be authored with a single licensing URL, regardless of DSP used

• Providing for redirection in the case that a DSP ceases to be part of the ecosystem

In the Coordinator, the Rights Token contains a set of ‘license acquisition location’ URLs keyed

off DRM. It allows multiple URLs and provides for preference ranking so, if necessary, you can

work down a list of providers. Note that the Rights Token is tied to the Account and so is the

license acquisition URL. If you know the APID and the User, and have the right credentials, you

already have enough information to get the URL.

So, with the current mechanism, the DRM Client (or device) establishes an HTTPS connection

to the Coordinator with Basic Authentication (for the username and password), and a GET to

something like:

https://license.decellc.org/License/V1/APID/{APID}/DRM/{DRMName}

From the device standpoint, there is some kind of redirection. It is desirable to carry information

in the redirection, particularly about the Right, so the DSP doesn’t need to contact the

Coordinator again.

[CHS: Consider batching: user REST request that keys off APID to returns all license

acquisition URLs (keyed off DRM and with an optional ‘preference’ ranking). Currently outside

of REST security model].



Domain and DRMClient

1.52Domain Function Summary

Domains are created and deleted as part of Account creation/deletion. There are no operations

on the entire Domain element. Actions on DRMClients are handed under DRMClient.

The Coordinator is responsible for generating the initial set of domain credentials for each

approved DRM.

[TBS: DomainGet to get the list of DRMClientIDs]

1.53DRM Client Function Summary

[TBS]

1.54Domain and DRM Client Functions

The Coordinator has the ability to add/remove clients from the domain using the "domain

management" functionality of each approved DRM.

[CHS: We need to decide if devices could also be added by the DSP, but we can enable this

and make it explicit if we need to. Probably not P0]

DECE assumes the following basic behavior for DRM Domain Management:

• Prior to a DRM Client joining a Domain, a “join domain” trigger is generated by the

Domain Manager. The triggering mechanism is different for each DRM, but

conceptually they are the same. [CHS: Do we need to confirm this?]

• The DRM Client receives the trigger, although DECE does not specify how this

happens.

• The DRM Client users the trigger to communicate with the Domain Manager. This is

specified by the DRM.

• The byproduct of this communication is the DRM Client joining or leaving the Domain

In some cases, it is not possible to communicate with a device and remove the DRM Client from

the Domain in an orderly fashion. Forced Removal removes the DRM Client from the list of

DRM Clients in the Account, without an exchange with the DRM Client. The ecosystem does

not know whether or not the DRM Client is still in the Domain, or more generally whether the

Device can still play content licensed to the DRM Client.



There are two means to initiate the triggers:

• a User may do so through the HTML User Interface (documented in the User Experience

specification [REF])

• a Device may do so on behalf of a User through an API for this purpose (see Devices

[REF in this doc.])

The exact form of the trigger is specified as part of the DRM. For use with the Web User

Interface, it is expected that the trigger will come in the form of a file with a MIME type that takes

the appropriate action upon opening.

The addition of the DRM Client to the Account occurs when the DRM Client is added to the

Domain, not when the trigger is generated. Hence, there could be other means of generating

triggers (e.g., at a DSP) that would still result in a proper addition of a DRM Client to an

Account.

1.54.1 DRMClientJoinTrigger (), DRMClientRemoveTrigger()


Path:

[BaseURL]/Account/{AccountID}/DRMClient/Join/<DRM Name>

[BaseURL]/Account/{AccountID}/DRMClient/Remove/<DRM Name>/{DRMClientID}

Method: GET

Authorized Role(s): UI, Device (see below)

Request Parameters:

AccountID is for the account that is requesting the DRM Client

<DRM Name> is the DRM Name for the DRM

{DRMClientID} is identifier for DRM Client to be removed from the Domain

Request Body: None [CHS: Maybe we should combine this with DeviceInfoUpdate-req.

If it happens from the device, we then have the information we need for the DRMClient record.

If it happens from the UI, we can make sure we generate the right trigger (i.e., for the right



DRM). We would still need DeviceInfoUpdate for changes after the fact (e.g., change

DisplayName.)]

Response Body


DRMClientTrigger-

resp

Trigger DRM Trigger dece:base64Binary (Choice)

MIME MIME Type for Trigger xs:string

Error Error response on failure dece:ErrorResponse-type

(Choice) 1..n

1.54.1.2 Behavior

The Coordinator, using the DRM Domain Manager for the DRM specified in DRM Name,

generates the appropriate trigger.

1.54.1.3 Errors

Join

• Maximum number of devices exceeded

Remove

• DRMClientID is not in Domain

1.54.2 DRMClientRemoveForce()


Path:

[BaseURL]/Account/{AccountID}/DRMClient/ForceRemove/<DRM Name>/{DRMClientID}

Method: POST




Request Parameters:

AccountID is for the account that is requesting the DRM Client

<DRM Name> is the DRM Name for the DRM

{DRMClientID} is identifier for DRM Client to be removed from the Domain

Request Body: None

Response Body: None

1.54.2.2 Behavior

The Coordinator marks the DRM Client as removed from the Domain.

[CHS: Do we need to say anything about forced removal policies?]

1.54.2.3 Errors

• DRMClientID is not in Domain

1.54.3 DRMClientInfoUpdate()


Path:

[BaseURL]/Account/{AccountID}/DRMClient/Info/{DRMClientID}

Method: PUT


Request Parameters:

AccountID is for the account that contains the DRM Client

{DRMClientID} is identifier for DRM Client whose information is to be accessed

Request Body:




DRMClientInfoUpdate-

req

dece:DRMClientDeviceInfo-type

(extension)

Response Body: None

1.54.3.2 Behavior

DRM Client Information is replaced with the contents od DRMClientInfoUpdate-req.

1.54.3.3 Errors

• DRMClientID is not in Account

1.54.4 DRMClientInfoGet()

This API is used to retrieve information about the DRM Client and associated Device.

Note that it is not strictly symmetrical with DRMClientInfoUpdate()


Path:

[BaseURL]/Account/{AccountID}/DRMClient/Info/{DRMClientID}

Method: GET

Authorized Role(s): UI, Device, Retailer (see below)

Request Parameters:


{DRMClientID} is identifier for DRM Client whose information is to be accessed

Request Body: None

Response Body:


DRMClientInfoGet-



resp

Info Information about DRM Client and Device

dece:DRMClientData-type

(Choice)


(Choice) 1..n

1.54.4.2 Behavior

DRM Client Information is returned.

1.54.4.3 Errors

• DRMClientID is not in Account

1.54.5 DomainClientGet()

Retrieves list of DRM Clients in Domain.


Path:

[BaseURL]/Account/{AccountID}/Domain/DRMClients

Method: GET

Authorized Role(s): UI

Request Parameters:


Request Body: None

Response Body:


DRMClientInfoGet-

resp



DRMClientID DRMClientIDs for DRMClients in Domain

dece:DRMClientID-type (Choice)1..12


(Choice) 1..n

1.54.5.2 Behavior

DRM Client Information is returned.

1.54.5.3 Errors

• [TBD—can’t think of any]

1.54.6 DRM Client Types

These elements describe a DRM Client and maintain the necessary credentials.

1.54.7 DRMClient-type

Element Attribute Definition Value Cardinality

DRMClient-type dece:DRMClientData-type (extension)

DRMClientID Unique identifier for this device dece:DRMClientID-type

1.54.8 DRMClientData-type

Element Attribute Definition Value Cardinalit

y

DRMClientData-

type

DRMSupported DRM supported by this DRM Client. Must be consistent with other elements.one of DRM Name [REF]

xs:stringdrmID-type

NativeDRMClientID A DRM-specific object used to identify the DRM Client. Opaque to the Coordinator

xs:base64Binary



DeviceInfo DRM Client capabilities dece:DRMClientDeviceInfo-type

State Information about the status of the device, including information about removal. This should only exist if the DRM Client has been removed at least once. [CHS: Name is ‘Removal’ to avoid confusion with distinct ‘Status’ element.]

dece:DRMClientState-type

DRMSupported may have the following values: “oma”, “playready”, “marlin” or name for other

approved DRMs (TBD).

1.54.9 DRMClientDeviceInfo-type

This is a placeholder for any information reported by the DRM Client about the Device.

Includes general information about DRM Client and its associated Device. [CHS: would people

prefer name/value pairs?]


DRMClientCapabilities-

type

DisplayName Name to use for DRM Client/Device xs:string

Profiles Profiles supported by DRM Client’s Device

dece:DRMClientDeviceInfo-type

Model Model number of device xs:string 0..1

SerialNo Serial number of device xs:string 0..1

Brand Brand of company selling device xs:string 0..1

Image Link to device image xs:anyURI 0..1

DECEVersionCompliance Indicates version of DECE with which device is compliant.

xs:string



1.54.10 DRMClientProfile-type

As shown, this indicates whether a particular profile is supported for the Device associated with

this DRM Client and whether it can burn DVDs. [CHS: I assume we need more here, but this

needs to come from the DRM client group.]

“true” indicates the feature is supported. [CHS: would people prefer name/value pairs?]


DRMClientProfile-

type

HDPlay Will Device play HD? xs:boolean

SDPlay Will Device play SD? xs:boolean

PDPlay Will Device play PD? xs:boolean

SDBurn Will Device burn SD ISOs? xs:boolean

1.55DRMClientState-type

This is used to capture status of a deleted DRM Client. Status shall be interpreted as follows:

• Active – DRM Client is active.

• Deleted – DRM Client has been removed in a coordinated fashion. The Device can be

assumed to no longer play content from the Account’s Domain.

• Suspended—DRM Client has been suspended for some purpose. This is reserved for

future use.

• Forced—DRM Client was removed from the Domain, but without Device coordination. It

is unknown whether or not the Device can still play content in the Domain.

• Other—reserved for future use


DRMClientState-

type

Status Status of removal. xs:string



“active” “deleted” “suspended”“forced”“other”

Date Period right will be held. xs:dateTime

ModifiedBy Organizational entity modifying md:orgID-type

Description Text description including any information about status change.

xs:string 0..1

History Historical tracking of status. dece:DRMClientState-type

0..n

1.56Domain Types

1.56.1 Domain-type


Domain-type

DomainID dece:DomainID-type

AccountID Associates the domain with an account.

dece:AccountID-type

DRMClient Lists all DRM clients in the domain.

dece:DRMClientID-type 0..12

DomainMetadata Metadata for domain (CHS: TBD).

dece:DomainMetadata-type

NativeCredentials Maps the domain the DRM native domains.

dece:DomainNativeCredentials-type

1.56.2 DomainMetadata-type

CHS: Does anything go here?



1.56.3 DRMNativeCredentials-type

A domain covers all DRMs. This maps a DECE domain to all DRM domains.

This element contains the DRM native credentials for a domain. This is assumed to be a binary

block of data. “OtherAsAppropriate” is included to indicate that all approved DRMs will be

included.


DRMNativeCredentials-

type

OMA OMA credential xs:base64Binary

PlayReady PlayReady credential xs:base64Binary

Marlin Marlin credential xs:base64Binary

(OtherAsAppropriate) (see above) xs:base64Binary

1.56.4 DomainMetadata-type

[CHS: don’t know what goes here. This is just a place holder.]

1.56.5 Other Types

1.56.5.1 timeinfo-type

This can be used to keep track of changes.

[CHS: I’m not sure if this is needed. If it is, it should probably have some form of annotation to

determine who did what.]


timeinfo-type

Creation xs:dateTime

Modification xs:dateTime 0..n



Stream

1.57Stream Function Overview

[TBS]

1.57.1 StreamCreate()


The LASP posts a request (to Coordinator) to create a streaming session for specified content

on behalf of the User. The Coordinator must verify the following criteria in order to grant that

request: User Group possesses content Rights Token (RTID), number of active LASP Sessions

is less than ACCOUNT_LASP_SESSION_LIMIT, User has requisite Privilege Level and meets

Parental Control Policy requirement.

The Coordinator grants authorization to create a stream by responding with a unique stream

identifier (StreamHandle) and a grant expiration timestamp (Expiration). Note, Dynamic LASP

streaming sessions are not allowed to exceed 24 hours (Variable TBD) in length without re-

authentication.


Path:

[BaseURL]/Account/{AccountID}/Stream

Method: POST

Authorized Role(s): Linked LASP, Dynamic LASP

Request Parameters:

AccountID is for the account that will “own” the stream.

Request Body


StreamCreate-

req

Parameters for StreamCreate() dece:StreamData-type

Response Body




StreamCreate-

resp

StreamHandle Stream handle for created stream. dece:StreamCreateRespData-type

(Choice)

Error Error response on failure dece:ErrorResponse-type (Choice) 1..n


StreamCreateRespData-

type

StreamHandle Stream handle for created stream. dece:StreamHandle-type

Expiration Date and time when stream will expire. LASP must either renew or stop servicing stream by this time

xs:dateTime

1.57.1.3 Behavior

The RightsTokenID provided in the request MUST be for the content being requested.

Requestor MAY generate a TransactionID.

The Coordinator MUST verify the following criteria in order to grant stream authorization: User

Group possesses content Rights Token (RTID), number of active LASP Sessions is less than

ACCOUNT_LASP_SESSION_LIMIT, User has requisite Privilege Level, and User meets

Parental Control Policy requirement to access content. If all the above checks are successful,

then a StreamHandle is created and returned to the requester.

The Coordinator MUST maintain stream description parameters for all streams – both active

and inactive. See Stream-Type data structure for details. The Coordinator will record initial

stream parameters upon authorization and StreamHandle creation. Authorizations must also be

reflected in Account parameters, i.e., active session count.



1.57.1.4 Errors

<<<Need to enumerate error codes>>>

1.57.2 StreamListView(), StreamView()


This API supports LASP, UI and CS functions. Which data are returned depend on the Role

making the request.


Path:

[BaseURL]/Account/{AccountID}/Stream/[{StreamHandle}]|[?max={numstreams}]

Method: GET

Authorized Role(s): UI, LASP

Request Parameters:

AccountID is the account ID for which streamlist is requested.

StreamHandle, when present, identifiers the stream queried.

?max={numstreams} specifies the maximum number of streams to return.

Request Body: None

Response Body:

When StreamHandle is present, StreamView-resp is returned. When StreamHandle is not

present, StreamListView is returned.


StreamListView-

resp

Stream Stream information returned dece:StreamList-type (Choice)


(Choice)1..n




StreamView-resp

Stream Stream information returned dece:Stream-type (Choice)


(Choice)1..n

1.57.2.3 Behavior

The requester makes this request on behalf of an authorized user.

Requestor MUST redirect the user to the Coordinator for authentication prior to the query being

sent. This is only required if user opt-in is not allowed.

The response by the Coordinator depends on the requestor.

• If the requestor is a LASP, the Coordinator MUST only return information on the stream

or streams created by that LASP.

• If the requestor is UI, the Coordinator MUST return information for the stream or streams

that are active.

• If {numstreams} is specified, then active and inactive streams will be returned in

chronological order, with up to {numstreams} streams return. If {numstreams}=0, all

streams will be returned. [CHS: This is derived from a UI requirement to display last 10

items streamed.]

The responder returns the requested information in a single structure.

1.57.2.4 Errors

TBD



1.57.3 StreamAvailable()


This API is used by any LASP to determine if streams are currently available. Note that this

does not guarantee that streams will be available, even immediately following this request, as

other streams could be created in the interim..


Path:

[BaseURL]/Account/{AccountID}/Stream/available

Method: GET

Authorized Role(s): Dynamic LASP, Linked LASP, Customer Support, UI

Request Parameters: none

Request Body: none

Response Body


StreamAvailable-

resp

Available Number of streams available xs:int (Choice)


(Choice)1..n

1.57.3.3 Behavior

The Coordinator is returns the number of streams currently available.

1.57.3.4 Errors

[Should just be account issues.]



1.57.4 StreamDelete()


The LASP uses this message to inform the Coordinator that the content is no longer being

streamed to the user. The content could have been halted due to completion of the content

stream, user action to halt (rather than pause) the stream, or a time out occurred infringing on

the duration of streaming content policy.


Path:

[BaseURL]/Account/{AccountID}/Stream/{StreamHandle}

Method : DELETE

Authorized Role(s): Dynamic LASP, Linked LASP, Customer Support

Request Parameters

AccountID is the account ID for which operation is requested.

StreamHandle identifiers the stream to be released.

Request Body: Null

Response Body: Standard Response

1.57.4.3 Behavior

The Coordinator marks the Active to ‘false’ to indicate the stream is inactive. EndTime is

created with the current date and time. ClosedBy is crated and is set to the ID of the entity

closing the stream.

StreamList activecount is decremented (but no less than zero).

1.57.4.4 Errors

Closing a stream that’s already closed.



1.58Stream types

1.58.1 StreamList-type

A stream is subordinate to an Account.


StreamList-type

[CHS: It does not currently contain account as an attribute, although we might have to add it later when this is used in isolation from the account.]

ActiveCount Number of active streams xs:int

Stream A description of each stream See Stream-type 0..n

1.58.2 StreamData-type

This element is part of the stream. It is broken out separately because it is the subset of the

data used to create the stream.


StreamData-

type

UserID User ID who created/owns stream dece:UserID-type

RightsTokenID ID of Rights Token that holds the asset being streamed. This provides information about what stream is in use (particularly for customer support)


TransactionID Transaction information provided by the LASP to identify its transaction associated with this stream. A TransactionID need not be unique to a particular stream (i.e., a transaction may span multiple streams). Its use is at the discretion of the LASP

xs:string 0..1



1.58.3 Stream-type

This is a description of a stream. It may be active or inactive (i.e., historical). CHS: I’m

expecting confusion about streams not working because user is oversubscribed. I don’t know if

we need to keep all this information but, for prudence, and for the moment, I’m leaving it in.


Stream-type

StreamHandle Unique identifier for each stream. It is unique to the account, so it does not need to be handled as an ID. The coordinator must ensure it is unique.

dece:StreamHandle-type

StreamData Information about stream creation dece:StreamData-type

Active Whether or not stream is considered active (i.e., against count). “TRUE” means active.

xs:boolean

StartTime Time streaming actually started xs:dateTime 0..1

CreatedTime Time stream created xs:dateTime

DeletionTime Time stream ended (if ended). Must be present if ClosedBy is present

xs:dateTime 0..1

CreatedBy LASP that created the stream dece:LaspID-type

ClosedBy Entity that closed the stream (could be LASP or Customer Support)

dece:orgID-type 0..1

1.58.4 StreamDelete-resp


StreamDelete-resp

Error Error response on failure. ErrorNumber will be 0 upon success. CHS: I don’t like this and will figure out something else.

dece:ErrorResponse-type



1.58.5 StreamHandle-type

This is a xs:int.



Node/Account Bind Functions

1.59Types of Binding

Binding Accounts is the process of granting Nodes access to certain Account information on

behalf of Users without an explicit Coordinator login. These Nodes are LASPs (both Linked and

Dynamic) and Retailers. The binding rights that may be granted are Rights Locker Access and

LASP linking.

1.60Binding for Rights Locker Access

Retailers, Dynamic LASPs and Linked LASPs can be granted the right to access an Account’s

Rights Locker. The default access is for a Node to only have access to Rights Tokens created

by that Node. For example, if Retailer X creates Rights Token X1 and Retailer Y creates Rights

Token Y1, X can only access X1 and Y can only access Y1. Binding allows full access to the

entire Rights Locker. For example, if granted to X, it may access X1 and Y1.

Access can be granted in the context of specific Users, or all Users on that Account. This done

though the AccessUser element. If granted for all Users, all Rights Tokens are accessible. If

granted for a subset of Users on the Account, only those Rights Tokens granted for those Users

can be accessed. This specifically addresses the case where a User has “ExclusiveAccess”

set for certain Rights Tokens. More specifically, if a User is not included in the list of

AccessUser elements, Rights Tokens with that User and ExclusiveAccess set will not be visible

to the Node.

1.61Binding for Streaming (Linked LASPs)

The LASP binding process allows a LASP to act on behalf of an Account. Once bound, a LASP

maintains other LASP responsibilities such as enforcing the maximum number of simultaneous

streams.

There are two parts to the binding process:

• The Coordinator keeps a record of which accounts are bound which LASPs

• The LASP is given a certificate to use on the Account’s behalf to access Rights and

Streams.

There are various policy issues regarding limits on linked LASPs. These can be supported by

the Coordinator through the use of the mechanism described here. Issues include:

• Number of linked LASPs for an account



• Duration of a binding – handled through the certificate

• The linked LASP is given full access to the Rights Locker; that is, the linked LASP is

implicitly (not explicitly) included in the Account’s AccountRetailerAccessList.

Issues not addressed through this API include

• The number of devices associated with a linked LASP account. For example, the

number of cable settop boxes associated with a cable subscriber account.

• Implementation of Parental Controls. Linked LASPs have visibility into rights for all

users, regardless of Rating (including the purchasing User’s “ExclusiveAccess” status).

• Streaming method (addressed in Approved Streaming Method [REF]

Note that linked LASPs, like dynamic LASPs, are not assumed to have access to all DECE

content, so not everything in the Rights Locker will be streamable.

Linked LASPs have the option of progressively downloading a DECE Common Container to a

device within its system. In this case, the linked LASP is operating as a DSP and both the

LASP and the device must operate under the rules of DSPs, DECE Devices and DRM Domains.

1.62Node/Account Functions

1.62.1 Authentication

Upon binding, the Coordinator provides the Node with an OAuth certificate that can

subsequently be used to access Coordinator functions on behalf of the User.

[CHS: A simpler method would be to use the Node’s credentials as identification allowing a

match to be made with the NodeAccess elements. This also obviates the need to revoke

certificates. Any reason not to do that?]

1.62.2 LLASPBindCreate

This creates a binding between a Linked LASP and an account. Once completed the Linked

LASP may obtain certain Account information and may initiate Streams for the Account.


Path:

[BaseURL]/Account/{AccountID}/LLASPBind/



Method: POST | PUT

Authorized Role(s): LLASP, UI

Request Parameters:

• {AccountID} is Account ID to be bound

Request Body:


AccountLLASPBind-

req

dece:AccountLLASP-type

Response Body: None


AccountLLASPBind-

resp

Expiration Date and time (UTC) when binding expires

xs:dateTime (choice)

Error Upon failure, error information is returned

dece:ResponseError-type

(choice)

1.62.2.2 Behavior

Create or renews the binding between linked LASP and Account. If established, the Linked

LASP may obtain streams on the User’s behalf without User login.

If the binding is allowed, an expiration time for the binding is returned in the Expiration element

of AccountLLASPBind-resp. After the date and time specified, the binding is terminated by the

Coordinator.

If the binding exists, it may be renewed or extended. This will be based on [TBD] policy.

If the binding exists, data in the binding (i.e., AccountLLASP-type) replaces what is in the

current binding.



Rights Locker Opt-in is implicit for a Linked LASP and therefore a separate RightsLockerOptIn

is not required.

1.62.2.3 Errors

• Maximum number of bindings exceeded.

• User information does not match account. (covered under standard errors, but of

particular note here).

• Binding User doest not match User logged in

• Update attempted without matching laspID. Request was a PUT, but a record with the

matching laspID did not exist.

1.62.3 LLASPBindDelete

LLASPBindDelete removes the binding between the Linked LASP and the Account. If initiated

by the LinkedLASP, the disassociation is orderly. If initiated by the User Interface or Customer

Support, the Linked LASP is not directly informed, but will be unable to authenticate and

therefore will be unable to access User Account information or initiate streams.

[CHS: We need to add error status across the board that indicates that an OAuth certificate is

no longer valid for various reasons.]


Path:

[BaseURL]/Account/{AccountID}/LLASPBind/{laspID}

Method: DELETE


Request Parameters:

• {AccountID} is Account ID for the Account wishing to unbind

• {laspID} is linked LASP whose binding is to be removed

Request Body: None

Response Body: None



1.62.3.2 Behavior

Removes binding between linked LASP given by {laspID} and Account given by {AccountID}.

1.62.3.3 Errors

• LASP with laspID not bound to Account with AccountID

1.62.4 LLASPBindAvailable

The maximum number of bindings between Linked LASPs and Accounts is limited by policy.

[CHS: Currently 3.] This API allows for a check of availability before attempting to bind. This

does not guarantee that the binding will succeed because other binding requests could come

between the LLASPBindAvailable and the LLASPBindCreate.


Path:

[BaseURL]/Account/{AccountID}/LLASPBindAvailable

Method: DELETE


Request Parameters:

• {AccountID} is Account ID for the Account considering binding.

Request Body: None

Response Body:


AccountLLASPBindAvailable-

resp

Available Number of Linked LASP binding slots available

xs:int (Choice)


(Choice)1..n



1.62.4.2 Behavior

Returns the number of available slots in the Available element onf AccoutnLLASPBindAvialable-

resp.

1.62.4.3 Errors

• LASP with laspID not bound to Account with AccountID

1.62.5 LockerOptInCreate, Update

This creates an association between the Account and a Node granting Rights Locker read

privileges to the Node. [CHS: I am assuming this is only for retailers and LASPs.]


Path:

[BaseURL]/Account/{AccountID}/LockerOptin

Method: POST | PUT

Authorized Role(s): Retailer, LASP, UI

Request Parameters:

• {AccountID} is Account ID

Request Body:


AccountAccessRightsLockerCreate-

req

dece:AccountAccessRightsLocker-type

Response Body: None


AccountAccessRightsLocker-

resp



Expiration Date and time (UTC) when opt-in expires

xs:dateTime (choice)



(choice)

1.62.5.2 Behavior

Create or renews the binding between linked Node and Account for the purposes of allowing

rights locker access. If established, the Node may obtain Account Rights Locker information on

the User’s behalf. Without the opt-in, a Retailer may only access Rights it created, CS and UI

may access the full Rights Locker and other Nodes may not access the Rights Locker.

If the binding is allowed, an expiration time for the binding is returned in the Expiration element

of AccountLLASPBind-resp. After the date and time specified, the binding is terminated by the

Coordinator.

If the binding exists, it may be renewed or extended. This will be based on [TBD] policy.

If the PUT is used to indicate an update, and the binding exists to a matching OrgID, data in the

binding (i.e., AccountAccessRightsLocker-type) replaces what is in the current binding.

1.62.5.3 Errors

• Maximum number of bindings exceeded.

• User information does not match account. (covered under standard errors, but of

particular note here).

• Binding User doest not match User logged in

• Update attempted with unmatched OrgID—when a PUT is done but there is no existing

record with a matching OrgID.

1.62.6 LockerOptInDelete

This removes the association between the Account and a Node granting Rights Locker read

privileges to the Node. Once removed, the Node may no longer access the Rights Locker

beyond what it could normally (e.g., as a Retailer).




Path:

[BaseURL]/Account/{AccountID}/LockerOptin/{OrgID}

Method: DELETE


Request Parameters:

• {AccountID} is Account ID for the Account wishing to unbind

• {orgID} is Node whose binding is to be removed [CHS: NOTE to self: should

probably use Node ID rather than OrdID]

Request Body: None

Response Body: None

1.62.6.2 Behavior

Removes Rights Locker opt-in binding between Node given by {OrgID} and Account given by

{AccountID}.

1.62.6.3 Errors

• Node with ID OrgID not bound to Account with AccountID

1.63Node/Account Types

These types are in the NodeAccess element in the Account-type under Account [REF].



Account

1.64Account Function Summary

These functions are designed to ensure that an account is always a valid state. To achieve

that, it is necessary to create Account, User Group, DRM Client, Rights Locker and User

elements atomically. The AccountCreate function creates those elements. Note that there are

several Account creation Use Cases that begin with content to be licensed. Account creation

would then be followed with an immediate purchase.

Once created, an Account cannot be directly purged from the system. This allows Account

deletion to be reversible through Customer Support in the case of accidental or malicious

removal. AccountDelete changes the status of the Account elements and all related elements

to ‘deleted’. This has the effect of making the account non-functional in a reversible fashion

(i.e., return status to ‘active’). The reasoning behind this is that the rights tokens maintained

within the account have value and account deletion would effectively destroy those assets.

[CHS: summary out of date.]

Account (Do we need a merge account, split account?)

Function Name Path Method Roles Comments Request

Parameters

Request Body Response Body

AccountDataGet() /Account/{AccountID} GET RetailerDSPLASPUser

Return Account metadata.

Also used to determine if account is still valid

Error: Reference source not found

UpdateXYZ() /Account/{AccountID} PUT RetailerDSPLASPUser

Update user editable fields associated with the account, such as Account Friendly Name, parental control on or off, status? etc.





1.65Account Functions

1.65.1 AccountCreate()


This creates an account and all of the necessary elements for a minimal account. An account

needs at least one user so the first user is part of the API request. If successful, the IDs for the

elements created (rights locker, domain, etc.) are returned. If unsuccessful, an error is returned.

The User who created the account is given Full Access.


Path:

[BaseURL]/Account

Method: POST

Authorized Role(s): Retailer, UI


Request Body: AccountCreate-req


AccountCreate-req dece:AccountData-type

FirstUser Information about the one user that must be included to make this valid. This is the same information that is used to create a user by itself.

dece:UserCreate-req

DisplayName Display name for account. xs:string

Response Body: AccountCreate-resp




StreamViewAccountCreate

-resp


(Choice 1)

AccountID AccountID of new account dece:AccountID-type (Choice 2)

DomainID ID of Domain created for new account

dece:DomainID-type (choice 2)

RightsLockerID ID for Rights Locker created for new account.


(choice 2)

1.65.1.3 Behavior

Create creates the account and all the necessary domains, groups, etc. [CHS: detail]

Delete updates the Status and History elements to reflect the deletion of the account. Nothing

else is modified.

1.65.1.4 Errors

[TBS]

1.65.2 AccountDelete()


This deletes an account. The account is flagged that it is deleted without removing the data .

This is a reversible process. Status is changed to “deleted”.

This is performed on behalf of an authenticated Administrative User for the Account. If

performed through the Retailer, it must be done by the Retailer who created the Account. [CHS:

True?]

[CHS: This is pretty drastic. Do we want to add rules like Account must be empty except for one

Admin user?]

Account deletion may be initiated only by a User on that Account with Full Access privileges.



[CHS: Can we delete accounts at some point, such as ‘deleted’ for 1 year? This may be

considered more of a policy issue.]


Path:

[BaseURL]/Account/{AccountID}

Method: DELETE


Request Parameters:

• {AccountID} is the ID for the account to be deleted.

Request Body: None

Response Body: None

1.65.2.3 Behavior

Delete updates the Status and History elements to reflect the deletion of the account. Nothing

else is modified.

1.65.3 AccountDataGet(), AccountDataSet(),

AccountDataDelete()


This API is used to create, modify, retrieve or delete account descriptive information. There are

variations on the basic request access subsets of the total data set.

1.65.3.2 API Details: Metadata

Account data contains general information about the account. Functions are provided to

retrieve and modify subsets of account data.

The general pattern for update is to GET the subset and then POST a complete replacement for

that subset including updates.

[CHS: We need security model. ]



Account data can be updated by a Retailer or the UI on behalf of a properly authenticated

Account Administrator. The Coordinator SHALL generate an email notice to all [CHS: is this

right?] Account Administrators that indicates which Account metadata has been updated.

A Retailer may only modify account information if it was the Retailer that created the Account.

Path:

[BaseURL]/Account/<accountID>/metadata

Method: GET | PUT


Any of the Roles may get information. Only Customer Support may modify information.

Metadata is created at Account Creation.

Request Parameters:

• {accountID} is the ID of the Account to be accessed.

1.65.3.2.1 Request

GET Request Body: none

PUT Request Body: AccountMetadata-type

1.65.3.2.2 Response

GET Response Body: AccountMetadata-type

PUT Response Body: none

1.65.3.2.3 Behavior

The GET request has no parameters and returns the complete set of metadata for the account.

The PUT request updates the complete set of metadata. There are not individual requests for

each element.

Possible errors include: [TBS]



1.65.3.3 API Details: Setting

There are provisions for access all settings or individual settings. [CHS: Should we add

something for all settings?]

Settings are name/value pairs. The name SHALL be unique. Attempts to create (POST) a

setting with a name that already exists SHALL result in an error. Similarly, GETs and DELETEs

for names that do not exist SHALL result in an error.

Path

• GET all parameters:

[BaseURL]/Account/<accountID>/setting

• GET or DELETE specific parameters:

[BaseURL]/Account/<accountID>/setting/<UserID>

• PUT or POST specific parameters:

[BaseURL]/Account/<accountID>/setting/[<UserID>[?=<Priv>]]

Method: GET | POST | PUT | DELETE

Authorized Role(s): Retailer, US

[CHS: This is a general mechanism that has no specific attributes associated with it. As

such, it’s hard to assign specific rules about who can do what. When we get some

specifics it will make sense to define access controls. We might want rules such as only

the creator can modify or delete, but then we’d need to keep track of retailerID with the

name/value pair. Open to suggestions…]

Request Parameters

The parameter to be added, deleted, retrieved or modified is part of the URL and shown above

as <name>. <name> is case insensitive.

Request Body:

GET, DELETE: None

POST, PUT: AccountSettingNVPair-type

Response Body



POST, PUT, DELETE: None

GET single value: AccountSettingNVPair-type

GET all values (i.e., no Name specified): AccountSettings-type

1.65.3.4 API Details: Privileges

Account privileges define privileges no a per-user basis. User may have more than one

privilege.

Path

• GET all parameters:

[BaseURL]/Account/<accountID>/priv

• GET or DELETE specific parameters:

[BaseURL]/Account/<accountID>/priv/<name>

• PUT or POST specific parameters:

[BaseURL]/Account/<accountID>/priv/[<name>[?=<value>]]

Method: GET | POST | PUT | DELETE


[CHS: This is a general mechanism that has no specific attributes associated with it. As

such, it’s hard to assign specific rules about who can do what. When we get some

specifics it will make sense to define access controls. We might want rules such as only

the creator can modify or delete, but then we’d need to keep track of retailerID with the

name/value pair. Open to suggestions…]

Request Parameters

The privilege for a given user with user ID = <UserID> to be added, deleted, retrieved or

modified is part of the URL and shown above as <UserID>.

Request Body:

GET, DELETE: None

POST, PUT: AccountPrivileges-type



Response Body

POST, PUT, DELETE: None

GET single value: AccountPrivileges-type

GET all values (i.e., no UserID specified): AccountPrivilegesList-type

1.65.4 Behavior

[CHS: Put specific rules here. What is created as part of account creation? Can’t delete the

last privilege for a user. Must have at least one user with admin privileges.]

1.66UpdateXYZ()

[CHS: At some point we’ll need to be able to update domains, user groups, etc., but I’m not sure

we need this for V1.]

1.67Account Data

1.67.1 Account ID

AccountID is type dece:id-type.

AccountID is created by the Coordinator. Its content is left to implementation, although it must

be unique.

1.67.2 Account-type

This is the top level element for a DECE Account. It is identified by AccountID.


Account-type

AccountID Unique Identifier for this account

dece:AccountID-type

AccountDataDisplayName Information about account such as display name and whether or not it is activeDisplay Name for the Account

See AccountData-typexs:string



Created Date created xs:dateTime

AccountStatus Current status of the account

xs:string, see below

UserGroupID Reference to a User Group contained within account. Currently only one User Group is allowed.

dece:UserGroupID-type

RightsLockerID Reference to account’s rights locker. Rights tied to account. Currently, only one Rights Locker is allowed.


DomainID Reference to DRM domain associated with this account. Currently, only one Domain per DRM is allowed.

dece:DomainID-type

Streams LASP stream status. See StreamsList-type

NodeAcccess Identification of retailers that may access full rights locker in accordance with policy (e.g., opt-in). Both LASPs and DSPs must also be Retailers, so for consistency this information is maintained in terms of Retailer.

dece:AccountAccess-type 0..1

Settings Series of name/value pairs that constitute settings for account. This is defined as name/value pairs so pre-definition of attributes is not required.

See AccountSettings-type 0..1

Status Current status of account, dece:ElementStatus-type



for example is it active or deleted. This also includes history.

Status may have the following enumerated values:

• “ pending” account is pending but not fully created

• “ archived” account is inactive but remains in the database

• “ suspended” account has been suspended for some reason

• “ active” is the normal condition for an account.

1.67.3 AccountData-type


AccountData-type

AccountID Unique Identifier for this account dece:AccountID-type

Metadata Information about account such as display name and whether or not it is active

See AccountMetadata-type

Settings Series of name/value pairs that constitute settings for account. This is defined as name/value pairs so pre-definition of attributes is not required.

See AccountSettings-type

0..1

AccountPrivilegesList Which users have which account privileges. This is 1..n but effectively bound by the (maximum) number of users in the account.

See AccountPrivilegesList-type

1.67.4 Account Metadata-type

This element holds data about the account.




AccountMetadata-

type

displayName User visible display name for account. xs:string

Created Date and time created xs:dateTime

Status Current status of the account xs:string, see below

Status may have the following enumerated values:

• “pending” account is pending but not fully created

• “archived” account is inactive but remains in the database

• “suspended” account has been suspended for some reason

• “active” is the normal condition for an account.

1.67.5 AccountSettings-type

Account settings are name/value pairs of strings. There are currently no pre-defined values.

Strings are case sensitive.


AccountSettings-type

AccountSettingsNVPair 1..n

Name Name part of name/value pair. xs:string

Value Value part of name/value pair xs:string

1.67.6 AccountPrivilegesList-type

List of privileges.


AccountPrivilegesList-

type



AccountPrivileges Individual account privileges, one per user. There must be at least one for the account administrator (full access) and at most 6 for total number of users. CHS: I’m reluctant to hardcode 6 as there will certainly be exceptions. I’d rather this be imposed by policy than XML.

dece:AccountPrivileges-type

1..6

1.67.7 AccountPrivileges-type

Individual access privileges are assigned to each user. One privilege does not imply another;

for example, an administrator is not automatically assumed to have purchase privileges. “True”

implies the privilege is granted.


AccountPrivileges-

type

UserID dece:UserID-type

Priv Privilege level. These are defined in the usage model, section 3.5.3.

xs:string (enumerated: “basic”, “controlled”, “full”)

1.67.8 AccountData-type


AccountData-type

Metadata Account Metadata (TBD) dece:AccountMetadata-type

Settings Settings for account dece:AccountSettings-type 0..1

AccountPrivilegesList Privileges for each user. CHS: dece:AccountPrivilegesList-



This should probably NOT be specific for creation as the original user should automatically be created and assigned a priv of to be “full”

type

1.67.9 AccountAccess-type

Nodes may have access to rights locker and streams as determined by policy.


AccountAccessNode-

type

RightsLockerOptIn Entries for Nodes to access Rights Locker

dece:AccountAccessRightsLocker-type

0..n

LASP Entries for Linked LASPs to bind to Account

dece:AccountAccessLLASP-type 0..n

DeviceList Entries for Nodes to access Device list

dece:AccountAccessDeviceList-type

0..n

1.67.10 AccountAccessRightsLocker-type

This element describes which rights lockers given Node may access. The absence of a granted

right implies no access.

A separate element must be included for each Node. Exclusion of OrgID implies all.


AccountAccessRightsLocker-

type

OrgID ID of Node who is granted access.




AccessUser UserIDs associated with the Access. If no UserID is specified, the right is assumed to be all Users on the Account

dece:UserID-type 0..n

GrantingUser UserID associated with User who created this Access

dece:UserID-type

1.67.11 AccountAccessLLASP-type

This element describes which rights lockers and binding rights given LASP may access. The

absence of a granted right implies no access.

A separate element must be included for each LLASP.


AccountAccessRetailer-

type

laspID ID of Node who is granted access. The absence of the ID type implies all LASPs


BindingUser UserID associated with User who created this Access

dece:UserID-type

Credentials Information used to authenticate access [TBD]

xs:base64Binary

1.67.12 AccountAccessDeviceList-type

This element describes whether a given Node may access information about Devices on the

Account. The absence of a granted right implies no access.

A separate element must be included for each Node. Exclusion of OrgID implies all.




AccountAccessDeviceList-type

OrgID ID of Node who is granted access.


GrantingUser UserID associated with User who created this Access

dece:UserID-type



User and User Group

1.68User Functions

1.68.1 User Functions

User Function URL Prefix: …/Account/{AccoundID}/UserGroup/{UserGroupID}/

[Summary TBS]

1.68.2 UserCreate()


Users may be create via two methods, this one and through account creation. In both cases,

the applicable element is UserCreate-req.

[CHS: Currently credentials (e.g., username/password) are not included. I need to know the

sequence before defining this. Does the entity creating the user create credentials or is the user

referred to the UI for this? Perhaps the user gets an email with initial credentials.]


Path:

[BaseURL]/Account/{AccountID}/UserGroup/{UserGroupID}/User

Method: POST


Request Parameters:

The URL provides the AccountID for the account and UserGroupID for the User Group within

the Account for which the User will be added.

Request Body:


UserCreate-req Information about the user to be created.

dece:UserDataType

Response Body:




UserCreate-resp

UserID Upon success, a new unique User ID is returned.

dece:UserID-type (choice)



(choice)

1.68.2.3 Behavior

A UserCreate-req is supplied via the request to the Coordinator. If all rules are met, the

Coordinator creates the User and returns a UserID. If rules are not met, an error is returned.

1.68.2.4 Errors

• Max number of users in the account is exceeded

• UserGroup errors (doesn’t exist, not in account, etc.)

• User information incomplete or incorrect (see errors for modifying individual

parameters)

1.68.3 UserGroupGet(), UserGet()


User information may be retrieved either for individual user or as a Group.


Path:

For an individual user:

[BaseURL]/Account/{AccountID}/UserGroup/{UserGroupID}/User/{UserID}

For an User Group:

[BaseURL]/Account/{AccountID}/UserGroup/{UserGroupID}

Method: GET




Request Parameters:

The URL provides the AccountID for the account and UserGroupID for the User Group within

the Account for which the User will be added.

Request Body: None

Response Body:

For a single User, requests by all but Customer Support get UserGet-resp.


UserGet-resp

User Information about User dece:UserGet-type (choice)

Error Error information dece:ResponseError-type

(choice)


UserGet-type Information about a single user dece:UserDataType (extension)

UserID User ID for User returned. dece:UserID-type

For a group request, UserGroupGet-resp is returned.


UserGroupGet-resp

User Information about User Group dece:UserGroupGet-type

(choice)

Error Error information dece:ResponseError- (choice)



type


UserGroupGet-

type

UserGroupID dece:UserGroupID-type

AccountID Reference to the account information for this UserGroup. User may be in multiple accounts.

User User Data for each active user dece:UserGet-type 1..6

1.68.3.3 Behavior

A UserCreate-req is supplied via the request to the Coordinator. If all rules are met, the

Coordinator creates the User and returns a UserID. If rules are not met, an error is returned.

Only active users are returned. [CHS: Is this true for UI? If not, we’ll need data that shows

whether or not a user is active. Or, we can cheat and make it two calls: retrieve active, retrieve

inactive.]

1.68.3.4 Errors

• Unknown Account User Group, User.

• Invalid combination of Account, User Group, User

1.68.4 UserDelete()


This removes a User from a UserGroup and transitively from the Account. The user is flagged

as deleted, rather than completely removed to provide audit trail and to allow Customer Support

to correct.



[CHS: What happens if the orphan user tries to log in? Can they use their existence to create a

new, separate account? Perhaps we should have actions as part of delete such as “Delete and

Create new account” or “Delete and move to another account.”]


Path:

[BaseURL]/Account/{AccountID}/UserGroup/{UserGroupID}/User/{UserID}

Method: DELETE



[CHS: Possible attributes for what do with the User, ?=move…]

Request Body: None

Response Body: ResponseStandard-type

1.68.4.3 Requester Behavior

Coordinator updates status to reflect deletion.

If the User is the last administrator on the account, request will fail.

[CHS: What happens if this is the last user on the account?]

[CHS: Do we have controls on this?]

1.68.4.4 Errors

• Unknown Account User Group, User.

• Invalid combination of Account, User Group, User

• User is last administrator, another must be assigned prior to deletion



1.68.5 UserDataGet(), UserDataSet(), UserDataDelete()


This API is used to create, modify, retrieve or delete User descriptive information. There are

variations on the basic request access subsets of the total data set.


The following are used to retrieve, update and in some cases delete User elements. Except as

noted, all APIs behave the same, except for the data passed or returned.

1.68.5.2.1 Name

Name is the User’s name.

Path:

[BaseURL]/User/<UserID>/name

Method: GET | PUT

Authorized Role(s): Retailer , UI

1.68.5.2.1.1 Request

GET Request Body: None

PUT Request Body: UserName-type

1.68.5.2.1.2 Response

GET Response Body: UserName-type [CHS: Need to turn this into a -resp including error]


1.68.5.2.1.3 Behavior

The GET request has no parameters and returns the name information for the account.

The PUT request updates the name information. There are not individual requests for each

subelement.




1.68.5.2.2 Contact

Contact is contact information for the User.

Path:

[BaseURL]/User/<UserID>/contact

Method: GET | PUT

Authorized Role(s): Retailer (GET only), UI (GET only), CS


Contact information is created at User Creation.

1.68.5.2.2.1 Request


PUT Request Body: ContactInfo-type

1.68.5.2.2.2 Response

GET Response Body: ContactInfo-type [CHS: Need to turn this into a -resp including error]


1.68.5.2.2.3 Behavior

The GET request has no parameters and returns the contact information for the account.

The PUT request updates the contact information. There are not individual requests for each

subelement.


1.68.5.2.3 Languages

One or more language may be listed for each User.

[CHS: This is set up to update the entire structure, but probably should be done to handle

individual languages. This will require the creation of UserLangage-type (singular).]

Path:



[BaseURL]/User/<UserID>/language

Method: GET | PUT



Language information (i.e., at least one primary language) is created at User Creation.

1.68.5.2.3.1 Request


PUT Request Body: dece:UserLanguages-type

1.68.5.2.3.2 Response

GET Response Body: dece:UserLanguages-type [CHS: Need to turn this into a -resp

including error]


1.68.5.2.3.3 Behavior

The GET request has no parameters and returns the languages for the User.

The PUT replaces the existing languages with new languages.


• Invalid languages

• No primary languages

• [CHS: maybe for duplicates and other structural errors.]

1.68.5.2.4 Adult

Adult is a single flag that indicates whether the User is and adult for the purposes of parental

controls.

Path:

[BaseURL]/User/<UserID>/adult



Method: GET | PUT


Any of the Roles may get information. Only Customer Support may modify information. Adult

information is created at User Creation.

1.68.5.2.4.1 Request


PUT Request Body: UserAdult-type

1.68.5.2.4.2 Response

GET Response Body: UserAdult-type [CHS: Need to turn this into a -resp including error]


1.68.5.2.4.3 Behavior

The GET request has no parameters and returns the Adult flag for the User.

The PUT request updates the Adult flag.


1.68.5.2.5 Ratings

Zero or more language may be listed for each User.

[CHS: This is set up to update the entire structure, but probably should be done to handle

individual ratings. General information and list of “AllowedRating” should be separated to do

this.]

Path:

[BaseURL]/User/<UserID>/rating

Method: GET | PUT


Any of the Roles may get information. Only Customer Support may modify information. Rating

information is optional.



1.68.5.2.5.1 Request


PUT Request Body: dece:Ratings-type

1.68.5.2.5.2 Response

GET Response Body: dece:Ratings-type [CHS: Need to turn this into a -resp including error]


1.68.5.2.5.3 Behavior

The GET request has no parameters and returns the ratings for the User.

The PUT replaces the existing ratings with new ratings.


• Invalid ratings

• [CHS: maybe for duplicates and other structural errors.]

1.68.5.2.6 Credentials

[TBS]

1.68.6 InviteUser()

[CHS: Need to find use case on this…]

1.68.7 CheckUserIDAvailability()

[CHS: We haven’t defined user IDs. If ID is email, this doesn’t really apply.]

1.69User Types

This is the top-level type for DECE Users.

1.69.1 UserData-type




UserData-type

Name Name information (same as used for Metadata)

md:PersonName-type

UserGroupID Reference to the User Group information for this User. User may be in multiple User Groups. [CHS: Do we need provisions for 0 accounts (e.g., while building account)?]

ContactInfo Contact information See UserContactInfo-type

languages Languages used by user See UserLanguages-type

Adult Indicates whether use should be treated as an adult with respect to parental control ADULT flag. true=yes.

xs:boolean

ParentalControls List of parental controls that are allowed for child user.

dece:UserParentalControls-type

0..1

1.69.2 User-type


User-type userData-type (extension)

UserID dece:UserID-type

Credentials Login information. [CHS: Might there be more than one login?]

dece:UserCredentials-type

Status Element status (e.g., is it active) dece:ElementStatus-type

1.69.3 UserCredentials-type

This is essentially a placeholder.




UserCredentials-

type

username User’s username xs:string

password Password associated with username xs:string

1.69.4 UserContactInfo-type

How user may be reached.


UserContactInfo-type

PrimaryEmail Primary email address for user. xs:string

AlternateEmail Alternate email addresses, if any xs:string 0..n

Address Mail address xs:string 0..1

Phone Phone number. Use international (i.e., +1 …) format.

xs:string 0..1

1.69.5 UserLanguages-type

Specifies which languages users prefers.

Language should be preferred if the “primary” attribute is “TRUE”. Any language marked

primary should be preferred to languages whose “primary” attribute is missing or “FALSE”.

At least one language must be specified.


UserLanguages-

type

language User’s language. [CHS: Should we use XML’s language (RFC 3066) or something else?]

xs:language 1..n



primary If “TRUE” language is the primary language.

xs:boolean 0..1

1.69.6 UserParentalControls-type

This element provides account managers (parents) control across all content within the account

for a other users (children). The data is intended to be interpreted as follows (References are to

Technical Specification Parental Controls, v0.5):

• Any content-specific overrides come first. CHS: Are content-specific overrides V1 or

V2?

• If content is rated

o AllowedRating, if matching content rating, comes next. CHS: Need to define

what happens if there are multiple ratings that conflict—do we need a flag for

“most constrained” versus “most lenient”? Ref: 2.1.1.1

o Next, if UseAgeAsDefault is true, the user will be allowed to access content for

which their age satisfies parental control criteria. For example, a 14 year old

can access content restructured through 13 year olds. CHS: Need to define

how this works within conflicts.

• If content is unrated (Ref: 2.1.1.2)

o If BlockUnrated is true, block

o If BlockUnrated is fales, allow

Users are granted or denied certain rights in retail offerings based on parental controls:

• If HideRestrictedContent is set to TRUE, content that is not within their ratings will not

be visible to the user in a retail situation. (ref: 2.1.2 (3)(a))

• If NoPurchaseRestrictiedContent is set to True, the user will not be allowed to purchase

content that is not compatible with their rating? If HideRestrictedContent is set to TRUE,

this should be set to TRUE. Ref: 2.1.2 (3)(b).

• CHS, regarding 2.1.2 (3)(c), I don’t know what this means, so it’s not covered here.

Element Attribut

e

Definition Value Card

.



UserParentalControls-

type

BlockUnrated Should unrated content be blocked by default? True=Yes. This may be overridden by specific exception stated by parent (CHS: V2?)

xs:boolean

UseAgeAsDefault Should the user’s age be the default criterion for determining whether content is viewable? True=yes.

xs:boolean

birthdate

Birthdate to use for age calculations

xs:date 0..1

AllowedRating Rating Matrix that lists what ratings a view may view. This is optional, and will likely not be exposed in DECE version 1.

dece::ContentPCRAtingsMatrix-typeCHS: This type indirectly provides for a parent to allow adult content to be accessed by a minor. I don’t know if we should allow this, exclude it in XML or specify this for the implementation.

0..1

HideRestrictedContent Should content that is not compatible with the child’s rating be viewable in retail? TRUE=Hidden

xs:boolean

NoPurchaseRestrictedContent

Should content that is not compatible with child’s rating be blocked from purchase by that child? True=not purchasable.

xs:boolean

ParentalControlPIN PIN for overriding parental controls. Ref 2.1.2(4). CHS: I’m not sure it this is a per-child or a per-account basis. As it does not

xs:int



function in devices, I don’t really see why it’s here at all.

1.69.7 UserAccessList-type

This element provides for either an inclusion list or exclusion list. With an inclusion list, only

those in the list are given access. With an exclusion list, those on the list are denied access, but

all others are given access.

InclusionList and ExclusionList are an XML choice.


UserAccessList-

type

UserInclusionList List of those allowed access dece:UserList-type

UserExclusionList List of those denied access dece:UserList-type

1.69.8 UserList-type

This construct provides a list of users


UserList-type

User A user dece:UserID-type 1..n

1.70User Group Types

1.70.1 UserGroup-type


UserGroup-type

UserGroupID dece:UserGroupID-type



AccountID Reference to the account information for this UserGroup. User may be in multiple accounts.

User DECE User dece:UserID-type 1..6

Status Element status dece:ElementStatus

1.71Node Management

Nodes are instantiations of Roles. Nodes are known to the Coordinator and must be

authenticated to perform Role functions. This sections addresses Roles other than DRMClient

and Coordinator.

Nodes are only created as and administrative function of the DECE LLC and must be consistent

with the business and legal agreements.

Nodes covered by these APIs include. APIs below reference to <role> refers to this table.

Role <role>

Retailer rtr

Linked LASP llp

Dynamic LASP dlp

DSP dsp

Customer

Support

csp

User Interface usi

Currently, only one instance of the Coordinator exists. DRM Clients are handled under DRM

Client [REF].

1.72Node Functions

Nodes are created through administrative functions. This is highly sensitive and will therefore

be highly controlled. The Access Control on these APIs is [TBD]. [CHS: We might determine

that these are abstract and have no REST APIs.]

The purpose of Node Functions is to supply the Coordinator with information about the Node.

Once the Node function is executed, the Node may access the Coordinator in accordance with

the access privileges associated with that Node type.



1.72.1 NodeCreate, NodeUpdate

Node functions apply to All Node functions have the same form.


This is the means that Node information is entered into the Coordinator. It also activates the

Node.





Path:

[BaseURL]/Node

Method: POST | PUT

Authorized Role(s): Coordinator?


Request Body:


NodeCreate-req dece:NodeInfo-type (extension)


1.72.1.3 Behavior

With a POST, Node is created. Within some period of time [TBD] the Node becomes active.

With a PUT, an existing node identified by ID attribute in the CreateNote-req is replaced by the

new information. The Coordinator keeps a complete audit of behavior. [CHS: I’m not sure how

this will be implemented, so I’m adding all the little functions like updating POCs. Overall it’s

quite risky the way it is and implementers will want to consider other options.]



1.72.1.4 Errors

• [CHS: Note sure what can go wrong here. This is a fairly special API, so the

only errors I can think of is a malformed request.]

1.72.2 NodeDelete

Nodes cannot simple be deleted as in many cases User experience may be affected and

portions of the ecosystem may not operate correctly.


This is the means that Node information is entered into the Coordinator. It also activates the

Node.





Path:

[BaseURL]/Node/{orgID}

Method: DELETE

Authorized Role(s): Coordinator?

Request Parameters: {orgID} is the ID for the organization to be deleted

Request Body: None


1.72.2.3 Behavior

The Node is deactivated. Access to the Node is terminated, including existing connections.

1.72.2.4 Errors

• [CHS: Note sure what can go wrong here. This is a fairly special API, so the

only errors I can think of is a malformed request.]



1.73Node Types

This is general information on a retailer. It is required to display retailer information along with

rights information and to refer a rights purchaser back to the purchaser’s web site.

[CHS: we need some mechanism for referring to alternate retailers if a retailer shuts its doors.]

1.73.1 NodeInfo-type


NodeInfo-type Dece:OrgInfo-type (extension)

Role Role(s) associated with the Node xs:string<role> above

1..7

Credentials Binary credentials in conformance with access model

Xs:base64Binary

1.73.2 OrgInfo-type


OrgInfo-type

ID Unique identifier for organization defined by DECE.

md:orgID-type

Name User-friendly display name for retailer [CHS: do we need to include multiple languages or otherwise regionalize?] [CHS: Internationalize]

xs:string

PrimaryPOC Primary name, addresses, phones and emails for contact

md:ContactInfo-type

OtherPOC Other names, addresses, phones and emails for contact

md:ContactInfo-type

Website Link to retailer’s top-level page. [CHS: multiple links? If so, how does one decide which one to use?]

xs:anyURI



Logo Reference to retailer logo image. [CHS: we need to restrain types and sizes.]

xs:anyURI 0..1

1.73.3 Disc Burn

Disk burn is the process of creating a physical instantiation of a Logical Asset in the Rights

Locker. Initially, this refers to creating a CSS-protected DVD burned in accordance with DECE

rules. The specification is designed for some generality to support future creation of other

media.

1.74Overview

A disc burn is DECE export to a physical media-based DRM such as CSS. The target DRM

system has rights outside the knowledge of DECE, for example, DVD discs have region codes,

and different output protections may be required (such as anti-rip technologies in conjunction

with CSS, or particular watermark technologies may be required to be applied). Those additional

rights are defined by DECE in xxx specification [CHS/JT: TBD whether content provider, DECE

or some combination defines the rules].

1.75Burn Image and License

A DECE User must possess a Burn Image Container and a suitable Burn License to burn a

DVD.

1.75.1 Burn Image Container

A “Burn Image Container” is a DRM-protected Physical Asset that containing image in one of

the following formats as defined in xxx:

• DVD Forum “DVD-Download Version 1.0”

• DVD Forum “DVD-Download for Dual Layer Version 2.0”

The image is encrypted. This image is distributed to DECE DSPs in accordance with xxx

specification.

ISO should be in DVD Forum’s Download format, AES-encrypted with DECE Common

Container format, but not DRM-specific. [JT: Need to decide how decryption key is passed to

burn client. Need robustness specs to limit in-the-clear content during conversion from common

container to CSS-protected disc.]



1.75.2 ISO Encryption/Decryption and CSS Burn Authorization

[CHS: Is this one thing or two? Do they go in the container, or are the delivered

separately?]ISO Decryption [Need to talk about this.] A CSS Burn Authorization is information

required by the burning hardware and software to create a valid recordable CSS DVD.

Information in a Burn License is provided by an approved CSS Auth Server [cite]. The Burn

License has information that can be used to ensure the retailer [I don’t think we really mean

retailer here] has valid contracts in place for the output technologies purchased, issue CSS keys

bound to the particular media being burned, that the copy count has not been exceeded, the

DVD region code is correct, Macrovision ACP is preserved, the retailer or the client software

hasn’t been revoked and is up to the required security patch level, and that media defects are

correctly handled as required by the content owner and retailer,b etc.

A DRM License is a license for a DECE Approved DRM system that contains information that

allows the content in the Burn Image Container to be accessed for the purposes of burning.

1.76Burn Software and Hardware

A DECE User must have software and hardware compliant with [CITE] to burn a CSS DVD.

This may be available in the form of suitable software, computer and burning drive under the

user’s control, or it can be a 3rd party such as a retailer.

1.77Disk Burn Process (Home Burn)

1.77.1 Container Download

Prior to delivering a Burn Image Container to a User, the DSP must

• Verify that the user has a right to the content

• Determine whether a burn right exists and put a hold on the right.

• Obtain CSS Burn Authorization information

• Consume a burn right from that user

The DSP verifies content rights the same as for other content [cite].

The DSP must verify that the user has a burn right and that burn right must be consumed prior

to delivering a Burn Image Container to a User. This is done with the BurnRightHold() call.



The DSP must obtain Burn License information. If it obtains it correctly, the DSP then uses

BurnRightConsume() to consume the right. If license acquisition is unsuccessful,

BurnRightRelease() is used to return the burn right.

Note that the model of holding the right then either consuming it or releasing it is designed to

avoid the race condition where two entities are in the burn process simultaneously.

Delivery of the Burn Image Container is specified by DECE as part of the DSP Specification

<<CITE>> [CHS/JT: TBD]

The burn process must be in accordance with [xxx], but is otherwise not specified by DECE.

1.78Disk Burn Process (Retail Burn)

[TBD: Jim T]

1.79Burn Right Functions

[Summary TBS]

1.79.1 BurnRightHold()


This API is used to reserve a burn right. It is used by a DSP to reserve the burn right.


Path:

[BaseURL]/Account/{AccountID}/BurnRequest/{RTID}/{Profile}

Method: POST

Authorized Role(s): DSP

Request Parameters:

{RTID} refers to the rights token that holds the burn right

{Profile} contains the profile that is desired to be burned. Currently the only valid entry is

“ISO”, but in the future this may be other profiles.

Request Body: Null



Response Body:


BurnRightHold-

resp

Timeout Period right will be held. xs:dateTime (Choice)

Error Error response on failure dece:ErrorResponse-type (Choice)

Timeout is the time in UTC at which the request will expire.

1.79.1.3 Requester Behavior

The requestor must only use BurnRightHold() when in the process of preparing for a burn.

It must be followed within the time specified as part of the response with either a

BurnRightRelease() or BurnRightConsume().

If a requestor needs to extent the time, a BurnRightRelease() may be followed by a new

BurnRightHold().

1.79.1.4 Responder Behavior

If the Account has a burn right as specified, success is returned by the Coordinator with a

timeout period.

If the timeout period is reached with no response from the requestor, the burn right is released

as with BurnRightRelease().

Note that excessive timeouts indicate a problem with a DSP or possibly fraud and should be

handled accordingly.

1.79.1.5 Errors

[TBS]



1.79.2 BurnRightRelease()

1.79.3 BurnRightDelete()

1.79.3.1 Behavior

1.79.4 BurnRightGet()

1.80Burn Right Data

1.80.1



Device Interface

[CHS: This section should be eliminated with its content going to three places: Intro up front.

Security as part of the API general interface (where other secure channel info goes), in each

API that applies.]

Users access DECE functions through the User Interface Role (UI) web interface. The Device

Interface is designed to provide a subset of that functionality to devices without a browser.

1.81Security

These services are offered through the same service mechanisms as the Coordinator, except

the Role is not authenticated. As there is no means to identify what is accessing this interface,

service access is controlled by User Authentication. Specifically,

• Services are offered via a TLS secured channel, without peer authentication

• HTTP Basic Authentication is used to identify and authenticate Users.

• No services will be provided to entities that do not correctly authenticate to a valid DECE

User.

1.82Functions provided through Device Interface

The following APIs are available to a device through the Portal:

• RightsLockerGet

• RightsDataGet

• RightsSummaryGet [CHS: Can metadata be merged in with this?]

• MetadataGet

• MetadtataPhysicalGet [CHS: This may not be needed.]

• DRMClientJoinTrigger()

• DRMClieintRemoveTrigger()

• [CHS: What others?]



Other

1.83ElementStatus-type

This is used to capture status of an element. Specifically, this will indicate whether an element

is deleted.

[CHS: I’m a little concerned that this might create bugs because it may be inactive, but not being

checked by the code. Should we add an “isActive” flag somewhere?]


ElementStatus-

type

Status Error response on failure xs:string“active”“deleted”“suspended”“other”

Date Period right will be held. xs:dateTime

ModifiedBy Organizational entity modifying md:orgID-type

Description Text description including any information about status change.

xs:string 0..1

History Historical tracking of status. dece:ElementStatus-type 0..n



Error

This section defines error responses to Coordinator API requests.

1.84Error Identification

Errors are uniquely identified by an integer.

1.85ResponseError-type

The ResponseError-type is used as part of each response element to describe error conditions.

This appears as an Error element.

ErrorID identifies the error condition returned. It is an integer uniquely assigned to that error.

Reason is a text description of the error in English. In the absence of more descriptive

information, this should be the Title of the error, where the Title is a description defined in this

document (Title column of error tables).

OriginalRequest is a string containing the exact XML from the request. [CHS: necessary?]


ResponseError-

type

ErrorID Error code xs:int

Reason Human readable explanation of reason xs:string

OriginalRequest Request that generated the error. This includes the URL but not information that may have been provided in the original HTTP request.

xs:string

ErrorLink URL for detailed explanation of error with possible self-help. [CHS: If this is for end-users, it will have to be localized. This could also be just for developers. Or we could include two strings, one for developers and one for end users.]

xs:anyURI (0..1)



1.86Common Errors

These are frequently occurring errors that are not listed explicitly in other sections of this

document.

ErrorID Title Description

Invalid or missing AccountID

Invalid or missing [CHS: for each ID type]

Mismatched AccountID and UserID UserID does not match Account

Mismatched <x ID> and <y ID> [CHS: For all possible mismatches]

Missing data [CHS: This is a generic one to cover cases of missing more specific messages]

User does not have privileges to take this action

This generally occurs when someone other than a full access user tries to do something that only a full access user may do.



Caching and Subscriptions

[CHS: Need to define caching mechanisms: a basic mechanism plus specific data that can be

cached. Example includes “all rights tokens sold by a Retaier” or “all devices in an account”.]


DECE Coordinator API Specification Inter… · dece coordinator api specification (draft) dece...

Documents

Transcript of DECE Coordinator API Specification Inter… · dece coordinator api specification (draft) dece...