CUnifiedCertStore Class Reference

#include <unifiedcertstore.h>

Link against: certstore.lib

class CUnifiedCertStore : public CActive, public MCertStore

Inherits from

CUnifiedCertStore
- CActive
  - CBase
- MCertStore

Public Member Functions
	~CUnifiedCertStore()
virtual void	Applications(const CCTCertInfo &, RArray< TUid > &, TRequestStatus &)
virtual void	CancelApplications()
virtual void	CancelGetCert()
IMPORT_C void	CancelInitialize()
virtual void	CancelIsApplicable()
virtual void	CancelList()
IMPORT_C void	CancelRemove()
virtual void	CancelRetrieve()
IMPORT_C void	CancelSetApplicability()
IMPORT_C void	CancelSetTrust()
virtual void	CancelTrusted()
IMPORT_C MCTCertStore &	CertStore(TInt)
IMPORT_C TInt	CertStoreCount()
virtual void	GetCert(CCTCertInfo *&, const TCTTokenObjectHandle &, TRequestStatus &)
IMPORT_C void	Initialize(TRequestStatus &)
virtual void	IsApplicable(const CCTCertInfo &, TUid, TBool &, TRequestStatus &)
virtual void	List(RMPointerArray< CCTCertInfo > &, const CCertAttributeFilter &, TRequestStatus &)
IMPORT_C void	List(RMPointerArray< CCTCertInfo > &, const CCertAttributeFilter &, const TDesC8 &, TRequestStatus &)
IMPORT_C void	List(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 TInt	ReadOnlyCertStoreCount()
IMPORT_C void	Remove(const CCTCertInfo &, TRequestStatus &)
virtual void	Retrieve(const CCTCertInfo &, TDes8 &, TRequestStatus &)
IMPORT_C void	Retrieve(const CCTCertInfo &, CCertificate *&, TRequestStatus &)
IMPORT_C void	SetApplicability(const CCTCertInfo &, const RArray< TUid > &, TRequestStatus &)
IMPORT_C void	SetTrust(const CCTCertInfo &, TBool, TRequestStatus &)
virtual void	Trusted(const CCTCertInfo &, TBool &, TRequestStatus &)
IMPORT_C MCTWritableCertStore &	WritableCertStore(TInt)
IMPORT_C TInt	WritableCertStoreCount()

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 & )

