/*
* Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description: An implementation of single authentication object
*
*/
#ifndef CWIMAUTHENTICATIONOBJECT_H
#define CWIMAUTHENTICATIONOBJECT_H
// INCLUDES
#include <mctauthobject.h>
#include <mctkeystore.h>
#include <unifiedcertstore.h>
#include <mctwritablecertstore.h>
#include <unifiedkeystore.h>
#include "WimToken.h"
// FORWARD DECLARATIONS
class CCTKeyInfo;
class CWimPin;
// CLASS DECLARATION
/**
* Represents one authentication object (for example a pin code)
*
* @lib WimPlugin
* @since Series 60 2.1
*/
class CWimAuthenticationObject : public CActive, public MCTAuthenticationObject
{
public: // Two-phased constructor
/**
* @param aToken A reference to current token
* @param aWimPin A reference to current pin manager
* @param aLabel A reference to label for this object
* @param aType Type of this object
* @param aHandle Handle of this object
* @param aObjectStatus Status of this object
* @return An instance of this class
*/
static CWimAuthenticationObject* NewLC( CWimToken& aToken,
CWimPin& aWimPin,
const TDesC& aLabel,
const TUid aType,
const TInt aHandle,
TUint32 aObjectStatus );
public: // Functions from base class MCTTokenObject
/**
* Returns a reference to this authentication object's
* human-readable label.
* @return A reference to object's label.
*/
const TDesC& Label() const;
/**
* Returns a reference to current token.
* @return A reference to current token.
*/
MCTToken& Token() const;
/**
* Returns type (UID) of current authentication object.
* Must be unique within a token. WIM_PIN_G_UID or WIM_PIN_NR_UID
* @return UID of the current object.
*/
TUid Type() const;
/**
* Returns a handle of the authentication object.
* @return A handle
* Must be unique within a token.
*/
TCTTokenObjectHandle Handle() const;
public: // Functions from base class MCTAuthenticationObject
/**
* Returns a list of all the objects which this authentication object
* protects; for example keys and certificates.
* The caller of this functions owns all its parameters.
* @param aObjects (OUT) The returned objects will be appended
* to this array.
* @param aStatus (IN/OUT) Completed with the return code when
* the operation completes.
* KErrNone, if no errors detected. Note: if protected
* objects are not found, it is also KErrNone
* KErrCancel, if call is canceled
* KErrHardwareNotAvailable, if Wim card suddenly removed
* Any other system wide error code (e.g. KErrNoMemory)
* @return void
*/
void ListProtectedObjects( RMPointerArray<MCTTokenObject>& aObjects,
TRequestStatus& aStatus );
/**
* Cancels an ongoing ListProtectedObjects operation.
* @return void
*/
void CancelListProtectedObjects();
/**
* Changes the reference data (e.g. PIN value). The security
* dialog component will prompt for the old and new reference data.
* @param aStatus (IN/OUT) Completed with the return code when the
* operation completes.
* KErrNone, if no errors detected.
* KErrLocked, if this authentication object is blocked
* KErrNotSupported, if authentication object reference data
* cannot be changed
* KErrBadData, if user entered wrong authentication data
* KErrHardwareNotAvailable, if Wim card suddenly removed
* Any other system wide error code (e.g. KErrNoMemory)
* @return void
*/
void ChangeReferenceData( TRequestStatus &aStatus );
/**
* Cancels an ongoing ChangeReferenceData operation.
* @return void
*/
void CancelChangeReferenceData();
/**
* Unblocks the authentication object. The security dialog component will
* prompt for the unblocking authentication object.
* @param aStatus (IN/OUT) Completed with the return code when the
* operation completes.
* KErrNone, if no errors detected, or authentication object was
* not blocked
* KErrNotSupported, if authentication object cannot be unblocked
* KErrBadData, if user entered wrong authentication data
* KErrHardwareNotAvailable, if Wim card suddenly removed
* Any other system wide error code (e.g. KErrNoMemory)
* @return void
*/
void Unblock( TRequestStatus &aStatus );
/**
* Cancels an ongoing Unblock operation.
* @return void
*/
void CancelUnblock();
/**
* Gets the status of the authentication object.
* @return See TCTAuthenticationStatus for the format of the
* return value.
* When status cannot be fetched for some reasons, this value
* is zero.
*/
TUint32 Status() const;
/**
* Disables the authentication object.
* @param aStatus (IN/OUT) Completed with the return code when the
* operation completes.
* KErrNone, if no errors detected
* KErrLocked, if authentication object is blocked
* KErrNotFound, if authentication object cannot be found
* KErrBadData, if user entered wrong authentication data
* KErrHardwareNotAvailable, if Wim card suddenly removed
* Any other system wide error code (e.g. KErrNoMemory)
* @return void
*/
void Disable( TRequestStatus &aStatus );
/**
* Cancels an ongoing Disable operation.
* @return void
*/
void CancelDisable();
/**
* Enables the authentication object.
* @param aStatus (IN/OUT) Completed with the return code when
* the operation completes.
* KErrNone, if no errors detected
* KErrLocked, if authentication object is blocked
* KErrNotFound, if authentication object cannot be found
* KErrBadData, if user entered wrong authentication data
* KErrHardwareNotAvailable, if Wim card suddenly removed
* Any other system wide error code (e.g. KErrNoMemory)
* @return void
*/
void Enable( TRequestStatus &aStatus );
/**
* Cancels an ongoing Enable operation.
* @return void
*/
void CancelEnable();
/**
* Opens the authentication object, meaning that the protected objects
* can be accessed without provoking the authentication mechanism for
* the duration of the timeout period. Note. It is not strictly
* necessary to call this function, as the authentication object will
* be opened when any operation that needs it to be opened is called,
* but it is sometimes useful to control the timing of authentication
* dialogs. Note also that this function will do nothing if the
* authentication object is open, or if it authentication object requires
* the authentication.
* @param aStatus TRequestStatus from the caller.(IN/OUT)
* KErrNone, if no errors detected, or authentication object
* is open
* KErrLocked, if authentication object is blocked
* KErrNotFound, if authentication object cannot be found
* KErrNotSupported, if authentication object is not openable
* KErrHardwareNotAvailable, if Wim card suddenly removed
* Any other system wide error code (e.g. KErrNoMemory)
* @return void
*/
void Open( TRequestStatus& aStatus );
/**
* Closes an authentication object.
* @param aStatus TRequestStatus from the caller.(IN/OUT)
* KErrNone, if no errors detected or authentication object
* is closed.
* KErrLocked, if authentication object is blocked
* KErrNotSupported, if authentication object is not closeable
* KErrHardwareNotAvailable, if Wim card suddenly removed
* Any other system wide error code (e.g. KErrNoMemory)
* @return void
*/
void Close( TRequestStatus& aStatus );
/**
* Returns the amount of time in seconds that the authentication object
* will remain open for, or 0 if it is closed. Thís call is valid
* only for authentication object, that can be opened (e.g. PIN-G)
* @param aStime Time (in seconds) to be returned. (OUT)
* @param aStatus TRequestStatus from the caller. (IN/OUT)
* KErrNone, if no errors detected, or authentication object
* is closed.
* KErrLocked, if authentication object is blocked
* KErrNotSupported, if authentication object is not allowed to
* be asked for timing information
* KErrHardwareNotAvailable, if Wim card suddenly removed
* Any other system wide error code (e.g. KErrNoMemory)
* @return void
*/
void TimeRemaining( TInt& aStime, TRequestStatus& aStatus );
/**
* Sets the time in seconds for this authentication
* object. Permitted values include 0, meaning always ask, and -1,
* meaning until it's explicitly closed. Particular authentication
* objects might restrict the range of values permitted. Thís call
* is valid only for authentication object, that can be opened
* (e.g. PIN-G)
* @param aTime (IN) Timeout (in seconds) to be set.
* @param aStatus TRequestStatus from the caller. (IN/OUT)
* KErrNone, if no errors detected, or authentication object
* is closed.
* KErrLocked, if authentication object is blocked
* KErrArgument, if aTime is not allowed. Permitted values
* include 0, meaning always ask, and -1, meaning until it's
* explicitly closed.
* KErrNotSupported, if authentication object is not allowed to
* be set time
* KErrHardwareNotAvailable, if Wim card suddenly removed
* Any other system wide error code (e.g. KErrNoMemory)
* @return void
*/
void SetTimeout( TInt aTime, TRequestStatus& aStatus );
/**
* Gets the current timeout value, in seconds. See SetTimeout for
* an explanation of the values. Thís call is valid only for
* authentication object, that can be opened (e.g. PIN-G)
* @param aTime Current timeout (in seconds) to be returned. (OUT)
* @param aStatus TRequestStatus from the caller. (IN/OUT)
* KErrNone, if no errors detected, or authentication object
* is closed.
* KErrNotSupported, if authentication object is not allowed to
* be queried about timing information
* KErrHardwareNotAvailable, if Wim card suddenly removed
* Any other system wide error code (e.g. KErrNoMemory)
* @return void
*/
void Timeout( TInt& aTime, TRequestStatus& aStatus );
/**
* Returns more token information than framework's MCTToken.
* Needed in MCTAuthenticationObjectList interface when creating
* authentication objects.
* @return A reference to CWimToken.
*/
CWimToken& TokenWider() const;
/**
* Returns a reference to pin module.
* Needed in MCTAuthenticationObjectList interface when creating
* authentication objects.
* @return A reference to CWimPin.
*/
CWimPin& PinModule() const;
protected: // From base class MCTTokenObject
virtual void DoRelease();
protected: // From base class CActive
void RunL();
/**
* Leaves in RunL are handled here.
* @param aError Leaving code
* @return An integer that should be KErrNone if leave was handled.
*/
TInt RunError( TInt aError );
void DoCancel();
private: // Constructors
/**
* Default constructor
* @param aToken A reference to current token
* @param aWimPin A reference to current pin manager
* @param aType Type of this object
* @param aHandle Handle of this object
* @param aObjectStatus Status of this object
*/
CWimAuthenticationObject( CWimToken& aToken,
CWimPin& aWimPin,
const TUid aType,
const TInt aHandle,
TUint32 aObjectStatus );
/**
* Second phase constructor
* @param aLabel A reference to this object's label
*/
void ConstructL( const TDesC& aLabel );
// Destructor
virtual ~CWimAuthenticationObject();
private: // Own functions
/**
* Frees unified key store resources.
* @return void
*/
void FreeUnifiedKeyStore();
/**
* Frees unified cert store resources.
* @return void
*/
void FreeUnifiedCertStore();
/**
* Selects keys according to given filter.
* @return void
*/
void DoFilterKeys();
/**
* Validates protected certificates
* @return void
*/
void DoListCertEntries();
/**
* Constructs final protected objects
* @return void
*/
void DoMakeObjectsL();
/**
* General function for creating authentication objects.
* @param aHandle Handle of authentication object
* @return A pointer to created object
*/
MCTAuthenticationObject* MakeAuthObjectL();
/**
* Returns true or false indicating if token is removed or not
* @return Boolean true or false
*/
TBool TokenRemoved();
// Checks if token is removed or is this object active
TBool EnteringAllowed( TRequestStatus& aStatus );
private: // Data
// State flag for RunL
enum TPhase
{
EGetKeyInfos = 0,
EFilterKeys,
EGetCerts,
EInitCertStore,
EListCertEntries,
EMakeObjects,
EIdle,
EEnablePinQuery,
EDisablePinQuery,
EChangePin,
EUnblockPin,
EVerifyPin
};
// Flag for internal state machine
TPhase iPhase;
// Used for saving caller status
// This class don't own the pointed object
TRequestStatus* iOriginalRequestStatus;
// A reference to current token. Will be asssigned in construction.
// This class don't own that referenced object.
CWimToken& iToken;
// Pointer to pin manager, this class don't own pointed object.
CWimPin& iWimPin;
// A pointer to buffer containing human readable label for
// this authentication object. This class owns this buffer.
HBufC* iLabel;
// Contains the type of this authentication object.
// For example WIM_PIN_G_UID or WIM_PIN_NR_UID
TUid iType;
// The handle of authentication object. An integer value
// running from 0 to (number of authentication objects) - 1
TInt iObjectId;
// Holds a status of this authentication object.
// See enum TCTAuthenticationStatus in MCTAuthObject.h
// for status values.
TUint32 iObjectStatus;
// Used with unified key store to save keys for a while
RMPointerArray<CCTKeyInfo> iKeyInfos;
// Used with unified key store to filter keys
TCTKeyAttributeFilter iKeyFilter;
// Temporal array for object pointers
// This array is used to append objects in List operation
// This class don't own the pointed objects
RMPointerArray<MCTTokenObject>* iObjects;
// A pointer to unified key store
// This class owns the pointed object
CUnifiedKeyStore* iUnifiedKeyStore;
// A pointer to unified cert store
// This class owns the pointed object
CUnifiedCertStore* iUnifiedCertStore;
// A pointer to certificate filter object
// This class owns the pointed object.
CCertAttributeFilter* iCertFilter;
// Temporal array for certificates this authentication
// object protects.
RMPointerArray<CCTCertInfo> iCertStoreEntries;
// A Reference to wider implementation specific token
// for internal functions.
CWimToken& iTokenWider;
// For call to Unified KeyStore, which might have file key store
RFs iFs;
// Array of pointers to PIN modules.This class don't own pointed
// objects.
const CArrayPtrFlat<CWimPin>* iPinNRs;
};
#endif // CWIMAUTHENTICATIONOBJECT_H
// End of File