1 /*

     2 * Copyright (c) 2007 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: Utility to perform gba bootstrapping

    15 *

    16 */

    17 

    18 

    19 #ifndef GBAUTILITY_H

    20 #define GBAUTILITY_H

    21 

    22 #include <e32base.h>

    23 

    24 // FORWARD DECLARATION

    25 class CGbaClientRequestHandler;

    26 

    27 //CONST

    28 const TInt KMaxBTIDLength=0xff;

    29 const TInt KMaxKNAFLength=0xff;

    30 const TInt KMaxURLLength=0xff;

    31 const TInt KMaxRANDLength=0xff;

    32 const TInt KMaxKIMPILength=0xff;

    33 const TInt KMaxUICCLabel=0x20;

    34 const TInt KMaxIMaterial=0xff;

    35 const TInt KMaxKeyUsage=0x05;

    36 

    37 _LIT8(KUSIM,"USIM");

    38 _LIT8(KSIM,"SIM"); //Not support yet

    39 _LIT8(KISIM,"ISIM"); //Not support yet

    40 

    41 enum EGBABootstrapFlags

    42     {

    43     // Use the cached if not expired

    44     EGBADefault = 0,

    45     // Do not use cached credentials, instead force bootraps with BSF

    46     EGBAForce        

    47     };

    48 

    49 // GBA_U 

    50 enum EGBARunType

    51     {

    52     ENoType = 0,

    53     E2GGBA,     //2G GBA-specific functions are carried out in the ME

    54     E3GGBAME,   //3G GBA-specific functions are carried out in the ME

    55     EGBAU       //The UICC is GBA aware

    56     };

    57 

    58 //Structure of Gba input

    59 typedef struct

    60     {

    61     //Input, FQDN of NAF

    62     TBuf8<KMaxURLLength> iNAFName;

    63     //Input, EGBADefault or EGBAForces

    64     TUint iFlags;

    65     //Input, the label of UICC apps that user wants to use

    66     //KUSIM for example, if empty use default UICC apps

    67     TBuf8<KMaxUICCLabel> iUICCLabel;                            //Currently not supported.

    68     //Input, key usage identifier appended into NafName, for key derivation

    69     TBuf8<KMaxKeyUsage> iProtocolIdentifier;

    70     //the id of prefered access point for bootstrap, if no prefered one, set to -1.

    71     TInt iAPID;

    72     } TGBABootstrapInputParams;

    73     

    74 

    75 //Structure of Gba output credentials

    76 typedef struct

    77     {

    78     //Output B-TID

    79     TBuf8<KMaxBTIDLength>  iBTID;

    80     //Output Ks_NAF

    81     TBuf8<KMaxKNAFLength>  iKNAF;

    82     //Output lifetime

    83     TTime   iLifetime;               

    84     //Output

    85     TBuf8<KMaxKIMPILength> iKIMPI;         

    86     EGBARunType            iGbaRunType;

    87     //output, type of uicc application

    88     TBuf8<KMaxUICCLabel> iOutputUICCLabel;

    89     } TGBABootstrapOutputParams;

    90     

    91     

    92     

    93 /**

    94 * Observer class for gba client

    95 *

    96 * @lib gba2.lib

    97 * @since S60 3.2

    98 *

    99 */  

   100 class MGbaObserver

   101     {

   102     public:

   103         

   104         /**

   105         * Callback function

   106         * When bootstrap is done and credentials are ready, this function

   107         * will be called.

   108         *

   109         * @since S60 3.2

   110         * @return error: KErrNone in case of success bootstrap request                        

   111         *                otherwise any of the standard Symbian error codes.                

   112         */

   113 	      virtual void BootstrapComplete(TInt error) = 0;

   114 

   115     };

   116 

   117 

   118 // CLASS DECLARATION

   119 /**

   120  * Interface for handling gba bootstrapping

   121  *

   122  * @lib gba2.lib

   123  * @since S60 3.2

   124  *

   125 */  

   126 class CGbaUtility : public CBase

   127     {

   128     public:

   129         

   130         /**

   131         * NewL factory function with an observer. It is used with callback function

   132         * which should be implemented by the client. The interface is defined in class

   133         * MGbaObserver

   134         *

   135         * @since S60 3.2

   136         * @param aObserver Client implemented observer that will be

   137         *                  called when the bootstrap is done

   138         * @return

   139         */

   140         IMPORT_C  static CGbaUtility* NewL(MGbaObserver& aObserver);

   141 

   142         /**

   143         * NewLC factory function with an observer. It is used with callback function

   144         * which should be implemented by the client. The interface is defined in class

   145         * MGbaObserver

   146         *

   147         * @since S60 3.2

   148         * @param aObserver Client implemented observer that will be

   149         *                  called when the bootstrap is done

   150         * @return

   151         */

   152         IMPORT_C static CGbaUtility* NewLC(MGbaObserver& aObserver) ;

   153         

   154         

   155         /**

   156         * NewL factory function without observer. User should create its own state 

   157         * machine.

   158         *

   159         * @since S60 3.2

   160         * @param 

   161         *

   162         * @return

   163         */

   164         IMPORT_C  static CGbaUtility* NewL();

   165 

   166         /**

   167         * NewLC factory function without observer. User should create its own state 

   168         * machine.

   169         *

   170         * @since S60 3.2

   171         * @param 

   172         *

   173         * @return

   174         */

   175         IMPORT_C static CGbaUtility* NewLC() ;

   176 

   177         

   178         /**

   179         * destructor

   180         */

   181         virtual ~CGbaUtility();

   182 

   183     public:

   184     

   185         /**

   186         * Bootstrap function. It is a asynchronous function with callback function.

   187         * Performs a bootstrap and calls the callback function when bootstrap is done.

   188         * This function should be used when the instance of CGbaUtility is 

   189         * created by factory function with observer.

   190         * This function requires ReadDeviceData capability

   191         *

   192         * @since S60 3.2

   193         * @param aInput - structure to hold input  parameters,

   194         *        aOutput - structure to hold output  parameters 

   195         *        client must ensure that ouput buffer is available when boostrapping is completed

   196         *

   197         * @return KErrNone factory function and bootstrap match

   198         *         KErrGeneral factory fucntion and boostrap function doesnot match

   199         *         KErrInUse	if there any outstanding bootstrap request in place

   200         */

   201         IMPORT_C TInt Bootstrap( const TGBABootstrapInputParams aInput, TGBABootstrapOutputParams& aOutput);

   202         

   203         /**

   204         * Performs asynchronous bootstrap.

   205         * This function should be used when the instance of CGbaUtility is 

   206         * created by factory function without observer.

   207         * This function requires ReadDeviceData capability

   208         *

   209         * @since S60 3.2

   210         * @param aInput - structure to hold input  parameters,

   211         * aOutput - structure to hold output  parameters 

   212         * client must ensure that ouput buffer is available when boostrapping is completed

   213         *        aStatus  - KErrNone - in case the bootstrap request is completed successfully

   214         *                 - KErrCancel - in case the bootstrap request is cancelled

   215         *                 - KErrInUse - if there any outstanding bootstrap request in place

   216         */

   217         IMPORT_C void Bootstrap( const TGBABootstrapInputParams aInput, TGBABootstrapOutputParams& aOutput, TRequestStatus& aStatus);

   218                 

   219         /**

   220         * Cancel Bootstrap function

   221         *

   222         * @since S60 3.2

   223         * @param 

   224         * @return KErrNone if Cancel bootstrap request is success,otherwise return a standard symbian error.

   225         */

   226         IMPORT_C TInt CancelBootstrap();

   227             

   228         

   229         /**

   230          * Set the BSF address.

   231          * required WriteDeviceData capability.

   232          * The BSF address set by this function will overwrite

   233          * the one calculated from IMPI.

   234          * @since S60 3.2

   235          * @param aNewVal contain the address

   236          * @return KErrPermissionDenied, not enought capability

   237          * */

   238         IMPORT_C TInt SetBSFAddress( const TDesC8& aAddress );

   239       

   240     

   241     private:

   242       

   243       CGbaUtility();

   244       

   245       void ConstructL( MGbaObserver& aObserver );

   246       

   247       void ConstructL();

   248       

   249     private:

   250       CGbaClientRequestHandler* iGbaRequestHandler;

   251     

   252     };

   253 

   254 #endif //GBAUTILITY_H

   255 //EOF