/*
* Copyright (c) 1998-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: 
* PKIXCERTCHAIN.H
* PKIX certificate chain implementation
*
*/




/**
 @file 
 @internalTechnology 
*/
 
#ifndef __PKIXCERTCHAIN_H__
#define __PKIXCERTCHAIN_H__

#include <e32std.h>
#include <x509certchain.h>
#include <pkixvalidationresult.h>

//implements key validation according to RFC 2459 (PKIX cert/CRL profile), section 6
class CPKIXValidationState;
class CPKIXChainBuilder;
class CPKIXCertChainAO;
class CPKIXCertChainHelper;
class MCertStore;

/**
 * Base class for CPKIXCertChain
 * @internalTechnology
 */
class CPKIXCertChainBase : public CX509CertChain
	{
public:
	//constructors
	/** Creates a certificate chain using the binary data in aEncodedCerts.
	*
	* @param aCertStore		The certificate store to use when looking for root certificates.
	* @param aEncodedCerts	One or more concatenated DER encoded X.509 certificates. 
	*						The first certificate will be interpreted as the end entity certificate to 
	*						be validated; subsequent certificates may be in any order and may be used 
	*						by the chain as intermediate certificates, but not root certificates. The 
	*						individual certificates can be retrieved since each one contains its own length.
	* @param aClient		The Uid identifying the purpose for which the chain will be used. 
	* 						This value will be used to select a subset of stored certificates, by way of their trust 
	*						settings, to be used as candidate root certificates. */
	IMPORT_C static CPKIXCertChainBase* NewL(MCertStore& aCertStore, const TPtrC8& aEncodedCerts, 
		const TUid aClient);
	
	/** Creates a certificate chain using the binary data in aEncodedCerts, and puts 
	* a pointer to the new object onto the cleanup stack.
	*
	* @param aCertStore		The certificate store to use when looking for root certificates.
	* @param aEncodedCerts	One or more concatenated DER encoded X.509 certificates. 
	* 						The first certificate will be interpreted as the end entity certificate to 
	* 						be validated; subsequent certificates may be in any order and may be used 
	* 						by the chain as intermediate certificates, but not root certificates. The 
	* 						individual certificates can be retrieved since each one contains its own length.
	* @param aClient		The Uid identifying the purpose for which the chain will be used. 
	* 						This value will be used to select a subset of stored certificates, by way of their trust 
	*						settings, to be used as candidate root certificates. */
	IMPORT_C static CPKIXCertChainBase* NewLC(MCertStore& aCertStore, const TPtrC8& aEncodedCerts, 
		const TUid aClient);
		
	/** Creates a certificate chain using the binary data in aEncodedCerts.
	*
	* @param aCertStore		The certificate store to use when looking for root certificates.
	* @param aEncodedCerts	One or more concatenated DER encoded X.509 certificates. 
	* 						The first certificate will be interpreted as the end entity certificate to 
	* 						be validated; subsequent certificates may be in any order and may be used 
	* 						by the chain as intermediate certificates, but not root certificates. Any 
	* 						self signed certificates supplied here after the first one will be discarded, 
	* 						as self signed certificates cannot by definition be intermediate certificates. 
	* 						The individual certificates can be retrieved since each one contains its own 
	* 						length.
	* @param aRootCerts		An array of certificates which the chain will treat as candidate root 
	* 						certificates. If one of these overloads is used, the chain will not look in 
	* 						stores for root certificates, but will only use the certificates supplied here. */
	IMPORT_C static CPKIXCertChainBase* NewL(MCertStore& aCertStore, const TPtrC8& aEncodedCerts, 
		const RPointerArray<CX509Certificate>& aRootCerts);
		
	/** Creates a certificate chain using the binary data in aEncodedCerts and puts 
	* a pointer to the new object onto the cleanup stack.
	*
	* @param aCertStore		The certificate store to use when looking for root certificates.
	* @param aEncodedCerts	One or more concatenated DER encoded X.509 certificates. 
	* 						The first certificate will be interpreted as the end entity certificate to 
	* 						be validated; subsequent certificates may be in any order and may be used 
	* 						by the chain as intermediate certificates, but not root certificates. Any 
	* 						self signed certificates supplied here after the first one will be discarded 
	* 						as self signed certificates cannot by definition be intermediate certificates. 
	* 						The individual certificates can be retrieved since each one contains its own 
	* 						length.
	* @param aRootCerts		An array of certificates which the chain will treat as candidate root 
	* 						certificates. If one of these overloads is used, the chain will not look in 
	* 						stores for root certificates, but will only use the certificates supplied here. */
	IMPORT_C static CPKIXCertChainBase* NewLC(MCertStore& aCertStore, const TPtrC8& aEncodedCerts, 
		const RPointerArray<CX509Certificate>& aRootCerts);
		
	/** Destructor.
	*
	* Frees all resources owned by the object. */
	IMPORT_C ~CPKIXCertChainBase();
		//validation

	/** Validates the chain.
	*
	* @param aValidationResult	On completion, this contains the result of the validation.
	* @param aValidationTime	The time that should be presumed to be the current time when checking timestamps.
	* @param aStatus			An asynchronous request status object. */
	IMPORT_C void ValidateL(CPKIXValidationResultBase& aValidationResult, 
		const TTime& aValidationTime, TRequestStatus& aStatus);
	
	/** Validates the chain.
	*
	* @param aValidationResult	On completion, this contains the result of the validation.
	* @param aValidationTime	The time that should be presumed to be the current time when checking timestamps.
	* @param aInitialPolicies	The policies we want to be present in the certificate chain.
	* @param aStatus 			An asynchronous request status object. */
	IMPORT_C void ValidateL(CPKIXValidationResultBase& aValidationResult, 
		const TTime& aValidationTime, const CArrayPtr<HBufC>& aInitialPolicies, 
		TRequestStatus& aStatus);

	/** Cancels an asynchronous ValidateL() operation. */
	IMPORT_C void CancelValidate();

	/** Adds one or more intermediate certificates to use when building the chain .
	*
	* Any self signed certs are ignored.
	*
	* @param aEncodedCerts	The concatenation of one or more DER encoded X.509 certificates. */
	IMPORT_C void AddCertL(const TPtrC8& aEncodedCerts);
	
	/** Tests whether the root certificate of the chain is locatable.
	*
	* Note that the value is only significant after a successful call to ValidateL().
	* 
	* @return	ETrue if the chain has a root; EFalse, otherwise. */
	IMPORT_C TBool ChainHasRoot() const;	
	
	/** Returns a list of the critical extension OIDs that are supported by the 
	* chain validator. If a critical extension is encountered in a certificate 
	* chain whose OID matches an element in this set then the chain validator 
	* shall treat this as a warning instead of an error. 
	* 
	* If CPKIXCertChain::SetSupportedCriticalExtensionsL() has not been called, this 
	* list will return the default set of supported critical extensions which 
	* includes the X.509 standard and Symbian specific SIS file critical extensions. 
	* These extensions may change in the future and should not be relied upon.
	* 
	* @return	The current list of supported critical extension OIDs. Ownership is not 
	* transferred to the caller. */
	IMPORT_C const RPointerArray<TDesC>& SupportedCriticalExtensions() const;
	
	/** Adds one or more critical extension OIDs to the list of supported critical 
	* extensions. Duplicate OID values are not added.
	* 
	* @param aCriticalExtOids	A list of the critical extensions OIDs to append to the supported 
	* list. Ownership is not transferred from the caller. */
	IMPORT_C void AddSupportedCriticalExtensionsL(const RPointerArray<TDesC>& aCriticalExtOids);
	
	/** Removes one or more critical extension OIDs from the list of supported critical extensions.
	* 
	* @param aCriticalExts	A list of the critical extensions OIDs to remove from the supported list. 
	* Ownership is with the original caller. Oids will not be destroyed. */
	IMPORT_C void RemoveSupportedCriticalExtensions(const RPointerArray<TDesC>& aCriticalExtOids);

	/** Completely replaces the set of supported critical extensions for certificate validation. If a critical 
	* extension is encountered matching one of these OIDs then its occurrence is treated as a warning rather 
	* than an error.  The results of which can be queried through a call to CPKIXValidationResult::ValidationWarnings().
	* 
	* @param aCriticalExtOids	A list of the critical extensions OIDs for the class to support. Ownership is
	* not transferred from the caller. */
	IMPORT_C void SetSupportedCriticalExtensionsL(const RPointerArray<TDesC>& aCriticalExtOids);

	/** Resets the current list of supported critical extensions and re-populates it with the default set
	* which includes the X.509 standard and Symbian specific SIS file critical extensions. These extensions 
	* may change in the future and should not be relied upon. */
	IMPORT_C void ResetSupportedCriticalExtsToDefaultL();
	
	/** Specify if a failed check on the certificate validity date is treated as an error or a warning.
	*
	* @param aIsFatal  ETrue for reporting as an error; EFalse for a warning.*/
	IMPORT_C void SetValidityPeriodCheckFatal(TBool aIsFatal);

	/** Returns whether or not validity period check failures will be reported as an error or a warning.
	*
	* @param aIsFatal  ETrue if failure is reported as an error; EFalse for a warning.*/
	IMPORT_C TBool ValidityPeriodCheckFatal() const;

protected:
	IMPORT_C CPKIXCertChainBase();
	IMPORT_C void ConstructL(MCertStore& aCertStore, const TPtrC8& aEncodedCerts, TUid aClient);
	IMPORT_C void ConstructL(MCertStore& aCertStore, const TPtrC8& aEncodedCerts, const RPointerArray<CX509Certificate>& aRootCerts);

public:
	// Public non-exported methods called by CPKIXCertChainAO
	CArrayPtrFlat<CX509Certificate>& Chain();
	const RPointerArray<CX509Certificate>& IntermediateCerts();	
	TBool ChainHasRoot();
	void RemoveLastCerts(TInt aNumberOfCertsToRemove);	
	void SetChainHasRoot(TBool aHasRoot);

private:
	void DoConstructL(const TPtrC8& aEncodedCerts);

	/**
	 * This function adds certificates to the chain but only the ones that are not
	 * self-signed.
	 *
	 * @param aEncodedCerts	The encoded certificates.
	 */
	void AddIntermediateCertsL(const TPtrC8& aEncodedCerts);

private:
	/**
	 * Holds a list of candiate intermediate certs - these come from the encoded
	 * certs passed at construction time, and also any added with AddCertL().
	 */
	RPointerArray<CX509Certificate> iIntermediateCerts;

	/**
	 * This is ETrue if the chain has a root and EFalse if it hasn't.  The value
	 * is only significant after a successfull call to ValidateL().
	 */
	TBool iChainHasRoot;

	/**
	 * Most of the fucntionality of the class is asynchronous and is in fact
	 * delegated to iActiveObject which will deal with all the asynchronous
	 * functions.
	 */
	CPKIXCertChainAO* iActiveObject;
	
	/**
	 * Holds a list of supported critical extensions set by the client.
	 */
	RPointerArray<TDesC> iSupportedCriticalExts;
	
	/**
	 * When true (the defaut) indicates that a failed check on the validity period of a
	 * certificate will result in a fatal error.  When false this instead results in a
	 * warning.
	 */
	TBool iDateTimeCheckFatal;
	};


