Class CUnifiedCertStore

class CUnifiedCertStore : public CActive, public MCertStore;

Description

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.

Derivation

• MCertStore - No description.

• CBase - Base class for all classes to be instantiated on the heap

• CActive - The core class of the active object abstraction

• CUnifiedCertStore - The unified certificate store

Members

Defined in CUnifiedCertStore:
Applications(), CancelApplications(), CancelGetCert(), CancelInitialize(), CancelIsApplicable(), CancelList(), CancelRemove(), CancelRetrieve(), CancelSetApplicability(), CancelSetTrust(), CancelTrusted(), CertStore(), CertStoreCount(), DoCancel(), GetCert(), Initialize(), IsApplicable(), List(), List(), List(), NewL(), NewL(), NewLC(), NewLC(), ReadOnlyCertStore(), ReadOnlyCertStoreCount(), Remove(), Retrieve(), Retrieve(), RunError(), RunL(), SetApplicability(), SetTrust(), Trusted(), WritableCertStore(), WritableCertStoreCount(), ~CUnifiedCertStore()

Inherited from CActive:
Cancel(), Deque(), EPriorityHigh, EPriorityIdle, EPriorityLow, EPriorityStandard, EPriorityUserInput, Extension_(), IsActive(), IsAdded(), Priority(), SetActive(), SetPriority(), TPriority, iStatus

Inherited from CBase:
Delete(), operator new()

static IMPORT_C CUnifiedCertStore *NewL(RFs &aFs, TBool aOpenForWrite);

Description

Creates a new CUnifiedCertStore

Parameters

RFs &aFs A file server session. It must already be open. TBool 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 value

CUnifiedCertStore * A pointer to an instance of the CUnifiedCertStore class.

static IMPORT_C CUnifiedCertStore *NewLC(RFs &aFs, TBool aOpenForWrite);

Description

Creates a new CUnifiedCertStore and pushes it on the cleanup stack.

Parameters

RFs &aFs A file server session. It must already be open. TBool 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 value

CUnifiedCertStore * A pointer to an instance of the CUnifiedCertStore class.

static IMPORT_C CUnifiedCertStore *NewL(RFs &aFs, TBool aOpenForWrite, RArray< TInt > &aOrderFilter);

Description

Creates a new CUnifiedCertStore with the sequence filter, so that multiple certstores that are managed by it will be filtered and ordered.

Parameters

RFs &aFs A file server session. It must already be open. TBool 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. RArray< TInt > &aOrderFilter An array of the unique sequence IDs specifying CertStore ordering.

Return value

CUnifiedCertStore * A pointer to an instance of the CUnifiedCertStore class.

static IMPORT_C CUnifiedCertStore *NewLC(RFs &aFs, TBool aOpenForWrite, RArray< TInt > &aOrderFilter);

Description

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.

Parameters

RFs &aFs A file server session. It must already be open. TBool 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. RArray< TInt > &aOrderFilter An array of the unique sequence IDs specifying CertStore ordering.

Return value

CUnifiedCertStore * A pointer to an instance of the CUnifiedCertStore class.

IMPORT_C ~CUnifiedCertStore();

Description

The destructor destroys all the resources owned by this object.

IMPORT_C void Initialize(TRequestStatus &aStatus);

Description

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.

Parameters

TRequestStatus &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 CancelInitialize();

Description

Cancels an ongoing Initialize() operation.

The operation completes with KErrCancel.

virtual void List(RMPointerArray< CCTCertInfo > &aCertInfos, const CCertAttributeFilter &aFilter, TRequestStatus &aStatus);

Description

Lists all certificates that satisfy the supplied filter.

Parameters

RMPointerArray< CCTCertInfo > &aCertInfos An array that the returned certificates are added to . const CCertAttributeFilter &aFilter A filter to restrict which certificates are returned. TRequestStatus &aStatus The request status object.

virtual void CancelList();

Description

virtual void GetCert(CCTCertInfo *&aCertInfo, const TCTTokenObjectHandle &aHandle, TRequestStatus &aStatus);

