How to write CAF Streaming Agents

This document gives guidance on how to create CAF Streaming Agents.

A streaming agent needs to be able to:

• Receive short-term keys, which provide short-term cryptographic context for protected data packets

• Use long-term keys and enforce usage rights such as the dates for which the subscription has been purchased and post-acquisition rights

Long-term decryption keys and usage rights are usually combined in a single Rights Object (RO). (There may be cases where there are no usage rights and where the long-term keys arrive separately, as in the case of the OMA BCAST SmartCard profile.) The Rights Object can arrive either through interactive channels or broadcast channels.

During run-time, a separate RO is generated if a user wishes to record. This RO does not have to correspond to a particular standard and details of the RO are decided by the licensee or partner implementing the agent.

For background information on CAF Streaming Agents, see CAF Streaming Agent overview.

Separating the streaming agent into client and server

As with all CAF agents, it is best to create a client-server boundary, which allows the CAF streaming agent to validate the capabilities of its users.

Only by using a client-server separation, and validating capabilities on all sensitive operations, can the agent ensure that a trusted DRM path is enforced. All operations that involve cryptographic operations and access to long-term and short-term keys must be considered sensitive. It is best to implement the parts of the agent that require access to encryption/decryption keys or rights in the CAF server-side streaming agent.

Both CAF streaming agent client-side and server-side are implemented by the agent's developer. (The Streaming CAF framework and key stream sinks are delivered and maintained by Symbian.)

The following guidelines are suggested for implementing client-server agents with streaming capabilities. Please note that this is a suggested design only and is not actively enforced by the system.

The client-side streaming agent should:

• Receive details of the key stream decoder

• Establish a connection with the agent server and get and set information for the server

• Marshall calls to the server side

The server-side streaming agent should:

• Allow retrieval of stream protection meta-data to authorised clients

• Push decoded keys to key stream sink

• Carry out any potentially destructive operations such as deleting rights

• Capability enforcement

Note: Whereas regular (file) CAF agents have access to the content, for streamed media, the CAF Streaming Agent has no access to the content.

Note that Symbian provides implementations of the key sink. Currently, only an IPSec implementation is available. SRTP and ISMACryp implementations are planned.

This documentation provides a summary explanation of the reference implementation in the following sections:

• Writing the server

• Writing the client

The reference implementation code is available at the following location: .../caf2/test/reftestagent/streamingrefagent.

To enable support of a particular streaming DRM scheme, the CAF streaming agent needs to implement CAgentKeyStreamDecoder and CStreamAgentFactory, which includes the IsKeyStreamSupportedL method to determine whether the stream agent supports the key management scheme specified in the SDP key stream definition.

The server needs to

1. Set up a key stream sink (details of which are sent by the client)

2. Process the relevant part of the SDP information (SDP is the session description protocol for communicating with publishers. It includes all the information that a device needs including port numbers and data types etc.)

3. Find and load the Rights Object (RO), details of which are found in the SDPMediaField of the SDP document

In the reference implementation, the sraserver.h, srasession.cpp (the session) and sraprocessor.cpp (the processor) files contain the code necessary to achieve these requirements. A CAF Streaming Agent's implementers may, however, implement the requirements as they choose.

The session

In the reference implementation, srasession.cpp carries out the following tasks:

• Defines the methods for starting and connecting to the server

• Calls the InternalizeLC() method, which creates the relevant key stream sink and sets the encryption and decryption algorithms for decrypting

The declaration for the CSraSession class is in sraserver.h.

In the reference code, the SetKeyStreamSinkL() method obtains a key stream sink from the client. The SetSdpMediaFieldL method sets the SDP key stream field coming from the client. The SetSdpDocumentL() method sets the SDP document object coming from the client.

The processor

In the reference implementation, the processor listens to predefined ports. When a key stream arrives at the port, it is decrypted and the decrypted key is sent to the application that decodes the data stream. It uses the long-term key, which is extracted from the Rights Object to decrypt. The processor provides the required information including the encryption key authentication key and the SPI (security parameter index). The processor currently supports only IPSec, but may be extended to support other protocol types.

The declaration for the CSraProcessor class is in sraprocessor.h.

In the reference code, the ProcessL() method does the following:

1. Reads a short-term key message

2. Creates a short-term key message object

3. Uses the short-term key message to create an IPSec key association object

4. Processes the new key association

The CAF streaming agent client, in this reference implementation, is used by the the key stream decoder (initialised by the streaming player middleware) to establish a connection with the CAF streaming agent server and to get and set information and objects from the connected server.

In the reference implementation discussed below, the client:

1. Connects to the CAF streaming agent server

2. Provides methods to get the value of a requested attribute or string attribute

3. Provides a file handle to get the post-delivery Rights Object the CAF streaming agent server

4. Sends a key stream sink object to the reference agent server

5. Provides methods to send SDP media field object data and SDP documents to the CAF streaming agent server

In the reference implementation, the declaration for the SraClient class is in sraclient.h.

The following methods implemented in the reference client, provide access to information including post-delivery rights from the server: GetAttributeL(), GetStringAttributeLC() and GetPostDeliveryRightsL().

The SendKeyStreamSinkL() method sends a key stream sink object to the CAF streaming agent server.

The SendSdpMediaFieldL() and SendSdpDocumentL() methods send SDP media field object data and SDP documents to the CAF streaming agent server.

For related information, see:

• Reference code at ... /caf2/test/reftestagent/streamingrefagent