CUnifiedCertStore Class Reference

#include <unifiedcertstore.h>

Link against: certstore.lib

class CUnifiedCertStore : public CActive, public MCertStore

Inherits from

Public Member Functions
~CUnifiedCertStore()
virtual voidApplications(const CCTCertInfo &, RArray< TUid > &, TRequestStatus &)
virtual voidCancelApplications()
virtual voidCancelGetCert()
IMPORT_C voidCancelInitialize()
virtual voidCancelIsApplicable()
virtual voidCancelList()
IMPORT_C voidCancelRemove()
virtual voidCancelRetrieve()
IMPORT_C voidCancelSetApplicability()
IMPORT_C voidCancelSetTrust()
virtual voidCancelTrusted()
IMPORT_C MCTCertStore &CertStore(TInt)
IMPORT_C TIntCertStoreCount()
virtual voidGetCert(CCTCertInfo *&, const TCTTokenObjectHandle &, TRequestStatus &)
IMPORT_C voidInitialize(TRequestStatus &)
virtual voidIsApplicable(const CCTCertInfo &, TUid, TBool &, TRequestStatus &)
virtual voidList(RMPointerArray< CCTCertInfo > &, const CCertAttributeFilter &, TRequestStatus &)
IMPORT_C voidList(RMPointerArray< CCTCertInfo > &, const CCertAttributeFilter &, const TDesC8 &, TRequestStatus &)
IMPORT_C voidList(RMPointerArray< CCTCertInfo > &, const CCertAttributeFilter &, RPointerArray< const TDesC8 >, TRequestStatus &)
IMPORT_C CUnifiedCertStore *NewL(RFs &, TBool)
IMPORT_C CUnifiedCertStore *NewL(RFs &, TBool, RArray< TInt > &)
IMPORT_C CUnifiedCertStore *NewLC(RFs &, TBool)
IMPORT_C CUnifiedCertStore *NewLC(RFs &, TBool, RArray< TInt > &)
IMPORT_C MCTCertStore &ReadOnlyCertStore(TInt)
IMPORT_C TIntReadOnlyCertStoreCount()
IMPORT_C voidRemove(const CCTCertInfo &, TRequestStatus &)
virtual voidRetrieve(const CCTCertInfo &, TDes8 &, TRequestStatus &)
IMPORT_C voidRetrieve(const CCTCertInfo &, CCertificate *&, TRequestStatus &)
IMPORT_C voidSetApplicability(const CCTCertInfo &, const RArray< TUid > &, TRequestStatus &)
IMPORT_C voidSetTrust(const CCTCertInfo &, TBool, TRequestStatus &)
virtual voidTrusted(const CCTCertInfo &, TBool &, TRequestStatus &)
IMPORT_C MCTWritableCertStore &WritableCertStore(TInt)
IMPORT_C TIntWritableCertStoreCount()
Inherited Attributes
CActive::iStatus
Inherited Enumerations
CActive:TPriority
Inherited Functions
CActive::CActive(TInt)
CActive::Cancel()
CActive::Deque()
CActive::Extension_(TUint,TAny *&,TAny *)
CActive::IsActive()const
CActive::IsAdded()const
CActive::Priority()const
CActive::SetActive()
CActive::SetPriority(TInt)
CActive::~CActive()
CBase::CBase()
CBase::Delete(CBase *)
CBase::operator new(TUint)
CBase::operator new(TUint,TAny *)
CBase::operator new(TUint,TLeave)
CBase::operator new(TUint,TLeave,TUint)
CBase::operator new(TUint,TUint)
CBase::~CBase()

Detailed 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.

Constructor & Destructor Documentation

~CUnifiedCertStore ( )

IMPORT_C~CUnifiedCertStore()

The destructor destroys all the resources owned by this object.

Member Function Documentation

Applications ( const CCTCertInfo &, RArray< TUid > &, TRequestStatus & )

voidApplications(const CCTCertInfo &aCertInfo,
RArray< TUid > &aApplications,
TRequestStatus &aStatus
)[virtual]

