diff -r 04da681812a9 -r 457cd4423b8c inc/DrmKeyStorage.h --- a/inc/DrmKeyStorage.h Tue Apr 27 16:56:11 2010 +0300 +++ b/inc/DrmKeyStorage.h Tue May 11 16:28:38 2010 +0300 @@ -1,5 +1,5 @@ /* -* Copyright (c) 2002-2004 Nokia Corporation and/or its subsidiary(-ies). +* Copyright (c) 2002-2010 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" @@ -25,7 +25,12 @@ // CLASS DECLARATION /** -* CDrmKeyStorage: Contains key storage for OMA DRM 2.0 +* CDrmKeyStorage: Contains key storage for OMA DRM 2.x +* +* Generally the methods to the class require that a root certificate is selected. +* A specific root certificate can be selected or the default root can be selected. +* Operations needing the PKI keys should fail if the key has not been selected. +* Suggested error code: KErrNotReady * * @lib - * @since 3.0 @@ -38,53 +43,231 @@ public: // New functions + /** + * Destructor + */ + virtual ~MDrmKeyStorage() = 0; + /** + * ModulusSize + * + * Return the modulus size of the selected certificates private key. + * + * @return Modulus size of the PKI key + */ + virtual TInt ModulusSize() = 0; - + + /** + * SelectTrustedRootL + * + * Selects the trusted root certificate to be used for operation occurring after + * this call + * + * @param aRootKeyHash Hash of the root key to be used. + * @leave Symbian OS error codes + */ + virtual void SelectTrustedRootL( const TDesC8& aRootKeyHash) = 0; - + + /** + * SelectedRootIsCmla + * + * Checks if the selected root is a CMLA root + * + * @return ETrue if the selected root is a CMLA root + * EFalse if the root does not exist or is not a CMLA root + */ + virtual TBool SelectedRootIsCmla() = 0; - + + /** + * SelectDefaultRootL + * + * Selects the default root certificate of the device/keystorage implementation + * + * @leave Symbian OS error code if the root can't be selected for some reason + */ + virtual void SelectDefaultRootL() = 0; - + + /** + * GetTrustedRootsL + * + * Get a list of unique identifiers for the trusted roots of the + * device / keystorage implementation. Generally PKI public key hash values. + * + * @param aRootList A pointer array of trusted root certificate hash values + * or other unique identifiers for the certificates + * @leave Symbian OS error codes + */ + virtual void GetTrustedRootsL( RPointerArray& aRootList) = 0; - + + /** + * GetCertificateChainL + * + * Get the certificate chain of the selected certificate + * + * @param aRootList A pointer array of certificate hash values + * or other unique identifiers for the certificates + * in the certificate chain + * @leave Symbian OS error codes + */ + virtual void GetCertificateChainL( RPointerArray& aCertChain) = 0; + + /** + * RsaSignL + * + * Create an RSA signature of the buffer given + * + * @param aInput A descriptor containing the data to be signed + * @return Signed buffer. Caller is responsible for freeing it. + * @leave Symbian OS error codes + */ virtual HBufC8* RsaSignL( const TDesC8& aInput) = 0; - + + /** + * RsaDecryptL + * + * Decrypt the RSA encrypted buffer + * + * @param aInput A descriptor containing the data to be decrypted + * @return Decrypted buffer. Caller is responsible for freeing it. + * @leave Symbian OS error codes + */ + virtual HBufC8* RsaDecryptL( const TDesC8& aInput) = 0; - + + /** + * ImportDataL + * + * Allows the importing of PKI keys into the system + * Should import: Private Key, Public Certificate and all + * signing certificates for the certificate chain all the way to the root. + * + * Mostly usable for debugging purposes. Should be used with caution. + * + * @param aPrivateKey Private key of the imported PKI key. + * @param aCertificateChain Public Certificate and signing certificates + * @leave Symbian OS error codes + */ + virtual void ImportDataL( const TDesC8& aPrivateKey, const RArray& aCertificateChain) = 0; - + + /** + * GetDeviceSpecificKeyL + * + * Get the device specific key/identifier that has a length of + * KDeviceSpecificKeyLength. Must return the same value every time. + * This method must not require the root to be selected. + * + * Does not require the selection of + * + * @param aKey Buffer to fit the bytes of a device specific + * unique key / identifier. Must return the same + * value every time + * @leave Symbian OS error codes + */ + virtual void GetDeviceSpecificKeyL( TBuf8& aKey) = 0; + + /** + * GetRdbSerialNumberL + * + * This method fetches a unique serial number for the OMA DRM rights database + * currently in use. Does not have to be unique per device, but should return + * the same value while the current database is in use. + * Should create a new serial number if one does not exists. + * + * @param aSerialNumber Serial number for the OMA DRM + * rights database + * @leave Symbian OS error codes + */ virtual void GetRdbSerialNumberL( TBuf8& aSerialNumber) = 0; - + + /** + * GenerateNewRdbSerialNumberL( + * + * This method creates a new unique serial number for the OMA DRM rights database. + * Length of the serial number is defined by KRdbSerialNumberLength constant. + * Should be random and must be persisted until a new serial number is generated by + * a new call to this method. + * + * Recommend storing the serial number into the file system or other secure location. + * For example under the rightsserver.exe private directory. + * + * @leave Symbian OS error codes + */ + virtual void GenerateNewRdbSerialNumberL() = 0; - + + /** + * UdtEncryptL + * + * Encrypt the User Data Transfer data. Usable only in the user data transfer use case. + * Uses it's own User Data Transfer PKI key. + * + * @param aInput Input buffer to be encrypted + * @return Buffer encrypted with the User Data Transfer specific PKI key. + * @leave Symbian OS error codes + */ + virtual HBufC8* UdtEncryptL( const TDesC8& aInput) = 0; - + + /** + * GetRootCertificatesL + * + * Get a list of all the root certificates of the device. + * Returns actual binary format (.der) certificates. + * + * @param aRootCerts Param description + * @return Return value descriptions + * @leave Symbian OS error codes + */ + virtual void GetRootCertificatesL( RPointerArray& aRootCerts) = 0; + /** + * RandomDataGetL + * + * Get random data into the beginning of the aData buffer. + * + * @param aData A return buffer that has enough space for the aLength amount of data. + * @param aLength Amount of random data requested + * @leave Symbian OS error codes + */ + virtual void RandomDataGetL( TDes8& aData, const TInt aLength ) = 0; }; +/** +* DrmKeyStorageNewL +* +* @return Pointer to an object which implements the MDrmKeyStorage +* interface. Underlying implementation tells which +* keystorage to load if there are emulator/hw specific ones +* @leave Symbian OS error codes +*/ + IMPORT_C MDrmKeyStorage* DrmKeyStorageNewL(); #endif // DRMKEYSTORAGE_H