diff -r 000000000000 -r 2c201484c85f cryptomgmtlibs/cryptotokenfw/inc_interfaces/MCTAuthObject.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/cryptomgmtlibs/cryptotokenfw/inc_interfaces/MCTAuthObject.h Wed Jul 08 11:25:26 2009 +0100 @@ -0,0 +1,300 @@ +/* +* 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 + +/** 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& 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& 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__