1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/authserver/authplugininterface.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,276 @@
1.4 +/*
1.5 +* Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of the License "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description:
1.18 +* CAuthPluginInterface
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +/**
1.24 + @file
1.25 + @publishedAll
1.26 + @released
1.27 +*/
1.28 +
1.29 +#ifndef AUTHPLUGININTERFACE_H
1.30 +#define AUTHPLUGININTERFACE_H
1.31 +
1.32 +
1.33 +#include <authserver/authtypes.h>
1.34 +#include <ecom/implementationinformation.h>
1.35 +
1.36 +namespace AuthServer
1.37 +{
1.38 +
1.39 +/// The interface UID for the authentication plugin interface
1.40 +const TUid KCAuthPluginInterfaceUid = { 0x102740FE };
1.41 +
1.42 +
1.43 +/**
1.44 + * The ECOM interface for authentication plugins. An authentication plugin is
1.45 + * used to help identify the current device holder. When a plugin is asked to
1.46 + * identify the holder, it interacts with the user and potentially hardware or
1.47 + * services provided by other servers. The plugin then generates some data
1.48 + * which is unique and repeatable for the input recieved. This data should
1.49 + * not be persisted on the device in any form that can easily be used to
1.50 + * recover the data.
1.51 + *
1.52 + * For example, a plugin might request a PIN number from the user. The plugin
1.53 + * will take the number, perhaps compare the hash of the number against the
1.54 + * hashes recorded during training and if a match is found return the identity
1.55 + * along with some unique data associated with it.
1.56 + *
1.57 + */
1.58 +class CAuthPluginInterface : public CBase
1.59 + {
1.60 +public:
1.61 +
1.62 + /**
1.63 + * @return the id of the plugin. This should be the ECOM implementation id.
1.64 + **/
1.65 + virtual TPluginId Id() const = 0;
1.66 +
1.67 + /**
1.68 + *
1.69 + * @return the name of the plugin.
1.70 + *
1.71 + **/
1.72 + virtual const TPtrC& Name() const = 0;
1.73 +
1.74 + /**
1.75 + *
1.76 + * @return a description of the plugin.
1.77 + *
1.78 + **/
1.79 + virtual const TPtrC& Description() const = 0;
1.80 +
1.81 + /**
1.82 + *
1.83 + * @return the minimum entropy of the plugin.
1.84 + *
1.85 + **/
1.86 + virtual TEntropy MinEntropy() const = 0;
1.87 +
1.88 + /**
1.89 + *
1.90 + * @return the rate of false positive identifications.
1.91 + *
1.92 + **/
1.93 + virtual TPercentage FalsePositiveRate() const = 0;
1.94 +
1.95 + /**
1.96 + *
1.97 + * @return the rate of false negative identifications.
1.98 + *
1.99 + **/
1.100 + virtual TPercentage FalseNegativeRate() const = 0;
1.101 +
1.102 + /**
1.103 + *
1.104 + * @return the type of plugin
1.105 + *
1.106 + **/
1.107 + virtual TAuthPluginType Type() const = 0;
1.108 +
1.109 + /**
1.110 + * Performs actions required to identify the current device holder.
1.111 + *
1.112 + * For details see the reference/test implementation of a knowledge-type
1.113 + * plugin called the pinplugin.
1.114 + *
1.115 + * @param aId in the event of a successfull call, aId will be set to the
1.116 + * id of the identity. The value is not modified otherwise. It should be
1.117 + * noted that a successful call includes the possibility of not
1.118 + * recognising the user in which case aId should be set to
1.119 + * KUnknownIdentity.
1.120 + *
1.121 + * @param aClientMessage A displayable text string parameter for authentication
1.122 + * requests.It shall be passed to plug-ins to display to the users.
1.123 + *
1.124 + * @param aResult in the event of a successfull call, aResult contains the
1.125 + * data generated from the identification process. This data is used by
1.126 + * the authentication server to generate a transient key which in turn is
1.127 + * used to decrypt the identities protection key. If the call was
1.128 + * unsuccessful or the user is unknown no buffer will be created. Ownership of
1.129 + * the buffer is transfered to the caller.
1.130 + *
1.131 + * @param aRequest the request status through which the caller will be
1.132 + * notified of completion. Upon completion, the status value will be one of the
1.133 + * following :
1.134 + * KErrNone if the identification process is successful.
1.135 + * KErrAuthServPluginCancelled if the user cancels the identification process for
1.136 + * this plugin.
1.137 + * KErrAuthServPluginQuit if the user quits the whole identification
1.138 + * process.
1.139 + * ... or any of the system wide error codes.
1.140 + **/
1.141 +
1.142 +
1.143 + virtual void Identify(TIdentityId& aId, const TDesC& aClientMessage,
1.144 + HBufC8*& aResult, TRequestStatus& aRequest) = 0;
1.145 +
1.146 + /**
1.147 + * Cancel the current action. This method must complete with KErrCancel
1.148 + * any outstanding asyncronous requests such as Train or Identify.
1.149 + **/
1.150 +
1.151 +
1.152 + virtual void Cancel() = 0;
1.153 +
1.154 + /**
1.155 + * This method tells the plugin to operate in training mode. After the
1.156 + * successful this method the plugin should be able to correctly identify
1.157 + * the specified identity using the Identify method. If the plugin already
1.158 + * has existing training data for the identity then the data should be
1.159 + * replaced. Care should be taken to allow the user to cancel or quit the
1.160 + * training without losing the existing training.
1.161 + *
1.162 + * @param aId the identity for whom to train the plugin. This allows the
1.163 + * plugin to persist training data associated with the identity and delete
1.164 + * or update that data later on.
1.165 + *
1.166 + * @param aResult this buffer will be filled with data that matches the
1.167 + * current device holder. This should be the same data as is returned by
1.168 + * the Identify method for the same identity. Ownership of the buffer is
1.169 + * transfered to the caller.
1.170 + *
1.171 + * @param aRequest the request status through which the caller will be
1.172 + * notified of completion. Upon completion the status value will be one of the
1.173 + * following :
1.174 + * KErrNone if the training process is successful.
1.175 + * KErrAuthServPluginCancelled if the user cancels the training process for
1.176 + * this plugin.
1.177 + * KErrAuthServPluginQuit if the user quits the whole training
1.178 + * process.
1.179 + * ... or any of the system wide error codes.
1.180 + **/
1.181 +
1.182 +
1.183 + virtual void Train(TIdentityId aId, HBufC8*& aResult,
1.184 + TRequestStatus& aRequest) = 0;
1.185 +
1.186 + /**
1.187 + * @return true if the plugin can be used for identification or training
1.188 + * purposes without further user intervention.
1.189 + **/
1.190 +
1.191 +
1.192 + virtual TBool IsActive() const = 0;
1.193 +
1.194 + /**
1.195 + * Remove any stored training data for the specified identity. This is
1.196 + * used if an identity is being removed from the device. No user
1.197 + * interaction should take place as a result of this call.
1.198 + *
1.199 + * @param aId the identity for whom to remove any persisted training data.
1.200 + *
1.201 + * @return KErrNone if the operation is successful.
1.202 + * @return KErrAuthServNoSuchIdentity if the TIdentityId wasn't recognised.
1.203 + * @return ... or any of the system wide error codes.
1.204 + **/
1.205 +
1.206 +
1.207 + virtual TInt Forget(TIdentityId aId) = 0;
1.208 +
1.209 + /**
1.210 + * Pretend the device holder has identified themselves using a default
1.211 + * entry. For example, a pin number plugin would return the same data as
1.212 + * if the holder had entered the default pin. This call is used during the
1.213 + * creation of the initial device identity and allows the device to be
1.214 + * operated without the user being forced to train plugins the first time
1.215 + * the device is started. No user interaction should take place as a
1.216 + * result of this call.
1.217 + *
1.218 + * Only plugins of type EAuthKnowledge should support default
1.219 + * data. Plugins of other types will be ignored.
1.220 + *
1.221 + * @param aId The identity that will be registered using the default data.
1.222 + *
1.223 + * @param aOutputBuf This buffer should be filled with the data that would
1.224 + * be generated if the phone holder identified themselves using the
1.225 + * default manner. Ownership of the buffer is transfered to the caller.
1.226 + *
1.227 + * @return KErrNone if the plugin supports default data.
1.228 + * @return KErrNotSupported if the plugin doesn't support default data.
1.229 + * @return ... or any of the system wide error codes.
1.230 + **/
1.231 +
1.232 +
1.233 + virtual TInt DefaultData(TIdentityId aId, HBufC8*& aOutputBuf) = 0;
1.234 +
1.235 + /**
1.236 + * This method tells the plugin to remove the training data held for the given identity
1.237 + * and to regenerate it using the supplied registration data. The intent of this method
1.238 + * is to allow a backend reset of user credentials in situations where the user is not
1.239 + * able to provide the credentials for some reason (for instance the user has forgotten
1.240 + * the password). Note that no user interaction should take place as a result of this call.
1.241 + * Since the registration data may not be usable by all plugin types it is expected that only
1.242 + * EAuthKnowledge type plugins (those based on pins, passphrases, etc.) use this data for
1.243 + * registering the user and return the result.
1.244 + *
1.245 + * @param aId The identity whose training data should be reset.
1.246 + *
1.247 + * @param aRegistrationData The data that can be used to register the identity.
1.248 + * This data is meaningful for EAuthKnowledge type plugins. Other plugins may choose to
1.249 + * ignore this parameter. An empty descriptor signifies the absence of registration data.
1.250 + *
1.251 + * @param aResult This buffer will be filled with data that matches the specified identity.
1.252 + * This should be the same data subsequently returned by the Identify method for the same identity.
1.253 + * Note that plugins that aren't supplied registration data or those that don't use the supplied
1.254 + * registration data for the reset can return NULL. Ownership of the buffer is transfered to
1.255 + * the caller.
1.256 + *
1.257 + * @return KErrNone if the plugin is successfully able to either remove and/or reset the training data.
1.258 + * @return KErrNotSupported if the plugin doesn't support a reset functionality.
1.259 + * @return ... or any of the system wide error codes.
1.260 + **/
1.261 +
1.262 +
1.263 + virtual TInt Reset(TIdentityId aId, const TDesC& aRegistrationData,
1.264 + HBufC8*& aResult) = 0;
1.265 +
1.266 + /**
1.267 + *
1.268 + * Destructor.
1.269 + *
1.270 + **/
1.271 +
1.272 +
1.273 + virtual ~CAuthPluginInterface() {};
1.274 +
1.275 +};
1.276 +
1.277 +} // namespace
1.278 +
1.279 +#endif