/*
* Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the License "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: 
* MCTKeystore.h
*
*/


/**
 @file 
 @publishedPartner
 @released
*/
 
#ifndef __MCTKEYSTORE_H__
#define __MCTKEYSTORE_H__

#include <securitydefs.h>
#include <mkeystore.h>
#include <s32file.h>

#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
#include <mctkeystoreuids.h>
#endif

/** The UID of the filekey store */
const TInt KTokenTypeFileKeystore = 0x101F7333;

#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS

/** The type ID of CCTKeyInfo objects */
const TUid KKeyInfoUID = {0x101F5152};
const TUid KNonRepudiationSignerUID = {0x101F7A40};
const TUid KKeyStoreAuthObjectUID = {0x101FE681};

#endif

class MCTAuthenticationObject;

/**
 * Defines the interface for a read-only key store token.
 *
 * All the details are defined in MKeyStore as they are shared by the unified
 * key store.
 * 
 * The class adds no extra member functions or data. 
 * 
 */
class MCTKeyStore : public MCTTokenInterface, public MKeyStore
	{
	};

/**
 * Base class for CCTKeyInfo.
 *
 */
class CKeyInfoBase : protected CBase
	{
public:

	/** Key algorithms. */
	enum EKeyAlgorithm
		{
		EInvalidAlgorithm	= 0,
		ERSA				= 1,
		EDSA				= 2,
		EDH					= 3,
		};

	/** Flags for key access bitfield. */
	enum EKeyAccess
		{
		EInvalidAccess		= 0x00,
		ESensitive			= 0x01,
		EExtractable		= 0x02,
		EAlwaysSensitive	= 0x04,
		ENeverExtractable	= 0x08,
		ELocal				= 0x10
		};

public:
	
	inline TKeyIdentifier ID() const;						///< The ID (SHA-1 hash) of the key 
	inline TKeyUsagePKCS15 Usage() const;					///< The key usage 
	inline TUint Size() const;								///< The size of the key 
	inline const TDesC& Label() const;						///< The key's label.
	inline const TSecurityPolicy& UsePolicy() const; 		///< The security policy for key use 
	inline const TSecurityPolicy& ManagementPolicy() const; ///< The security policy for key management 
	inline EKeyAlgorithm Algorithm() const;					///< The key algorithm

	/**
	 * The key access type. The return code is bitfield made up of 0 or more
	 * values from EKeyAccess ORed together.
	 */
	inline TInt AccessType() const;

	/**
	 * Returns whether the key is native.
	 *
	 * A native key is one where operations on the key are performed on the same
	 * hardware as the the key is stored. For instance, if a key that is stored
	 * on secure hardware but calculations are carried out on the main
	 * processor, it isn't native.
	 */
	inline TBool Native() const;
	
	inline TTime StartDate() const;					///< The start time, or TTime(0) if not set
	inline TTime EndDate() const;					///< The end time, or TTime(0) if not set
	inline const TDesC8& PKCS8AttributeSet() const;	///< The PKCS#8 attribute set.

	/**
	 * Externalizes the key data to stream
	 */
	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

public:

	/**
	 * Get the handle of the key.  This is a identifier that uniquely identifies
	 * the key within one store, and is used to construct the token handle.
	 */
	inline TInt HandleID() const;

	/**
	 * Set the handle of the key.  Called by the token when a key is created.
	 *
	 * @param aHandle The new handle of the key
	 */
	inline void SetHandle(TInt aHandle);

	/**
	 * Called by the token when a key is created, to set the key identifier
	 * (SHA-1 hash) of the new key
	 *
	 * @param aId The newly generated SHA-1 hash
	 */
	inline void SetIdentifier(TKeyIdentifier aId);

	/**
	 * Set the size of a key.
	 */
	inline void SetSize(TUint aSize);

	/**
	 * Set the key algorithm.
	 */
	inline void SetAlgorithm(EKeyAlgorithm aAlg);

protected:

	/**
	 * Protected constructor, called by derived classes.
	 */
	IMPORT_C CKeyInfoBase(TKeyIdentifier aID,
						  TKeyUsagePKCS15 aUsage,
						  TUint aSize,
						  HBufC* aLabel,
						  TInt aHandle,
						  const TSecurityPolicy& aUsePolicy,
						  const TSecurityPolicy& aManagementPolicy,
						  EKeyAlgorithm aAlgorithm,
						  TInt aAccessType,
						  TBool aNative,
						  TTime aStartDate,
						  TTime aEndDate,
						  HBufC8* aPKCS8AttributeSet);

	/**
	 * Protected constructor, called by derived classes.
	 */
	IMPORT_C CKeyInfoBase();

	/**
	 * Second phase constructor.  Called by derived classes' NewL methods.
	 */
	IMPORT_C void ConstructL();

	/**
	 * Second phase constructor.  Called by derived classes' NewL methods.
	 */
	IMPORT_C void ConstructL(RReadStream& aIn);

	/**
	 * Destructor is protected so CCTKeyInfo can force users to call Release.
	 */
	IMPORT_C ~CKeyInfoBase();

private:

	/**
	 * Internalizes key data from a stream.
	 */
	void InternalizeL(RReadStream& aStream);
	
protected:
	TKeyIdentifier iID;					///< The ID of the key
	TKeyUsagePKCS15 iUsage;				///< The usage of the key 
	TUint iSize;						///< The size of the key 
	HBufC* iLabel;						///< The identifying label of the key
	TInt iHandle;						///< The handle of the key
	TSecurityPolicy iUsePolicy;			///< The secutity policy for key use
	TSecurityPolicy iManagementPolicy;	///< The secutity policy for key management
	EKeyAlgorithm iAlgorithm;			///< The key type (RSA, DSA etc)
	TInt iAccessType;					///< Key sensitivity
	TBool iNative;						///< Key is native (cryptographic operations are carried out on the store)
	TTime iStartDate;					///< Key Start Date 
	TTime iEndDate;						///< Key end date 
	HBufC8* iPKCS8AttributeSet;			///< Attributes as a DER-encoded set
	};

