--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/drm_plat/drm_legacy_api/inc/DRMRightsClient.h Thu Dec 17 08:52:27 2009 +0200
@@ -0,0 +1,731 @@
+/*
+* Copyright (c) 2003-2005 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: This class is the client side handle of DRM Engine
+*
+*/
+
+
+
+#ifndef RDRMRIGHTSCLIENT_H
+#define RDRMRIGHTSCLIENT_H
+
+// INCLUDES
+#include <e32std.h>
+#include <Oma2Agent.h>
+#include <DRMTypes.h>
+
+using namespace ContentAccess;
+
+// CONSTANTS
+// MACROS
+
+// DATA TYPES
+// FUNCTION PROTOTYPES
+// FORWARD DECLARATIONS
+class RFs;
+class CDRMPermission;
+
+// CLASS DECLARATION
+
+/**
+* This class is the client side interface for DRM3 Rights Server.
+* This class can be used to access the DRM Rights Database.
+*
+* @lib DRM Core
+* @since S60 Release 2.5
+*/
+class RDRMRightsClient : public RSessionBase
+ {
+ public: // Constructor & destructor
+ /**
+ * C++ default constructor.
+ */
+ IMPORT_C RDRMRightsClient();
+
+ /**
+ * Destructor.
+ */
+ IMPORT_C virtual ~RDRMRightsClient();
+
+ /**
+ * This method opens the connection between the client and the server.
+ * @since 2.5
+ * @return Error code. KErrNone if the operation is successful.
+ */
+ IMPORT_C TInt Connect();
+
+ /**
+ * This function closes the connection between the client and the server.
+ * It is safe to call this method even if connection is not established.
+ * @since S60Rel2.5
+ */
+ IMPORT_C void Close();
+
+ public: // New functions
+
+ /**
+ * Starts the rights server in case it is not yet started. It is
+ * safe to call this method even if the server is running.
+ * @since S60Rel3.0
+ * @return Symbian OS error code if any.
+ */
+ IMPORT_C static TInt StartServer();
+
+ /**
+ * Adds the given rights object into rights database.
+ * @since S60Rel2.5
+ * @param aCEK CEK.
+ * @param aRightsObject Rights object to be added.
+ * @param aCID Content-ID.
+ * @return Error code.
+ */
+ IMPORT_C TInt AddRecord(
+ const TDesC8& aCEK,
+ const CDRMPermission& aRightsObject,
+ const TDesC8& aCID,
+ TDRMUniqueID& aID );
+
+ /**
+ * Adds a protected RO where the CEK wrapped with another key.
+ * @since 3.0
+ * @param aProtectedCek wrapped CEK
+ * @param aDomainPermission Domain or regular permission
+ * @param aRightsObject Rights object to be added.
+ * @param aCID Content-ID.
+ * @return Error code.
+ */
+
+ IMPORT_C TInt AddProtectedRecord(
+ const TDesC8& aProtectedCek,
+ TBool aDomainRecord,
+ const CDRMPermission& aRightsObject,
+ const TDesC8& aCID,
+ TDRMUniqueID& aID ); // Unique ID, out-parameter
+
+ /**
+ * Gets all database entries related to specified Content-ID.
+ * @since S60Rel2.5
+ * @param aId Content ID.
+ * @param aRightsList List of rights objects.
+ */
+ IMPORT_C void GetDBEntriesL(
+ const TDesC8& aId,
+ RPointerArray< CDRMPermission >& aRightsList );
+
+ /**
+ * Gets a database entry related to given content ID and unique ID.
+ * @since S60Rel2.5
+ * @param aContentID Content-ID.
+ * @param aUniqueID Unique identifier.
+ * @return Associated rights object.
+ */
+ IMPORT_C CDRMPermission* GetDbEntryL(
+ const TDesC8& aContentID,
+ const TDRMUniqueID& aUniqueID );
+
+ /**
+ * Deletes all rights objects with specified Content-ID.
+ * @since S60Rel2.5
+ * @param aContentID Content-ID of the rights objects to be deleted.
+ * @return Error code. KErrNone if successful.
+ */
+ IMPORT_C TInt DeleteDbEntry( const TDesC8& aContentID );
+
+ /**
+ * Deletes one rights object, identified by Content-ID and unique ID.
+ * @since S60Rel2.5
+ * @param aContentID Content-ID of the rights object.
+ * @param aUniqueID Unique ID.
+ * @return Error code. KErrNone if successful operation.
+ */
+ IMPORT_C TInt DeleteDbEntry(
+ const TDesC8& aContentID,
+ const TDRMUniqueID& aUniqueID );
+
+ /**
+ * Exports all content ID's from the database to a file.
+ * @since S60Rel2.5
+ * @param aFileName Out-parameter: contains the name of the file
+ * if the method completes with KErrNone. The
+ * descriptor parameter is assumed to be large
+ * enough. The caller is responsible of deleting
+ * the file afterwards.
+ * @return Error code. KErrNone if successful operation.
+ */
+ IMPORT_C TInt ExportContentIDList( TDes& aFileName );
+
+ /**
+ * This method exports all Content-IDs from the database file
+ * in an array. The caller is responsible of destroying the array
+ * afterwards.
+ * @since S60Rel2.5
+ * @param aCIDList An out-parameter: contains the Content-IDs
+ * after successful return.
+ * @return A Symbian OS error code or DRM3 error code. KErrNone in
+ * successful operation.
+ */
+ IMPORT_C TInt ExportContentIDList( RPointerArray< HBufC8 >& aCIDList );
+
+ /**
+ * Returns the decryption key to the content.
+ *
+ * @since 2.5
+ * @param aIntent In-parameter: How the content is going to be consumed.
+ * @param aContentID Content-ID of the related content.
+ * @param aKey Out-parameter: Contains the key if function returns
+ * successfully.
+ * @return Error code. KErrNone if successful operation.
+ */
+ IMPORT_C TInt GetDecryptionKey(
+ const TInt aIntent,
+ const TDesC8& aContentID,
+ TDes8& aKey );
+
+ /**
+ * This method checks whether the caller has sufficient rights over
+ * the content at this very moment.
+ * @param aIntent Intended usage.
+ * @param aContentID Content-ID.
+ * @return KErrNone in successful
+ * completition.
+ */
+ IMPORT_C TInt CheckRights(
+ const TInt aIntent,
+ const TDesC8& aContentID,
+ TUint32& aRejection );
+
+ /**
+ * This method checks whether the caller has sufficient rights over
+ * the content at this very moment. It also returns the active rights.
+ * @param aIntent Intended usage.
+ * @param aContentID Content-ID.
+ * @return Permission for the intent. NULL if no permissions exist
+ * completition.
+ */
+ IMPORT_C CDRMPermission* GetActiveRightsL(
+ const TInt aIntent,
+ const TDesC8& aContentID,
+ TUint32& aRejection );
+
+ /**
+ * Sets the key for subsequent encryption and decryption operations.
+ * The key is stored on the server side in the session and will
+ * be usable until the session is closed. The key will be fetched
+ * from the rights database by looking up the content ID.
+ *
+ * @param aContentId Content ID to get the key for
+ * @return KErrNone if the key was initialized properly
+ */
+ IMPORT_C TInt InitializeKey( const TDesC8& aContentId );
+
+ /**
+ * Similar to InitializeKeyL, but sets the key by using a group
+ * key as the input.
+ *
+ * @param aContentId Group ID to get the key for
+ * @param aGroupKey Group key
+ * @param aEncryptionMethod encryption method
+ * @return KErrNone if the key was initialized properly
+ */
+ IMPORT_C TInt InitializeGroupKey(
+ const TDesC8& aGroupId,
+ const TDesC8& aGroupKey,
+ TEncryptionMethod aMethod );
+
+ /**
+ * Encrypts data using the session key. The data parameter must
+ * have enough space to accomodate for the addition of the paddding
+ * if it shall be added (up to 32 bytes more data)
+ *
+ * @param aIv AES CBC initialization vector
+ * @param aData data to be encrypted, encrypted data on return
+ * @return KErrNone if the encryption succeeded
+ */
+ IMPORT_C TInt Encrypt(
+ const TDesC8& aIv,
+ TPtr8& aData,
+ TBool aAddPadding = EFalse );
+
+ /**
+ * Decrypts data using the session key. Padding will be removed
+ * if requested.
+ *
+ * @param aIv AES CBC initialization vector
+ * @param aData data to be encrypted, encrypted data on return
+ * @return KErrNone if the encryption succeeded
+ */
+ IMPORT_C TInt Decrypt(
+ const TDesC8& aIv,
+ TPtr8& aData,
+ TBool aRemovePadding = EFalse );
+ /**
+ * Returns the amount of unique URIs in the database.
+ * @since 2.5
+ * @return => 0: Amount of ROs,
+ * < 0 : error.
+ */
+ IMPORT_C TInt Count();
+
+ /**
+ * Empties the rights database totally.
+ * @since 2.5
+ * @return Symbian OS / DRM3 wide error code.
+ */
+ IMPORT_C TInt DeleteAll();
+
+ /**
+ * Consume the right with specific contentID and intent
+ * @since 2.5
+ * @return Symbian OS / DRM3 wide error code.
+ */
+ IMPORT_C TInt Consume(
+ const TInt aIntent,
+ const TDesC8& aContentID);
+
+ /**
+ * Check if Consume is possible. Does not consume rights.
+ * @since 3.0
+ * @return KErrNone if Consume is possible
+ */
+ IMPORT_C TInt CheckConsume(
+ const TInt aIntent,
+ const TDesC8& aContentID);
+
+ /**
+ * Calculate the padding amount for a data block
+ * @since 3.0
+ * @return The padding value
+ */
+ IMPORT_C TInt CalculatePadding(
+ const TDesC8& aLastTwoDataBlocks);
+
+ IMPORT_C TInt ForwardLockURI( HBufC8*& aURI );
+
+ /**
+ * AddDomainRO
+ *
+ * Add the xml representation of the domain RO to the database
+ *
+ * @param aRoId : the rights object id of the domain ro
+ * @param aXmlData : the xml data of the rights object
+ * @return Symbian OS error code
+ */
+ IMPORT_C TInt AddDomainRO(
+ const TDesC8& aRoId,
+ const TDesC8& aXmlData );
+
+ /**
+ * GetDomainROL
+ *
+ * Get the xml representation of the domain RO from the database
+ *
+ * @param aRoId : the rights object id of the domain ro
+ * @return Functional RO xml representation or Leave with
+ * Symbian OS error code
+ */
+ IMPORT_C HBufC8* GetDomainROL( const TDesC8& aRoId );
+
+ /**
+ * GetDomainRoForCidL
+ *
+ * Get the domain RO for a content ID from the database
+ *
+ * @param aContentId the content ID of the domain ro
+ * @param aRoList list of domain rights objects for this ID
+ * @return Symbian OS error code
+ */
+ IMPORT_C void GetDomainRosForCidL(
+ const TDesC8& aContentId,
+ RPointerArray<HBufC8>& aRoList );
+
+ /**
+ * DeleteDomainRO
+ *
+ * Delete the xml representation of the domain RO from the database
+ *
+ * @param aRoId : the rights object id of the domain ro
+ * @return Symbian OS error code
+ */
+ IMPORT_C TInt DeleteDomainRO( const TDesC8& aRoId );
+
+ /**
+ * IsInReplayCache
+ *
+ * Checks whether the protected RO identified by aID and aTime
+ * has already been added to Replay Cache.
+ *
+ * @param aID: rights ID
+ * @param aTime: RO timestamp
+ * @param aInCache: out-parameter: boolean result
+ * @return Symbian OS error code
+ */
+ IMPORT_C TInt IsInCache( const TDesC8& aID,
+ const TTime& aTime,
+ TBool& aInCache );
+
+ /**
+ * IsInReplayCache
+ *
+ * Checks whether the protected RO identified by aID
+ * has already been added to Replay Cache.
+ *
+ * @param aID: rights ID
+ * param aInCache: out-parameter: boolean result
+ * @return Symbian OS error code
+ */
+ IMPORT_C TInt IsInCache( const TDesC8& aID,
+ TBool& aInCache );
+
+ /**
+ * AddToReplayCache
+ *
+ * Adds an entry to Replay Cache.
+ * Note! Does not check whether the entry is already in cache. Use
+ * IsInCache() first to determine whether the entry already exists.
+ *
+ * @param aID: RO ID
+ * @param aTIme: RO timestamp
+ * @return Symbian OS error code.
+ */
+ IMPORT_C TInt AddToCache( const TDesC8& aID,
+ const TTime& aTime );
+
+ /**
+ * AddToReplayCache
+ *
+ * Adds an entry to Replay Cache.
+ * Note! Does not check whether the entry is already in cache. Use
+ * IsInCache() first to determine whether the entry already exists.
+ *
+ * @param aID: RO ID
+ * @return Symbian OS error code.
+ */
+ IMPORT_C TInt AddToCache( const TDesC8& aID );
+
+ /**
+ * DeleteExpiredPermissions
+ *
+ * Deletes expired permissions from the rights database
+ * Note this function will possibly take a lot of time to complete
+ * and if the drm time is not available it does not touch any time
+ * based rights
+ *
+ * @param aStatus: asynchronous request status
+ * @return none
+ */
+ IMPORT_C void DeleteExpiredPermissions( TRequestStatus& aStatus );
+
+ /**
+ * SetEstimatedArrival
+ *
+ * Sets the time in which the rights object should arrive
+ *
+ * @since 3.0
+ * @param aContentID : content URI
+ * @param aDeltaSeconds : time in seconds to wait for rights
+ * @return Symbian OS error code if any.
+ */
+ IMPORT_C TInt SetEstimatedArrival( const TDesC8& aContentID,
+ TTimeIntervalSeconds aDeltaSeconds );
+
+ /**
+ * GetEstimatedArrival
+ *
+ * Gets the time in which the rights object should arrive
+ *
+ * @since 3.0
+ * @param aContentID : content URI
+ * @param aDeltaSeconds : time in seconds to wait for rights
+ * -1 if the content should have arrived
+ * @return Symbian OS error code if any.
+ * KErrNotFound if the content is not in the list
+ */
+ IMPORT_C TInt GetEstimatedArrival( const TDesC8& aContentID,
+ TTimeIntervalSeconds& aDeltaSeconds );
+
+
+ /**
+ * SetName
+ *
+ * Associates a human-readable name to given content-ID.
+ *
+ * @since 3.0
+ * @param aContentID: Content URI.
+ * @param aName: New name.
+ * @return Symbian OS error code if any
+ */
+ IMPORT_C TInt SetName( const TDesC8& aContentID,
+ const TDesC& aName );
+
+ /**
+ * GetName
+ *
+ * Retrieves the human-readable name associated to given content-ID
+ *
+ * @since 3.0
+ * @param aContentID: Content URI.
+ * @param aName: Out-parameter: The name associated to content.
+ * @return Symbian OS error code if any. KErrNotFound in case the
+ * content URI is not in the database.
+ */
+ IMPORT_C TInt GetName( const TDesC8& aContentID,
+ HBufC*& aName );
+
+ /**
+ * Cancel
+ *
+ * Cancel any asynchronous operation.
+ *
+ * @since 3.0
+ */
+ IMPORT_C void Cancel();
+
+ /**
+ * GetUdtData
+ *
+ * Retrieves the udt data from the server
+ *
+ * @since 3.0
+ * @param aUdtData: the udt data
+ * @return Symbian OS error code if any. KErrNotFound in case the
+ * content URI is not in the database.
+ */
+ IMPORT_C TInt GetUdtData( TDes8& aUdtData );
+
+ /**
+ * InitializeUdt
+ *
+ * Initializes the user data transfer
+ *
+ * @since 3.0
+ * @param aKey : Encryption key of the udt file encrypted with the
+ * device public key
+ * @return Symbian OS error code if any. KErrNotFound in case the
+ * content URI is not in the database.
+ */
+ IMPORT_C TInt InitiateUdt( const TDesC8& aKey );
+
+
+ /**
+ * Initializes the export all orphaned content ID's.
+ * When the request completes, you can ask for the
+ * contents with the ExportOrphanedContentIdList functions
+ *
+ * @since 3.0
+ * @param aPerformScan : ETrue if file system scan needs to be
+ * performed
+ * EFalse if not
+ * @param aStatus : Request status for the asynchronous call
+ * @return None
+ */
+ IMPORT_C void InitOrphanedContentIdList( TBool aPerformScan,
+ TRequestStatus& aStatus );
+
+
+ /**
+ * Exports all orphaned content ID's from the database to a file.
+ * @since 3.0
+ * @param aFileName Out-parameter: contains the name of the file
+ * if the method completes with KErrNone. The
+ * descriptor parameter is assumed to be large
+ * enough. The caller is responsible of deleting
+ * the file afterwards.
+ * @param aPerformScan : ETrue if file system scan needs to be
+ * performed
+ * EFalse if not
+ * @return Error code. KErrNone if successful operation.
+ */
+ IMPORT_C TInt ExportOrphanedContentIdList( TDes& aFileName );
+
+ /**
+ * Exports all orphaned content ID's from the database
+ * in an array. The caller is responsible of destroying the array
+ * afterwards.
+ * @since 3.0
+ * @param aContentIdList : An out-parameter: contains the Content-IDs
+ * after successful return.
+ * @param aPerformScan : ETrue if file system scan needs to be
+ * performed
+ * EFalse if not
+ * @return A Symbian OS error code or DRM error code. KErrNone in
+ * successful operation.
+ */
+ IMPORT_C TInt ExportOrphanedContentIdList(
+ RPointerArray<HBufC8>& aContentIdList);
+
+ IMPORT_C TInt EncodeRightsIssuerField( const TDesC8& aOldValue,
+ HBufC8*& aNewValue );
+
+ IMPORT_C TInt DecodeRightsIssuerField( const TDesC8& aEncoded,
+ HBufC8*& aDecoded );
+
+ /**
+ * Sets the authentication seed data for a content ID
+ * @since 3.0
+ * @param aContentID Content ID
+ * @param aSeed Authentication seed
+ * @return Error code. KErrNone if successful operation.
+ */
+ IMPORT_C TInt SetAuthenticationSeed( const TDesC8& aContentId,
+ const TDesC8& aSeed );
+
+ /**
+ * GSets the authentication seed data for a content ID
+ * @since 3.0
+ * @param aContentID Content ID
+ * @param aSeed Authentication seed
+ * @return Error code. KErrNone if successful operation.
+ */
+ IMPORT_C TInt GetAuthenticationSeed( const TDesC8& aContentId,
+ TDes8& aSeed );
+ /**
+ * Integrity protection for protected ROs. Calculates HMAC value
+ * usign aSignedInfoElement and MAC key. MAC key is unwrapped
+ * in AddRecord method. So AddRecord must be called successfully
+ * before this method can be called.
+ *
+ * @since 3.0
+ * @param aSignedInfoElement Complete XML ro element <roap:ro>
+ * @param aMacValue MAC value from protectedRO element
+ * @return Error code. KErrNone if successful operation.
+ KErrRightsServerMacFailed, if MAC validation fails
+ */
+ IMPORT_C TInt VerifyMacL( const TDesC8& aSignedInfoElement,
+ const TDesC8& aMacValue ) const;
+
+
+ /**
+ * Retrieve the individuals from the Rights Server so proper
+ * comparisons of rights object validity can be performed outside
+ * of the rights server
+ *
+ * @since 3.1
+ * @param aIndividuals : Pointer array of the individuals supported
+ * @return Error code with server side error.
+ * KErrNone if successful operation.
+ */
+ IMPORT_C TInt GetSupportedIndividualsL(
+ RPointerArray<HBufC8>& aIndividuals) const;
+
+ /**
+ * Stop watching the DCF repository server
+ *
+ * @since 3.1
+ */
+ IMPORT_C void StopWatching() const;
+
+
+ /**
+ * Unwraps MAC and REK keys that are protected using device public key
+ * or domain key. If the keys are wrapped with device public key aDomainId
+ * parameter must be set to zero length.
+ *
+ * @since 3.1
+ * @param aMacAndRek : Public key protected MAC and REK keys
+ * @param aTransportScheme: Used key wrapping scheme (e.g. OMA or CMLA)
+ * @param aRightsIssuerId: Defines the RI that has wrapped the keys
+ * @param aDomainId: Defines the domain key that used for wrapping the keys.
+ * If a device public key is used, the length of aDomainId must be zero
+ * @return Error code with server side error.
+ * KErrNone if successful operation.
+ */
+ IMPORT_C TInt UnwrapMacAndRek( const TDesC8& aMacAndRek,
+ TKeyTransportScheme aTransportScheme,
+ const TDesC8& aRightsIssuerId,
+ const TDesC8& aDomainId ) const;
+
+ /**
+ * Fills the input buffer with random data. The length of the aRandomData must
+ * be set to the correct value.
+ *
+ * @since 3.1
+ * @param aRandomData : Out-parameter that will be filled with random data
+ */
+ IMPORT_C void GetRandomDataL( TDes8& aRandomData ) const;
+
+ /**
+ * Returns the metering data for the requested rights-issuer id
+ *
+ * @since 3.2
+ * @param aRiId : Rights-Issuer Id for which the metering data is acquired
+ * @return MeteringData which includes the cipher data and all tags inside
+ * meteringReport -element
+ */
+
+ IMPORT_C HBufC8* GetMeteringDataL( const TDesC8& aRiId );
+
+ /**
+ * Deletes the metering data of the requested rights-issuer id
+ *
+ * @since 3.2
+ * @param aRiId : Rights-Issuer Id for which the metering data is deleted
+ * @return Error code with server side error.
+ * KErrNone if successful operation.
+ */
+
+ IMPORT_C TInt DeleteMeteringDataL( const TDesC8& aRiId );
+
+
+ public: // Functions from base classes
+
+ protected: // New functions
+
+ protected: // Functions from base classes
+
+ private:
+
+ /**
+ * Convert internally used temporary file into list.
+ * @since S60Rel2.5
+ * @param aFs Open file server session.
+ * @param aFileName Source file name
+ * @param aList Destination list.
+ */
+ void FileToListL( RFs& aFs,
+ const TDesC& aFileName,
+ RPointerArray< CDRMPermission >& aList );
+ /**
+ * Converts a file of URIs into an array.
+ * @since S60Rel2.5
+ * @param aFs Open file server session.
+ * @param aFile Input file.
+ * @param aList Output list.
+ */
+ void URIFileToArrayL( RFs& aFs,
+ const TDesC& aFile,
+ RPointerArray< HBufC8 >& aList );
+
+
+ // Prohibit copy constructor if not deriving from CBase.
+ RDRMRightsClient( const RDRMRightsClient& );
+ // Prohibit assigment operator if not deriving from CBase.
+ RDRMRightsClient& operator=( const RDRMRightsClient& );
+
+ public: // Data
+
+ protected: // Data
+
+ private: // Data
+ TAny* iPtr; // Reserved for future use
+
+ public: // Friend classes
+
+ protected: // Friend classes
+
+ private: // Friend classes
+ };
+
+#endif // RDRMRIGHTSCLIENT_H
+
+// End of File