/*
* 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: 
*
*/


/**
 @file 
 @publishedAll
 @released
*/
 
#ifndef __WTLSCERTCHAIN_H__
#define __WTLSCERTCHAIN_H__

#include <e32std.h>
#include <unifiedcertstore.h>
#include <wtlscert.h>
#include <wtlsnames.h>

class TWTLSValidationStatus
/** The validation status.
*
* Some errors cannot be blamed on any single certificate, in which case the 
* iCert value is meaningless. The same structure is used for errors and for warnings. 
*
*/
	{
public:
	/** Creates a validation status object.
	* 
	* @param aError	The error type that occurred when validating the certificate chain.
	* @param aCert	The index number for the certificate that gave rise to the error. */
	IMPORT_C TWTLSValidationStatus(const TValidationError aError, const TInt aCert);
	
	/** The reason for the error. */
	TValidationError iReason;
	
	/** The index number for the certificate that gave rise to the error. */
	TInt iCert;
	};

class CWTLSValidationResult : public CBase
/** Encapsulates the results of the validation process.
* 
* It is returned to client code, which can examine it. Client code takes ownership of it. 
*
*/
	{
public:
	/** Creates a new CWTLSValidationResult object and puts a pointer to it on the 
	* cleanup stack.
	* 
	* @return	The new WTLS Validation Result object. */
	IMPORT_C static CWTLSValidationResult* NewLC();
	
	/** Creates a new CWTLSValidationResult object.
	* 
	* @return	The new WTLS Validation Result object. */
	IMPORT_C static CWTLSValidationResult* NewL();
	
	/** Destructor.
	* 
	* Frees all resources owned by the object, prior to its destruction. */
	IMPORT_C ~CWTLSValidationResult();
	
	/** Gets the error status of the operation.
	* 
	* Any errors here are considered fatal: validation has failed.
	* 
	* @return	The error status of the operation. */
	IMPORT_C const TWTLSValidationStatus Error() const;
	
	/** Gets an array of any warnings generated.
	* 
	* The warnings may or may not be fatal, depending on the context, which the 
	* client is expected to provide.
	* 
	* @return	An array of any warnings generated. */
	IMPORT_C const CArrayFixFlat<TWTLSValidationStatus>& Warnings() const;
	
	/** Resets the validation result object to its default values. 
	 * @internalAll
	 */
	void Reset();
	
	/** Sets the error.
	* 
	* @param aError	The error type that occurred when validating the certificate chain.
	* @param aCert	The index number for the certificate that gave rise to the error. 
	* @internalAll
	*/
	void SetError(const TValidationError aError, const TInt aCert);
	
	/** Adds a warning to the validation.
	* 
	* @param aWarning	The validation status object to be added. 
	* @internalAll
	*/
	void AppendWarningL(TWTLSValidationStatus aWarning);

private:
	CWTLSValidationResult();
	void ConstructL();
	TWTLSValidationStatus iError;
	CArrayFixFlat<TWTLSValidationStatus>* iWarnings;
	};

class CWTLSRootCerts;
class CWTLSCertChainAO;

class CWTLSCertChain : public CBase
/** Implements a WTLS certificate chain. 
*
*/
	{
	friend class CWTLSCertChainAO;

public:
	/** 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 WTLS 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.
	* @param aClient		The uid of the client. It is a value identifying the application 
	* 						to the chain; this will be used to select a subset of stored 
	* 						certificates to use as candidate root certificates. */
	IMPORT_C static CWTLSCertChain* 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 WTLS 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.
	* @param aClient		The uid of the client. It is a value identifying the application 
	* 						to the chain; this will be used to select a subset of stored 
	* 						certificates to use as candidate root certificates. */
	IMPORT_C static CWTLSCertChain* 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 WTLS 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.
	* @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 CWTLSCertChain* NewL(RFs& aFs, const TPtrC8& aEncodedCerts,
		const CArrayPtr<CWTLSCertificate>& 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 WTLS 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.
	* @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 CWTLSCertChain* NewLC(RFs& aFs, const TPtrC8& aEncodedCerts,
		const CArrayPtr<CWTLSCertificate>& aRootCerts);
	
	/** Destructor.
	* 
	* Frees all resources owned by the object. */
	IMPORT_C ~CWTLSCertChain();
	
	/** Validates the chain.
	* 
	* @param aValidationResult	On completion, this contains the result of the validation.
	* @param aValidationTime	The time for which validation should be performed, usually 
	* 							the current time.
	* @param aStatus			An asynchronous request status object. */
	IMPORT_C void ValidateL(CWTLSValidationResult& aValidationResult, 
		const TTime& aValidationTime, TRequestStatus& aStatus);
	
	/** Gets the number of WTLS certificates in the chain.
	* 
	* @return	The number of WTLS certificates in the chain. */
	IMPORT_C TInt Count() const;
	
	/** Gets the certificate at the specified index.
	* 
	* @param aIndex	The ordinal number representing the position of the certificate 
	* 				within the chain.
	* @return		The WTLS certificate at the specified index. */
	IMPORT_C const CWTLSCertificate& Cert(TInt aIndex) const;
	
	/** 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;
	
	/** Appends the specified encoded certificate to the chain.
	* 
	* @param aEncodedCerts	One or more concatenated DER encoded WTLS certificates. 
	* 						These certificates will be used as candidates. 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. */
	IMPORT_C void AppendCertsL(const TPtrC8& aEncodedCerts);

private:
	CWTLSCertChain(RFs& aFs);
	void ConstructL(const TPtrC8& aEncodedCerts, const TUid aClient);
	void ConstructL(const TPtrC8& aEncodedCerts, const CArrayPtr<CWTLSCertificate>& aRootCerts);
	void DoConstructL(const TPtrC8& aEncodedCerts);
		
private:
	RFs& iFs;
	CWTLSCertChainAO* iActiveObject;
	CArrayPtrFlat<CWTLSCertificate>* iChain;
	TBool iChainHasRoot;
	};

#endif