/**
 * Information about a key, as returned by MCTKeyStore::List.
 *
 */
class CCTKeyInfo : public CKeyInfoBase, public MCTTokenObject
	{
public:

	/**
	 * 
	 * Creates a CCTKeyInfo from constituents.  This is called by the unified
	 * key store, and should not be called directly.
	 *
	 * @param aID The SHA1 hash of the key
	 * @param aUsage The usage of the key
	 * @param aSize The size of the key in bytes
	 * @param aProtector A protector object if the key is protected by a PIN.
	 * This may be NULL if the protector is not known.
	 * @param aLabel The label of the key (takes ownership).
	 * @param aToken The token the key is in
	 * @param aHandle The object ID part of the object handle; an
	 * integer that is unique amongst keys in this token.
	 * @param aUsePolicy The security policy for key use
	 * @param aManagementPolicy The security policy for key management
	 * @param aAlgorithm The key algorithm (RSA, DSA or Diffie-Hellman)
	 * @param aAccessType The access type of the key
	 * @param aNative	Defines whether the key is native
	 * @param aStartDate The key validity start date
	 * @param aEndDate The key validity end date
	 * @param aPKCS8AttributeSet (optional) The DER encoded PKCS8 attribute set
	 * (takes ownership).
	 *
	 * @leave KErrKeyUsage If the key usage flags are not valid or not
	 * consistent with the key algorithm.
	 * @leave KErrKeyValidity If the validity start and end dates are specified
	 * but do not form a valid time period.
	 */
	IMPORT_C static CCTKeyInfo* NewL(TKeyIdentifier aID,
									 TKeyUsagePKCS15 aUsage,
									 TUint aSize,
									 MCTAuthenticationObject* aProtector,
									 HBufC* aLabel,
									 MCTToken& aToken,
									 TInt aHandle,
									 const TSecurityPolicy& aUsePolicy,
									 const TSecurityPolicy& aManagementPolicy,
									 EKeyAlgorithm aAlgorithm,
									 TInt aAccessType,
									 TBool aNative,
									 TTime aStartDate,
									 TTime aEndDate,
									 HBufC8* aPKCS8AttributeSet = NULL);

	/**
	 * Creates a new KeyInfo from a stream.
	 *
	 * @param aStream The stream to read the key data from
	 * @param aToken The token that the key is in
	 *
	 * @leave KErrKeyUsage If the key usage flags are not valid or not
	 * consistent with the key algorithm.
	 * @leave KErrKeyValidity If the validity start and end dates are specified
	 * but do not form a valid time period.
	 */
	IMPORT_C static CCTKeyInfo* NewL(RReadStream& aStream, MCTToken& aToken);

public:

	/**
	 * The PIN (or other authentication object) that protects the key, or NULL
	 * if not set.  This object is owned by key store.
	 */
	inline MCTAuthenticationObject* Protector() const;

	/**
	 * Sets the authentication object for this key.  The object's Release method
	 * will be called by the destructor, allowing for refence counting of auth
	 * objects to be implemented if desired.
	 */
	inline void SetProtector(MCTAuthenticationObject& aProtector);
	
	/** The CT handle to this object. */
	inline operator TCTTokenObjectHandle() const;

public:

	// from MCTTokenObject

	/** The label of the key */
 	virtual const TDesC& Label() const;

	/** The token the key is in */
	virtual MCTToken& Token() const;

	/** Returns KKeyInfoUID to indicate this is a key info object */
	virtual TUid Type() const;

	/**
	 * A handle for the key. This can be used to identify a key to
	 * another process.
	 */
	virtual TCTTokenObjectHandle Handle() const;

private:

	CCTKeyInfo(TKeyIdentifier aID,
			   TKeyUsagePKCS15 aUsage,
			   TUint aSize,
			   MCTAuthenticationObject* aProtector,
			   HBufC* aLabel,
			   MCTToken& aToken,
			   TInt aHandle,
			   const TSecurityPolicy& aUsePolicy,
			   const TSecurityPolicy& aManagementPolicy,
			   EKeyAlgorithm aAlgorithm,
			   TInt aAccessType,
			   TBool aNative,
			   TTime aStartDate,
			   TTime aEndDate,
			   HBufC8* aPKCS8AttributeSet);

	CCTKeyInfo(MCTToken& aToken);

	~CCTKeyInfo();

private:

	/** The token the key is in*/
	MCTToken& iToken;

	/** The protector object of the key. This pointer is not owned by the class */
	MCTAuthenticationObject* iProtector;
};

