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