1 /*

     2 * Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the License "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 /**

    22  @file

    23  @publishedPartner

    24  @released

    25 */

    26 

    27 #ifndef __MCTAOSTORE_H__

    28 #define __MCTAOSTORE_H__

    29 

    30 #include <ct.h>

    31 

    32 /** The UID for the authentication object interface. */

    33 const TInt KCTInterfaceAuthenticationObject = 0x101F51AE;

    34 

    35 /**

    36  * A timeout value for an auth object indicating that it stays open until

    37  * explicity closed.

    38  */

    39 const TInt KTimeoutNever = -1;

    40 

    41 /**

    42  * A timeout value for an auth object indicating that the authentication data

    43  * must be entered every time the protected objects are used.

    44  */

    45 const TInt KTimeoutImmediate = 0;

    46 

    47 /**

    48  * The status of an authentication object.

    49  */

    50 enum TCTAuthenticationStatus

    51 	{

    52 	/** The authentication object is enabled. If it is not enabled, the objects protected 

    53 	* by this authentication object can be accessed without authentication. */

    54 	EEnabled		= 0x80,

    55 	/** The reference data cannot be changed. */

    56 	EChangeDisabled	= 0x40,

    57 	/** The authentication cannot be unblocked. */

    58 	EUnblockDisabled	= 0x20,

    59 	/** The authentication object can be disabled. */

    60 	EDisableAllowed	= 0x10,

    61 	/** The authentication object is blocked, meaning that the

    62 	* unblocking PIN must be entered to re-enable the authentication object. */

    63 	EAuthObjectBlocked= 0x08,

    64 	};	

    65 

    66 /** 

    67  * This class allows authentication objects to be queried and manipulated.

    68  * 

    69  * Authentication objects are obtained from the MCTAuthenticationObjectList class, 

    70  * which is the class returned as the token interface. 

    71  */

    72 class MCTAuthenticationObject: public MCTTokenObject

    73 	{

    74 public:

    75 	/** Constructor */

    76 	inline MCTAuthenticationObject(MCTToken& aToken);

    77 

    78 	// Listing Protected Objects

    79 	/** 

    80 	 * Gets a list of all the objects that this authentication object protects.

    81 	 * 

    82 	 * @param aObjects	The returned objects will be appended to this array.

    83 	 * @param aStatus	Completed with the return code when the operation completes. 

    84 	 */

    85 	virtual void ListProtectedObjects(RMPointerArray<MCTTokenObject>& aObjects, TRequestStatus& aStatus) = 0;

    86 

    87 	/** Cancels an asynchronous ListProtectedObjects() operation. */

    88 	virtual void CancelListProtectedObjects() = 0;

    89 	

    90 	// Changing the reference data

    91 	/** 

    92 	 * Changes the reference data (e.g. PIN value).

    93 	 * 

    94 	 * The security dialog component will prompt for the old and new reference data.

    95 	 *

    96 	 * The authentication object may not allow its reference data to be changed -

    97 	 * this is indicated by the EChangeDisabled bit of Status() being set.

    98 	 * 

    99 	 * @param aStatus	Completed with the return code when the operation completes.

   100 	 *

   101 	 * @leave KErrNotFound If no reference data was originally set.

   102 	 */

   103 	virtual void ChangeReferenceData(TRequestStatus &aStatus) = 0;

   104 

   105 	/** Cancels an asynchronous ChangeReferenceData() operation. */

   106 	virtual void CancelChangeReferenceData() = 0;

   107 	

   108 	/** 

   109 	 * Unblocks the authentication object.

   110 	 * 

   111 	 * The security dialog component will prompt for the unblocking

   112 	 * authentication object.

   113 	 *

   114 	 * It is only valid to call this method when the authentication object is

   115 	 * blocked, ie when the EAuthObjectBlocked bit of Status() is set.

   116 	 * 

   117 	 * The object may not allow unblocking (either because of failed unblock

   118 	 * attempts or because it doesn't support the concept) - this is indicated by

   119 	 * the EUnblockDisabled bit of Status() being set.

   120 	 * 

   121 	 * @param aStatus	Completed with the return code when the operation completes. 

   122 	 */

   123 	virtual void Unblock(TRequestStatus &aStatus) = 0;

   124 

   125 	/** Cancels an asynchronous Unblock() operation. */

   126 	virtual void CancelUnblock() = 0;

   127 	

   128 	/** 

   129 	 * Gets the status of the authentication object.

   130 	 * 

   131 	 * @return	See TCTAuthenticationStatus() for the format of the return value. 

   132 	 */

   133 	virtual TUint32 Status() const = 0;

   134 

   135 	// Enabling and Disabling

   136 	/** 

   137 	 * Disables the authentication object.

   138 	 *

   139 	 *  It is only valid to call this method if the object is enabled, indicated

   140 	 *  by the EEnabled bit of Status() being set.

   141 	 *

   142 	 *  Also, the authentication object may not support being enabled/disabled -

   143 	 *  the EDisableAllowed bit of Status() must be set for this to work.

   144 	 *  

   145 	 * @param aStatus	Completed with the return code when the operation completes. 

   146 	 */

   147 	virtual void Disable(TRequestStatus &aStatus) = 0;

   148 

   149 	/** Cancels an asynchronous Disable() operation. */

   150 	virtual void CancelDisable() = 0;

   151 

   152 	/** 

   153 	 * Enables the authentication object.

   154 	 *

   155 	 *  It is only valid to call this method if the object is disabled, indicated

   156 	 *  by the EEnabled bit of Status() being clear.

   157 	 *

   158 	 *  Also, the authentication object may not support being enabled/disabled -

   159 	 *  the EDisableAllowed bit of Status() must be set for this to work.

   160 	 *  

   161 	 * @param aStatus	Completed with the return code when the operation completes. 

   162 	 */

   163 	virtual void Enable(TRequestStatus &aStatus) = 0;

   164 

   165 	// Cancel an ongoing Enable operation

   166 	/** Cancels an asynchronous Enable() operation. */

   167 	virtual void CancelEnable() = 0;

   168 	

   169 	/** 

   170 	 * Opens the authentication object.

   171 	 * 

   172 	 * This means that the protected objects can be accessed without provoking

   173 	 * the authentication mechanism for the duration of the timeout period.

   174 	 * 	

   175 	 * Note that it is not strictly necessary to call this function, as the

   176 	 * authentication object will be opened when any operation that needs it to

   177 	 * be opened is called, but it is sometimes useful to control the timing of

   178 	 * authentication dialogs. Note also that this function will do nothing if

   179 	 * the authentication object is open, or if the authentication object

   180 	 * requires the authentication data to be entered every time.

   181 	 * 

   182 	 * @param aStatus	Completed with the return code when the operation completes.

   183 	 */

   184 	virtual void Open(TRequestStatus& aStatus) = 0;

   185 

   186 	/** 

   187 	 * Closes an authentication object. 

   188 	 * 

   189 	 * @param aStatus	Completed with the return code when the operation completes.

   190 	 */

   191 	virtual void Close(TRequestStatus& aStatus) = 0;

   192 

   193 	/** 

   194 	 * Gets the amount of time in seconds that the authentication object

   195 	 * will remain open for, or 0 if it is closed.

   196 	 * 

   197 	 * @param aStime		Time in seconds when the operation completes.

   198 	 * @param aStatus	Completed with the return code when the operation completes.

   199 	 */

   200 	virtual void TimeRemaining(TInt& aStime, TRequestStatus& aStatus) = 0;

   201 		

   202 	/** 

   203 	 * Sets the time in seconds for this authentication object. 

   204 	 * 

   205 	 * Permitted values include 0, meaning always ask, and -1,

   206 	 * meaning until it's explicitly closed. Particular authentication

   207 	 * objects might restrict the range of values permitted.

   208 	 * 

   209 	 * @param aTime		Time in seconds

   210 	 * @param aStatus	Completed with the return code when the operation completes

   211 	 *

   212 	 * @leave KErrArgument If the timeout specified is invalid.

   213 	 */

   214 	virtual void SetTimeout(TInt aTime, TRequestStatus& aStatus) = 0;

   215 

   216 	/** 

   217 	 * Gets the current timeout value, in seconds. 

   218 	 * 

   219 	 * For an explanation of the values, see SetTimeout().

   220 	 * 

   221 	 * @param aTime		Time in seconds.

   222 	 * @param aStatus	Completed with the return code when the operation completes.

   223 	 */

   224 	virtual void Timeout(TInt& aTime, TRequestStatus& aStatus) = 0;

   225 		

   226 	/** Cancels an asynchronous Open() operation. */

   227 	virtual void CancelOpen() {};

   228 

   229 	/** Cancels an asynchronous Close() operation. */

   230   	virtual void CancelClose() {};

   231 

   232 	/** Cancels an asynchronous TimeRemaining() operation. */

   233 	virtual void CancelTimeRemaining() {};

   234 	

   235 	/** Cancels an asynchronous SetTimeout() operation. */

   236 	virtual void CancelSetTimeout() {};

   237 

   238 	/** Cancels an asynchronous Timeout() operation. */

   239 	virtual void CancelTimeout() {};

   240 

   241 	};

   242 

   243 /** 

   244  * An interface that enables clients to list all the authentication objects on 

   245  * a token, find out which objects they protect, and change/unblock/enable/disable them.

   246  * 

   247  * It may be used to implement a 'PIN manager' control panel item. This could 

   248  * list the PINs (by label), allow one to be selected, list what it is used for 

   249  * (including information such as what operations on that object are protected 

   250  * by that PIN), and then allow the user to change, enable, disable, and unblock 

   251  * the PIN.

   252  * 

   253  * Note that no PINs appear anywhere in this API. The code implementing this 

   254  * API will display a PIN dialog via the secure dialog interface when a PIN is 

   255  * required. The main advantage of this is that if some hostile code were to 

   256  * capture a PIN, it couldn't do anything with it as none of the APIs take a 

   257  * PIN. A secondary benefit is that the same API can work with biometrics or 

   258  * other methods of authentication. 

   259  */

   260 class MAuthenticationObjectList

   261 	{

   262 public:	

   263 	/** 

   264 	 * Gets a list of all the authenticaiton objects in the token.

   265 	 * 

   266 	 * This is an asynchronous request.

   267 	 * 

   268 	 * @param aAuthObjects	On return, a list of all the authentication objects.

   269 	 * @param aStatus		The request status object; contains the result of the List() request 

   270 	 * 						when complete. Set to KErrCancel if an outstanding request is cancelled. 

   271 	 */

   272 	// @param aAuthObjects	The returned authentication objects will be appended to this array

   273 	// @param aStatus		This will be completed with the final status code

   274 	virtual void List(RMPointerArray<MCTAuthenticationObject>& aAuthObjects,	TRequestStatus& aStatus) = 0;

   275 

   276 	/** 

   277 	 * Cancels an asynchronous List() operation.

   278 	 * 

   279 	 * The operation completes with KErrCancel. 

   280 	 */

   281 	virtual void CancelList() = 0;

   282 	};

   283 

   284 

   285 /**

   286  * The class returned as the token interface.

   287  * 

   288  * The class does not define any extra member functions or data. 

   289  */

   290 class MCTAuthenticationObjectList : public MCTTokenInterface, 

   291 									public MAuthenticationObjectList

   292 	{

   293 	};

   294 

   295 inline MCTAuthenticationObject::MCTAuthenticationObject(MCTToken& aToken)

   296 		: MCTTokenObject(aToken)

   297 	{

   298 	}

   299 

   300 #endif //__MCTAOSTORE_H__