Description

Parameters

CCTCertInfo *&aCertInfo const TCTTokenObjectHandle &aHandle TRequestStatus &aStatus

virtual void CancelGetCert();

Description

virtual void Applications(const CCTCertInfo &aCertInfo, RArray< TUid > &aApplications, TRequestStatus &aStatus);

Description

Gets the list of applications . Applications are represented by UIDs .

Parameters

const CCTCertInfo &aCertInfo RArray< TUid > &aApplications An array that the returned application UIDs are added to. TRequestStatus &aStatus The request status object.

virtual void CancelApplications();

Description

virtual void IsApplicable(const CCTCertInfo &aCertInfo, TUid aApplication, TBool &aIsApplicable, TRequestStatus &aStatus);

Description

Parameters

const CCTCertInfo &aCertInfo TUid aApplication TBool &aIsApplicable TRequestStatus &aStatus

virtual void CancelIsApplicable();

Description

virtual void Trusted(const CCTCertInfo &aCertInfo, TBool &aTrusted, TRequestStatus &aStatus);

Description

Parameters

const CCTCertInfo &aCertInfo TBool &aTrusted TRequestStatus &aStatus

virtual void CancelTrusted();

Description

virtual void Retrieve(const CCTCertInfo &aCertInfo, TDes8 &aEncodedCert, TRequestStatus &aStatus);

Description

Parameters

const CCTCertInfo &aCertInfo TDes8 &aEncodedCert TRequestStatus &aStatus

virtual void CancelRetrieve();

Description

Capability:	WriteDeviceData	This requires the WriteDeviceData capability when applied to CA certificates.
Capability:	WriteUserData	This requires the WriteUserData capability when applied to user certificates.

IMPORT_C void Remove(const CCTCertInfo &aCertInfo, TRequestStatus &aStatus);

Description

Removes a certificate.

Parameters

const CCTCertInfo &aCertInfo The certificate to be removed. TRequestStatus &aStatus The request status object; contains the result of the Remove() request when complete. Set to KErrCancel if an outstanding request is cancelled.

Leave codes

KErrPermissionDenied If the caller doesn't have the required capabilities.

IMPORT_C void CancelRemove();

Description

Cancels an ongoing Remove() operation.

The operation completes with KErrCancel.

Capability:

WriteDeviceData

This requires the WriteDeviceData capability.

IMPORT_C void SetApplicability(const CCTCertInfo &aCertInfo, const RArray< TUid > &aApplications, TRequestStatus &aStatus);

Description

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.

Parameters

const CCTCertInfo &aCertInfo The certificate whose applicability should be updated. const RArray< TUid > &aApplications The new applicability settings. Ownership of this remains with the caller, and it must remain valid for the lifetime of the call. TRequestStatus &aStatus The request status object; contains the result of the SetApplicability() request when complete. Set to KErrCancel, if an outstanding request is cancelled.

Leave codes

KErrPermissionDenied If the caller doesn't have the required capabilities.

IMPORT_C void CancelSetApplicability();

Description

Cancels an ongoing SetApplicability() operation.

The operation completes with KErrCancel.

Capability:

WriteDeviceData

This requires the WriteDeviceData capability.

IMPORT_C void SetTrust(const CCTCertInfo &aCertInfo, TBool aTrusted, TRequestStatus &aStatus);

Description

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.

Parameters

const CCTCertInfo &aCertInfo The certificate to be updated. TBool aTrusted ETrue, if trusted; EFalse, otherwise. TRequestStatus &aStatus The request status object; contains the result of the SetTrust() request when complete. Set to KErrCancel, if an outstanding request is cancelled.

Leave codes

KErrPermissionDenied If the caller doesn't have the required capabilities.

IMPORT_C void CancelSetTrust();

Description

Cancels an ongoing SetTrust() operation.

The operation completes with KErrCancel.

IMPORT_C void List(RMPointerArray< CCTCertInfo > &aCertInfos, const CCertAttributeFilter &aFilter, const TDesC8 &aIssuer, TRequestStatus &aStatus);

