--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/authenticationservices/authenticationserver/inc/authserver/authplugininterface.h Tue Nov 24 09:06:03 2009 +0200
@@ -0,0 +1,276 @@
+/*
+* Copyright (c) 2005-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:
+* CAuthPluginInterface
+*
+*/
+
+
+/**
+ @file
+ @publishedAll
+ @released
+*/
+
+#ifndef AUTHPLUGININTERFACE_H
+#define AUTHPLUGININTERFACE_H
+
+
+#include <authserver/authtypes.h>
+#include <ecom/implementationinformation.h>
+
+namespace AuthServer
+{
+
+/// The interface UID for the authentication plugin interface
+const TUid KCAuthPluginInterfaceUid = { 0x102740FE };
+
+
+/**
+ * The ECOM interface for authentication plugins. An authentication plugin is
+ * used to help identify the current device holder. When a plugin is asked to
+ * identify the holder, it interacts with the user and potentially hardware or
+ * services provided by other servers. The plugin then generates some data
+ * which is unique and repeatable for the input recieved. This data should
+ * not be persisted on the device in any form that can easily be used to
+ * recover the data.
+ *
+ * For example, a plugin might request a PIN number from the user. The plugin
+ * will take the number, perhaps compare the hash of the number against the
+ * hashes recorded during training and if a match is found return the identity
+ * along with some unique data associated with it.
+ *
+ */
+class CAuthPluginInterface : public CBase
+ {
+public:
+
+ /**
+ * @return the id of the plugin. This should be the ECOM implementation id.
+ **/
+ virtual TPluginId Id() const = 0;
+
+ /**
+ *
+ * @return the name of the plugin.
+ *
+ **/
+ virtual const TPtrC& Name() const = 0;
+
+ /**
+ *
+ * @return a description of the plugin.
+ *
+ **/
+ virtual const TPtrC& Description() const = 0;
+
+ /**
+ *
+ * @return the minimum entropy of the plugin.
+ *
+ **/
+ virtual TEntropy MinEntropy() const = 0;
+
+ /**
+ *
+ * @return the rate of false positive identifications.
+ *
+ **/
+ virtual TPercentage FalsePositiveRate() const = 0;
+
+ /**
+ *
+ * @return the rate of false negative identifications.
+ *
+ **/
+ virtual TPercentage FalseNegativeRate() const = 0;
+
+ /**
+ *
+ * @return the type of plugin
+ *
+ **/
+ virtual TAuthPluginType Type() const = 0;
+
+ /**
+ * Performs actions required to identify the current device holder.
+ *
+ * For details see the reference/test implementation of a knowledge-type
+ * plugin called the pinplugin.
+ *
+ * @param aId in the event of a successfull call, aId will be set to the
+ * id of the identity. The value is not modified otherwise. It should be
+ * noted that a successful call includes the possibility of not
+ * recognising the user in which case aId should be set to
+ * KUnknownIdentity.
+ *
+ * @param aClientMessage A displayable text string parameter for authentication
+ * requests.It shall be passed to plug-ins to display to the users.
+ *
+ * @param aResult in the event of a successfull call, aResult contains the
+ * data generated from the identification process. This data is used by
+ * the authentication server to generate a transient key which in turn is
+ * used to decrypt the identities protection key. If the call was
+ * unsuccessful or the user is unknown no buffer will be created. Ownership of
+ * the buffer is transfered to the caller.
+ *
+ * @param aRequest the request status through which the caller will be
+ * notified of completion. Upon completion, the status value will be one of the
+ * following :
+ * KErrNone if the identification process is successful.
+ * KErrAuthServPluginCancelled if the user cancels the identification process for
+ * this plugin.
+ * KErrAuthServPluginQuit if the user quits the whole identification
+ * process.
+ * ... or any of the system wide error codes.
+ **/
+
+
+ virtual void Identify(TIdentityId& aId, const TDesC& aClientMessage,
+ HBufC8*& aResult, TRequestStatus& aRequest) = 0;
+
+ /**
+ * Cancel the current action. This method must complete with KErrCancel
+ * any outstanding asyncronous requests such as Train or Identify.
+ **/
+
+
+ virtual void Cancel() = 0;
+
+ /**
+ * This method tells the plugin to operate in training mode. After the
+ * successful this method the plugin should be able to correctly identify
+ * the specified identity using the Identify method. If the plugin already
+ * has existing training data for the identity then the data should be
+ * replaced. Care should be taken to allow the user to cancel or quit the
+ * training without losing the existing training.
+ *
+ * @param aId the identity for whom to train the plugin. This allows the
+ * plugin to persist training data associated with the identity and delete
+ * or update that data later on.
+ *
+ * @param aResult this buffer will be filled with data that matches the
+ * current device holder. This should be the same data as is returned by
+ * the Identify method for the same identity. Ownership of the buffer is
+ * transfered to the caller.
+ *
+ * @param aRequest the request status through which the caller will be
+ * notified of completion. Upon completion the status value will be one of the
+ * following :
+ * KErrNone if the training process is successful.
+ * KErrAuthServPluginCancelled if the user cancels the training process for
+ * this plugin.
+ * KErrAuthServPluginQuit if the user quits the whole training
+ * process.
+ * ... or any of the system wide error codes.
+ **/
+
+
+ virtual void Train(TIdentityId aId, HBufC8*& aResult,
+ TRequestStatus& aRequest) = 0;
+
+ /**
+ * @return true if the plugin can be used for identification or training
+ * purposes without further user intervention.
+ **/
+
+
+ virtual TBool IsActive() const = 0;
+
+ /**
+ * Remove any stored training data for the specified identity. This is
+ * used if an identity is being removed from the device. No user
+ * interaction should take place as a result of this call.
+ *
+ * @param aId the identity for whom to remove any persisted training data.
+ *
+ * @return KErrNone if the operation is successful.
+ * @return KErrAuthServNoSuchIdentity if the TIdentityId wasn't recognised.
+ * @return ... or any of the system wide error codes.
+ **/
+
+
+ virtual TInt Forget(TIdentityId aId) = 0;
+
+ /**
+ * Pretend the device holder has identified themselves using a default
+ * entry. For example, a pin number plugin would return the same data as
+ * if the holder had entered the default pin. This call is used during the
+ * creation of the initial device identity and allows the device to be
+ * operated without the user being forced to train plugins the first time
+ * the device is started. No user interaction should take place as a
+ * result of this call.
+ *
+ * Only plugins of type EAuthKnowledge should support default
+ * data. Plugins of other types will be ignored.
+ *
+ * @param aId The identity that will be registered using the default data.
+ *
+ * @param aOutputBuf This buffer should be filled with the data that would
+ * be generated if the phone holder identified themselves using the
+ * default manner. Ownership of the buffer is transfered to the caller.
+ *
+ * @return KErrNone if the plugin supports default data.
+ * @return KErrNotSupported if the plugin doesn't support default data.
+ * @return ... or any of the system wide error codes.
+ **/
+
+
+ virtual TInt DefaultData(TIdentityId aId, HBufC8*& aOutputBuf) = 0;
+
+ /**
+ * This method tells the plugin to remove the training data held for the given identity
+ * and to regenerate it using the supplied registration data. The intent of this method
+ * is to allow a backend reset of user credentials in situations where the user is not
+ * able to provide the credentials for some reason (for instance the user has forgotten
+ * the password). Note that no user interaction should take place as a result of this call.
+ * Since the registration data may not be usable by all plugin types it is expected that only
+ * EAuthKnowledge type plugins (those based on pins, passphrases, etc.) use this data for
+ * registering the user and return the result.
+ *
+ * @param aId The identity whose training data should be reset.
+ *
+ * @param aRegistrationData The data that can be used to register the identity.
+ * This data is meaningful for EAuthKnowledge type plugins. Other plugins may choose to
+ * ignore this parameter. An empty descriptor signifies the absence of registration data.
+ *
+ * @param aResult This buffer will be filled with data that matches the specified identity.
+ * This should be the same data subsequently returned by the Identify method for the same identity.
+ * Note that plugins that aren't supplied registration data or those that don't use the supplied
+ * registration data for the reset can return NULL. Ownership of the buffer is transfered to
+ * the caller.
+ *
+ * @return KErrNone if the plugin is successfully able to either remove and/or reset the training data.
+ * @return KErrNotSupported if the plugin doesn't support a reset functionality.
+ * @return ... or any of the system wide error codes.
+ **/
+
+
+ virtual TInt Reset(TIdentityId aId, const TDesC& aRegistrationData,
+ HBufC8*& aResult) = 0;
+
+ /**
+ *
+ * Destructor.
+ *
+ **/
+
+
+ virtual ~CAuthPluginInterface() {};
+
+};
+
+} // namespace
+
+#endif