1 /*

     2 * Copyright (c) 1997-2009 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 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".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 /**

    22  @file

    23  @internalAll

    24 */

    25 

    26 #ifndef __SECDLG_H__

    27 #define __SECDLG_H__

    28 

    29 #include <ct.h>

    30 #include <securitydefs.h>

    31 

    32 /** Security Dialog API */

    33 

    34 

    35 /** The maximum length of a PIN label */

    36 const TInt KPINLabelMaxLength = 64;

    37 

    38 /** TPINLabel is a human-readable name for the PIN to be entered. */

    39 //64 = 255 bytes / poss 4bytes per unicode character

    40 typedef TBuf<KPINLabelMaxLength> TPINLabel;

    41 

    42 

    43 /**

    44  * Provides information associated with the PIN, 

    45  * to enable the dialog to display the name and do some basic correctness checking.

    46  */

    47 class TPINParams

    48 	{

    49 public:

    50 	/** The label that identifies the PIN */

    51 	TPINLabel iPINLabel;

    52 	/** The label of the token */

    53 	TPINLabel iTokenLabel;

    54 	/** The minimum length of the PIN */

    55 	TInt iMinLength;

    56 	/** The maximum length of the PIN */

    57 	TInt iMaxLength;

    58 	};

    59 

    60 /** The max PIN length should not exceed 32, because this is the maximum

    61  *	size possible in the CEikSecretEditor class. */

    62 const TInt KMaxPINLength = 32;

    63 

    64 /** A PIN value */

    65 typedef TBuf<KMaxPINLength> TPINValue;

    66 

    67 /** Unblocking PINs can be up to 64 characters if they are entered in the clear. */

    68 const TInt KMaxUnblockPINLength = 64;

    69 

    70 /** An unblocking PIN value */

    71 typedef TBuf<KMaxUnblockPINLength> TUnblockPINValue;

    72 

    73 /**

    74  * Definition of the security dialog interface

    75  *

    76  * @since 7.0

    77  */

    78 class MSecurityDialog 

    79 	{

    80 public:

    81 	/**

    82 	 * TConnectionType defines the possible protocols used in EstablishSecureConnection

    83 	 * which allows the type of the certificate to be derived.

    84 	 */

    85 	enum TConnectionType

    86 		{

    87 		/** WTLS */

    88 		EWTLS,

    89 		/** TLS */

    90 		ETLS

    91 		};

    92 

    93 

    94 public:

    95 	/**

    96 	 * Prompts the user to enter a PIN. 

    97 	 *

    98 	 * @param aPINParams	Information about the PIN to enter.

    99 	 * @param aRetry		Indicates whether the user is retrying.

   100 	 * @param aPINValue		On return, the PIN the user entered: 

   101 	 * @param aStatus		This will be set to KErrNotFound if no certificates could

   102 	 * 						be presented to the user.

   103 	 */

   104 	virtual void EnterPIN( const TPINParams& aPINParams, TBool aRetry, TPINValue& aPINValue,

   105 						   TRequestStatus& aStatus ) = 0;

   106 

   107 	/**

   108 	 * Prompts the user to change a PIN. 

   109 	 * 

   110 	 * @param aPINParams	Information about the PIN to change

   111 	 * @param aRetry		Indicates whether the user is retrying

   112 	 * @param aOldPINValue	On return, the old PIN the user entered 

   113 	 * @param aNewPINValue	On return, the new PIN the user entered

   114 	 * @param aStatus		This will be set to KErrNotFound if no certificates could

   115 	 * 						be presented to the user.

   116 	 */

   117 	virtual void ChangePIN( const TPINParams& aPINParams, TBool aRetry,

   118 							TPINValue& aOldPINValue, TPINValue& aNewPINValue,

   119 							TRequestStatus& aStatus ) = 0;

   120 

   121 

   122 

   123 	/**

   124 	 * Prompts the user to enable a PIN. 

   125 	 * 

   126 	 * @param aPINParams	Information about the PIN to enable.

   127 	 * @param aRetry		Indicates whether the user is retrying.

   128 	 * @param aPINValue		On return, the PIN the user entered: 

   129 	 * @param aStatus		This will be set to KErrNotFound if no certificates could

   130 	 * 						be presented to the user.

   131 	 */

   132 	virtual void EnablePIN( const TPINParams& aPINParams, TBool aRetry, TPINValue& aPINValue,

   133 							TRequestStatus& aStatus ) = 0;

   134 

   135 	/**

   136 	 * Prompts the user to disable a PIN. 

   137 	 * 

   138 	 * @param aPINParams	Information about the PIN to disable.

   139 	 * @param aRetry		Indicates whether the user is retrying. 

   140 	 * @param aPINValue		On return, the PIN the user entered: 

   141 	 * @param aStatus		This will be set to KErrNotFound if no certificates could

   142 	 * 						be presented to the user.

   143 	 */

   144 	virtual void DisablePIN( const TPINParams& aPINParams, TBool aRetry,

   145 								TPINValue& aPINValue, TRequestStatus& aStatus ) = 0;

   146 	/**

   147 	 * Prompts the user to unblock a PIN. 

   148 	 *

   149 	 * The unblocking PIN is not displayed as it is entered, and can be a

   150 	 * maximum of 32 characters long - hence it is passed back as a TPINValue.

   151 	 * 

   152 	 * @param aBlockedPINParams		Information about the PIN to unblock

   153 	 * @param aUnblockingPINParams	Information about the unblocking PIN

   154 	 * @param aRetry				Indicates whether the user is retrying

   155 	 * @param aUnblockingPINValue	On return, the PIN the user entered

   156 	 * @param aNewPINValue			On return, the new PIN the user entered

   157 	 * @param aStatus				This will be set to KErrNotFound if no certificates could

   158 	 * 								be presented to the user.

   159 	 */	

   160 	virtual void UnblockPIN( const TPINParams& aBlockedPINParams,

   161 							 const TPINParams& aUnblockingPINParams, TBool aRetry,

   162 							 TPINValue& aUnblockingPINValue, TPINValue& aNewPINValue,

   163 							 TRequestStatus& aStatus ) = 0;

   164 

   165 	/**

   166 	 * Informs the user that the PIN has become blocked.

   167 	 * 

   168 	 * @param aPINParams	Information about the blocked PIN.

   169 	 * @param aStatus		This will be set to KErrNotFound if no certificates could

   170 	 * 						be presented to the user.

   171 	 */

   172 	virtual void PINBlocked( const TPINParams& aPINParams, TRequestStatus& aStatus ) = 0;

   173 	

   174 	

   175 	/**

   176 	 * Informs the user that a secure connection is being established with the given

   177 	 * server, allowing them to proceed or cancel the operation.

   178 	 * 

   179 	 * @param aCertData					The certificate sent by the server.

   180 	 * @param aCertHandleList			A selection of certificates to display to the user. All

   181 	 *									certificates are displayed if this is empty.

   182 	 * @param aConnectionType			This allows the type of certificate to be identified.

   183 	 * @param aDoClientAuthentication	Determines whether the user is prompted to

   184 	 * 									agree to authenticate themselves to the server.

   185 	 * 									If this was true before the function was called, it

   186 	 * 									will contain the result of the user's decision on return.

   187 	 * @param aCertHandle				An identifier for the certificate the user selected.

   188 	 * @param aStatus					This will be set to KErrNotFound if no certificates could

   189 	 * 									be presented to the user.

   190 	 */	

   191 	virtual void EstablishSecureConnection( const TDesC8& aCertData,

   192 						const RArray<TCTTokenObjectHandle>& aCertHandleList,

   193 						MSecurityDialog::TConnectionType aConnectionType,

   194 						TBool& aDoClientAuthentication, TCTTokenObjectHandle& aCertHandle,

   195 						TRequestStatus& aStatus ) = 0;

   196 

   197 	/**

   198 	 * Signs some text.

   199 	 * 

   200 	 * @param aTextToSign		The text to be signed.

   201 	 * @param aCertHandleList	A selection of certificates to display to the user.

   202 	 *							All certificates are displayed if this is empty.

   203 	 * @param aCertHandle		On return, an identifier for the certificate the user selected.

   204 	 * 							aStatus - this will be set to KErrNotFound if no certificates

   205 	 *							could be presented to the user.

   206 	 * @param aStatus			This will be set to KErrNotFound if no certificates could

   207 	 * 							be presented to the user.

   208 	 */

   209 	virtual void SignText( const TDesC& aTextToSign,

   210 							const RArray<TCTTokenObjectHandle>& aCertHandleList, 

   211 							TCTTokenObjectHandle& aCertHandle,

   212 							TRequestStatus& aStatus ) = 0;

   213 

   214 	/**

   215 	 * Frees resources of the MSecurityDialog class

   216 	 */

   217 	virtual void Release()=0;

   218 	/**

   219 	 * Informs the user that the server authentication has failed.

   220 	 *

   221 	 * @param aServerName	 The name of the server.

   222 	 * @param aFailurereason The server authentication failure reason

   223 	 * @param aencodedCert	 The certificate sent by the server.

   224 	 * @param aStatus		 This will be set to KErrNone or KErrAbort depending upon

   225 	 *						 the EContinue or EStop.

   226 	 *						 

   227 	 */

   228 	virtual void ServerAuthenticationFailure(const TDesC8& aServerName,

   229 						const TValidationError& aFailureReason, const TDesC8& aEncodedCert,

   230 						TRequestStatus& aStatus ) = 0;

   231 

   232 protected:

   233 	/**

   234 	 * Destructor for the MSecurityDialog class

   235 	 */

   236 	inline virtual ~MSecurityDialog()=0;

   237  public:

   238 	// This is at the end to preserve BC

   239 	/**

   240 	 * Informs the user that the unblock PIN has been blocked.

   241 	 * 

   242 	 * @param aPINParams	Information about the blocked PIN.

   243 	 * @param aStatus		This will be set to KErrNotFound if no certificates could

   244 	 * 						be presented to the user.

   245 	 */

   246 	virtual void TotalBlocked( const TPINParams& aPINParams, TRequestStatus& aStatus ) = 0;

   247 

   248 	/**

   249 	 * Prompts the user to unblock a PIN.

   250 	 *

   251 	 * The unblocking PIN is displayed to the user in the clear as it is

   252 	 * entered, and can be a maximum of 64 characters long - it is passed back

   253 	 * as a TUnblockPINValue.

   254 	 * 

   255 	 * @param aBlockedPINParams		Information about the PIN to unblock

   256 	 * @param aUnblockingPINParams	Information about the unblocking PIN

   257 	 * @param aRetry				Indicates whether the user is retrying

   258 	 * @param aUnblockingPINValue	On return, the PIN the user entered

   259 	 * @param aNewPINValue			On return, the new PIN the user entered

   260 	 * @param aStatus				This will be set to KErrNotFound if no certificates could

   261 	 * 								be presented to the user.

   262 	 */

   263 	virtual void UnblockPINInClear( const TPINParams& aBlockedPINParams,

   264 									const TPINParams& aUnblockingPINParams, TBool aRetry,

   265 									TUnblockPINValue& aUnblockingPINValue, TPINValue& aNewPINValue,

   266 									TRequestStatus& aStatus ) = 0;

   267 

   268 	/**

   269 	 * Cancels an ongoing dialog.

   270 	 */

   271 	virtual void Cancel() = 0; 

   272 	};

   273 

   274 inline MSecurityDialog::~MSecurityDialog() {}

   275 

   276 /**

   277  * Factory for creating the relevant concrete subclass of the security dialog

   278  */

   279 class SecurityDialogFactory

   280 	{

   281 public:

   282 	/**

   283 	 * Creates an instance of a subclass of MSecurityDialog. Implement to create

   284 	 * the appropriate security dialog

   285 	 * 

   286 	 * @return	An object that implements MSecurityDialog functions

   287 	 */

   288 	IMPORT_C static MSecurityDialog* CreateL();

   289 	};

   290 

   291 

   292 #endif