1 /*

     2 * Copyright (c) 2002 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 "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:  An implementation of single authentication object

    15 *

    16 */

    17 

    18 

    19 #ifndef CWIMAUTHENTICATIONOBJECT_H

    20 #define CWIMAUTHENTICATIONOBJECT_H

    21 

    22 // INCLUDES

    23 

    24 #include <mctauthobject.h>

    25 #include <mctkeystore.h>

    26 #include <unifiedcertstore.h>

    27 #include <mctwritablecertstore.h>

    28 #include <unifiedkeystore.h>

    29 #include "WimToken.h"

    30 

    31 // FORWARD DECLARATIONS

    32 

    33 class CCTKeyInfo;

    34 class CWimPin;

    35 

    36 // CLASS DECLARATION

    37 

    38 /**

    39 *  Represents one authentication object (for example a pin code)

    40 *

    41 *  @lib   WimPlugin

    42 *  @since Series 60 2.1

    43 */

    44 

    45 class CWimAuthenticationObject : public CActive, public MCTAuthenticationObject

    46     {

    47 

    48     public: // Two-phased constructor

    49 

    50         /**

    51         * @param  aToken   A reference to current token

    52         * @param  aWimPin  A reference to current pin manager

    53         * @param  aLabel   A reference to label for this object

    54         * @param  aType    Type of this object

    55         * @param  aHandle  Handle of this object

    56         * @param  aObjectStatus  Status of this object

    57         * @return An instance of this class

    58         */

    59         static CWimAuthenticationObject* NewLC( CWimToken& aToken, 

    60                                                 CWimPin& aWimPin,

    61                                                 const TDesC& aLabel,

    62                                                 const TUid aType,

    63                                                 const TInt aHandle,

    64                                                 TUint32 aObjectStatus );

    65 

    66     public: // Functions from base class MCTTokenObject

    67 

    68         /**

    69         * Returns a reference to this authentication object's 

    70         * human-readable label.

    71         * @return A reference to object's label.

    72         */

    73         const TDesC& Label() const;

    74 

    75         /**

    76         * Returns a reference to current token.

    77         * @return A reference to current token.

    78         */

    79         MCTToken& Token() const;

    80 

    81         /**

    82         * Returns type (UID) of current authentication object. 

    83         * Must be unique within a token. WIM_PIN_G_UID or WIM_PIN_NR_UID

    84         * @return UID of the current object.

    85         */

    86         TUid Type() const;      

    87 

    88         /**

    89         * Returns a handle of the authentication object.

    90         * @return A handle

    91         *         Must be unique within a token.

    92         */

    93         TCTTokenObjectHandle Handle() const;    

    94 

    95     public: // Functions from base class MCTAuthenticationObject

    96 

    97         /**

    98         * Returns a list of all the objects which this authentication object 

    99         * protects; for example keys and certificates.

   100         * The caller of this functions owns all its parameters.

   101         * @param  aObjects (OUT) The returned objects will be appended 

   102         *         to this array.

   103         * @param  aStatus (IN/OUT) Completed with the return code when 

   104         *         the operation completes.

   105         *         KErrNone, if no errors detected. Note: if protected

   106         *         objects are not found, it is also KErrNone

   107         *         KErrCancel, if call is canceled

   108         *         KErrHardwareNotAvailable, if Wim card suddenly removed

   109         *         Any other system wide error code (e.g. KErrNoMemory)

   110         * @return void

   111         */

   112         void ListProtectedObjects( RMPointerArray<MCTTokenObject>& aObjects,

   113                                    TRequestStatus& aStatus );

   114 

   115         /**

   116         * Cancels an ongoing ListProtectedObjects operation.

   117         * @return void

   118         */

   119         void CancelListProtectedObjects();

   120 

   121         /**

   122         * Changes the reference data (e.g. PIN value). The security

   123         * dialog component will prompt for the old and new reference data.

   124         * @param  aStatus (IN/OUT) Completed with the return code when the 

   125         *         operation completes.

   126         *         KErrNone, if no errors detected.

   127         *         KErrLocked, if this authentication object is blocked

   128         *         KErrNotSupported, if authentication object reference data 

   129         *         cannot be changed

   130         *         KErrBadData, if user entered wrong authentication data

   131         *         KErrHardwareNotAvailable, if Wim card suddenly removed

   132         *         Any other system wide error code (e.g. KErrNoMemory)

   133         * @return void

   134         */

   135         void ChangeReferenceData( TRequestStatus &aStatus );

   136 

   137         /**

   138         * Cancels an ongoing ChangeReferenceData operation. 

   139         * @return void

   140         */

   141         void CancelChangeReferenceData();

   142 

   143         /**

   144         * Unblocks the authentication object. The security dialog component will

   145         * prompt for the unblocking authentication object.

   146         * @param  aStatus (IN/OUT) Completed with the return code when the 

   147         *         operation completes. 

   148         *         KErrNone, if no errors detected, or authentication object was

   149         *         not blocked

   150         *         KErrNotSupported, if authentication object cannot be unblocked

   151         *         KErrBadData, if user entered wrong authentication data

   152         *         KErrHardwareNotAvailable, if Wim card suddenly removed

   153         *         Any other system wide error code (e.g. KErrNoMemory)

   154         * @return void

   155         */

   156         void Unblock( TRequestStatus &aStatus );

   157     

   158         /**

   159         * Cancels an ongoing Unblock operation.

   160         * @return void

   161         */

   162         void CancelUnblock();

   163 

   164         /**

   165         * Gets the status of the authentication object. 

   166         * @return  See TCTAuthenticationStatus for the format of the 

   167         *          return value.

   168         *          When status cannot be fetched for some reasons, this value 

   169         *          is zero.

   170         */

   171         TUint32 Status() const;

   172 

   173         /**

   174         * Disables the authentication object.

   175         * @param  aStatus (IN/OUT) Completed with the return code when the 

   176         *         operation completes.

   177         *         KErrNone, if no errors detected

   178         *         KErrLocked, if authentication object is blocked

   179         *         KErrNotFound, if authentication object cannot be found

   180         *         KErrBadData, if user entered wrong authentication data

   181         *         KErrHardwareNotAvailable, if Wim card suddenly removed

   182         *         Any other system wide error code (e.g. KErrNoMemory)

   183         * @return void

   184         */

   185         void Disable( TRequestStatus &aStatus );

   186 

   187         /**

   188         * Cancels an ongoing Disable operation.

   189         * @return void

   190         */

   191         void CancelDisable();

   192 

   193         /**

   194         * Enables the authentication object.

   195         * @param  aStatus (IN/OUT) Completed with the return code when 

   196         *         the operation completes.

   197         *         KErrNone, if no errors detected

   198         *         KErrLocked, if authentication object is blocked

   199         *         KErrNotFound, if authentication object cannot be found

   200         *         KErrBadData, if user entered wrong authentication data

   201         *         KErrHardwareNotAvailable, if Wim card suddenly removed

   202         *         Any other system wide error code (e.g. KErrNoMemory)

   203         * @return void

   204         */

   205         void Enable( TRequestStatus &aStatus );

   206 

   207         /**

   208         * Cancels an ongoing Enable operation.

   209         * @return void

   210         */

   211         void CancelEnable();

   212 

   213         /** 

   214         * Opens the authentication object, meaning that the protected objects 

   215         * can be accessed without provoking the authentication mechanism for 

   216         * the duration of the timeout period. Note. It is not strictly 

   217         * necessary to call this function, as the authentication object will 

   218         * be opened when any operation that needs it to be opened is called, 

   219         * but it is sometimes useful to control the timing of authentication 

   220         * dialogs. Note also that this function will do nothing if the 

   221         * authentication object is open, or if it authentication object requires

   222         * the authentication.

   223         * @param aStatus  TRequestStatus from the caller.(IN/OUT)

   224         *         KErrNone, if no errors detected,  or authentication object

   225         *         is open

   226         *         KErrLocked, if authentication object is blocked

   227         *         KErrNotFound, if authentication object cannot be found

   228         *         KErrNotSupported, if authentication object is not openable 

   229         *         KErrHardwareNotAvailable, if Wim card suddenly removed

   230         *         Any other system wide error code (e.g. KErrNoMemory)

   231         * @return void

   232         */

   233         void Open( TRequestStatus& aStatus );

   234 

   235         /** 

   236         * Closes an authentication object.

   237         * @param aStatus  TRequestStatus from the caller.(IN/OUT)

   238         *         KErrNone, if no errors detected or authentication object

   239         *         is closed.

   240         *         KErrLocked, if authentication object is blocked

   241         *         KErrNotSupported, if authentication object is not closeable

   242         *         KErrHardwareNotAvailable, if Wim card suddenly removed

   243         *         Any other system wide error code (e.g. KErrNoMemory)

   244         * @return void

   245         */

   246         void Close( TRequestStatus& aStatus );

   247 

   248         /** 

   249         * Returns the amount of time in seconds that the authentication object

   250         * will remain open for, or 0 if it is closed. Thís call is valid

   251         * only for authentication object, that can be opened (e.g. PIN-G)

   252         * @param aStime   Time (in seconds) to be returned. (OUT)

   253         * @param aStatus  TRequestStatus from the caller. (IN/OUT)

   254         *         KErrNone, if no errors detected, or authentication object

   255         *         is closed.

   256         *         KErrLocked, if authentication object is blocked

   257         *         KErrNotSupported, if authentication object is not allowed to

   258         *         be asked for timing information

   259         *         KErrHardwareNotAvailable, if Wim card suddenly removed

   260         *         Any other system wide error code (e.g. KErrNoMemory)

   261         * @return void

   262         */

   263         void TimeRemaining( TInt& aStime, TRequestStatus& aStatus ); 

   264 

   265         /** 

   266         * Sets the time in seconds for this authentication

   267         * object. Permitted values include 0, meaning always ask, and -1,

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

   269         * objects might restrict the range of values permitted. Thís call 

   270         * is valid only for authentication object, that can be opened 

   271         * (e.g. PIN-G)

   272         * @param aTime    (IN) Timeout (in seconds) to be set.

   273         * @param aStatus  TRequestStatus from the caller. (IN/OUT)

   274         *         KErrNone, if no errors detected, or authentication object

   275         *         is closed.

   276         *         KErrLocked, if authentication object is blocked

   277         *         KErrArgument, if aTime is not allowed. Permitted values 

   278         *         include 0, meaning always ask, and -1, meaning until it's 

   279         *         explicitly closed.

   280         *         KErrNotSupported, if authentication object is not allowed to

   281         *         be set time

   282         *         KErrHardwareNotAvailable, if Wim card suddenly removed

   283         *         Any other system wide error code (e.g. KErrNoMemory)

   284         * @return void

   285         */

   286         void SetTimeout( TInt aTime, TRequestStatus& aStatus ); 

   287 

   288         /** 

   289         * Gets the current timeout value, in seconds. See SetTimeout for

   290         * an explanation of the values. Thís call is valid only for 

   291         * authentication object, that can be opened (e.g. PIN-G)

   292         * @param aTime  Current timeout (in seconds) to be returned. (OUT)

   293         * @param aStatus  TRequestStatus from the caller. (IN/OUT)

   294         *         KErrNone, if no errors detected, or authentication object

   295         *         is closed.

   296         *         KErrNotSupported, if authentication object is not allowed to

   297         *         be queried about timing information

   298         *         KErrHardwareNotAvailable, if Wim card suddenly removed

   299         *         Any other system wide error code (e.g. KErrNoMemory)

   300         * @return void

   301         */

   302         void Timeout( TInt& aTime, TRequestStatus& aStatus ); 

   303 

   304         /** 

   305         * Returns more token information than framework's MCTToken.

   306         * Needed in MCTAuthenticationObjectList interface when creating

   307         * authentication objects.

   308         * @return  A reference to CWimToken.

   309         */

   310         CWimToken& TokenWider() const;

   311 

   312         /** 

   313         * Returns a reference to pin module.

   314         * Needed in MCTAuthenticationObjectList interface when creating

   315         * authentication objects.

   316         * @return  A reference to CWimPin.

   317         */

   318         CWimPin& PinModule() const;

   319 

   320     protected:  // From base class MCTTokenObject

   321         

   322         virtual void DoRelease();

   323 

   324     protected:  // From base class CActive

   325 

   326         void RunL();

   327 

   328         /** 

   329         * Leaves in RunL are handled here.

   330         * @param  aError  Leaving code

   331         * @return An integer that should be KErrNone if leave was handled.

   332         */

   333         TInt RunError( TInt aError );

   334         

   335         void DoCancel();

   336 

   337     private: // Constructors

   338 

   339         /**

   340         * Default constructor

   341         * @param  aToken   A reference to current token

   342         * @param  aWimPin  A reference to current pin manager

   343         * @param  aType    Type of this object

   344         * @param  aHandle  Handle of this object

   345         * @param  aObjectStatus  Status of this object

   346         */

   347         CWimAuthenticationObject( CWimToken& aToken,

   348                                   CWimPin& aWimPin,

   349                                   const TUid aType,

   350                                   const TInt aHandle,

   351                                   TUint32 aObjectStatus );

   352 

   353         /**

   354         * Second phase constructor

   355         * @param  aLabel  A reference to this object's label

   356         */

   357         void ConstructL( const TDesC& aLabel );

   358 

   359         // Destructor

   360         virtual ~CWimAuthenticationObject();

   361 

   362     private: // Own functions

   363 

   364         /** 

   365         * Frees unified key store resources.

   366         * @return void

   367         */

   368         void FreeUnifiedKeyStore();

   369 

   370         /** 

   371         * Frees unified cert store resources.

   372         * @return void

   373         */

   374         void FreeUnifiedCertStore();

   375 

   376         /** 

   377         * Selects keys according to given filter.

   378         * @return void

   379         */

   380         void DoFilterKeys();

   381 

   382         /** 

   383         * Validates protected certificates

   384         * @return void

   385         */

   386         void DoListCertEntries();

   387 

   388         /** 

   389         * Constructs final protected objects

   390         * @return void

   391         */

   392         void DoMakeObjectsL();

   393 

   394         /** 

   395         * General function for creating authentication objects.

   396         * @param  aHandle  Handle of authentication object

   397         * @return  A pointer to created object

   398         */

   399         MCTAuthenticationObject* MakeAuthObjectL();

   400 

   401         /** 

   402         * Returns true or false indicating if token is removed or not

   403         * @return  Boolean true or false

   404         */

   405         TBool TokenRemoved();

   406 

   407         // Checks if token is removed or is this object active

   408         TBool EnteringAllowed( TRequestStatus& aStatus );

   409 

   410     private: // Data

   411 

   412         // State flag for RunL

   413 

   414         enum TPhase

   415             {

   416             EGetKeyInfos = 0,

   417             EFilterKeys,

   418             EGetCerts,

   419             EInitCertStore,

   420             EListCertEntries,

   421             EMakeObjects,

   422             EIdle,

   423             EEnablePinQuery,

   424             EDisablePinQuery,

   425             EChangePin,

   426             EUnblockPin,

   427             EVerifyPin

   428             };

   429 

   430         // Flag for internal state machine

   431         TPhase iPhase;

   432 

   433         // Used for saving caller status 

   434         // This class don't own the pointed object

   435         TRequestStatus* iOriginalRequestStatus;

   436 

   437         // A reference to current token. Will be asssigned in construction.

   438         // This class don't own that referenced object.

   439         CWimToken& iToken;

   440 

   441         // Pointer to pin manager, this class don't own pointed object.

   442         CWimPin& iWimPin;

   443 

   444         // A pointer to buffer containing human readable label for 

   445         // this authentication object. This class owns this buffer.

   446         HBufC* iLabel;

   447 

   448         // Contains the type of this authentication object.

   449         // For example WIM_PIN_G_UID or WIM_PIN_NR_UID

   450         TUid iType;     

   451 

   452         // The handle of authentication object. An integer value

   453         // running from 0 to (number of authentication objects) - 1

   454         TInt iObjectId;

   455 

   456         // Holds a status of this authentication object. 

   457         // See enum TCTAuthenticationStatus in MCTAuthObject.h 

   458         // for status values.

   459         TUint32 iObjectStatus;

   460 

   461         // Used with unified key store to save keys for a while

   462         RMPointerArray<CCTKeyInfo> iKeyInfos;

   463 

   464         // Used with unified key store to filter keys

   465         TCTKeyAttributeFilter iKeyFilter;   

   466 

   467         // Temporal array for object pointers

   468         // This array is used to append objects in List operation

   469         // This class don't own the pointed objects

   470         RMPointerArray<MCTTokenObject>* iObjects;

   471 

   472         // A pointer to unified key store

   473         // This class owns the pointed object

   474         CUnifiedKeyStore* iUnifiedKeyStore;

   475 

   476         // A pointer to unified cert store

   477         // This class owns the pointed object

   478         CUnifiedCertStore* iUnifiedCertStore;

   479 

   480         // A pointer to certificate filter object

   481         // This class owns the pointed object.

   482         CCertAttributeFilter* iCertFilter;

   483 

   484         // Temporal array for certificates this authentication 

   485         // object protects.

   486         RMPointerArray<CCTCertInfo> iCertStoreEntries;

   487 

   488         // A Reference to wider implementation specific token

   489         // for internal functions.

   490         CWimToken& iTokenWider;

   491 

   492         // For call to Unified KeyStore, which might have file key store

   493         RFs iFs;

   494 

   495         // Array of pointers to PIN modules.This class don't own pointed

   496         // objects.

   497         const CArrayPtrFlat<CWimPin>* iPinNRs; 

   498     };

   499 

   500 

   501 #endif      // CWIMAUTHENTICATIONOBJECT_H   

   502             

   503 // End of File