/*
* Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the License "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:
*
*/
/**
@file
@publishedPartner
@released
*/
#ifndef __MCTAOSTORE_H__
#define __MCTAOSTORE_H__
#include <ct.h>
/** The UID for the authentication object interface. */
const TInt KCTInterfaceAuthenticationObject = 0x101F51AE;
/**
* A timeout value for an auth object indicating that it stays open until
* explicity closed.
*/
const TInt KTimeoutNever = -1;
/**
* A timeout value for an auth object indicating that the authentication data
* must be entered every time the protected objects are used.
*/
const TInt KTimeoutImmediate = 0;
/**
* The status of an authentication object.
*/
enum TCTAuthenticationStatus
{
/** The authentication object is enabled. If it is not enabled, the objects protected
* by this authentication object can be accessed without authentication. */
EEnabled = 0x80,
/** The reference data cannot be changed. */
EChangeDisabled = 0x40,
/** The authentication cannot be unblocked. */
EUnblockDisabled = 0x20,
/** The authentication object can be disabled. */
EDisableAllowed = 0x10,
/** The authentication object is blocked, meaning that the
* unblocking PIN must be entered to re-enable the authentication object. */
EAuthObjectBlocked= 0x08,
};
/**
* This class allows authentication objects to be queried and manipulated.
*
* Authentication objects are obtained from the MCTAuthenticationObjectList class,
* which is the class returned as the token interface.
*/
class MCTAuthenticationObject: public MCTTokenObject
{
public:
/** Constructor */
inline MCTAuthenticationObject(MCTToken& aToken);
// Listing Protected Objects
/**
* Gets a list of all the objects that this authentication object protects.
*
* @param aObjects The returned objects will be appended to this array.
* @param aStatus Completed with the return code when the operation completes.
*/
virtual void ListProtectedObjects(RMPointerArray<MCTTokenObject>& aObjects, TRequestStatus& aStatus) = 0;
/** Cancels an asynchronous ListProtectedObjects() operation. */
virtual void CancelListProtectedObjects() = 0;
// Changing the reference data
/**
* Changes the reference data (e.g. PIN value).
*
* The security dialog component will prompt for the old and new reference data.
*
* The authentication object may not allow its reference data to be changed -
* this is indicated by the EChangeDisabled bit of Status() being set.
*
* @param aStatus Completed with the return code when the operation completes.
*
* @leave KErrNotFound If no reference data was originally set.
*/
virtual void ChangeReferenceData(TRequestStatus &aStatus) = 0;
/** Cancels an asynchronous ChangeReferenceData() operation. */
virtual void CancelChangeReferenceData() = 0;
/**
* Unblocks the authentication object.
*
* The security dialog component will prompt for the unblocking
* authentication object.
*
* It is only valid to call this method when the authentication object is
* blocked, ie when the EAuthObjectBlocked bit of Status() is set.
*
* The object may not allow unblocking (either because of failed unblock
* attempts or because it doesn't support the concept) - this is indicated by
* the EUnblockDisabled bit of Status() being set.
*
* @param aStatus Completed with the return code when the operation completes.
*/
virtual void Unblock(TRequestStatus &aStatus) = 0;
/** Cancels an asynchronous Unblock() operation. */
virtual void CancelUnblock() = 0;
/**
* Gets the status of the authentication object.
*
* @return See TCTAuthenticationStatus() for the format of the return value.
*/
virtual TUint32 Status() const = 0;
// Enabling and Disabling
/**
* Disables the authentication object.
*
* It is only valid to call this method if the object is enabled, indicated
* by the EEnabled bit of Status() being set.
*
* Also, the authentication object may not support being enabled/disabled -
* the EDisableAllowed bit of Status() must be set for this to work.
*
* @param aStatus Completed with the return code when the operation completes.
*/
virtual void Disable(TRequestStatus &aStatus) = 0;
/** Cancels an asynchronous Disable() operation. */
virtual void CancelDisable() = 0;
/**
* Enables the authentication object.
*
* It is only valid to call this method if the object is disabled, indicated
* by the EEnabled bit of Status() being clear.
*
* Also, the authentication object may not support being enabled/disabled -
* the EDisableAllowed bit of Status() must be set for this to work.
*
* @param aStatus Completed with the return code when the operation completes.
*/
virtual void Enable(TRequestStatus &aStatus) = 0;
// Cancel an ongoing Enable operation
/** Cancels an asynchronous Enable() operation. */
virtual void CancelEnable() = 0;
/**
* Opens the authentication object.
*
* This means that the protected objects can be accessed without provoking
* the authentication mechanism for the duration of the timeout period.
*
* Note that 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 the authentication object
* requires the authentication data to be entered every time.
*
* @param aStatus Completed with the return code when the operation completes.
*/
virtual void Open(TRequestStatus& aStatus) = 0;
/**
* Closes an authentication object.
*
* @param aStatus Completed with the return code when the operation completes.
*/
virtual void Close(TRequestStatus& aStatus) = 0;
/**
* Gets the amount of time in seconds that the authentication object
* will remain open for, or 0 if it is closed.
*
* @param aStime Time in seconds when the operation completes.
* @param aStatus Completed with the return code when the operation completes.
*/
virtual void TimeRemaining(TInt& aStime, TRequestStatus& aStatus) = 0;
/**
* 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.
*
* @param aTime Time in seconds
* @param aStatus Completed with the return code when the operation completes
*
* @leave KErrArgument If the timeout specified is invalid.
*/
virtual void SetTimeout(TInt aTime, TRequestStatus& aStatus) = 0;
/**
* Gets the current timeout value, in seconds.
*
* For an explanation of the values, see SetTimeout().
*
* @param aTime Time in seconds.
* @param aStatus Completed with the return code when the operation completes.
*/
virtual void Timeout(TInt& aTime, TRequestStatus& aStatus) = 0;
/** Cancels an asynchronous Open() operation. */
virtual void CancelOpen() {};
/** Cancels an asynchronous Close() operation. */
virtual void CancelClose() {};
/** Cancels an asynchronous TimeRemaining() operation. */
virtual void CancelTimeRemaining() {};
/** Cancels an asynchronous SetTimeout() operation. */
virtual void CancelSetTimeout() {};
/** Cancels an asynchronous Timeout() operation. */
virtual void CancelTimeout() {};
};
/**
* An interface that enables clients to list all the authentication objects on
* a token, find out which objects they protect, and change/unblock/enable/disable them.
*
* It may be used to implement a 'PIN manager' control panel item. This could
* list the PINs (by label), allow one to be selected, list what it is used for
* (including information such as what operations on that object are protected
* by that PIN), and then allow the user to change, enable, disable, and unblock
* the PIN.
*
* Note that no PINs appear anywhere in this API. The code implementing this
* API will display a PIN dialog via the secure dialog interface when a PIN is
* required. The main advantage of this is that if some hostile code were to
* capture a PIN, it couldn't do anything with it as none of the APIs take a
* PIN. A secondary benefit is that the same API can work with biometrics or
* other methods of authentication.
*/
class MAuthenticationObjectList
{
public:
/**
* Gets a list of all the authenticaiton objects in the token.
*
* This is an asynchronous request.
*
* @param aAuthObjects On return, a list of all the authentication objects.
* @param aStatus The request status object; contains the result of the List() request
* when complete. Set to KErrCancel if an outstanding request is cancelled.
*/
// @param aAuthObjects The returned authentication objects will be appended to this array
// @param aStatus This will be completed with the final status code
virtual void List(RMPointerArray<MCTAuthenticationObject>& aAuthObjects, TRequestStatus& aStatus) = 0;
/**
* Cancels an asynchronous List() operation.
*
* The operation completes with KErrCancel.
*/
virtual void CancelList() = 0;
};
/**
* The class returned as the token interface.
*
* The class does not define any extra member functions or data.
*/
class MCTAuthenticationObjectList : public MCTTokenInterface,
public MAuthenticationObjectList
{
};
inline MCTAuthenticationObject::MCTAuthenticationObject(MCTToken& aToken)
: MCTTokenObject(aToken)
{
}
#endif //__MCTAOSTORE_H__