CUnifiedCertStore in Security Certificate_and_Key

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(const CCTCertInfo &,RArray< TUid > &,TRequestStatus &)Gets the list of applications . Applications are represented by UIDs .
CancelApplications()Cancels an ongoing CUnifiedCertStore::Applications(const CCTCertInfo &,RArra...
CancelGetCert()Cancel an ongoing CUnifiedCertStore::GetCert(CCTCertInfo *&,const TCTTokenOb...
CancelInitialize()Cancels an ongoing CUnifiedCertStore::Initialize(TRequestStatus &) operation...
CancelIsApplicable()Cancels an ongoing CUnifiedCertStore::IsApplicable(const CCTCertInfo &,TUid,...
CancelList()Cancels an ongoing CUnifiedCertStore::List(RMPointerArray< CCTCertInfo > &...
CancelRemove()Cancels an ongoing CUnifiedCertStore::Remove(const CCTCertInfo &,TRequestSta...
CancelRetrieve()Cancels an ongoing CUnifiedCertStore::Retrieve(const CCTCertInfo &,TDes8 &am...
CancelSetApplicability()Cancels an ongoing CUnifiedCertStore::SetApplicability(const CCTCertInfo &,c...
CancelSetTrust()Cancels an ongoing CUnifiedCertStore::SetTrust(const CCTCertInfo &,TBool,TRe...
CancelTrusted()Cancels an ongoing CUnifiedCertStore::Trusted(const CCTCertInfo &,TBool &...
CertStore(TInt)Gets a particular certificate store.
CertStoreCount()constGets the number of certificate stores.
DoCancel()Implements cancellation of an outstanding request.
GetCert(CCTCertInfo *&,const TCTTokenObjectHandle &,TRequestStatus &)Get a certificate given its handle.
Initialize(TRequestStatus &)Initializes the manager.
IsApplicable(const CCTCertInfo &,TUid,TBool &,TRequestStatus &)Tests if a certificate is applicable to a particular application.
List(RMPointerArray< CCTCertInfo > &,const CCertAttributeFilter &,RPointerArray< const TDesC8 >,TRequestStatus &)Lists all certificates that have a particular issuer.
List(RMPointerArray< CCTCertInfo > &,const CCertAttributeFilter &,TRequestStatus &)Lists all certificates that satisfy the supplied filter.
List(RMPointerArray< CCTCertInfo > &,const CCertAttributeFilter &,const TDesC8 &,TRequestStatus &)Lists all certificates that have a particular subject DN.
NewL(RFs &,TBool)Creates a new CUnifiedCertStore
NewL(RFs &,TBool,RArray< TInt > &)Creates a new CUnifiedCertStore with the sequence filter, so that multiple certs...
NewLC(RFs &,TBool)Creates a new CUnifiedCertStore and pushes it on the cleanup stack.
NewLC(RFs &,TBool,RArray< TInt > &)Creates a new CUnifiedCertStore with the sequence filter, so that multiple certs...
ReadOnlyCertStore(TInt)Gets a particular read-only certificate store.
ReadOnlyCertStoreCount()constGets the number of read-only certificate stores.
Remove(const CCTCertInfo &,TRequestStatus &)Removes a certificate.
Retrieve(const CCTCertInfo &,CCertificate *&,TRequestStatus &)Retrieves a certificate as a parsed object.
Retrieve(const CCTCertInfo &,TDes8 &,TRequestStatus &)Retrieves the actual data of the certificate.
RunError(TInt)
RunL()Handles an active object's request completion event.
SetApplicability(const CCTCertInfo &,const RArray< TUid > &,TRequestStatus &)Replaces the current applicability settings with the settings in the supplied ar...
SetTrust(const CCTCertInfo &,TBool,TRequestStatus &)Changes the trust settings.
Trusted(const CCTCertInfo &,TBool &,TRequestStatus &)Tests whether a certificate is trusted.
WritableCertStore(TInt)Gets a particular writeable certificate store.
WritableCertStoreCount()constGets the number of writeable certificate stores.
~CUnifiedCertStore()The destructor destroys all the resources owned by this object.

Inherited from CActive:

CActive(TInt)Constructs the active object with the specified priority.
Cancel()Cancels the wait for completion of an outstanding request.
Deque()Removes the active object from the active scheduler's list of active objects.
EPriorityHighA priority higher than EPriorityUserInput.
EPriorityIdleA low priority, useful for active objects representing background processing.
EPriorityLowA priority higher than EPriorityIdle but lower than EPriorityStandard.
EPriorityStandardMost active objects will have this priority.
EPriorityUserInputA priority higher than EPriorityStandard; useful for active objects handling use...
Extension_(TUint,TAny *&,TAny *)Extension function
IsActive()constDetermines whether the active object has a request outstanding.
IsAdded()constDetermines whether the active object has been added to the active scheduler's li...
Priority()constGets the priority of the active object.
SetActive()Indicates that the active object has issued a request and that it is now outstan...
SetPriority(TInt)Sets the priority of the active object.
TPriorityDefines standard priorities for active objects.
iStatusThe request status associated with an asynchronous request.

Inherited from CBase:

Delete(CBase *)Deletes the specified object.
operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...
operator new(TUint,TAny *)Initialises the object to binary zeroes.
operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...
operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...
operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...

IMPORT_C static 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.

IMPORT_C static 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.

IMPORT_C static 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.

IMPORT_C static 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 CUnifiedCertStore::Initialize(TRequestStatus &) request when complete. Set to KErrCancel if any outstanding request is cancelled.

IMPORT_C void CancelInitialize();

Description

Cancels an ongoing CUnifiedCertStore::Initialize(TRequestStatus &) 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

Cancels an ongoing CUnifiedCertStore::List(RMPointerArray< CCTCertInfo > &,const CCertAttributeFilter &,TRequestStatus &) operation.

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

Description

Get a certificate given its handle.

Parameters

`CCTCertInfo *&aCertInfo`	The returned certificate.
`const TCTTokenObjectHandle &aHandle`	The handle of the certificate to return.
`TRequestStatus &aStatus`	The request status object; contains the result of the `CUnifiedCertStore::GetCert(CCTCertInfo *&,const TCTTokenObjectHandle &,TRequestStatus &)` request when complete. Set to KErrCancel if any outstanding request is cancelled.

virtual void CancelGetCert();

Description

Cancel an ongoing CUnifiedCertStore::GetCert(CCTCertInfo *&,const TCTTokenObjectHandle &,TRequestStatus &) operation.

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

Cancels an ongoing CUnifiedCertStore::Applications(const CCTCertInfo &,RArray< TUid > &,TRequestStatus &) operation.

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

Description

Tests if a certificate is applicable to a particular application.

Parameters

`const CCTCertInfo &aCertInfo`	The certificate in question.
`TUid aApplication`	The application.
`TBool &aIsApplicable`	Set to ETrue or EFalse by the function to return the result.
`TRequestStatus &aStatus`	The request status object; contains the result of the `CUnifiedCertStore::IsApplicable(const CCTCertInfo &,TUid,TBool &,TRequestStatus &)` request when complete. Set to KErrCancel if any outstanding request is cancelled.

virtual void CancelIsApplicable();

Description

Cancels an ongoing CUnifiedCertStore::IsApplicable(const CCTCertInfo &,TUid,TBool &,TRequestStatus &) operation.

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

Description

Tests whether a certificate is trusted.

Trust is only meaningful for CA certificates where it means that the certificate can be used as a trust root for the purposes of certificate validation.

Parameters

`const CCTCertInfo &aCertInfo`	The certificate we are interested in.
`TBool &aTrusted`	Used to return the trust status.
`TRequestStatus &aStatus`	The request status object; contains the result of the `CUnifiedCertStore::Trusted(const CCTCertInfo &,TBool &,TRequestStatus &)` request when complete. Set to KErrCancel if any outstanding request is cancelled.

virtual void CancelTrusted();

Description

Cancels an ongoing CUnifiedCertStore::Trusted(const CCTCertInfo &,TBool &,TRequestStatus &) operation.

Capability:

ReadUserData

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

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

Description

Retrieves the actual data of the certificate.

Parameters

`const CCTCertInfo &aCertInfo`	The certificate to retrieve.
`TDes8 &aEncodedCert`	A buffer to put the certificate in. It must be big enough; the size is stored in aCertInfo.
`TRequestStatus &aStatus`	The request status object; contains the result of the `CUnifiedCertStore::Retrieve(const CCTCertInfo &,TDes8 &,TRequestStatus &)`request when complete. Set to KErrCancel if any outstanding request is cancelled.

Leave codes

KErrPermissionDenied

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

virtual void CancelRetrieve();

Description

Cancels an ongoing CUnifiedCertStore::Retrieve(const CCTCertInfo &,TDes8 &,TRequestStatus &) operation.

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 `CUnifiedCertStore::Remove(const CCTCertInfo &,TRequestStatus &)` 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 CUnifiedCertStore::Remove(const CCTCertInfo &,TRequestStatus &) 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 `CUnifiedCertStore::SetApplicability(const CCTCertInfo &,const RArray< TUid > &,TRequestStatus &)` 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 CUnifiedCertStore::SetApplicability(const CCTCertInfo &,const RArray< TUid > &,TRequestStatus &) 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 `CUnifiedCertStore::SetTrust(const CCTCertInfo &,TBool,TRequestStatus &)` 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 CUnifiedCertStore::SetTrust(const CCTCertInfo &,TBool,TRequestStatus &) 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 CUnifiedCertStore::CertStoreCount()const - 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 CUnifiedCertStore::ReadOnlyCertStoreCount()const - 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 CActive::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.

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

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 CUnifiedCertStore::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)

CUnifiedCertStore::RunL() runs under a trap harness in the active scheduler. If it leaves, then the active scheduler calls CUnifiedCertStore::RunError(TInt) 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 CUnifiedCertStore::RunL() or CUnifiedCertStore::RunError(TInt) functions.

Description

Parameters


                                 						TInt aError

Return value


                                 						TInt

Class CUnifiedCertStore

Description

Derivation

Members

Construction and destruction

NewL(RFs &,TBool)

Description

Parameters

Return value

NewLC(RFs &,TBool)

Description

Parameters

Return value

NewL(RFs &,TBool,RArray< TInt > &)

Description

Parameters

Return value

NewLC(RFs &,TBool,RArray< TInt > &)

Description

Parameters

Return value