/*

* 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 

 @publishedAll

 @released

*/

#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

 */

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.

 *

 * @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