1.1 --- a/epoc32/include/wtlscertchain.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/wtlscertchain.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,258 @@
1.4 -wtlscertchain.h
1.5 +/*
1.6 +* Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* under the terms of the License "Eclipse Public License v1.0"
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description:
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +
1.24 +
1.25 +/**
1.26 + @file
1.27 + @internalAll
1.28 +*/
1.29 +
1.30 +#ifndef __WTLSCERTCHAIN_H__
1.31 +#define __WTLSCERTCHAIN_H__
1.32 +
1.33 +#include <e32std.h>
1.34 +#include <unifiedcertstore.h>
1.35 +#include <wtlscert.h>
1.36 +#include <wtlsnames.h>
1.37 +
1.38 +class TWTLSValidationStatus
1.39 +/** The validation status.
1.40 +*
1.41 +* Some errors cannot be blamed on any single certificate, in which case the
1.42 +* iCert value is meaningless. The same structure is used for errors and for warnings.
1.43 +*
1.44 +* @publishedAll
1.45 +* @released */
1.46 + {
1.47 +public:
1.48 + /** Creates a validation status object.
1.49 + *
1.50 + * @param aError The error type that occurred when validating the certificate chain.
1.51 + * @param aCert The index number for the certificate that gave rise to the error. */
1.52 + IMPORT_C TWTLSValidationStatus(const TValidationError aError, const TInt aCert);
1.53 +
1.54 + /** The reason for the error. */
1.55 + TValidationError iReason;
1.56 +
1.57 + /** The index number for the certificate that gave rise to the error. */
1.58 + TInt iCert;
1.59 + };
1.60 +
1.61 +class CWTLSValidationResult : public CBase
1.62 +/** Encapsulates the results of the validation process.
1.63 +*
1.64 +* It is returned to client code, which can examine it. Client code takes ownership of it.
1.65 +*
1.66 +* @publishedAll
1.67 +* @released */
1.68 + {
1.69 +public:
1.70 + /** Creates a new CWTLSValidationResult object and puts a pointer to it on the
1.71 + * cleanup stack.
1.72 + *
1.73 + * @return The new WTLS Validation Result object. */
1.74 + IMPORT_C static CWTLSValidationResult* NewLC();
1.75 +
1.76 + /** Creates a new CWTLSValidationResult object.
1.77 + *
1.78 + * @return The new WTLS Validation Result object. */
1.79 + IMPORT_C static CWTLSValidationResult* NewL();
1.80 +
1.81 + /** Destructor.
1.82 + *
1.83 + * Frees all resources owned by the object, prior to its destruction. */
1.84 + IMPORT_C ~CWTLSValidationResult();
1.85 +
1.86 + /** Gets the error status of the operation.
1.87 + *
1.88 + * Any errors here are considered fatal: validation has failed.
1.89 + *
1.90 + * @return The error status of the operation. */
1.91 + IMPORT_C const TWTLSValidationStatus Error() const;
1.92 +
1.93 + /** Gets an array of any warnings generated.
1.94 + *
1.95 + * The warnings may or may not be fatal, depending on the context, which the
1.96 + * client is expected to provide.
1.97 + *
1.98 + * @return An array of any warnings generated. */
1.99 + IMPORT_C const CArrayFixFlat<TWTLSValidationStatus>& Warnings() const;
1.100 +
1.101 + /** Resets the validation result object to its default values.
1.102 + * @internalAll
1.103 + */
1.104 + void Reset();
1.105 +
1.106 + /** Sets the error.
1.107 + *
1.108 + * @param aError The error type that occurred when validating the certificate chain.
1.109 + * @param aCert The index number for the certificate that gave rise to the error.
1.110 + * @internalAll
1.111 + */
1.112 + void SetError(const TValidationError aError, const TInt aCert);
1.113 +
1.114 + /** Adds a warning to the validation.
1.115 + *
1.116 + * @param aWarning The validation status object to be added.
1.117 + * @internalAll
1.118 + */
1.119 + void AppendWarningL(TWTLSValidationStatus aWarning);
1.120 +
1.121 +private:
1.122 + CWTLSValidationResult();
1.123 + void ConstructL();
1.124 + TWTLSValidationStatus iError;
1.125 + CArrayFixFlat<TWTLSValidationStatus>* iWarnings;
1.126 + };
1.127 +
1.128 +class CWTLSRootCerts;
1.129 +class CWTLSCertChainAO;
1.130 +
1.131 +class CWTLSCertChain : public CBase
1.132 +/** Implements a WTLS certificate chain.
1.133 +*
1.134 +* @publishedAll
1.135 +* @released */
1.136 + {
1.137 + friend class CWTLSCertChainAO;
1.138 +
1.139 +public:
1.140 + /** Creates a certificate chain using the binary data in aEncodedCerts.
1.141 + *
1.142 + * @param aFs An open file server session.
1.143 + * @param aEncodedCerts One or more concatenated DER encoded WTLS certificates.
1.144 + * The first certificate will be interpreted as the end entity
1.145 + * certificate to be validated; subsequent certificates may be
1.146 + * in any order and may be used by the chain as intermediate
1.147 + * certificates, but not root certificates.
1.148 + * @param aClient The uid of the client. It is a value identifying the application
1.149 + * to the chain; this will be used to select a subset of stored
1.150 + * certificates to use as candidate root certificates. */
1.151 + IMPORT_C static CWTLSCertChain* NewL(RFs& aFs, const TPtrC8& aEncodedCerts,
1.152 + const TUid aClient);
1.153 +
1.154 + /** Creates a certificate chain using the binary data in aEncodedCerts and puts
1.155 + * a pointer to the new object onto the cleanup stack.
1.156 + *
1.157 + * @param aFs An open file server session
1.158 + * @param aEncodedCerts One or more concatenated DER encoded WTLS certificates.
1.159 + * The first certificate will be interpreted as the end entity
1.160 + * certificate to be validated; subsequent certificates may be
1.161 + * in any order and may be used by the chain as intermediate
1.162 + * certificates, but not root certificates.
1.163 + * @param aClient The uid of the client. It is a value identifying the application
1.164 + * to the chain; this will be used to select a subset of stored
1.165 + * certificates to use as candidate root certificates. */
1.166 + IMPORT_C static CWTLSCertChain* NewLC(RFs& aFs, const TPtrC8& aEncodedCerts,
1.167 + const TUid aClient);
1.168 +
1.169 + /** Creates a certificate chain using the binary data in aEncodedCerts.
1.170 + *
1.171 + * @param aFs An open file server session.
1.172 + * @param aEncodedCerts One or more concatenated DER encoded WTLS certificates.
1.173 + * The first certificate will be interpreted as the end entity
1.174 + * certificate to be validated; subsequent certificates may be
1.175 + * in any order and may be used by the chain as intermediate
1.176 + * certificates, but not root certificates. Any self signed
1.177 + * certificates supplied here after the first one will be
1.178 + * discarded, as self signed certificates cannot by definition
1.179 + * be intermediate certificates.
1.180 + * @param aRootCerts An array of certificates which the chain will treat as
1.181 + * candidate root certificates. If one of these overloads is
1.182 + * used, the chain will not look in stores for root certificates,
1.183 + * but will only use the certificates supplied here. */
1.184 + IMPORT_C static CWTLSCertChain* NewL(RFs& aFs, const TPtrC8& aEncodedCerts,
1.185 + const CArrayPtr<CWTLSCertificate>& aRootCerts);
1.186 +
1.187 + /** Creates a certificate chain using the binary data in aEncodedCerts and puts
1.188 + * a pointer to the new object onto the cleanup stack.
1.189 + *
1.190 + * @param aFs An open file server session.
1.191 + * @param aEncodedCerts One or more concatenated DER encoded WTLS certificates.
1.192 + * The first certificate will be interpreted as the end entity
1.193 + * certificate to be validated; subsequent certificates may be
1.194 + * in any order and may be used by the chain as intermediate
1.195 + * certificates, but not root certificates. Any self signed
1.196 + * certificates supplied here after the first one will be
1.197 + * discarded as self signed certificates cannot by definition
1.198 + * be intermediate certificates.
1.199 + * @param aRootCerts An array of certificates which the chain will treat as
1.200 + * candidate root certificates. If one of these overloads is
1.201 + * used, the chain will not look in stores for root certificates,
1.202 + * but will only use the certificates supplied here. */
1.203 + IMPORT_C static CWTLSCertChain* NewLC(RFs& aFs, const TPtrC8& aEncodedCerts,
1.204 + const CArrayPtr<CWTLSCertificate>& aRootCerts);
1.205 +
1.206 + /** Destructor.
1.207 + *
1.208 + * Frees all resources owned by the object. */
1.209 + IMPORT_C ~CWTLSCertChain();
1.210 +
1.211 + /** Validates the chain.
1.212 + *
1.213 + * @param aValidationResult On completion, this contains the result of the validation.
1.214 + * @param aValidationTime The time for which validation should be performed, usually
1.215 + * the current time.
1.216 + * @param aStatus An asynchronous request status object. */
1.217 + IMPORT_C void ValidateL(CWTLSValidationResult& aValidationResult,
1.218 + const TTime& aValidationTime, TRequestStatus& aStatus);
1.219 +
1.220 + /** Gets the number of WTLS certificates in the chain.
1.221 + *
1.222 + * @return The number of WTLS certificates in the chain. */
1.223 + IMPORT_C TInt Count() const;
1.224 +
1.225 + /** Gets the certificate at the specified index.
1.226 + *
1.227 + * @param aIndex The ordinal number representing the position of the certificate
1.228 + * within the chain.
1.229 + * @return The WTLS certificate at the specified index. */
1.230 + IMPORT_C const CWTLSCertificate& Cert(TInt aIndex) const;
1.231 +
1.232 + /** Tests whether the root certificate of the chain is locatable.
1.233 + *
1.234 + * Note that the value is only significant after a successfull call to ValidateL().
1.235 + *
1.236 + * @return ETrue if the chain has a root; EFalse, otherwise. */
1.237 + IMPORT_C TBool ChainHasRoot() const;
1.238 +
1.239 + /** Appends the specified encoded certificate to the chain.
1.240 + *
1.241 + * @param aEncodedCerts One or more concatenated DER encoded WTLS certificates.
1.242 + * These certificates will be used as candidates. The first
1.243 + * certificate will be interpreted as the end entity certificate
1.244 + * to be validated; subsequent certificates may be in any order
1.245 + * and may be used by the chain as intermediate certificates,
1.246 + * but not root certificates. */
1.247 + IMPORT_C void AppendCertsL(const TPtrC8& aEncodedCerts);
1.248 +
1.249 +private:
1.250 + CWTLSCertChain(RFs& aFs);
1.251 + void ConstructL(const TPtrC8& aEncodedCerts, const TUid aClient);
1.252 + void ConstructL(const TPtrC8& aEncodedCerts, const CArrayPtr<CWTLSCertificate>& aRootCerts);
1.253 + void DoConstructL(const TPtrC8& aEncodedCerts);
1.254 +
1.255 +private:
1.256 + RFs& iFs;
1.257 + CWTLSCertChainAO* iActiveObject;
1.258 + CArrayPtrFlat<CWTLSCertificate>* iChain;
1.259 + TBool iChainHasRoot;
1.260 + };
1.261 +
1.262 +#endif