2 * Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).
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".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
15 * CAuthPluginInterface
26 #ifndef AUTHPLUGININTERFACE_H
27 #define AUTHPLUGININTERFACE_H
30 #include <authserver/authtypes.h>
31 #include <ecom/implementationinformation.h>
36 /// The interface UID for the authentication plugin interface
37 const TUid KCAuthPluginInterfaceUid = { 0x102740FE };
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
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.
55 class CAuthPluginInterface : public CBase
60 * @return the id of the plugin. This should be the ECOM implementation id.
62 virtual TPluginId Id() const = 0;
66 * @return the name of the plugin.
69 virtual const TPtrC& Name() const = 0;
73 * @return a description of the plugin.
76 virtual const TPtrC& Description() const = 0;
80 * @return the minimum entropy of the plugin.
83 virtual TEntropy MinEntropy() const = 0;
87 * @return the rate of false positive identifications.
90 virtual TPercentage FalsePositiveRate() const = 0;
94 * @return the rate of false negative identifications.
97 virtual TPercentage FalseNegativeRate() const = 0;
101 * @return the type of plugin
104 virtual TAuthPluginType Type() const = 0;
107 * Performs actions required to identify the current device holder.
109 * For details see the reference/test implementation of a knowledge-type
110 * plugin called the pinplugin.
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
118 * @param aClientMessage A displayable text string parameter for authentication
119 * requests.It shall be passed to plug-ins to display to the users.
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.
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
131 * KErrNone if the identification process is successful.
132 * KErrAuthServPluginCancelled if the user cancels the identification process for
134 * KErrAuthServPluginQuit if the user quits the whole identification
136 * ... or any of the system wide error codes.
140 virtual void Identify(TIdentityId& aId, const TDesC& aClientMessage,
141 HBufC8*& aResult, TRequestStatus& aRequest) = 0;
144 * Cancel the current action. This method must complete with KErrCancel
145 * any outstanding asyncronous requests such as Train or Identify.
149 virtual void Cancel() = 0;
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.
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.
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.
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
171 * KErrNone if the training process is successful.
172 * KErrAuthServPluginCancelled if the user cancels the training process for
174 * KErrAuthServPluginQuit if the user quits the whole training
176 * ... or any of the system wide error codes.
180 virtual void Train(TIdentityId aId, HBufC8*& aResult,
181 TRequestStatus& aRequest) = 0;
184 * @return true if the plugin can be used for identification or training
185 * purposes without further user intervention.
189 virtual TBool IsActive() const = 0;
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.
196 * @param aId the identity for whom to remove any persisted training data.
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.
204 virtual TInt Forget(TIdentityId aId) = 0;
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.
215 * Only plugins of type EAuthKnowledge should support default
216 * data. Plugins of other types will be ignored.
218 * @param aId The identity that will be registered using the default data.
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.
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.
230 virtual TInt DefaultData(TIdentityId aId, HBufC8*& aOutputBuf) = 0;
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.
242 * @param aId The identity whose training data should be reset.
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.
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
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.
260 virtual TInt Reset(TIdentityId aId, const TDesC& aRegistrationData,
261 HBufC8*& aResult) = 0;
270 virtual ~CAuthPluginInterface() {};