void	Applications	(	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
aApplications	An array that the returned application UIDs are added to.
aStatus	The request status object.

CancelApplications ( )

void

CancelApplications

(

)

[virtual]

Reimplemented from MCertStore::CancelApplications()

Cancels an ongoing Applications() operation.

CancelGetCert ( )

void

CancelGetCert

(

)

[virtual]

Reimplemented from MCertStore::CancelGetCert()

Cancel an ongoing GetCert() operation.

CancelInitialize ( )

IMPORT_C void

CancelInitialize

(

)

Cancels an ongoing Initialize() operation.

The operation completes with KErrCancel.

CancelIsApplicable ( )

void

CancelIsApplicable

(

)

[virtual]

Reimplemented from MCertStore::CancelIsApplicable()

Cancels an ongoing IsApplicable() operation.

CancelList ( )

void

CancelList

(

)

[virtual]

Reimplemented from MCertStore::CancelList()

Cancels an ongoing List() operation.

CancelRemove ( )

IMPORT_C void

CancelRemove

(

)

Cancels an ongoing Remove() operation.

The operation completes with KErrCancel.

CancelRetrieve ( )

void

CancelRetrieve

(

)

[virtual]

Reimplemented from MCertStore::CancelRetrieve()

Cancels an ongoing Retrieve() operation.

CancelSetApplicability ( )

IMPORT_C void

CancelSetApplicability

(

)

Cancels an ongoing SetApplicability() operation.

The operation completes with KErrCancel.

CancelSetTrust ( )

IMPORT_C void

CancelSetTrust

(

)

Cancels an ongoing SetTrust() operation.

The operation completes with KErrCancel.

CancelTrusted ( )

void

CancelTrusted

(

)

[virtual]

Reimplemented from MCertStore::CancelTrusted()

Cancels an ongoing Trusted() operation.

CertStore ( TInt )

IMPORT_C MCTCertStore &

CertStore

(

TInt

aIndex

)

Gets a particular certificate store.

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

Return Value: The certificate store.

CertStoreCount ( )

IMPORT_C TInt

CertStoreCount

(

)

const

Gets the number of certificate stores.

Return Value: The total number of certificate stores.

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

void	GetCert	(	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
aCertInfo	The returned certificate.
aHandle	The handle of the certificate to return.
aStatus	The 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 void

Initialize

(

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
aStatus	The 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 & )

void	IsApplicable	(	const CCTCertInfo &	aCertInfo,
			TUid	aApplication,
			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
aCertInfo	The certificate in question.
aApplication	The application.
aIsApplicable	Set to ETrue or EFalse by the function to return the result.
aStatus	The 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 & )

void	List	(	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
aCertInfos	An array that the returned certificates are added to .
aFilter	A filter to restrict which certificates are returned.
aStatus	The request status object.

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

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

Lists all certificates that have a particular subject DN.

Parameters
aCertInfos	An array that the returned certificates are added to
aFilter	A filter to restrict which certificates are returned.
aIssuer	Only certificates with this issuer DN will be returned
aStatus	Asynchronous request status.

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

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

Lists all certificates that have a particular issuer.

Parameters
aCertInfos	An array that the returned certificates are added to
aFilter	A filter to restrict which certificates are returned.
aIssuers	Only certificates with this issuer will be returned
aStatus	Asynchronous request status.

NewL ( RFs &, TBool )

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

Creates a new CUnifiedCertStore

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

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

IMPORT_C CUnifiedCertStore *	NewL	(	RFs &	aFs,
			TBool	aOpenForWrite,
			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
aFs	A file server session. It must already be open.
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.
aOrderFilter	An 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,
			TBool	aOpenForWrite
		)	[static]

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

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

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

IMPORT_C CUnifiedCertStore *	NewLC	(	RFs &	aFs,
			TBool	aOpenForWrite,
			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
aFs	A file server session. It must already be open.
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.
aOrderFilter	An 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

(

TInt

aIndex

)

Gets a particular read-only certificate store.

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

Return Value: The read-only certificate store.

ReadOnlyCertStoreCount ( )

IMPORT_C TInt

ReadOnlyCertStoreCount

(

)

const

Gets the number of read-only certificate stores.

Return Value: The number of read-only certificate stores.

Remove ( const CCTCertInfo &, TRequestStatus & )

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

Removes a certificate.

Parameters
aCertInfo	The certificate to be removed.
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.

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

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

void	Retrieve	(	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
aCertInfo	The certificate to retrieve.
aEncodedCert	A buffer to put the certificate in. It must be big enough; the size is stored in aCertInfo.
aStatus	The request status object; contains the result of the Retrieve()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.

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

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

IMPORT_C void	Retrieve	(	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
aCertInfo	The certificate to retrieve
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.
aStatus	Asynchronous request status.

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

Capability
ReadUserData	This 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 void	SetApplicability	(	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
aCertInfo	The certificate whose applicability should be updated.
aApplications	The new applicability settings. Ownership of this remains with the caller, and it must remain valid for the lifetime of the call.
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.

Capability
WriteDeviceData	This requires the WriteDeviceData capability.

SetTrust ( const CCTCertInfo &, TBool, TRequestStatus & )

IMPORT_C void	SetTrust	(	const CCTCertInfo &	aCertInfo,
			TBool	aTrusted,
			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
aCertInfo	The certificate to be updated.
aTrusted	ETrue, if trusted; EFalse, otherwise.
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.

Capability
WriteDeviceData	This requires the WriteDeviceData capability.

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

void	Trusted	(	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
aCertInfo	The certificate we are interested in.
aTrusted	Used to return the trust status.
aStatus	The 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

(

TInt

aIndex

)

Gets a particular writeable certificate store.

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

Return Value: The writeable certificate store.

WritableCertStoreCount ( )

IMPORT_C TInt

WritableCertStoreCount

(

)

const

Gets the number of writeable certificate stores.

Return Value: The number of writeable certificate stores.