/**
 * This class implements a PKIX certificate chain.
 *
 * @publishedAll
 * @released
 * @since v6.0
 */
class CPKIXCertChain : public CPKIXCertChainBase
	{
public:
	
		//constructors
	/** Creates a certificate chain using the binary data in aEncodedCerts.
	*
	* @param aFs			An open file server session.
	* @param aEncodedCerts	One or more concatenated DER encoded X.509 certificates. 
	*						The first certificate will be interpreted as the end entity certificate to 
	*						be validated; subsequent certificates may be in any order and may be used 
	*						by the chain as intermediate certificates, but not root certificates. The 
	*						individual certificates can be retrieved since each one contains its own length.
	* @param aClient		The Uid identifying the purpose for which the chain will be used. 
	* 						This value will be used to select a subset of stored certificates, by way of their trust 
	*						settings, to be used as candidate root certificates. */
	IMPORT_C static CPKIXCertChain* NewL(RFs& aFs, const TPtrC8& aEncodedCerts, 
		const TUid aClient);
	
	/** Creates a certificate chain using the binary data in aEncodedCerts, and puts 
	* a pointer to the new object onto the cleanup stack.
	*
	* @param aFs			An open file server session
	* @param aEncodedCerts	One or more concatenated DER encoded X.509 certificates. 
	* 						The first certificate will be interpreted as the end entity certificate to 
	* 						be validated; subsequent certificates may be in any order and may be used 
	* 						by the chain as intermediate certificates, but not root certificates. The 
	* 						individual certificates can be retrieved since each one contains its own length.
	* @param aClient		The Uid identifying the purpose for which the chain will be used. 
	* 						This value will be used to select a subset of stored certificates, by way of their trust 
	*						settings, to be used as candidate root certificates. */
	IMPORT_C static CPKIXCertChain* NewLC(RFs& aFs, const TPtrC8& aEncodedCerts, 
		const TUid aClient);
		
	/** Creates a certificate chain using the binary data in aEncodedCerts.
	*
	* @param aFs			An open file server session.
	* @param aEncodedCerts	One or more concatenated DER encoded X.509 certificates. 
	* 						The first certificate will be interpreted as the end entity certificate to 
	* 						be validated; subsequent certificates may be in any order and may be used 
	* 						by the chain as intermediate certificates, but not root certificates. Any 
	* 						self signed certificates supplied here after the first one will be discarded, 
	* 						as self signed certificates cannot by definition be intermediate certificates. 
	* 						The individual certificates can be retrieved since each one contains its own 
	* 						length.
	* @param aRootCerts		An array of certificates which the chain will treat as candidate root 
	* 						certificates. If one of these overloads is used, the chain will not look in 
	* 						stores for root certificates, but will only use the certificates supplied here. */
	IMPORT_C static CPKIXCertChain* NewL(RFs& aFs, const TPtrC8& aEncodedCerts, 
		const RPointerArray<CX509Certificate>& aRootCerts);
		
	/** Creates a certificate chain using the binary data in aEncodedCerts and puts 
	* a pointer to the new object onto the cleanup stack.
	*
	* @param aFs			An open file server session.
	* @param aEncodedCerts	One or more concatenated DER encoded X.509 certificates. 
	* 						The first certificate will be interpreted as the end entity certificate to 
	* 						be validated; subsequent certificates may be in any order and may be used 
	* 						by the chain as intermediate certificates, but not root certificates. Any 
	* 						self signed certificates supplied here after the first one will be discarded 
	* 						as self signed certificates cannot by definition be intermediate certificates. 
	* 						The individual certificates can be retrieved since each one contains its own 
	* 						length.
	* @param aRootCerts		An array of certificates which the chain will treat as candidate root 
	* 						certificates. If one of these overloads is used, the chain will not look in 
	* 						stores for root certificates, but will only use the certificates supplied here. */
	IMPORT_C static CPKIXCertChain* NewLC(RFs& aFs, const TPtrC8& aEncodedCerts, 
		const RPointerArray<CX509Certificate>& aRootCerts);
		
		//destructor
	/** Destructor.
	*
	* Frees all resources owned by the object. */
	IMPORT_C ~CPKIXCertChain();
		//validation

	/** Validates the chain.
	*
	* @param aValidationResult	On completion, this contains the result of the validation.
	* @param aValidationTime	The time that should be presumed to be the current time when checking timestamps.
	* @param aStatus			An asynchronous request status object. */
	IMPORT_C void ValidateL(CPKIXValidationResult& aValidationResult, 
		const TTime& aValidationTime, TRequestStatus& aStatus);
	
	/** Validates the chain.
	*
	* @param aValidationResult	On completion, this contains the result of the validation.
	* @param aValidationTime	The time that should be presumed to be the current time when checking timestamps.
	* @param aInitialPolicies	The policies we want to be present in the certificate chain.
	* @param aStatus 			An asynchronous request status object. */
	IMPORT_C void ValidateL(CPKIXValidationResult& aValidationResult, 
		const TTime& aValidationTime, const CArrayPtr<HBufC>& aInitialPolicies, 
		TRequestStatus& aStatus);

	/** Cancels an asynchronous ValidateL() operation. */
	IMPORT_C void CancelValidate();

	/** Adds a certificate (if it is not self-signed) to the chain .
	*
	* @param aEncodedCerts	A DER encoded X.509 certificate. */
	IMPORT_C void AddCertL(const TPtrC8& aEncodedCerts);
	
	/** Tests whether the root certificate of the chain is locatable.
	*
	* Note that the value is only significant after a successfull call to ValidateL().
	* 
	* @return	ETrue if the chain has a root; EFalse, otherwise. */
	IMPORT_C TBool ChainHasRoot() const;

	/** Returns a list of the critical extension OIDs that are supported by the 
	* chain validator. If a critical extension is encountered in a certificate 
	* chain whose OID matches an element in this set then the chain validator 
	* shall treat this as a warning instead of an error. 
	* 
	* If CPKIXCertChain::SetSupportedCriticalExtensionsL() has not been called, this 
	* list will return the default set of supported critical extensions which 
	* includes the X.509 standard and Symbian specific SIS file critical extensions. 
	* These extensions may change in the future and should not be relied upon.
	* 
	* @return	The current list of supported critical extension OIDs. Ownership is not 
	* transferred to the caller. */
	IMPORT_C const RPointerArray<TDesC>& SupportedCriticalExtensions() const;
	
	/** Adds one or more critical extension OIDs to the list of supported critical 
	* extensions. Duplicate OID values are not added.
	* 
	* @param aCriticalExtOids	A list of the critical extensions OIDs to append to the supported 
	* list. Ownership is not transferred from the caller. */
	IMPORT_C void AddSupportedCriticalExtensionsL(const RPointerArray<TDesC>& aCriticalExtOids);
	
	/** Removes one or more critical extension OIDs from the list of supported critical extensions.
	* 
	* @param aCriticalExts	A list of the critical extensions OIDs to remove from the supported list. 
	* Ownership is with the original caller. Oids will not be destroyed. */
	IMPORT_C void RemoveSupportedCriticalExtensions(const RPointerArray<TDesC>& aCriticalExtOids);

	/** Completely replaces the set of supported critical extensions for certificate validation. If a critical 
	* extension is encountered matching one of these OIDs then its occurrence is treated as a warning rather 
	* than an error.  The results of which can be queried through a call to CPKIXValidationResult::ValidationWarnings().
	* 
	* @param aCriticalExtOids	A list of the critical extensions OIDs for the class to support. Ownership is
	* not transferred from the caller. */
	IMPORT_C void SetSupportedCriticalExtensionsL(const RPointerArray<TDesC>& aCriticalExtOids);

	/** Resets the current list of supported critical extensions and re-populates it with the default set
	* which includes the X.509 standard and Symbian specific SIS file critical extensions. These extensions 
	* may change in the future and should not be relied upon. */
	IMPORT_C void ResetSupportedCriticalExtsToDefaultL();

	/** Specify if a failed check on the certificate validity date is treated as an error or a warning.
	*
	* @param aIsFatal  ETrue for reporting as an error; EFalse for a warning.*/
	IMPORT_C void SetValidityPeriodCheckFatal(TBool aIsFatal);

 private:
	CPKIXCertChain();
	void ConstructL(RFs& aFs, const TPtrC8& aEncodedCerts, TUid aClient);
	void ConstructL(RFs& aFs, const TPtrC8& aEncodedCerts,
					const RPointerArray<CX509Certificate>& aRootCerts);

 private:
	CPKIXCertChainHelper* iHelper;
	};

#endif