Reimplemented from MCertStore::Applications(const CCTCertInfo &,RArray< TUid > &,TRequestStatus &)

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

Parameters
aApplicationsAn array that the returned application UIDs are added to.
aStatusThe request status object.

CancelApplications ( )

voidCancelApplications()[virtual]

Reimplemented from MCertStore::CancelApplications()

Cancels an ongoing Applications() operation.

CancelGetCert ( )

voidCancelGetCert()[virtual]

Reimplemented from MCertStore::CancelGetCert()

Cancel an ongoing GetCert() operation.

CancelInitialize ( )

IMPORT_C voidCancelInitialize()

Cancels an ongoing Initialize() operation.

The operation completes with KErrCancel.

CancelIsApplicable ( )

voidCancelIsApplicable()[virtual]

Reimplemented from MCertStore::CancelIsApplicable()

Cancels an ongoing IsApplicable() operation.

CancelList ( )

voidCancelList()[virtual]

Reimplemented from MCertStore::CancelList()

Cancels an ongoing List() operation.

CancelRemove ( )

IMPORT_C voidCancelRemove()

Cancels an ongoing Remove() operation.

The operation completes with KErrCancel.

CancelRetrieve ( )

voidCancelRetrieve()[virtual]

Reimplemented from MCertStore::CancelRetrieve()

Cancels an ongoing Retrieve() operation.

CancelSetApplicability ( )

IMPORT_C voidCancelSetApplicability()

Cancels an ongoing SetApplicability() operation.

The operation completes with KErrCancel.

CancelSetTrust ( )

IMPORT_C voidCancelSetTrust()

Cancels an ongoing SetTrust() operation.

The operation completes with KErrCancel.

CancelTrusted ( )

voidCancelTrusted()[virtual]

Reimplemented from MCertStore::CancelTrusted()

Cancels an ongoing Trusted() operation.

CertStore ( TInt )

IMPORT_C MCTCertStore &CertStore(TIntaIndex)

Gets a particular certificate store.

Parameters
aIndexThe index of the required certificate store. A number between 0 and CertStoreCount() - 1.
Return Value
The certificate store.

CertStoreCount ( )

IMPORT_C TIntCertStoreCount()const

Gets the number of certificate stores.

Return Value
The total number of certificate stores.

GetCert ( CCTCertInfo *&, const TCTTokenObjectHandle &, TRequestStatus & )

voidGetCert(CCTCertInfo *&aCertInfo,
const TCTTokenObjectHandle &aHandle,
TRequestStatus &aStatus
)[virtual]

Reimplemented from MCertStore::GetCert(CCTCertInfo *&,const TCTTokenObjectHandle &,TRequestStatus &)

Getting a certificate given a handle. Get a certificate given its handle.

Parameters
aCertInfoThe returned certificate.
aHandleThe handle of the certificate to return.
aStatusThe request status object; contains the result of the GetCert() request when complete. Set to KErrCancel if any outstanding request is cancelled.

Initialize ( TRequestStatus & )

IMPORT_C voidInitialize(TRequestStatus &aStatus)

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
aStatusThe request status object; contains the result of the Initialize() request when complete. Set to KErrCancel if any outstanding request is cancelled.

IsApplicable ( const CCTCertInfo &, TUid, TBool &, TRequestStatus & )

voidIsApplicable(const CCTCertInfo &aCertInfo,
TUidaApplication,
TBool &aIsApplicable,
TRequestStatus &aStatus
)[virtual]

Reimplemented from MCertStore::IsApplicable(const CCTCertInfo &,TUid,TBool &,TRequestStatus &)

Tests if a certificate is applicable to a particular application.

Parameters
aCertInfoThe certificate in question.
aApplicationThe application.
aIsApplicableSet to ETrue or EFalse by the function to return the result.
aStatusThe request status object; contains the result of the IsApplicable() request when complete. Set to KErrCancel if any outstanding request is cancelled.

List ( RMPointerArray< CCTCertInfo > &, const CCertAttributeFilter &, TRequestStatus & )

