--- a/epoc32/include/unifiedcertstore.h Tue Nov 24 13:55:44 2009 +0000
+++ b/epoc32/include/unifiedcertstore.h Tue Mar 16 16:12:26 2010 +0000
@@ -1,1 +1,610 @@
-unifiedcertstore.h
+/*
+* Copyright (c) 2001-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:
+* UNIFIEDCERTSTORE.H
+* The unified certificate store implementation
+*
+*/
+
+
+
+
+/**
+ @file
+ @internalTechnology
+ @released
+*/
+
+#ifndef __UNIFIEDCERTSTORE_H__
+#define __UNIFIEDCERTSTORE_H__
+
+class CCertificate;
+
+#include <signed.h>
+#include <e32std.h>
+#include <f32file.h>
+#include <e32property.h>
+#include <sacls.h>
+#include <mcertstore.h>
+#include <ct/rmpointerarray.h>
+#include <ct/rcpointerarray.h>
+
+
+
+
+/**
+ *
+ * Publish and Subscribe - UnifiedCertSTore Category
+ * Aliased here to System Category to prevent SC break.
+ *
+ */
+const TUid KUnifiedCertStorePropertyCat = {KUidSystemCategoryValue};
+
+/**
+ *
+ * Publish and subscribe key for UnifiedCertSTore.
+ */
+enum TUnifiedCertStoreKey
+ {
+ /**
+ *
+ * The Publish and subscribe key for the certstore changes.
+ * If the client of the UnifiedCertstore needs to be notified when
+ * certificate addition, removal and trust&application setting occurs,
+ * the client needs to subscribe to KUnifiedCertStorePropertyCat and
+ * EUnifiedCertStoreFlag.
+ *
+ * Aliased here to KUidUnifiedCertstore flag to avoid SC break.
+ */
+ EUnifiedCertStoreFlag = KUidUnifiedCertstoreFlag
+ };
+
+/**
+ *
+ * The Unique ID for unknown hardware certstore, used as the input parameter when it is to be filtered.
+ * @deprecated. Used only for Data compatibility.
+ */
+
+const TInt KUnknownHardwareCertStore = 0;
+
+
+/**
+ *
+ * The Unique ID for mutable software certstore, used as the input parameter when it is to be filtered.
+ *
+ */
+
+const TInt KThirdPartyCertStore = 1;
+
+
+/**
+ *
+ * The Unique ID for SIM certstore, used as the input parameter when it is to be filtered.
+ *
+ */
+
+const TInt KSIMCertStore = 2;
+
+/**
+ *
+ * The Unique ID for WIM certstore, used as the input parameter when it is to be filtered.
+ *
+ */
+
+const TInt KWIMCertStore = 3;
+
+/**
+ *
+ * The Unique ID for UICC certstore, used as the input parameter when it is to be filtered.
+ *
+ */
+const TInt KUICCCertStore = 4;
+
+/**
+ *
+ * The Unique ID for immutable software certstore, used as the input parameter when it is to be filtered.
+ *
+ */
+
+const TInt KManufactureCertStore = 5;
+
+// Forward declarations
+class MCTCertStore;
+class MCTWritableCertStore;
+class MCTTokenInterface;
+class MCTToken;
+class MCTTokenType;
+class CCTCertInfo;
+class CCertAttributeFilter;
+class CCTTokenTypeInfo;
+class TCTTokenObjectHandle;
+class CCheckedCertStore;
+
+// This class is forward declared to avoid including its definition in this
+// exported header file because it must only be used internally.
+class CUnifiedCertStoreWorkingVars;
+class CX500DistinguishedName;
+
+/**
+ * The unified certificate store.
+ *
+ * This class provides a certificate store whose contents are the sum of the
+ * contents of all certificate store implementations on the device. It is
+ * intended as the single point of access for clients wishing to use certificate
+ * stores.
+ *
+ * Since this class is intended for widespread use, capability checks relating
+ * to certificate access are documented here even though the checks are actually
+ * made in the individual cert store implementations.
+ *
+ * @publishedAll
+ * @released
+ */
+NONSHARABLE_CLASS(CUnifiedCertStore) : public CActive, public MCertStore
+ {
+public:
+ /**
+ * Creates a new CUnifiedCertStore
+ *
+ * @param aFs A file server session. It must already be open.
+ * @param aOpenForWrite ETrue if the stores must be opened with write access
+ * (e.g. for adding certificates) and EFalse if the user
+ * only needs read-only access.
+ * @return A pointer to an instance of the CUnifiedCertStore class.
+ */
+ IMPORT_C static CUnifiedCertStore* NewL(RFs& aFs, TBool aOpenForWrite);
+
+ /**
+ * Creates a new CUnifiedCertStore and pushes it on the cleanup stack.
+ *
+ * @param aFs A file server session. It must already be open.
+ * @param aOpenForWrite ETrue if the stores must be opened with write access
+ * (e.g. for adding certificates) and EFalse if the user
+ * only needs read-only access.
+ * @return A pointer to an instance of the CUnifiedCertStore class.
+ */
+ IMPORT_C static CUnifiedCertStore* NewLC(RFs& aFs, TBool aOpenForWrite);
+ /**
+ * Creates a new CUnifiedCertStore with the sequence filter, so that multiple certstores that are managed
+ * by it will be filtered and ordered.
+ *
+ * @param aFs A file server session. It must already be open.
+ * @param aOpenForWrite ETrue if the stores must be opened with write access
+ * (e.g. for adding certificates) and EFalse if the user
+ * only needs read-only access. Ownership is taken.
+ * @param aOrderFilter An array of the unique sequence IDs specifying CertStore ordering.
+ * @return A pointer to an instance of the CUnifiedCertStore class.
+ */
+ IMPORT_C static CUnifiedCertStore* NewL(RFs& aFs,
+ TBool aOpenForWrite,
+ RArray<TInt>& aOrderFilter);
+ /**
+ * Creates a new CUnifiedCertStore with the sequence filter, so that multiple certstores that are managed
+ * by it will be filtered and ordered, and it is pushed on the cleanup stack.
+ *
+ * @param aFs A file server session. It must already be open.
+ * @param aOpenForWrite ETrue if the stores must be opened with write access
+ * (e.g. for adding certificates) and EFalse if the user
+ * only needs read-only access. Ownership is taken.
+ * @param aOrderFilter An array of the unique sequence IDs specifying CertStore ordering.
+ * @return A pointer to an instance of the CUnifiedCertStore class.
+ */
+ IMPORT_C static CUnifiedCertStore* NewLC(RFs& aFs,
+ TBool aOpenForWrite,
+ RArray<TInt>& aOrderFilter);
+
+ /**
+ * The destructor destroys all the resources owned by this object.
+ */
+ IMPORT_C ~CUnifiedCertStore();
+
+ /**
+ * Initializes the manager.
+ *
+ * It must be called after the manager has been constructed
+ * and before any call to the manager functions.
+ *
+ * This is an asynchronous request.
+ *
+ * @param aStatus The request status object; contains the result of the Initialize()
+ * request when complete. Set to KErrCancel if any outstanding request is cancelled.
+ */
+ IMPORT_C void Initialize(TRequestStatus& aStatus);
+
+ /**
+ * Cancels an ongoing Initialize() operation.
+ *
+ * The operation completes with KErrCancel.
+ */
+ IMPORT_C void CancelInitialize();
+
+public: // Implementation of MCertStore interface
+
+ /** Lists all certificates that satisfy the supplied filter.
+ *
+ * @param aCertInfos An array that the returned certificates are added to .
+ * @param aFilter A filter to restrict which certificates are returned.
+ * @param aStatus The request status object.
+ *
+ */
+ virtual void List(RMPointerArray<CCTCertInfo>& aCertInfos,
+ const CCertAttributeFilter& aFilter, TRequestStatus& aStatus);
+ virtual void CancelList();
+ virtual void GetCert(CCTCertInfo*& aCertInfo, const TCTTokenObjectHandle& aHandle,
+ TRequestStatus& aStatus);
+ virtual void CancelGetCert();
+
+ /** Gets the list of applications . Applications are represented by UIDs .
+ *
+ * @param aCertInfos An array of certificates .
+ * @param aApplications An array that the returned application UIDs are added to.
+ * @param aStatus The request status object.
+ *
+ */
+ virtual void Applications(const CCTCertInfo& aCertInfo,
+ RArray<TUid>& aApplications, TRequestStatus &aStatus);
+ virtual void CancelApplications();
+ virtual void IsApplicable(const CCTCertInfo& aCertInfo, TUid aApplication,
+ TBool& aIsApplicable, TRequestStatus& aStatus);
+ virtual void CancelIsApplicable();
+ virtual void Trusted(const CCTCertInfo& aCertInfo, TBool& aTrusted,
+ TRequestStatus& aStatus);
+ virtual void CancelTrusted();
+ virtual void Retrieve(const CCTCertInfo& aCertInfo, TDes8& aEncodedCert,
+ TRequestStatus& aStatus);
+ virtual void CancelRetrieve();
+
+public: // Functions defined in MCTWritableCertStore except Add functions
+
+ /**
+ * Removes a certificate.
+ *
+ * @param aCertInfo The certificate to be removed.
+ * @param aStatus The request status object; contains the result of the Remove()
+ * request when complete. Set to KErrCancel if an outstanding request is cancelled.
+ *
+ * @capability WriteUserData This requires the WriteUserData capability when
+ * applied to user certificates.
+ * @capability WriteDeviceData This requires the WriteDeviceData capability
+ * when applied to CA certificates.
+ * @leave KErrPermissionDenied If the caller doesn't have the required
+ * capabilities.
+ */
+ IMPORT_C void Remove(const CCTCertInfo& aCertInfo, TRequestStatus& aStatus);
+
+ /**
+ * Cancels an ongoing Remove() operation.
+ *
+ * The operation completes with KErrCancel.
+ */
+ IMPORT_C void CancelRemove();
+
+ /**
+ * Replaces the current applicability settings with the settings in the
+ * supplied array.
+ *
+ * This should only be called for CA certificates - it has no meaning for
+ * user certificates.
+ *
+ * @param aCertInfo The certificate whose applicability should be updated.
+ * @param aApplications The new applicability settings. Ownership of this
+ * remains with the caller, and it must remain valid for the
+ * lifetime of the call.
+ * @param aStatus The request status object; contains the result of the SetApplicability()
+ * request when complete. Set to KErrCancel, if an outstanding request is cancelled.
+ *
+ * @capability WriteDeviceData This requires the WriteDeviceData capability.
+ * @leave KErrPermissionDenied If the caller doesn't have the required capabilities.
+ */
+ IMPORT_C void SetApplicability(const CCTCertInfo& aCertInfo,
+ const RArray<TUid>& aApplications, TRequestStatus &aStatus);
+
+ /**
+ * Cancels an ongoing SetApplicability() operation.
+ *
+ * The operation completes with KErrCancel.
+ */
+ IMPORT_C void CancelSetApplicability();
+
+ /**
+ * Changes the trust settings.
+ *
+ * A CA certificate is trusted if the user is willing to use it for authenticating
+ * servers. It has no meaning with other types of certificates.
+ *
+ * @param aCertInfo The certificate to be updated.
+ * @param aTrusted ETrue, if trusted; EFalse, otherwise.
+ * @param aStatus The request status object; contains the result of the SetTrust()
+ * request when complete. Set to KErrCancel, if an outstanding request is cancelled.
+ *
+ * @capability WriteDeviceData This requires the WriteDeviceData capability.
+ * @leave KErrPermissionDenied If the caller doesn't have the required capabilities.
+ */
+ IMPORT_C void SetTrust(const CCTCertInfo& aCertInfo, TBool aTrusted,
+ TRequestStatus& aStatus);
+
+ /**
+ * Cancels an ongoing SetTrust() operation.
+ *
+ * The operation completes with KErrCancel.
+ */
+ IMPORT_C void CancelSetTrust();
+
+public:
+ /**
+ * Lists all certificates that have a particular subject DN.
+ *
+ * @param aCertInfos An array that the returned certificates are added to
+ * @param aFilter A filter to restrict which certificates are returned.
+ * @param aIssuer Only certificates with this issuer DN will be returned
+ * @param aStatus Asynchronous request status.
+ */
+ IMPORT_C void List(RMPointerArray<CCTCertInfo>& aCertInfos,
+ const CCertAttributeFilter& aFilter,
+ const TDesC8& aIssuer,
+ TRequestStatus& aStatus);
+
+ /**
+ * Lists all certificates that have a particular issuer.
+ *
+ * @param aCertInfos An array that the returned certificates are added to
+ * @param aFilter A filter to restrict which certificates are returned.
+ * @param aIssuers Only certificates with this issuer will be returned
+ * @param aStatus Asynchronous request status.
+ */
+ IMPORT_C void List(RMPointerArray<CCTCertInfo>& aCertInfos,
+ const CCertAttributeFilter& aFilter,
+ RPointerArray<const TDesC8> aIssuers,
+ TRequestStatus& aStatus);
+
+ /**
+ * Retrieves a certificate as a parsed object.
+ *
+ * This will only work for certificates that have a CCertificate-derived
+ * representation, in other words X509 and WTLS certificates. If called for
+ * a URL certificate, KErrNotSupported is returned.
+ *
+ * @param aCertInfo The certificate to retrieve
+ * @param aCert The returned certificate. This object can safely be up-cast
+ * to a CX509Certificate or CWTLSCertificate if it's known that
+ * that is the certificate format.
+ * @param aStatus Asynchronous request status.
+ *
+ * @capability ReadUserData This requires the ReadUserData capability when
+ * applied to user certificates, as these may contain
+ * sensitive user data.
+ * @leave KErrPermissionDenied If called for a user certificate when the
+ * caller doesn't have the ReadUserData capability.
+ */
+ IMPORT_C void Retrieve(const CCTCertInfo& aCertInfo, CCertificate*& aCert,
+ TRequestStatus& aStatus);
+
+ /**
+ * Gets the number of certificate stores.
+ *
+ * @return The total number of certificate stores.
+ */
+ IMPORT_C TInt CertStoreCount() const;
+
+ /**
+ * Gets a particular certificate store.
+ *
+ * @param aIndex The index of the required certificate store.
+ * A number between 0 and CertStoreCount() - 1.
+ * @return The certificate store.
+ */
+ IMPORT_C MCTCertStore& CertStore(TInt aIndex);
+
+ /**
+ * Gets the number of writeable certificate stores.
+ *
+ * @return The number of writeable certificate stores.
+ */
+ IMPORT_C TInt WritableCertStoreCount() const;
+
+ /**
+ * Gets a particular writeable certificate store.
+ *
+ * @param aIndex The index of the required certificate store.
+ * A number between 0 and WriteableCertStoreCount() - 1.
+ * @return The writeable certificate store.
+ */
+ IMPORT_C MCTWritableCertStore& WritableCertStore(TInt aIndex);
+
+ /**
+ * Gets the number of read-only certificate stores.
+ *
+ * @return The number of read-only certificate stores.
+ */
+ IMPORT_C TInt ReadOnlyCertStoreCount() const;
+
+ /**
+ * Gets a particular read-only certificate store.
+ *
+ * @param aIndex The index of the required certificate store.
+ * A number between 0 and ReadOnlyCertStoreCount() - 1.
+ * @return The read-only certificate store.
+ */
+ IMPORT_C MCTCertStore& ReadOnlyCertStore(TInt aIndex);
+
+private:
+ enum TState
+ {
+ EIdle,
+
+ EInitializeGetTokenList,
+ EInitializeGetToken,
+ EInitializeGetWritableInterface,
+ EInitializeGetReadableInterface,
+ EInitializeGetReadableInterfaceFinished,
+ EInitializeFinished,
+
+ EList,
+ ERetrieve,
+ ERetrieveForList,
+
+ EGetCert,
+ EApplications,
+ EIsApplicable,
+ ETrusted,
+ ERetrieveData,
+ ERemove,
+ ESetApplicability,
+ ESetTrust
+ };
+ enum TCompareResults
+ {
+ ENo,
+ EYes,
+ EMaybe
+ };
+private:
+ CUnifiedCertStore(RFs& aFs, TBool aOpenForWrite);
+ void ConstructL(RArray<TInt>& aOrderFilter);
+ void DoCancel();
+ void RunL();
+ TInt RunError(TInt aError);
+
+ // Implementations for asynchronous operations
+ void InitializeL();
+ void ListL(RMPointerArray<CCTCertInfo>& aCertInfos,
+ const CCertAttributeFilter& aFilter);
+ void ListL(RMPointerArray<CCTCertInfo>& aCertInfos,
+ const CCertAttributeFilter& aFilter,
+ RPointerArray<const TDesC8> aIssuers);
+ void RetrieveL(const CCTCertInfo& aCertInfo, CCertificate*& aCert);
+ void GetCertL(CCTCertInfo*& aCertInfo, const TCTTokenObjectHandle& aHandle);
+ void ApplicationsL(const CCTCertInfo& aCertInfo, RArray<TUid>& aApplications);
+ void IsApplicableL(const CCTCertInfo& aCertInfo, TUid aApplication,
+ TBool& aIsApplicable);
+ void TrustedL(const CCTCertInfo& aCertInfo, TBool& aTrusted);
+ void RetrieveDataL(const CCTCertInfo& aCertInfo, TDes8& aEncodedCert);
+ void RemoveL(const CCTCertInfo& aCertInfo);
+ void SetApplicabilityL(const CCTCertInfo& aCertInfo,
+ const RArray<TUid>& aApplications);
+ void SetTrustL(const CCTCertInfo& aCertInfo, TBool aTrusted);
+
+ // Helper functions
+ void AllocWorkingVarsL();
+ void BeginAsyncOp(TRequestStatus& aStatus, TState aState);
+ void DestroyTemporaryMembers();
+ MCTCertStore* GetCertStore(const TCTTokenObjectHandle& aHandle);
+ void FindCertStoreL(const TCTTokenObjectHandle& aHandle);
+ void FindWritableCertStoreL(const TCTTokenObjectHandle& aHandle);
+ TCompareResults CompareCertInfoDN(const CCTCertInfo* aCertInfo);
+ TBool MatchL(const CX500DistinguishedName& aName) const;
+ void Complete(TInt aError);
+ void CancelOutstandingRequest();
+
+ // Filters CertStores according to specified order.
+ void ApplyOrderingL(RCPointerArray<CCTTokenTypeInfo>& aTokenTypes);
+
+ void FilterTokenTypesL(RCPointerArray<CCTTokenTypeInfo>& aSearchTokenTypes,
+ RCPointerArray<CCTTokenTypeInfo>& aTempTokenTypes,
+ TInt aOrderAttribute);
+
+private:
+ /**
+ * A file server session, this is not logically a part of this class
+ * but is needed for the client store and the file certstore.
+ */
+ RFs& iFs;
+
+ TBool iOpenedForWrite;
+
+ RPointerArray<CCheckedCertStore> iReadOnlyCertStores;
+ RPointerArray<CCheckedCertStore> iWritableCertStores;
+ RPointerArray<CCheckedCertStore> iCertStores;
+
+ TBool iCurrentlyDoingReadOnly;
+
+ /**
+ * This a TokenType retrieved from the iTokenTypes array.
+ * We use this to get a list of Tokens and to open these Tokens.
+ */
+ MCTTokenType* iTokenType;
+
+ /**
+ * This is the list of Tokens for one of the Token Types of iTokenTypes.
+ */
+ RCPointerArray<HBufC> iTokens;
+
+ /** All the UIDs of hardware token types */
+ RArray<TUid> iHardwareTypeUids;
+ /**
+ * This is used as an index for the iTokens array when we try
+ * to get an interface to each of the tokens.
+ */
+ TInt iIndexTokens;
+
+ /**
+ * A Token interface. We will use the interface to get a readable or writable
+ * certstore interface. The value is updated at EInitializeGetToken and used
+ * at EInitializeGetWritableInterface.
+ */
+ MCTToken* iToken;
+
+ /**
+ * We use this to (temporarily) store the interface we obtained from iToken.
+ * It will be inserted in iWritableCertStores or iCertStores.
+ */
+ MCTTokenInterface* iTokenInterface;
+
+ /**
+ The index of the plugin certstore that is being processed
+ */
+ TInt iIndex;
+
+ /**
+ * This is the status of the caller of an asynchronous function. It must be set
+ * to KRequestPending by the function while doing the processing.
+ */
+ TRequestStatus* iClientStatus;
+
+ TState iState;
+
+ TBool iIsInitialized;
+
+ /**
+ * This member holds all the variables that are only used to store temporary results
+ * while performing a given operation. It must be initialized at the start of the
+ * operation and deleted at the end of it whether the opeartion completes successfully
+ * or not. When no operation is being performed it must be 0.
+ */
+ CUnifiedCertStoreWorkingVars* iWorkingVars;
+
+ /**
+ * The cert store in use by an outstanding async operation.
+ */
+ MCTCertStore *iCurrentCertStore;
+
+ /**
+ * The writable cert store in use by an outstanding async operation.
+ */
+ MCTWritableCertStore *iCurrentWritableCertStore;
+
+ // Padding to keep class size constant
+ TInt32 iUnused1;
+ TInt32 iUnused2;
+
+ // An array of Uids specifying Token Type ordering
+ RArray<TInt> iOrderAttributes;
+
+ // Publish and subscribe property which is used to notify the
+ // cerificate addition,removal and application&trust setting.
+ RProperty iPSCertstoreChangeProperty;
+
+ };
+
+#endif