williamr@2: /*
williamr@2: * Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@2: * under the terms of the License "Eclipse Public License v1.0"
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description: 
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2:  @file
williamr@2:  @publishedAll
williamr@2:  @released
williamr@2: */
williamr@2: 
williamr@2: #ifndef __MCERTINFO_H__
williamr@2: #define __MCERTINFO_H__
williamr@2: 
williamr@2: #include <ct/rmpointerarray.h>
williamr@2: 
williamr@2: // Forward declarations
williamr@2: class CCTCertInfo;
williamr@2: class CCertAttributeFilter;
williamr@2: class TCTTokenObjectHandle;
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2:  * 
williamr@2:  * Defines the interface for a read-only certificate store.
williamr@2:  *
williamr@2:  * This documentation describes the security policy that must be enforced by
williamr@2:  * implementations of the interface.
williamr@2:  */
williamr@2: class MCertStore
williamr@2: 	{
williamr@2: public:
williamr@2: 	/**
williamr@2: 	 * Listing Certificates
williamr@2: 	 */
williamr@2: 
williamr@2: 	/**
williamr@2: 	 * Get a list of all certificates that satisfy the supplied filter.
williamr@2: 	 * 	
williamr@2: 	 * This is an async function; all errors are reported by completing aStatus
williamr@2: 	 * with the error value, and it can be cancelled with CancelList().
williamr@2: 	 * 
williamr@2: 	 * @param aCerts An array into which the returned certificates are placed.
williamr@2: 	 * @param aFilter A filter to select which certificates should be included.
williamr@2: 	 * @param aStatus A request status that will be completed when the operation completes.
williamr@2: 	 */	
williamr@2: 	virtual void List(RMPointerArray<CCTCertInfo>& aCerts, const CCertAttributeFilter& aFilter,
williamr@2: 					  TRequestStatus& aStatus) = 0;
williamr@2: 
williamr@2: 	/** Cancels an ongoing List() operation. */
williamr@2: 	virtual void CancelList() = 0;
williamr@2: 
williamr@2: 	/**
williamr@2: 	 * Getting a certificate given a handle.
williamr@2: 	 */
williamr@2: 	
williamr@2: 	/**
williamr@2: 	 * Get a certificate given its handle.
williamr@2: 	 * 
williamr@2: 	 * @param aCertInfo The returned certificate.
williamr@2: 	 * @param aHandle The handle of the certificate to return.
williamr@2: 	 * @param aStatus The request status object; contains the result of the
williamr@2: 	 *     GetCert() request when complete. Set to KErrCancel if any outstanding
williamr@2: 	 *     request is cancelled.
williamr@2: 	 */
williamr@2: 	virtual void GetCert(CCTCertInfo*& aCertInfo, const TCTTokenObjectHandle& aHandle, 
williamr@2: 						 TRequestStatus& aStatus) = 0;
williamr@2: 		
williamr@2: 	/** Cancel an ongoing GetCert() operation. */
williamr@2: 	virtual void CancelGetCert() = 0;
williamr@2: 	
williamr@2: 	/**
williamr@2: 	 * Querying the applications of a certificate.
williamr@2: 	 */
williamr@2: 
williamr@2: 	/**
williamr@2: 	 * Get the list of the applications associcated with certificate.
williamr@2: 	 * 
williamr@2: 	 * Applications are represented by UIDs. Examples would be Software Install,
williamr@2: 	 * TLS, WTLS, WMLScript, SignText, etc..
williamr@2: 	 * 
williamr@2: 	 * @param aCertInfo The certificate to return applications for.
williamr@2: 	 * @param aAplications An array to save the applications in.
williamr@2: 	 * @param aStatus The request status object; contains the result of the
williamr@2: 	 *     Applications() request when complete. Set to KErrCancel if any
williamr@2: 	 *     outstanding request is cancelled.
williamr@2: 	 */
williamr@2: 	virtual void Applications(const CCTCertInfo& aCertInfo, RArray<TUid>& aAplications,
williamr@2: 							  TRequestStatus& aStatus) = 0;
williamr@2: 		
williamr@2: 	/** Cancels an ongoing Applications() operation. */
williamr@2: 	virtual void CancelApplications() = 0;
williamr@2: 	
williamr@2: 	/**
williamr@2: 	 * Tests if a certificate is applicable to a particular application.	
williamr@2: 	 * 
williamr@2: 	 * @param aCertInfo The certificate in question.
williamr@2: 	 * @param aApplication The application.
williamr@2: 	 * @param aIsApplicable Set to ETrue or EFalse by the function to return the result.
williamr@2: 	 * @param aStatus The request status object; contains the result of the
williamr@2: 	 *     IsApplicable() request when complete. Set to KErrCancel if any
williamr@2: 	 *     outstanding request is cancelled.
williamr@2: 	 */
williamr@2: 	virtual void IsApplicable(const CCTCertInfo& aCertInfo, TUid aApplication, 
williamr@2: 							  TBool& aIsApplicable, TRequestStatus& aStatus) = 0;
williamr@2: 
williamr@2: 	/** Cancels an ongoing IsApplicable() operation. */
williamr@2: 	virtual void CancelIsApplicable() = 0;
williamr@2: 
williamr@2: 	/**
williamr@2: 	 * Trust querying
williamr@2: 	 */
williamr@2: 	
williamr@2: 	/**
williamr@2: 	 * Tests whether a certificate is trusted.
williamr@2: 	 * 
williamr@2: 	 * Trust is only meaningful for CA certificates where it means that the
williamr@2: 	 * certificate can be used as a trust root for the purposes of certificate
williamr@2: 	 * validation.
williamr@2: 	 * 
williamr@2: 	 * @param aCertInfo The certificate we are interested in.
williamr@2: 	 * @param aTrusted Used to return the trust status.
williamr@2: 	 * @param aStatus The request status object; contains the result of the
williamr@2: 	 *     Trusted() request when complete. Set to KErrCancel if any outstanding
williamr@2: 	 *     request is cancelled.
williamr@2: 	 */
williamr@2: 	virtual void Trusted(const CCTCertInfo& aCertInfo, TBool& aTrusted, 
williamr@2: 						 TRequestStatus& aStatus) = 0;
williamr@2: 
williamr@2: 	/** Cancels an ongoing Trusted() operation. */
williamr@2: 	virtual void CancelTrusted() = 0;
williamr@2: 
williamr@2: 	/**
williamr@2: 	 * Retrieving the actual certificate
williamr@2: 	 */
williamr@2: 
williamr@2: 	/**
williamr@2: 	 * Retrieves the actual data of the certificate.	
williamr@2: 	 *
williamr@2: 	 * @param aCertInfo The certificate to retrieve.
williamr@2: 	 * @param aEncodedCert A buffer to put the certificate in. It must be big
williamr@2: 	 *     enough; the size is stored in aCertInfo.
williamr@2: 	 * @param aStatus The request status object; contains the result of the
williamr@2: 	 *     Retrieve()request when complete. Set to KErrCancel if any outstanding
williamr@2: 	 *     request is cancelled.
williamr@2: 	 *
williamr@2: 	 * @capability ReadUserData This requires the ReadUserData capability when
williamr@2: 	 *     applied to user certificates, as these may contain sensitive user data.
williamr@2: 	 * @leave KErrPermissionDenied If called for a user certificate when the
williamr@2: 	 *     caller doesn't have the ReadUserData capability.
williamr@2: 	 */
williamr@2: 	virtual void Retrieve(const CCTCertInfo& aCertInfo, TDes8& aEncodedCert, 
williamr@2: 						  TRequestStatus& aStatus) = 0;
williamr@2: 		
williamr@2: 	/** Cancels an ongoing Retrieve() operation. */
williamr@2: 	virtual void CancelRetrieve() = 0;
williamr@2: 		
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: #endif