--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/cryptoservices/certificateandkeymgmt/inc/pkixCertChain_v2.h Wed Jul 08 11:25:26 2009 +0100
@@ -0,0 +1,434 @@
+/*
+* 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:
+* PKIXCERTCHAIN.H
+* PKIX certificate chain implementation
+*
+*/
+
+
+
+
+/**
+ @file
+ @internalTechnology
+*/
+
+#ifndef __PKIXCERTCHAIN_H__
+#define __PKIXCERTCHAIN_H__
+
+#include <e32std.h>
+#include <x509certchain.h>
+#include <pkixvalidationresult.h>
+
+//implements key validation according to RFC 2459 (PKIX cert/CRL profile), section 6
+class CPKIXValidationState;
+class CPKIXChainBuilder;
+class CPKIXCertChainAO;
+class CPKIXCertChainHelper;
+class MCertStore;
+
+/**
+ * Base class for CPKIXCertChain
+ * @internalTechnology
+ */
+class CPKIXCertChainBase : public CX509CertChain
+ {
+public:
+ //constructors
+ /** Creates a certificate chain using the binary data in aEncodedCerts.
+ *
+ * @param aCertStore The certificate store to use when looking for root certificates.
+ * @param aEncodedCerts One or more concatenated DER encoded X.509 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. The
+ * individual certificates can be retrieved since each one contains its own length.
+ * @param aClient The Uid identifying the purpose for which the chain will be used.
+ * This value will be used to select a subset of stored certificates, by way of their trust
+ * settings, to be used as candidate root certificates. */
+ IMPORT_C static CPKIXCertChainBase* NewL(MCertStore& aCertStore, 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 aCertStore The certificate store to use when looking for root certificates.
+ * @param aEncodedCerts One or more concatenated DER encoded X.509 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. The
+ * individual certificates can be retrieved since each one contains its own length.
+ * @param aClient The Uid identifying the purpose for which the chain will be used.
+ * This value will be used to select a subset of stored certificates, by way of their trust
+ * settings, to be used as candidate root certificates. */
+ IMPORT_C static CPKIXCertChainBase* NewLC(MCertStore& aCertStore, const TPtrC8& aEncodedCerts,
+ const TUid aClient);
+
+ /** Creates a certificate chain using the binary data in aEncodedCerts.
+ *
+ * @param aCertStore The certificate store to use when looking for root certificates.
+ * @param aEncodedCerts One or more concatenated DER encoded X.509 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.
+ * The individual certificates can be retrieved since each one contains its own
+ * length.
+ * @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 CPKIXCertChainBase* NewL(MCertStore& aCertStore, const TPtrC8& aEncodedCerts,
+ const RPointerArray<CX509Certificate>& aRootCerts);
+
+ /** Creates a certificate chain using the binary data in aEncodedCerts and puts
+ * a pointer to the new object onto the cleanup stack.
+ *
+ * @param aCertStore The certificate store to use when looking for root certificates.
+ * @param aEncodedCerts One or more concatenated DER encoded X.509 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.
+ * The individual certificates can be retrieved since each one contains its own
+ * length.
+ * @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 CPKIXCertChainBase* NewLC(MCertStore& aCertStore, const TPtrC8& aEncodedCerts,
+ const RPointerArray<CX509Certificate>& aRootCerts);
+
+ /** Destructor.
+ *
+ * Frees all resources owned by the object. */
+ IMPORT_C ~CPKIXCertChainBase();
+ //validation
+
+ /** Validates the chain.
+ *
+ * @param aValidationResult On completion, this contains the result of the validation.
+ * @param aValidationTime The time that should be presumed to be the current time when checking timestamps.
+ * @param aStatus An asynchronous request status object. */
+ IMPORT_C void ValidateL(CPKIXValidationResultBase& aValidationResult,
+ const TTime& aValidationTime, TRequestStatus& aStatus);
+
+ /** Validates the chain.
+ *
+ * @param aValidationResult On completion, this contains the result of the validation.
+ * @param aValidationTime The time that should be presumed to be the current time when checking timestamps.
+ * @param aInitialPolicies The policies we want to be present in the certificate chain.
+ * @param aStatus An asynchronous request status object. */
+ IMPORT_C void ValidateL(CPKIXValidationResultBase& aValidationResult,
+ const TTime& aValidationTime, const CArrayPtr<HBufC>& aInitialPolicies,
+ TRequestStatus& aStatus);
+
+ /** Cancels an asynchronous ValidateL() operation. */
+ IMPORT_C void CancelValidate();
+
+ /** Adds one or more intermediate certificates to use when building the chain .
+ *
+ * Any self signed certs are ignored.
+ *
+ * @param aEncodedCerts The concatenation of one or more DER encoded X.509 certificates. */
+ IMPORT_C void AddCertL(const TPtrC8& aEncodedCerts);
+
+ /** Tests whether the root certificate of the chain is locatable.
+ *
+ * Note that the value is only significant after a successful call to ValidateL().
+ *
+ * @return ETrue if the chain has a root; EFalse, otherwise. */
+ IMPORT_C TBool ChainHasRoot() const;
+
+ /** Returns a list of the critical extension OIDs that are supported by the
+ * chain validator. If a critical extension is encountered in a certificate
+ * chain whose OID matches an element in this set then the chain validator
+ * shall treat this as a warning instead of an error.
+ *
+ * If CPKIXCertChain::SetSupportedCriticalExtensionsL() has not been called, this
+ * list will return the default set of supported critical extensions which
+ * includes the X.509 standard and Symbian specific SIS file critical extensions.
+ * These extensions may change in the future and should not be relied upon.
+ *
+ * @return The current list of supported critical extension OIDs. Ownership is not
+ * transferred to the caller. */
+ IMPORT_C const RPointerArray<TDesC>& SupportedCriticalExtensions() const;
+
+ /** Adds one or more critical extension OIDs to the list of supported critical
+ * extensions. Duplicate OID values are not added.
+ *
+ * @param aCriticalExtOids A list of the critical extensions OIDs to append to the supported
+ * list. Ownership is not transferred from the caller. */
+ IMPORT_C void AddSupportedCriticalExtensionsL(const RPointerArray<TDesC>& aCriticalExtOids);
+
+ /** Removes one or more critical extension OIDs from the list of supported critical extensions.
+ *
+ * @param aCriticalExts A list of the critical extensions OIDs to remove from the supported list.
+ * Ownership is with the original caller. Oids will not be destroyed. */
+ IMPORT_C void RemoveSupportedCriticalExtensions(const RPointerArray<TDesC>& aCriticalExtOids);
+
+ /** Completely replaces the set of supported critical extensions for certificate validation. If a critical
+ * extension is encountered matching one of these OIDs then its occurrence is treated as a warning rather
+ * than an error. The results of which can be queried through a call to CPKIXValidationResult::ValidationWarnings().
+ *
+ * @param aCriticalExtOids A list of the critical extensions OIDs for the class to support. Ownership is
+ * not transferred from the caller. */
+ IMPORT_C void SetSupportedCriticalExtensionsL(const RPointerArray<TDesC>& aCriticalExtOids);
+
+ /** Resets the current list of supported critical extensions and re-populates it with the default set
+ * which includes the X.509 standard and Symbian specific SIS file critical extensions. These extensions
+ * may change in the future and should not be relied upon. */
+ IMPORT_C void ResetSupportedCriticalExtsToDefaultL();
+
+ /** Specify if a failed check on the certificate validity date is treated as an error or a warning.
+ *
+ * @param aIsFatal ETrue for reporting as an error; EFalse for a warning.*/
+ IMPORT_C void SetValidityPeriodCheckFatal(TBool aIsFatal);
+
+ /** Returns whether or not validity period check failures will be reported as an error or a warning.
+ *
+ * @param aIsFatal ETrue if failure is reported as an error; EFalse for a warning.*/
+ IMPORT_C TBool ValidityPeriodCheckFatal() const;
+
+protected:
+ IMPORT_C CPKIXCertChainBase();
+ IMPORT_C void ConstructL(MCertStore& aCertStore, const TPtrC8& aEncodedCerts, TUid aClient);
+ IMPORT_C void ConstructL(MCertStore& aCertStore, const TPtrC8& aEncodedCerts, const RPointerArray<CX509Certificate>& aRootCerts);
+
+public:
+ // Public non-exported methods called by CPKIXCertChainAO
+ CArrayPtrFlat<CX509Certificate>& Chain();
+ const RPointerArray<CX509Certificate>& IntermediateCerts();
+ TBool ChainHasRoot();
+ void RemoveLastCerts(TInt aNumberOfCertsToRemove);
+ void SetChainHasRoot(TBool aHasRoot);
+
+private:
+ void DoConstructL(const TPtrC8& aEncodedCerts);
+
+ /**
+ * This function adds certificates to the chain but only the ones that are not
+ * self-signed.
+ *
+ * @param aEncodedCerts The encoded certificates.
+ */
+ void AddIntermediateCertsL(const TPtrC8& aEncodedCerts);
+
+private:
+ /**
+ * Holds a list of candiate intermediate certs - these come from the encoded
+ * certs passed at construction time, and also any added with AddCertL().
+ */
+ RPointerArray<CX509Certificate> iIntermediateCerts;
+
+ /**
+ * This is ETrue if the chain has a root and EFalse if it hasn't. The value
+ * is only significant after a successfull call to ValidateL().
+ */
+ TBool iChainHasRoot;
+
+ /**
+ * Most of the fucntionality of the class is asynchronous and is in fact
+ * delegated to iActiveObject which will deal with all the asynchronous
+ * functions.
+ */
+ CPKIXCertChainAO* iActiveObject;
+
+ /**
+ * Holds a list of supported critical extensions set by the client.
+ */
+ RPointerArray<TDesC> iSupportedCriticalExts;
+
+ /**
+ * When true (the defaut) indicates that a failed check on the validity period of a
+ * certificate will result in a fatal error. When false this instead results in a
+ * warning.
+ */
+ TBool iDateTimeCheckFatal;
+ };
+
+
+/**
+ * This class implements a PKIX certificate chain.
+ *
+ * @publishedAll
+ * @released
+ * @since v6.0
+ */
+class CPKIXCertChain : public CPKIXCertChainBase
+ {
+public:
+
+ //constructors
+ /** 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 X.509 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. The
+ * individual certificates can be retrieved since each one contains its own length.
+ * @param aClient The Uid identifying the purpose for which the chain will be used.
+ * This value will be used to select a subset of stored certificates, by way of their trust
+ * settings, to be used as candidate root certificates. */
+ IMPORT_C static CPKIXCertChain* 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 X.509 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. The
+ * individual certificates can be retrieved since each one contains its own length.
+ * @param aClient The Uid identifying the purpose for which the chain will be used.
+ * This value will be used to select a subset of stored certificates, by way of their trust
+ * settings, to be used as candidate root certificates. */
+ IMPORT_C static CPKIXCertChain* 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 X.509 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.
+ * The individual certificates can be retrieved since each one contains its own
+ * length.
+ * @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 CPKIXCertChain* NewL(RFs& aFs, const TPtrC8& aEncodedCerts,
+ const RPointerArray<CX509Certificate>& 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 X.509 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.
+ * The individual certificates can be retrieved since each one contains its own
+ * length.
+ * @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 CPKIXCertChain* NewLC(RFs& aFs, const TPtrC8& aEncodedCerts,
+ const RPointerArray<CX509Certificate>& aRootCerts);
+
+ //destructor
+ /** Destructor.
+ *
+ * Frees all resources owned by the object. */
+ IMPORT_C ~CPKIXCertChain();
+ //validation
+
+ /** Validates the chain.
+ *
+ * @param aValidationResult On completion, this contains the result of the validation.
+ * @param aValidationTime The time that should be presumed to be the current time when checking timestamps.
+ * @param aStatus An asynchronous request status object. */
+ IMPORT_C void ValidateL(CPKIXValidationResult& aValidationResult,
+ const TTime& aValidationTime, TRequestStatus& aStatus);
+
+ /** Validates the chain.
+ *
+ * @param aValidationResult On completion, this contains the result of the validation.
+ * @param aValidationTime The time that should be presumed to be the current time when checking timestamps.
+ * @param aInitialPolicies The policies we want to be present in the certificate chain.
+ * @param aStatus An asynchronous request status object. */
+ IMPORT_C void ValidateL(CPKIXValidationResult& aValidationResult,
+ const TTime& aValidationTime, const CArrayPtr<HBufC>& aInitialPolicies,
+ TRequestStatus& aStatus);
+
+ /** Cancels an asynchronous ValidateL() operation. */
+ IMPORT_C void CancelValidate();
+
+ /** Adds a certificate (if it is not self-signed) to the chain .
+ *
+ * @param aEncodedCerts A DER encoded X.509 certificate. */
+ IMPORT_C void AddCertL(const TPtrC8& aEncodedCerts);
+
+ /** 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;
+
+ /** Returns a list of the critical extension OIDs that are supported by the
+ * chain validator. If a critical extension is encountered in a certificate
+ * chain whose OID matches an element in this set then the chain validator
+ * shall treat this as a warning instead of an error.
+ *
+ * If CPKIXCertChain::SetSupportedCriticalExtensionsL() has not been called, this
+ * list will return the default set of supported critical extensions which
+ * includes the X.509 standard and Symbian specific SIS file critical extensions.
+ * These extensions may change in the future and should not be relied upon.
+ *
+ * @return The current list of supported critical extension OIDs. Ownership is not
+ * transferred to the caller. */
+ IMPORT_C const RPointerArray<TDesC>& SupportedCriticalExtensions() const;
+
+ /** Adds one or more critical extension OIDs to the list of supported critical
+ * extensions. Duplicate OID values are not added.
+ *
+ * @param aCriticalExtOids A list of the critical extensions OIDs to append to the supported
+ * list. Ownership is not transferred from the caller. */
+ IMPORT_C void AddSupportedCriticalExtensionsL(const RPointerArray<TDesC>& aCriticalExtOids);
+
+ /** Removes one or more critical extension OIDs from the list of supported critical extensions.
+ *
+ * @param aCriticalExts A list of the critical extensions OIDs to remove from the supported list.
+ * Ownership is with the original caller. Oids will not be destroyed. */
+ IMPORT_C void RemoveSupportedCriticalExtensions(const RPointerArray<TDesC>& aCriticalExtOids);
+
+ /** Completely replaces the set of supported critical extensions for certificate validation. If a critical
+ * extension is encountered matching one of these OIDs then its occurrence is treated as a warning rather
+ * than an error. The results of which can be queried through a call to CPKIXValidationResult::ValidationWarnings().
+ *
+ * @param aCriticalExtOids A list of the critical extensions OIDs for the class to support. Ownership is
+ * not transferred from the caller. */
+ IMPORT_C void SetSupportedCriticalExtensionsL(const RPointerArray<TDesC>& aCriticalExtOids);
+
+ /** Resets the current list of supported critical extensions and re-populates it with the default set
+ * which includes the X.509 standard and Symbian specific SIS file critical extensions. These extensions
+ * may change in the future and should not be relied upon. */
+ IMPORT_C void ResetSupportedCriticalExtsToDefaultL();
+
+ /** Specify if a failed check on the certificate validity date is treated as an error or a warning.
+ *
+ * @param aIsFatal ETrue for reporting as an error; EFalse for a warning.*/
+ IMPORT_C void SetValidityPeriodCheckFatal(TBool aIsFatal);
+
+ private:
+ CPKIXCertChain();
+ void ConstructL(RFs& aFs, const TPtrC8& aEncodedCerts, TUid aClient);
+ void ConstructL(RFs& aFs, const TPtrC8& aEncodedCerts,
+ const RPointerArray<CX509Certificate>& aRootCerts);
+
+ private:
+ CPKIXCertChainHelper* iHelper;
+ };
+
+#endif