diff -r 000000000000 -r 95b198f216e5 drm_plat/drm_legacy_api/inc/DRMRightsClient.h --- /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 +#include +#include + +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& 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& 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 + * @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& 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