1 /*

     2 * Copyright (c) 2005-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 * CAuthPluginInterface 

    16 *

    17 */

    18 

    19 

    20 /**

    21  @file 

    22  @publishedAll

    23  @released

    24 */

    25 

    26 #ifndef AUTHPLUGININTERFACE_H

    27 #define AUTHPLUGININTERFACE_H

    28 

    29 

    30 #include <authserver/authtypes.h>

    31 #include <ecom/implementationinformation.h>

    32 

    33 namespace AuthServer

    34 {

    35 

    36 /// The interface UID for the authentication plugin interface

    37 const TUid KCAuthPluginInterfaceUid = { 0x102740FE }; 

    38 

    39 

    40 /**

    41  * The ECOM interface for authentication plugins. An authentication plugin is

    42  * used to help identify the current device holder. When a plugin is asked to

    43  * identify the holder, it interacts with the user and potentially hardware or

    44  * services provided by other servers. The plugin then generates some data

    45  * which is unique and repeatable for the input recieved. This data should

    46  * not be persisted on the device in any form that can easily be used to

    47  * recover the data.

    48  *

    49  * For example, a plugin might request a PIN number from the user. The plugin

    50  * will take the number, perhaps compare the hash of the number against the

    51  * hashes recorded during training and if a match is found return the identity

    52  * along with some unique data associated with it.

    53  *

    54  */	

    55 class CAuthPluginInterface : public CBase

    56 	{

    57 public:

    58 

    59 	/**

    60 	 * @return the id of the plugin. This should be the ECOM implementation id.

    61 	 **/

    62 	virtual TPluginId Id() const = 0;

    63 

    64 	/**

    65 	 *

    66 	 * @return the name of the plugin.

    67 	 * 

    68 	 **/

    69 	virtual const TPtrC& Name() const = 0;

    70 	

    71 	/**

    72 	 *

    73 	 * @return a description of the plugin.

    74 	 * 

    75 	 **/

    76 	virtual const TPtrC& Description() const = 0;

    77 

    78 	/**

    79 	 *

    80 	 * @return the minimum entropy of the plugin.

    81 	 * 

    82 	 **/

    83 	virtual TEntropy MinEntropy() const = 0;

    84 	

    85 	/**

    86 	 *

    87 	 * @return the rate of false positive identifications.

    88 	 * 

    89 	 **/

    90 	virtual TPercentage FalsePositiveRate() const = 0;

    91 

    92 	/**

    93 	 *

    94 	 * @return the rate of false negative identifications.

    95 	 * 

    96 	 **/

    97 	virtual TPercentage FalseNegativeRate() const = 0;

    98 

    99 	/**

   100 	 *

   101 	 * @return the type of plugin

   102 	 * 

   103 	 **/

   104 	virtual TAuthPluginType Type() const = 0;

   105 

   106 	/**

   107 	 * Performs actions required to identify the current device holder. 

   108 	 *

   109 	 * For details see the reference/test implementation of a knowledge-type 

   110 	 * plugin called the pinplugin.

   111 	 *

   112 	 * @param aId in the event of a successfull call, aId will be set to the

   113 	 * id of the identity. The value is not modified otherwise. It should be

   114 	 * noted that a successful call includes the possibility of not

   115 	 * recognising the user in which case aId should be set to

   116 	 * KUnknownIdentity.

   117 	 *

   118 	 * @param aClientMessage A displayable text string parameter for authentication

   119 	 * requests.It shall be passed to plug-ins to display to the users.

   120 	 *

   121 	 * @param aResult in the event of a successfull call, aResult contains the

   122 	 * data generated from the identification process. This data is used by

   123 	 * the authentication server to generate a transient key which in turn is

   124 	 * used to decrypt the identities protection key. If the call was

   125 	 * unsuccessful or the user is unknown no buffer will be created. Ownership of 

   126 	 * the buffer is transfered to the caller.

   127 	 *

   128 	 * @param aRequest the request status through which the caller will be

   129 	 * notified of completion. Upon completion, the status value will be one of the

   130 	 * following :

   131 	 * KErrNone if the identification process is successful.

   132 	 * KErrAuthServPluginCancelled if the user cancels the identification process for

   133 	 * this plugin.

   134 	 * KErrAuthServPluginQuit if the user quits the whole identification

   135 	 * process.

   136 	 * ... or any of the system wide error codes.

   137 	 **/

   138 

   139 

   140 	virtual void Identify(TIdentityId& aId, const TDesC& aClientMessage, 

   141 						  HBufC8*& aResult, TRequestStatus& aRequest) = 0;

   142 

   143 	/**

   144 	 * Cancel the current action. This method must complete with KErrCancel

   145 	 * any outstanding asyncronous requests such as Train or Identify.

   146 	 **/

   147 

   148 

   149 	virtual void Cancel() = 0;

   150 	

   151 	/**

   152 	 * This method tells the plugin to operate in training mode. After the

   153 	 * successful this method the plugin should be able to correctly identify

   154 	 * the specified identity using the Identify method. If the plugin already

   155 	 * has existing training data for the identity then the data should be

   156 	 * replaced. Care should be taken to allow the user to cancel or quit the

   157 	 * training without losing the existing training.  

   158 	 * 

   159 	 * @param aId the identity for whom to train the plugin. This allows the

   160 	 * plugin to persist training data associated with the identity and delete

   161 	 * or update that data later on.

   162 	 *

   163 	 * @param aResult this buffer will be filled with data that matches the

   164 	 * current device holder. This should be the same data as is returned by

   165 	 * the Identify method for the same identity. Ownership of the buffer is 

   166 	 * transfered to the caller.

   167 	 *

   168 	 * @param aRequest the request status through which the caller will be

   169 	 * notified of completion. Upon completion the status value will be one of the

   170 	 * following :

   171 	 * KErrNone if the training process is successful.

   172 	 * KErrAuthServPluginCancelled if the user cancels the training process for

   173 	 * this plugin.

   174 	 * KErrAuthServPluginQuit if the user quits the whole training

   175 	 * process.

   176 	 * ... or any of the system wide error codes.

   177 	 **/

   178 

   179 

   180 	 virtual void Train(TIdentityId aId, HBufC8*& aResult,

   181 						TRequestStatus& aRequest) = 0;

   182 

   183 	/**

   184 	 * @return true if the plugin can be used for identification or training

   185 	 * purposes without further user intervention. 

   186 	 **/

   187 

   188 

   189 	virtual TBool IsActive() const = 0;

   190 	

   191 	/**

   192 	 * Remove any stored training data for the specified identity. This is

   193 	 * used if an identity is being removed from the device. No user

   194 	 * interaction should take place as a result of this call.

   195 	 *

   196 	 * @param aId the identity for whom to remove any persisted training data.

   197 	 *

   198 	 * @return KErrNone if the operation is successful.

   199 	 * @return KErrAuthServNoSuchIdentity if the TIdentityId wasn't recognised.

   200 	 * @return ... or any of the system wide error codes.

   201 	 **/

   202 

   203 

   204 	 virtual TInt Forget(TIdentityId aId) = 0;

   205 

   206 	/**

   207 	 * Pretend the device holder has identified themselves using a default

   208 	 * entry. For example, a pin number plugin would return the same data as

   209 	 * if the holder had entered the default pin. This call is used during the

   210 	 * creation of the initial device identity and allows the device to be

   211 	 * operated without the user being forced to train plugins the first time

   212 	 * the device is started. No user interaction should take place as a

   213 	 * result of this call.

   214 	 *

   215 	 * Only plugins of type EAuthKnowledge should support default

   216 	 * data. Plugins of other types will be ignored.

   217 	 *

   218 	 * @param aId The identity that will be registered using the default data. 

   219 	 * 

   220 	 * @param aOutputBuf This buffer should be filled with the data that would

   221 	 * be generated if the phone holder identified themselves using the

   222 	 * default manner. Ownership of the buffer is transfered to the caller. 

   223 	 *

   224 	 * @return KErrNone if the plugin supports default data.

   225 	 * @return KErrNotSupported if the plugin doesn't support default data.

   226 	 * @return ... or any of the system wide error codes.

   227 	 **/

   228 

   229 

   230 	 virtual TInt DefaultData(TIdentityId aId, HBufC8*& aOutputBuf) = 0;

   231 

   232 	/**

   233 	 * This method tells the plugin to remove the training data held for the given identity 

   234 	 * and to regenerate it using the supplied registration data. The intent of this method 

   235 	 * is to allow a backend reset of user credentials in situations where the user is not 

   236 	 * able to provide the credentials for some reason (for instance the user has forgotten 

   237 	 * the password). Note that no user interaction should take place as a result of this call. 

   238 	 * Since the registration data may not be usable by all plugin types it is expected that only 

   239 	 * EAuthKnowledge type plugins (those based on pins, passphrases, etc.) use this data for 

   240 	 * registering the user and return the result.

   241 	 *

   242 	 * @param aId The identity whose training data should be reset. 

   243 	 * 

   244 	 * @param aRegistrationData The data that can be used to register the identity. 

   245 	 * This data is meaningful for EAuthKnowledge type plugins. Other plugins may choose to 

   246 	 * ignore this parameter. An empty descriptor signifies the absence of registration data.

   247 	 *

   248 	 * @param aResult This buffer will be filled with data that matches the specified identity. 

   249 	 * This should be the same data subsequently returned by the Identify method for the same identity. 

   250 	 * Note that plugins that aren't supplied registration data or those that don't use the supplied 

   251 	 * registration data for the reset can return NULL. Ownership of the buffer is transfered to 

   252 	 * the caller.

   253 	 *

   254 	 * @return KErrNone if the plugin is successfully able to either remove and/or reset the training data.

   255 	 * @return KErrNotSupported if the plugin doesn't support a reset functionality.

   256 	 * @return ... or any of the system wide error codes.

   257 	 **/

   258 

   259 

   260 	 virtual TInt Reset(TIdentityId aId, const TDesC& aRegistrationData, 

   261 			 			HBufC8*& aResult) = 0;

   262 	

   263 	/**

   264 	 * 

   265 	 * Destructor.

   266 	 * 

   267 	 **/

   268 

   269 

   270 	virtual ~CAuthPluginInterface() {};

   271 	

   272 };	

   273 

   274 } // namespace

   275 

   276 #endif