1.1 --- a/epoc32/include/pkixcertchain.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/pkixcertchain.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,434 @@
1.4 -pkixcertchain.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 +* PKIXCERTCHAIN.H
1.20 +* PKIX certificate chain implementation
1.21 +*
1.22 +*/
1.23 +
1.24 +
1.25 +
1.26 +
1.27 +/**
1.28 + @file
1.29 + @internalTechnology
1.30 +*/
1.31 +
1.32 +#ifndef __PKIXCERTCHAIN_H__
1.33 +#define __PKIXCERTCHAIN_H__
1.34 +
1.35 +#include <e32std.h>
1.36 +#include <x509certchain.h>
1.37 +#include <pkixvalidationresult.h>
1.38 +
1.39 +//implements key validation according to RFC 2459 (PKIX cert/CRL profile), section 6
1.40 +class CPKIXValidationState;
1.41 +class CPKIXChainBuilder;
1.42 +class CPKIXCertChainAO;
1.43 +class CPKIXCertChainHelper;
1.44 +class MCertStore;
1.45 +
1.46 +/**
1.47 + * Base class for CPKIXCertChain
1.48 + * @internalTechnology
1.49 + */
1.50 +class CPKIXCertChainBase : public CX509CertChain
1.51 + {
1.52 +public:
1.53 + //constructors
1.54 + /** Creates a certificate chain using the binary data in aEncodedCerts.
1.55 + *
1.56 + * @param aCertStore The certificate store to use when looking for root certificates.
1.57 + * @param aEncodedCerts One or more concatenated DER encoded X.509 certificates.
1.58 + * The first certificate will be interpreted as the end entity certificate to
1.59 + * be validated; subsequent certificates may be in any order and may be used
1.60 + * by the chain as intermediate certificates, but not root certificates. The
1.61 + * individual certificates can be retrieved since each one contains its own length.
1.62 + * @param aClient The Uid identifying the purpose for which the chain will be used.
1.63 + * This value will be used to select a subset of stored certificates, by way of their trust
1.64 + * settings, to be used as candidate root certificates. */
1.65 + IMPORT_C static CPKIXCertChainBase* NewL(MCertStore& aCertStore, const TPtrC8& aEncodedCerts,
1.66 + const TUid aClient);
1.67 +
1.68 + /** Creates a certificate chain using the binary data in aEncodedCerts, and puts
1.69 + * a pointer to the new object onto the cleanup stack.
1.70 + *
1.71 + * @param aCertStore The certificate store to use when looking for root certificates.
1.72 + * @param aEncodedCerts One or more concatenated DER encoded X.509 certificates.
1.73 + * The first certificate will be interpreted as the end entity certificate to
1.74 + * be validated; subsequent certificates may be in any order and may be used
1.75 + * by the chain as intermediate certificates, but not root certificates. The
1.76 + * individual certificates can be retrieved since each one contains its own length.
1.77 + * @param aClient The Uid identifying the purpose for which the chain will be used.
1.78 + * This value will be used to select a subset of stored certificates, by way of their trust
1.79 + * settings, to be used as candidate root certificates. */
1.80 + IMPORT_C static CPKIXCertChainBase* NewLC(MCertStore& aCertStore, const TPtrC8& aEncodedCerts,
1.81 + const TUid aClient);
1.82 +
1.83 + /** Creates a certificate chain using the binary data in aEncodedCerts.
1.84 + *
1.85 + * @param aCertStore The certificate store to use when looking for root certificates.
1.86 + * @param aEncodedCerts One or more concatenated DER encoded X.509 certificates.
1.87 + * The first certificate will be interpreted as the end entity certificate to
1.88 + * be validated; subsequent certificates may be in any order and may be used
1.89 + * by the chain as intermediate certificates, but not root certificates. Any
1.90 + * self signed certificates supplied here after the first one will be discarded,
1.91 + * as self signed certificates cannot by definition be intermediate certificates.
1.92 + * The individual certificates can be retrieved since each one contains its own
1.93 + * length.
1.94 + * @param aRootCerts An array of certificates which the chain will treat as candidate root
1.95 + * certificates. If one of these overloads is used, the chain will not look in
1.96 + * stores for root certificates, but will only use the certificates supplied here. */
1.97 + IMPORT_C static CPKIXCertChainBase* NewL(MCertStore& aCertStore, const TPtrC8& aEncodedCerts,
1.98 + const RPointerArray<CX509Certificate>& aRootCerts);
1.99 +
1.100 + /** Creates a certificate chain using the binary data in aEncodedCerts and puts
1.101 + * a pointer to the new object onto the cleanup stack.
1.102 + *
1.103 + * @param aCertStore The certificate store to use when looking for root certificates.
1.104 + * @param aEncodedCerts One or more concatenated DER encoded X.509 certificates.
1.105 + * The first certificate will be interpreted as the end entity certificate to
1.106 + * be validated; subsequent certificates may be in any order and may be used
1.107 + * by the chain as intermediate certificates, but not root certificates. Any
1.108 + * self signed certificates supplied here after the first one will be discarded
1.109 + * as self signed certificates cannot by definition be intermediate certificates.
1.110 + * The individual certificates can be retrieved since each one contains its own
1.111 + * length.
1.112 + * @param aRootCerts An array of certificates which the chain will treat as candidate root
1.113 + * certificates. If one of these overloads is used, the chain will not look in
1.114 + * stores for root certificates, but will only use the certificates supplied here. */
1.115 + IMPORT_C static CPKIXCertChainBase* NewLC(MCertStore& aCertStore, const TPtrC8& aEncodedCerts,
1.116 + const RPointerArray<CX509Certificate>& aRootCerts);
1.117 +
1.118 + /** Destructor.
1.119 + *
1.120 + * Frees all resources owned by the object. */
1.121 + IMPORT_C ~CPKIXCertChainBase();
1.122 + //validation
1.123 +
1.124 + /** Validates the chain.
1.125 + *
1.126 + * @param aValidationResult On completion, this contains the result of the validation.
1.127 + * @param aValidationTime The time that should be presumed to be the current time when checking timestamps.
1.128 + * @param aStatus An asynchronous request status object. */
1.129 + IMPORT_C void ValidateL(CPKIXValidationResultBase& aValidationResult,
1.130 + const TTime& aValidationTime, TRequestStatus& aStatus);
1.131 +
1.132 + /** Validates the chain.
1.133 + *
1.134 + * @param aValidationResult On completion, this contains the result of the validation.
1.135 + * @param aValidationTime The time that should be presumed to be the current time when checking timestamps.
1.136 + * @param aInitialPolicies The policies we want to be present in the certificate chain.
1.137 + * @param aStatus An asynchronous request status object. */
1.138 + IMPORT_C void ValidateL(CPKIXValidationResultBase& aValidationResult,
1.139 + const TTime& aValidationTime, const CArrayPtr<HBufC>& aInitialPolicies,
1.140 + TRequestStatus& aStatus);
1.141 +
1.142 + /** Cancels an asynchronous ValidateL() operation. */
1.143 + IMPORT_C void CancelValidate();
1.144 +
1.145 + /** Adds one or more intermediate certificates to use when building the chain .
1.146 + *
1.147 + * Any self signed certs are ignored.
1.148 + *
1.149 + * @param aEncodedCerts The concatenation of one or more DER encoded X.509 certificates. */
1.150 + IMPORT_C void AddCertL(const TPtrC8& aEncodedCerts);
1.151 +
1.152 + /** Tests whether the root certificate of the chain is locatable.
1.153 + *
1.154 + * Note that the value is only significant after a successful call to ValidateL().
1.155 + *
1.156 + * @return ETrue if the chain has a root; EFalse, otherwise. */
1.157 + IMPORT_C TBool ChainHasRoot() const;
1.158 +
1.159 + /** Returns a list of the critical extension OIDs that are supported by the
1.160 + * chain validator. If a critical extension is encountered in a certificate
1.161 + * chain whose OID matches an element in this set then the chain validator
1.162 + * shall treat this as a warning instead of an error.
1.163 + *
1.164 + * If CPKIXCertChain::SetSupportedCriticalExtensionsL() has not been called, this
1.165 + * list will return the default set of supported critical extensions which
1.166 + * includes the X.509 standard and Symbian specific SIS file critical extensions.
1.167 + * These extensions may change in the future and should not be relied upon.
1.168 + *
1.169 + * @return The current list of supported critical extension OIDs. Ownership is not
1.170 + * transferred to the caller. */
1.171 + IMPORT_C const RPointerArray<TDesC>& SupportedCriticalExtensions() const;
1.172 +
1.173 + /** Adds one or more critical extension OIDs to the list of supported critical
1.174 + * extensions. Duplicate OID values are not added.
1.175 + *
1.176 + * @param aCriticalExtOids A list of the critical extensions OIDs to append to the supported
1.177 + * list. Ownership is not transferred from the caller. */
1.178 + IMPORT_C void AddSupportedCriticalExtensionsL(const RPointerArray<TDesC>& aCriticalExtOids);
1.179 +
1.180 + /** Removes one or more critical extension OIDs from the list of supported critical extensions.
1.181 + *
1.182 + * @param aCriticalExts A list of the critical extensions OIDs to remove from the supported list.
1.183 + * Ownership is with the original caller. Oids will not be destroyed. */
1.184 + IMPORT_C void RemoveSupportedCriticalExtensions(const RPointerArray<TDesC>& aCriticalExtOids);
1.185 +
1.186 + /** Completely replaces the set of supported critical extensions for certificate validation. If a critical
1.187 + * extension is encountered matching one of these OIDs then its occurrence is treated as a warning rather
1.188 + * than an error. The results of which can be queried through a call to CPKIXValidationResult::ValidationWarnings().
1.189 + *
1.190 + * @param aCriticalExtOids A list of the critical extensions OIDs for the class to support. Ownership is
1.191 + * not transferred from the caller. */
1.192 + IMPORT_C void SetSupportedCriticalExtensionsL(const RPointerArray<TDesC>& aCriticalExtOids);
1.193 +
1.194 + /** Resets the current list of supported critical extensions and re-populates it with the default set
1.195 + * which includes the X.509 standard and Symbian specific SIS file critical extensions. These extensions
1.196 + * may change in the future and should not be relied upon. */
1.197 + IMPORT_C void ResetSupportedCriticalExtsToDefaultL();
1.198 +
1.199 + /** Specify if a failed check on the certificate validity date is treated as an error or a warning.
1.200 + *
1.201 + * @param aIsFatal ETrue for reporting as an error; EFalse for a warning.*/
1.202 + IMPORT_C void SetValidityPeriodCheckFatal(TBool aIsFatal);
1.203 +
1.204 + /** Returns whether or not validity period check failures will be reported as an error or a warning.
1.205 + *
1.206 + * @param aIsFatal ETrue if failure is reported as an error; EFalse for a warning.*/
1.207 + IMPORT_C TBool ValidityPeriodCheckFatal() const;
1.208 +
1.209 +protected:
1.210 + IMPORT_C CPKIXCertChainBase();
1.211 + IMPORT_C void ConstructL(MCertStore& aCertStore, const TPtrC8& aEncodedCerts, TUid aClient);
1.212 + IMPORT_C void ConstructL(MCertStore& aCertStore, const TPtrC8& aEncodedCerts, const RPointerArray<CX509Certificate>& aRootCerts);
1.213 +
1.214 +public:
1.215 + // Public non-exported methods called by CPKIXCertChainAO
1.216 + CArrayPtrFlat<CX509Certificate>& Chain();
1.217 + const RPointerArray<CX509Certificate>& IntermediateCerts();
1.218 + TBool ChainHasRoot();
1.219 + void RemoveLastCerts(TInt aNumberOfCertsToRemove);
1.220 + void SetChainHasRoot(TBool aHasRoot);
1.221 +
1.222 +private:
1.223 + void DoConstructL(const TPtrC8& aEncodedCerts);
1.224 +
1.225 + /**
1.226 + * This function adds certificates to the chain but only the ones that are not
1.227 + * self-signed.
1.228 + *
1.229 + * @param aEncodedCerts The encoded certificates.
1.230 + */
1.231 + void AddIntermediateCertsL(const TPtrC8& aEncodedCerts);
1.232 +
1.233 +private:
1.234 + /**
1.235 + * Holds a list of candiate intermediate certs - these come from the encoded
1.236 + * certs passed at construction time, and also any added with AddCertL().
1.237 + */
1.238 + RPointerArray<CX509Certificate> iIntermediateCerts;
1.239 +
1.240 + /**
1.241 + * This is ETrue if the chain has a root and EFalse if it hasn't. The value
1.242 + * is only significant after a successfull call to ValidateL().
1.243 + */
1.244 + TBool iChainHasRoot;
1.245 +
1.246 + /**
1.247 + * Most of the fucntionality of the class is asynchronous and is in fact
1.248 + * delegated to iActiveObject which will deal with all the asynchronous
1.249 + * functions.
1.250 + */
1.251 + CPKIXCertChainAO* iActiveObject;
1.252 +
1.253 + /**
1.254 + * Holds a list of supported critical extensions set by the client.
1.255 + */
1.256 + RPointerArray<TDesC> iSupportedCriticalExts;
1.257 +
1.258 + /**
1.259 + * When true (the defaut) indicates that a failed check on the validity period of a
1.260 + * certificate will result in a fatal error. When false this instead results in a
1.261 + * warning.
1.262 + */
1.263 + TBool iDateTimeCheckFatal;
1.264 + };
1.265 +
1.266 +
1.267 +/**
1.268 + * This class implements a PKIX certificate chain.
1.269 + *
1.270 + * @publishedAll
1.271 + * @released
1.272 + * @since v6.0
1.273 + */
1.274 +class CPKIXCertChain : public CPKIXCertChainBase
1.275 + {
1.276 +public:
1.277 +
1.278 + //constructors
1.279 + /** Creates a certificate chain using the binary data in aEncodedCerts.
1.280 + *
1.281 + * @param aFs An open file server session.
1.282 + * @param aEncodedCerts One or more concatenated DER encoded X.509 certificates.
1.283 + * The first certificate will be interpreted as the end entity certificate to
1.284 + * be validated; subsequent certificates may be in any order and may be used
1.285 + * by the chain as intermediate certificates, but not root certificates. The
1.286 + * individual certificates can be retrieved since each one contains its own length.
1.287 + * @param aClient The Uid identifying the purpose for which the chain will be used.
1.288 + * This value will be used to select a subset of stored certificates, by way of their trust
1.289 + * settings, to be used as candidate root certificates. */
1.290 + IMPORT_C static CPKIXCertChain* NewL(RFs& aFs, const TPtrC8& aEncodedCerts,
1.291 + const TUid aClient);
1.292 +
1.293 + /** Creates a certificate chain using the binary data in aEncodedCerts, and puts
1.294 + * a pointer to the new object onto the cleanup stack.
1.295 + *
1.296 + * @param aFs An open file server session
1.297 + * @param aEncodedCerts One or more concatenated DER encoded X.509 certificates.
1.298 + * The first certificate will be interpreted as the end entity certificate to
1.299 + * be validated; subsequent certificates may be in any order and may be used
1.300 + * by the chain as intermediate certificates, but not root certificates. The
1.301 + * individual certificates can be retrieved since each one contains its own length.
1.302 + * @param aClient The Uid identifying the purpose for which the chain will be used.
1.303 + * This value will be used to select a subset of stored certificates, by way of their trust
1.304 + * settings, to be used as candidate root certificates. */
1.305 + IMPORT_C static CPKIXCertChain* NewLC(RFs& aFs, const TPtrC8& aEncodedCerts,
1.306 + const TUid aClient);
1.307 +
1.308 + /** Creates a certificate chain using the binary data in aEncodedCerts.
1.309 + *
1.310 + * @param aFs An open file server session.
1.311 + * @param aEncodedCerts One or more concatenated DER encoded X.509 certificates.
1.312 + * The first certificate will be interpreted as the end entity certificate to
1.313 + * be validated; subsequent certificates may be in any order and may be used
1.314 + * by the chain as intermediate certificates, but not root certificates. Any
1.315 + * self signed certificates supplied here after the first one will be discarded,
1.316 + * as self signed certificates cannot by definition be intermediate certificates.
1.317 + * The individual certificates can be retrieved since each one contains its own
1.318 + * length.
1.319 + * @param aRootCerts An array of certificates which the chain will treat as candidate root
1.320 + * certificates. If one of these overloads is used, the chain will not look in
1.321 + * stores for root certificates, but will only use the certificates supplied here. */
1.322 + IMPORT_C static CPKIXCertChain* NewL(RFs& aFs, const TPtrC8& aEncodedCerts,
1.323 + const RPointerArray<CX509Certificate>& aRootCerts);
1.324 +
1.325 + /** Creates a certificate chain using the binary data in aEncodedCerts and puts
1.326 + * a pointer to the new object onto the cleanup stack.
1.327 + *
1.328 + * @param aFs An open file server session.
1.329 + * @param aEncodedCerts One or more concatenated DER encoded X.509 certificates.
1.330 + * The first certificate will be interpreted as the end entity certificate to
1.331 + * be validated; subsequent certificates may be in any order and may be used
1.332 + * by the chain as intermediate certificates, but not root certificates. Any
1.333 + * self signed certificates supplied here after the first one will be discarded
1.334 + * as self signed certificates cannot by definition be intermediate certificates.
1.335 + * The individual certificates can be retrieved since each one contains its own
1.336 + * length.
1.337 + * @param aRootCerts An array of certificates which the chain will treat as candidate root
1.338 + * certificates. If one of these overloads is used, the chain will not look in
1.339 + * stores for root certificates, but will only use the certificates supplied here. */
1.340 + IMPORT_C static CPKIXCertChain* NewLC(RFs& aFs, const TPtrC8& aEncodedCerts,
1.341 + const RPointerArray<CX509Certificate>& aRootCerts);
1.342 +
1.343 + //destructor
1.344 + /** Destructor.
1.345 + *
1.346 + * Frees all resources owned by the object. */
1.347 + IMPORT_C ~CPKIXCertChain();
1.348 + //validation
1.349 +
1.350 + /** Validates the chain.
1.351 + *
1.352 + * @param aValidationResult On completion, this contains the result of the validation.
1.353 + * @param aValidationTime The time that should be presumed to be the current time when checking timestamps.
1.354 + * @param aStatus An asynchronous request status object. */
1.355 + IMPORT_C void ValidateL(CPKIXValidationResult& aValidationResult,
1.356 + const TTime& aValidationTime, TRequestStatus& aStatus);
1.357 +
1.358 + /** Validates the chain.
1.359 + *
1.360 + * @param aValidationResult On completion, this contains the result of the validation.
1.361 + * @param aValidationTime The time that should be presumed to be the current time when checking timestamps.
1.362 + * @param aInitialPolicies The policies we want to be present in the certificate chain.
1.363 + * @param aStatus An asynchronous request status object. */
1.364 + IMPORT_C void ValidateL(CPKIXValidationResult& aValidationResult,
1.365 + const TTime& aValidationTime, const CArrayPtr<HBufC>& aInitialPolicies,
1.366 + TRequestStatus& aStatus);
1.367 +
1.368 + /** Cancels an asynchronous ValidateL() operation. */
1.369 + IMPORT_C void CancelValidate();
1.370 +
1.371 + /** Adds a certificate (if it is not self-signed) to the chain .
1.372 + *
1.373 + * @param aEncodedCerts A DER encoded X.509 certificate. */
1.374 + IMPORT_C void AddCertL(const TPtrC8& aEncodedCerts);
1.375 +
1.376 + /** Tests whether the root certificate of the chain is locatable.
1.377 + *
1.378 + * Note that the value is only significant after a successfull call to ValidateL().
1.379 + *
1.380 + * @return ETrue if the chain has a root; EFalse, otherwise. */
1.381 + IMPORT_C TBool ChainHasRoot() const;
1.382 +
1.383 + /** Returns a list of the critical extension OIDs that are supported by the
1.384 + * chain validator. If a critical extension is encountered in a certificate
1.385 + * chain whose OID matches an element in this set then the chain validator
1.386 + * shall treat this as a warning instead of an error.
1.387 + *
1.388 + * If CPKIXCertChain::SetSupportedCriticalExtensionsL() has not been called, this
1.389 + * list will return the default set of supported critical extensions which
1.390 + * includes the X.509 standard and Symbian specific SIS file critical extensions.
1.391 + * These extensions may change in the future and should not be relied upon.
1.392 + *
1.393 + * @return The current list of supported critical extension OIDs. Ownership is not
1.394 + * transferred to the caller. */
1.395 + IMPORT_C const RPointerArray<TDesC>& SupportedCriticalExtensions() const;
1.396 +
1.397 + /** Adds one or more critical extension OIDs to the list of supported critical
1.398 + * extensions. Duplicate OID values are not added.
1.399 + *
1.400 + * @param aCriticalExtOids A list of the critical extensions OIDs to append to the supported
1.401 + * list. Ownership is not transferred from the caller. */
1.402 + IMPORT_C void AddSupportedCriticalExtensionsL(const RPointerArray<TDesC>& aCriticalExtOids);
1.403 +
1.404 + /** Removes one or more critical extension OIDs from the list of supported critical extensions.
1.405 + *
1.406 + * @param aCriticalExts A list of the critical extensions OIDs to remove from the supported list.
1.407 + * Ownership is with the original caller. Oids will not be destroyed. */
1.408 + IMPORT_C void RemoveSupportedCriticalExtensions(const RPointerArray<TDesC>& aCriticalExtOids);
1.409 +
1.410 + /** Completely replaces the set of supported critical extensions for certificate validation. If a critical
1.411 + * extension is encountered matching one of these OIDs then its occurrence is treated as a warning rather
1.412 + * than an error. The results of which can be queried through a call to CPKIXValidationResult::ValidationWarnings().
1.413 + *
1.414 + * @param aCriticalExtOids A list of the critical extensions OIDs for the class to support. Ownership is
1.415 + * not transferred from the caller. */
1.416 + IMPORT_C void SetSupportedCriticalExtensionsL(const RPointerArray<TDesC>& aCriticalExtOids);
1.417 +
1.418 + /** Resets the current list of supported critical extensions and re-populates it with the default set
1.419 + * which includes the X.509 standard and Symbian specific SIS file critical extensions. These extensions
1.420 + * may change in the future and should not be relied upon. */
1.421 + IMPORT_C void ResetSupportedCriticalExtsToDefaultL();
1.422 +
1.423 + /** Specify if a failed check on the certificate validity date is treated as an error or a warning.
1.424 + *
1.425 + * @param aIsFatal ETrue for reporting as an error; EFalse for a warning.*/
1.426 + IMPORT_C void SetValidityPeriodCheckFatal(TBool aIsFatal);
1.427 +
1.428 + private:
1.429 + CPKIXCertChain();
1.430 + void ConstructL(RFs& aFs, const TPtrC8& aEncodedCerts, TUid aClient);
1.431 + void ConstructL(RFs& aFs, const TPtrC8& aEncodedCerts,
1.432 + const RPointerArray<CX509Certificate>& aRootCerts);
1.433 +
1.434 + private:
1.435 + CPKIXCertChainHelper* iHelper;
1.436 + };
1.437 +
1.438 +#endif