voidList(RMPointerArray< CCTCertInfo > &aCertInfos,
const CCertAttributeFilter &aFilter,
TRequestStatus &aStatus
)[virtual]

Reimplemented from MCertStore::List(RMPointerArray< CCTCertInfo > &,const CCertAttributeFilter &,TRequestStatus &)

Lists all certificates that satisfy the supplied filter.

Parameters
aCertInfosAn array that the returned certificates are added to .
aFilterA filter to restrict which certificates are returned.
aStatusThe request status object.

List ( RMPointerArray< CCTCertInfo > &, const CCertAttributeFilter &, const TDesC8 &, TRequestStatus & )

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

Lists all certificates that have a particular subject DN.

Parameters
aCertInfosAn array that the returned certificates are added to
aFilterA filter to restrict which certificates are returned.
aIssuerOnly certificates with this issuer DN will be returned
aStatusAsynchronous request status.

List ( RMPointerArray< CCTCertInfo > &, const CCertAttributeFilter &, RPointerArray< const TDesC8 >, TRequestStatus & )

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

Lists all certificates that have a particular issuer.

Parameters
aCertInfosAn array that the returned certificates are added to
aFilterA filter to restrict which certificates are returned.
aIssuersOnly certificates with this issuer will be returned
aStatusAsynchronous request status.

NewL ( RFs &, TBool )

IMPORT_C CUnifiedCertStore *NewL(RFs &aFs,
TBoolaOpenForWrite
)[static]

Creates a new CUnifiedCertStore

Parameters
aFsA file server session. It must already be open.
aOpenForWriteETrue 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
A pointer to an instance of the CUnifiedCertStore class.

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

IMPORT_C CUnifiedCertStore *NewL(RFs &aFs,
TBoolaOpenForWrite,
RArray< TInt > &aOrderFilter
)[static]

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

Parameters
aFsA file server session. It must already be open.
aOpenForWriteETrue 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.
aOrderFilterAn array of the unique sequence IDs specifying CertStore ordering.
Return Value
A pointer to an instance of the CUnifiedCertStore class.

NewLC ( RFs &, TBool )

IMPORT_C CUnifiedCertStore *NewLC(RFs &aFs,
TBoolaOpenForWrite
)[static]

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

Parameters
aFsA file server session. It must already be open.
aOpenForWriteETrue 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
A pointer to an instance of the CUnifiedCertStore class.

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

IMPORT_C CUnifiedCertStore *NewLC(RFs &aFs,
TBoolaOpenForWrite,
RArray< TInt > &aOrderFilter
)[static]

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
aFsA file server session. It must already be open.
aOpenForWriteETrue 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.
aOrderFilterAn array of the unique sequence IDs specifying CertStore ordering.
Return Value
A pointer to an instance of the CUnifiedCertStore class.

ReadOnlyCertStore ( TInt )

IMPORT_C MCTCertStore &ReadOnlyCertStore(TIntaIndex)

Gets a particular read-only certificate store.

Parameters
aIndexThe index of the required certificate store. A number between 0 and ReadOnlyCertStoreCount() - 1.
Return Value
The read-only certificate store.

ReadOnlyCertStoreCount ( )

IMPORT_C TIntReadOnlyCertStoreCount()const

Gets the number of read-only certificate stores.

Return Value
The number of read-only certificate stores.

Remove ( const CCTCertInfo &, TRequestStatus & )

IMPORT_C voidRemove(const CCTCertInfo &aCertInfo,
TRequestStatus &aStatus
)

Removes a certificate.

Parameters
aCertInfoThe certificate to be removed.
aStatusThe request status object; contains the result of the Remove() request when complete. Set to KErrCancel if an outstanding request is cancelled.
Leave Codes
KErrPermissionDeniedIf the caller doesn't have the required capabilities.
Capability
WriteUserDataThis requires the WriteUserData capability when applied to user certificates.
WriteDeviceDataThis requires the WriteDeviceData capability when applied to CA certificates.

