1 /*

     2 * Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the License "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 /**

    22  @file 

    23  @internalAll 

    24 */

    25  

    26 #ifndef __WTLSCERTCHAIN_H__

    27 #define __WTLSCERTCHAIN_H__

    28 

    29 #include <e32std.h>

    30 #include <unifiedcertstore.h>

    31 #include <wtlscert.h>

    32 #include <wtlsnames.h>

    33 

    34 class TWTLSValidationStatus

    35 /** The validation status.

    36 *

    37 * Some errors cannot be blamed on any single certificate, in which case the 

    38 * iCert value is meaningless. The same structure is used for errors and for warnings. 

    39 *

    40 * @publishedAll

    41 * @released */

    42 	{

    43 public:

    44 	/** Creates a validation status object.

    45 	* 

    46 	* @param aError	The error type that occurred when validating the certificate chain.

    47 	* @param aCert	The index number for the certificate that gave rise to the error. */

    48 	IMPORT_C TWTLSValidationStatus(const TValidationError aError, const TInt aCert);

    49 	

    50 	/** The reason for the error. */

    51 	TValidationError iReason;

    52 	

    53 	/** The index number for the certificate that gave rise to the error. */

    54 	TInt iCert;

    55 	};

    56 

    57 class CWTLSValidationResult : public CBase

    58 /** Encapsulates the results of the validation process.

    59 * 

    60 * It is returned to client code, which can examine it. Client code takes ownership of it. 

    61 *

    62 * @publishedAll

    63 * @released */

    64 	{

    65 public:

    66 	/** Creates a new CWTLSValidationResult object and puts a pointer to it on the 

    67 	* cleanup stack.

    68 	* 

    69 	* @return	The new WTLS Validation Result object. */

    70 	IMPORT_C static CWTLSValidationResult* NewLC();

    71 	

    72 	/** Creates a new CWTLSValidationResult object.

    73 	* 

    74 	* @return	The new WTLS Validation Result object. */

    75 	IMPORT_C static CWTLSValidationResult* NewL();

    76 	

    77 	/** Destructor.

    78 	* 

    79 	* Frees all resources owned by the object, prior to its destruction. */

    80 	IMPORT_C ~CWTLSValidationResult();

    81 	

    82 	/** Gets the error status of the operation.

    83 	* 

    84 	* Any errors here are considered fatal: validation has failed.

    85 	* 

    86 	* @return	The error status of the operation. */

    87 	IMPORT_C const TWTLSValidationStatus Error() const;

    88 	

    89 	/** Gets an array of any warnings generated.

    90 	* 

    91 	* The warnings may or may not be fatal, depending on the context, which the 

    92 	* client is expected to provide.

    93 	* 

    94 	* @return	An array of any warnings generated. */

    95 	IMPORT_C const CArrayFixFlat<TWTLSValidationStatus>& Warnings() const;

    96 	

    97 	/** Resets the validation result object to its default values. 

    98 	 * @internalAll

    99 	 */

   100 	void Reset();

   101 	

   102 	/** Sets the error.

   103 	* 

   104 	* @param aError	The error type that occurred when validating the certificate chain.

   105 	* @param aCert	The index number for the certificate that gave rise to the error. 

   106 	* @internalAll

   107 	*/

   108 	void SetError(const TValidationError aError, const TInt aCert);

   109 	

   110 	/** Adds a warning to the validation.

   111 	* 

   112 	* @param aWarning	The validation status object to be added. 

   113 	* @internalAll

   114 	*/

   115 	void AppendWarningL(TWTLSValidationStatus aWarning);

   116 

   117 private:

   118 	CWTLSValidationResult();

   119 	void ConstructL();

   120 	TWTLSValidationStatus iError;

   121 	CArrayFixFlat<TWTLSValidationStatus>* iWarnings;

   122 	};

   123 

   124 class CWTLSRootCerts;

   125 class CWTLSCertChainAO;

   126 

   127 class CWTLSCertChain : public CBase

   128 /** Implements a WTLS certificate chain. 

   129 *

   130 * @publishedAll

   131 * @released */

   132 	{

   133 	friend class CWTLSCertChainAO;

   134 

   135 public:

   136 	/** Creates a certificate chain using the binary data in aEncodedCerts.

   137 	* 

   138 	* @param aFs			An open file server session.

   139 	* @param aEncodedCerts	One or more concatenated DER encoded WTLS certificates. 

   140 	* 						The first certificate will be interpreted as the end entity 

   141 	* 						certificate to be validated; subsequent certificates may be 

   142 	* 						in any order and may be used by the chain as intermediate 

   143 	* 						certificates, but not root certificates.

   144 	* @param aClient		The uid of the client. It is a value identifying the application 

   145 	* 						to the chain; this will be used to select a subset of stored 

   146 	* 						certificates to use as candidate root certificates. */

   147 	IMPORT_C static CWTLSCertChain* NewL(RFs& aFs, const TPtrC8& aEncodedCerts, 

   148 		const TUid aClient);

   149 	

   150 	/** Creates a certificate chain using the binary data in aEncodedCerts and puts 

   151 	* a pointer to the new object onto the cleanup stack.

   152 	* 

   153 	* @param aFs			An open file server session

   154 	* @param aEncodedCerts	One or more concatenated DER encoded WTLS certificates. 

   155 	* 						The first certificate will be interpreted as the end entity 

   156 	* 						certificate to be validated; subsequent certificates may be 

   157 	* 						in any order and may be used by the chain as intermediate 

   158 	* 						certificates, but not root certificates.

   159 	* @param aClient		The uid of the client. It is a value identifying the application 

   160 	* 						to the chain; this will be used to select a subset of stored 

   161 	* 						certificates to use as candidate root certificates. */

   162 	IMPORT_C static CWTLSCertChain* NewLC(RFs& aFs, const TPtrC8& aEncodedCerts,

   163 		const TUid aClient);

   164 	

   165 	/** Creates a certificate chain using the binary data in aEncodedCerts.

   166 	* 

   167 	* @param aFs			An open file server session.

   168 	* @param aEncodedCerts	One or more concatenated DER encoded WTLS certificates. 

   169 	* 						The first certificate will be interpreted as the end entity 

   170 	* 						certificate to be validated; subsequent certificates may be 

   171 	* 						in any order and may be used by the chain as intermediate 

   172 	* 						certificates, but not root certificates. Any self signed 

   173 	* 						certificates supplied here after the first one will be 

   174 	* 						discarded, as self signed certificates cannot by definition 

   175 	* 						be intermediate certificates.

   176 	* @param aRootCerts		An array of certificates which the chain will treat as 

   177 	* 						candidate root certificates. If one of these overloads is 

   178 	* 						used, the chain will not look in stores for root certificates, 

   179 	* 						but will only use the certificates supplied here. */

   180 	IMPORT_C static CWTLSCertChain* NewL(RFs& aFs, const TPtrC8& aEncodedCerts,

   181 		const CArrayPtr<CWTLSCertificate>& aRootCerts);

   182 	

   183 	/** Creates a certificate chain using the binary data in aEncodedCerts and puts 

   184 	* a pointer to the new object onto the cleanup stack.

   185 	* 

   186 	* @param aFs			An open file server session.

   187 	* @param aEncodedCerts	One or more concatenated DER encoded WTLS certificates. 

   188 	* 						The first certificate will be interpreted as the end entity 

   189 	* 						certificate to be validated; subsequent certificates may be 

   190 	* 						in any order and may be used by the chain as intermediate 

   191 	* 						certificates, but not root certificates. Any self signed 

   192 	* 						certificates supplied here after the first one will be 

   193 	* 						discarded as self signed certificates cannot by definition 

   194 	* 						be intermediate certificates.

   195 	* @param aRootCerts		An array of certificates which the chain will treat as 

   196 	* 						candidate root certificates. If one of these overloads is 

   197 	* 						used, the chain will not look in stores for root certificates, 

   198 	* 						but will only use the certificates supplied here. */

   199 	IMPORT_C static CWTLSCertChain* NewLC(RFs& aFs, const TPtrC8& aEncodedCerts,

   200 		const CArrayPtr<CWTLSCertificate>& aRootCerts);

   201 	

   202 	/** Destructor.

   203 	* 

   204 	* Frees all resources owned by the object. */

   205 	IMPORT_C ~CWTLSCertChain();

   206 	

   207 	/** Validates the chain.

   208 	* 

   209 	* @param aValidationResult	On completion, this contains the result of the validation.

   210 	* @param aValidationTime	The time for which validation should be performed, usually 

   211 	* 							the current time.

   212 	* @param aStatus			An asynchronous request status object. */

   213 	IMPORT_C void ValidateL(CWTLSValidationResult& aValidationResult, 

   214 		const TTime& aValidationTime, TRequestStatus& aStatus);

   215 	

   216 	/** Gets the number of WTLS certificates in the chain.

   217 	* 

   218 	* @return	The number of WTLS certificates in the chain. */

   219 	IMPORT_C TInt Count() const;

   220 	

   221 	/** Gets the certificate at the specified index.

   222 	* 

   223 	* @param aIndex	The ordinal number representing the position of the certificate 

   224 	* 				within the chain.

   225 	* @return		The WTLS certificate at the specified index. */

   226 	IMPORT_C const CWTLSCertificate& Cert(TInt aIndex) const;

   227 	

   228 	/** Tests whether the root certificate of the chain is locatable.

   229 	* 

   230 	* Note that the value is only significant after a successfull call to ValidateL().

   231 	* 

   232 	* @return	ETrue if the chain has a root; EFalse, otherwise. */

   233 	IMPORT_C TBool ChainHasRoot() const;

   234 	

   235 	/** Appends the specified encoded certificate to the chain.

   236 	* 

   237 	* @param aEncodedCerts	One or more concatenated DER encoded WTLS certificates. 

   238 	* 						These certificates will be used as candidates. The first 

   239 	* 						certificate will be interpreted as the end entity certificate 

   240 	* 						to be validated; subsequent certificates may be in any order 

   241 	* 						and may be used by the chain as intermediate certificates, 

   242 	* 						but not root certificates. */

   243 	IMPORT_C void AppendCertsL(const TPtrC8& aEncodedCerts);

   244 

   245 private:

   246 	CWTLSCertChain(RFs& aFs);

   247 	void ConstructL(const TPtrC8& aEncodedCerts, const TUid aClient);

   248 	void ConstructL(const TPtrC8& aEncodedCerts, const CArrayPtr<CWTLSCertificate>& aRootCerts);

   249 	void DoConstructL(const TPtrC8& aEncodedCerts);

   250 		

   251 private:

   252 	RFs& iFs;

   253 	CWTLSCertChainAO* iActiveObject;

   254 	CArrayPtrFlat<CWTLSCertificate>* iChain;

   255 	TBool iChainHasRoot;

   256 	};

   257 

   258 #endif