--- 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 <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__
+/*
+* 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__