Description

Lists all certificates that have a particular subject DN.

Parameters

RMPointerArray< CCTCertInfo > &aCertInfos An array that the returned certificates are added to const CCertAttributeFilter &aFilter A filter to restrict which certificates are returned. const TDesC8 &aIssuer Only certificates with this issuer DN will be returned TRequestStatus &aStatus Asynchronous request status.

IMPORT_C void List(RMPointerArray< CCTCertInfo > &aCertInfos, const CCertAttributeFilter &aFilter, RPointerArray< const TDesC8 > aIssuers, TRequestStatus &aStatus);

Description

Lists all certificates that have a particular issuer.

Parameters

RMPointerArray< CCTCertInfo > &aCertInfos An array that the returned certificates are added to const CCertAttributeFilter &aFilter A filter to restrict which certificates are returned. RPointerArray< const TDesC8 > aIssuers Only certificates with this issuer will be returned TRequestStatus &aStatus Asynchronous request status.

Capability:

ReadUserData

This requires the ReadUserData capability when applied to user certificates, as these may contain sensitive user data.

IMPORT_C void Retrieve(const CCTCertInfo &aCertInfo, CCertificate *&aCert, TRequestStatus &aStatus);

Description

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.

Parameters

const CCTCertInfo &aCertInfo The certificate to retrieve CCertificate *&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. TRequestStatus &aStatus Asynchronous request status.

Leave codes

KErrPermissionDenied If called for a user certificate when the caller doesn't have the ReadUserData capability.

IMPORT_C TInt CertStoreCount() const;

Description

Gets the number of certificate stores.

Return value

TInt The total number of certificate stores.

IMPORT_C MCTCertStore &CertStore(TInt aIndex);

Description

Gets a particular certificate store.

Parameters

TInt aIndex The index of the required certificate store. A number between 0 and CertStoreCount() - 1.

Return value

MCTCertStore & The certificate store.

IMPORT_C TInt WritableCertStoreCount() const;

Description

Gets the number of writeable certificate stores.

Return value

TInt The number of writeable certificate stores.

IMPORT_C MCTWritableCertStore &WritableCertStore(TInt aIndex);

Description

Gets a particular writeable certificate store.

Parameters

TInt aIndex The index of the required certificate store. A number between 0 and WriteableCertStoreCount() - 1.

Return value

MCTWritableCertStore & The writeable certificate store.

IMPORT_C TInt ReadOnlyCertStoreCount() const;

Description

Gets the number of read-only certificate stores.

Return value

TInt The number of read-only certificate stores.

IMPORT_C MCTCertStore &ReadOnlyCertStore(TInt aIndex);

Description

Gets a particular read-only certificate store.

Parameters

TInt aIndex The index of the required certificate store. A number between 0 and ReadOnlyCertStoreCount() - 1.

Return value

MCTCertStore & The read-only certificate store.

private: virtual void DoCancel();

Description

Implements cancellation of an outstanding request.

This function is called as part of the active object's Cancel().

It must call the appropriate cancel function offered by the active object's asynchronous service provider. The asynchronous service provider's cancel is expected to act immediately.

DoCancel() must not wait for event completion; this is handled by Cancel().

private: virtual void RunL();

Description

Handles an active object's request completion event.

A derived class must provide an implementation to handle the completed request. If appropriate, it may issue another request.

The function is called by the active scheduler when a request completion event occurs, i.e. after the active scheduler's WaitForAnyRequest() function completes.

Before calling this active object's RunL() function, the active scheduler has:

1. decided that this is the highest priority active object with a completed request

2. marked this active object's request as complete (i.e. the request is no longer outstanding)

RunL() runs under a trap harness in the active scheduler. If it leaves, then the active scheduler calls RunError() to handle the leave.

Note that once the active scheduler's Start() function has been called, all user code is run under one of the program's active object's RunL() or RunError() functions.

private: virtual TInt RunError(TInt aError);

Description

Parameters

TInt aError

Return value

TInt