/**
 * A filter to specify which keys should be returned from the store by
 * MCTKeyStore::List.
 *
 */
struct TCTKeyAttributeFilter
	{
	enum TPolicyFilter
		{
		EAllKeys,
		EUsableKeys,
		EManageableKeys,
		EUsableOrManageableKeys
		};

	/** Constructor */
	IMPORT_C TCTKeyAttributeFilter();

	/**
	 * The hash of the key we're looking for. A zero-length descriptor means
	 * 'don't care
	 */
	TKeyIdentifier iKeyId;

	/**
	 * The required usage of the key. A key must match any of the usages
	 * specified. Use EAllUsages to return all usages.
	 */
	TKeyUsagePKCS15 iUsage;

	/**
	 * Filter returned keys by the operations the calling process is allowed to
	 * perform on them (as determined by the security policies set on them).
	 * 
	 * The default is EUsableKeys.  Note that if this is to set to KAllKeys, all
	 * keys will be returned, including those that are unusable by the calling
	 * process.
	 */
	TPolicyFilter iPolicyFilter;

	/** The algorithm. EInvalidAlgorithm indicates 'don't care */
	CCTKeyInfo::EKeyAlgorithm iKeyAlgorithm;
	};

#include "mctkeystore.inl"

#endif // __MCTKEYSTORE_H__
