diff -r 675a964f4eb5 -r 35751d3474b7 cryptomgmtlibs/cryptotokenfw/inc_interfaces/MCTAuthObject.h --- a/cryptomgmtlibs/cryptotokenfw/inc_interfaces/MCTAuthObject.h Tue Jul 21 01:04:32 2009 +0100 +++ b/cryptomgmtlibs/cryptotokenfw/inc_interfaces/MCTAuthObject.h Thu Sep 10 14:01:51 2009 +0300 @@ -1,300 +1,298 @@ -/* -* 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__ +/* +* 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__