1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/os/security/contentmgmt/contentaccessfwfordrm/engineering/dox/Architecture.dox	Fri Jun 15 03:10:57 2012 +0200
     1.3 @@ -0,0 +1,87 @@
     1.4 +// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
     1.5 +// All rights reserved.
     1.6 +// This component and the accompanying materials are made available
     1.7 +// under the terms of the License "Eclipse Public License v1.0"
     1.8 +// which accompanies this distribution, and is available
     1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
    1.10 +//
    1.11 +// Initial Contributors:
    1.12 +// Nokia Corporation - initial contribution.
    1.13 +//
    1.14 +// Contributors:
    1.15 +//
    1.16 +// Description:
    1.17 +// <hr>
    1.18 +// The Content Access Framework provides a common interface for applications to access content.
    1.19 +// In effect it behaves as a switch between different agents, known as Content Access Agents.
    1.20 +// Each agent is an ECOM plugin, which implements the Content Access Agent interface <code>0x10204740</code>. 
    1.21 +// This interface should be a static function that creates and returns an instance of a class derived 
    1.22 +// from <code>ContentAccess::CAgentFactory</code> (e.g. <code>ContentAccess::CF32AgentFactory</code>).
    1.23 +// <code>static CAgentFactory* AgentImplementationFunction();</code>
    1.24 +// for reading unprotected content files. If no other agent recognizes a file the F32 agent will be used
    1.25 +// to read it. In effect, this is the same as opening the file using an <code>RFile</code>, but allows the application
    1.26 +// to use the same code to read protected and unprotected content.
    1.27 +// The following diagram illustrates the implementation of CAF with two fictitious agents (OMA and MPEG).
    1.28 +// <hr>
    1.29 +// The problem with this implementation is that all three agents are loaded into the application's process space,
    1.30 +// which represents a security risk. The application could potentially access the key used to decrypt protected
    1.31 +// content.
    1.32 +// A better solution is to implement the parts of the agent that require access to encryption/decryption keys or
    1.33 +// rights in a separate server process. When platform security is enabled the server implementation also allows 
    1.34 +// the APIs to be policed by the agent server DLL to ensure only applcations with the right capabilities will 
    1.35 +// have access to the content.
    1.36 +// To improve performance any functionality that does not require access to keys or rights should be implemented
    1.37 +// in the client side DLL. Client side functionality reduces the number of context switches the processor needs 
    1.38 +// to perform resulting in improved performance from the agent.
    1.39 +// There is no need to implement the F32 agent in a server process since it is only used to access unprotected content.
    1.40 +// <hr>
    1.41 +// The following guidelines are suggested for implementing Client/Server agents, but may not be appropriate
    1.42 +// for all agents.
    1.43 +// <b> Client Side Functionality </b>
    1.44 +// - Implement the Content Access Agent ECOM interface
    1.45 +// - Browse the contents of files
    1.46 +// - Retrieve attributes or meta-data from a file
    1.47 +// - All functions requiring the agent to display a user interface or dialog
    1.48 +// - File recognition (for client applications and Apparc MIME types)
    1.49 +// - Marshall calls to the server side
    1.50 +// <b> Server Side Functionality </b>
    1.51 +// - Content Encryption (protecting plaintext)
    1.52 +// - Content Decryption (reading DRM content)
    1.53 +// - Manage, protect and store Rights
    1.54 +// - Any potentially destructive operation such as deleting content or rights
    1.55 +// - Notifications
    1.56 +// - Capability Enforcement
    1.57 +// <hr>
    1.58 +// The APIs provided in this document indicate the functions that are likely to require a client
    1.59 +// process to have DRM capability in order to use the functionality. The client process will only 
    1.60 +// need DRM capability if it attempts to read DRM content using an CAF agent that implements a DRM
    1.61 +// protection scheme. 
    1.62 +// The capability can only be enforced by the CAF agent running in a separate server process, so it is the responsibility
    1.63 +// of the agent to ensure the client process has the required capabilities.
    1.64 +// <b>There are no capabilities required to use unprotected content.</b>
    1.65 +// <hr>
    1.66 +// CAF is used to read unprotected or DRM protected content. It is a client side DLL that must be linked with
    1.67 +// the process using CAF. 
    1.68 +// The agents may run in separate processes and will not have the correct capabilities to open files in TCB or 
    1.69 +// server private directories using just a file name. These files must be opened by the process that owns the 
    1.70 +// file and an open \c RFile handle passed to CAF in order to read them.
    1.71 +// <hr>
    1.72 +// 
    1.73 +//
    1.74 +
    1.75 +/**
    1.76 + @page CAFArchitecture Architecture
    1.77 + - @ref ArchOverview
    1.78 + - @ref CAFClientServer
    1.79 + - @ref ClientServerImplementation 
    1.80 + - @ref CAFCapability
    1.81 + - @ref UsingCAF
    1.82 + @section ArchOverview Overview
    1.83 + There is a special agent supplied by Symbian known as the @ref AboutF32Agent "F32Agent". This agent is used as a fallback 
    1.84 + @image html Architecture1.gif
    1.85 + @section CAFClientServer Client / Server Agents
    1.86 + @image html Architecture2.gif
    1.87 + @section ClientServerImplementation Client / Server implementation guidelines
    1.88 + @section CAFCapability DRM Capability
    1.89 + @section UsingCAF Using CAF to read from other server private directories
    1.90 +*/