Retrieve ( const CCTCertInfo &, TDes8 &, TRequestStatus & )

voidRetrieve(const CCTCertInfo &aCertInfo,
TDes8 &aEncodedCert,
TRequestStatus &aStatus
)[virtual]

Reimplemented from MCertStore::Retrieve(const CCTCertInfo &,TDes8 &,TRequestStatus &)

Retrieving the actual certificate Retrieves the actual data of the certificate.

Parameters
aCertInfoThe certificate to retrieve.
aEncodedCertA buffer to put the certificate in. It must be big enough; the size is stored in aCertInfo.
aStatusThe request status object; contains the result of the Retrieve()request when complete. Set to KErrCancel if any outstanding request is cancelled.
Leave Codes
KErrPermissionDeniedIf called for a user certificate when the caller doesn't have the ReadUserData capability.
Capability
ReadUserDataThis requires the ReadUserData capability when applied to user certificates, as these may contain sensitive user data.

Retrieve ( const CCTCertInfo &, CCertificate *&, TRequestStatus & )

IMPORT_C voidRetrieve(const CCTCertInfo &aCertInfo,
CCertificate *&aCert,
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.

Parameters
aCertInfoThe certificate to retrieve
aCertThe returned certificate. This object can safely be up-cast to a CX509Certificate or CWTLSCertificate if it's known that that is the certificate format.
aStatusAsynchronous request status.
Leave Codes
KErrPermissionDeniedIf called for a user certificate when the caller doesn't have the ReadUserData capability.
Capability
ReadUserDataThis requires the ReadUserData capability when applied to user certificates, as these may contain sensitive user data.

SetApplicability ( const CCTCertInfo &, const RArray< TUid > &, TRequestStatus & )

IMPORT_C voidSetApplicability(const CCTCertInfo &aCertInfo,
const RArray< TUid > &aApplications,
TRequestStatus &aStatus
)

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
aCertInfoThe certificate whose applicability should be updated.
aApplicationsThe new applicability settings. Ownership of this remains with the caller, and it must remain valid for the lifetime of the call.
aStatusThe request status object; contains the result of the SetApplicability() request when complete. Set to KErrCancel, if an outstanding request is cancelled.
Leave Codes
KErrPermissionDeniedIf the caller doesn't have the required capabilities.
Capability
WriteDeviceDataThis requires the WriteDeviceData capability.

SetTrust ( const CCTCertInfo &, TBool, TRequestStatus & )

IMPORT_C voidSetTrust(const CCTCertInfo &aCertInfo,
TBoolaTrusted,
TRequestStatus &aStatus
)

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
aCertInfoThe certificate to be updated.
aTrustedETrue, if trusted; EFalse, otherwise.
aStatusThe request status object; contains the result of the SetTrust() request when complete. Set to KErrCancel, if an outstanding request is cancelled.
Leave Codes
KErrPermissionDeniedIf the caller doesn't have the required capabilities.
Capability
WriteDeviceDataThis requires the WriteDeviceData capability.

Trusted ( const CCTCertInfo &, TBool &, TRequestStatus & )

voidTrusted(const CCTCertInfo &aCertInfo,
TBool &aTrusted,
TRequestStatus &aStatus
)[virtual]

Reimplemented from MCertStore::Trusted(const CCTCertInfo &,TBool &,TRequestStatus &)

Trust querying 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
aCertInfoThe certificate we are interested in.
aTrustedUsed to return the trust status.
aStatusThe request status object; contains the result of the Trusted() request when complete. Set to KErrCancel if any outstanding request is cancelled.

WritableCertStore ( TInt )

IMPORT_C MCTWritableCertStore &WritableCertStore(TIntaIndex)

Gets a particular writeable certificate store.

Parameters
aIndexThe index of the required certificate store. A number between 0 and WriteableCertStoreCount() - 1.
Return Value
The writeable certificate store.

WritableCertStoreCount ( )

IMPORT_C TIntWritableCertStoreCount()const

Gets the number of writeable certificate stores.

Return Value
The number of writeable certificate stores.