--- a/cryptomgmtlibs/cryptotokenfw/docsrc/tsecdlg.dox Fri Apr 16 16:52:34 2010 +0300
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,190 +0,0 @@
-/**
-
-@page cryptotokens_TSecdlg tsecdlg - The dummy security dialog notifier
-
-@section tsecdlg_intro Introduction
-
-This document describes tsecdlg, the dummy security dialog notifier.
-
-The security dialog API provides a way for components to ask the user various
-standard security-related questions. For example, it contains methods to prompt
-the user to enter a passphrase, among others. The API is defined in the file
-secdlg.h.
-
-It is necessary to write test harnesses for clients of this API which can be run
-unattended, without user intervention. To achieve this, tsecdlg was developed.
-It allows user responses to security dialogs to be pre-defined, and enables a
-test harness to check that the expected dialogs would have been displayed to the
-user.
-
-@section tsecdlg_secdlg_implementation Security dialog implementation
-
-The dialogs that the user sees cannot be implemented as part of the security
-subsystem because they form part of the user interface layer. So the security
-dialog API passes client requests to the security dialog notifier. This is a
-type of plugin, and is typically supplied by the UI implementation - for example
-by techview. The protocol used to pass messages to and from the plugin is
-defined in the file secDlgImplDefs.h.
-
-tsecdlg is just an implementation of the security dialog notifier that doesn't
-ask the user for information. Instead it either gives default responses or
-reads them from a file.
-
-@section tsecdlg_when_to_use_tsecdlg When it's necessary to use tsecdlg
-
-Any test that directly or indirectly uses the security dialog API will require
-the use of tsecdlg if the tests are to be run unattended. At the moment, the
-keystore is the main client of this API. The keystore tests rely heavily on
-tsecdlg, and anything that uses keystore will probably need to use it as well -
-for example TLS.
-
-<hr>
-
-@section tsecdlg_preparation Preparation for running tests that use tsecdlg
-
-@section tsecdlg_building_tsecdlg Building tsecdlg
-
-Two versions of tsecdlg are built on all platforms - one for the extended
-notifier framework (ie graphical notifiers, or techview) and one for textshell.
-This means that tests will work in both environments.
-
-To build tsecdlg just requires building the test code supplied in the
-security cryptotokens component, eg:
-
-\code
-cd common\generic\security\cryptotokens\group
-bldmake bldfiles
-abld test build wins udeb
-\endcode
-
-There are two tsecdlg components:
-
-<table>
-<tr><th>Name</th><th>Location</th><th>Description</th></tr>
-<tr><td>t_secdlg</td><td>z:\\system\\notifiers\\tsecdlg.dll</td><td>Extended notifier</td></tr>
-<tr><td>t_secdlg_text</td><td>z:\\system\\tnotifiers\\tsecdlg_text.dll</td><td>Textshell notifier</td></tr>
-</table>
-
-@section tsecdlg_emulator_testing Testing on the emulator
-
-If you are running in techview mode, you must ensure that the techview
-implementation of the security dialog notifier (secdlg.dll) is not present (if
-both secldg.dll and tsecdlg.dll are present, epoc will crash). This can be
-found in in z:\\system\\notifiers, for example
-\\epoc32\\release\\wins\\udeb\\z\\system\\notifiers for wins udeb. The easiest
-way to ensure secdlg.dll is removed is to use the following command:
-
-\code
-del /s /f /q \epoc32\secdlg.dll
-\endcode
-
-This does not matter for textshell mode, because there is no default textshell
-security dialog plugin.
-
-@section tsecdlg_hardware_testing Testing on hardware
-
-To test on hardware, the appropriate dll (either techview or textshell) must be
-included in the ROM in the same location as it is in the emulator (ie
-z:\\system\\notifiers for techview mode). This can be done adding the following
-line to an iby file:
-
-\code
-file=ABI_DIR\BUILD_DIR\tsecdlg.dll System\Notifiers\tsecdlg.dll
-\endcode
-
-This is done for security tests in the file filetokenstests.iby.
-
-Note that if you are using techview mode, you must ensure that secdlg.dll is not
-included - you must edit \\epoc32\\rom\\include\\secui.iby and comment out the
-following line:
-
-\code
-file=ABI_DIR\BUILD_DIR\secdlg.dll System\Notifiers\Secdlg.dll
-\endcode
-
-<hr>
-
-@section tsecdlg_cryptotokens_operation tsecdlg operation
-
-tsecdlg has two modes of operation:
-
-@li Default mode
-@li Scripted mode
-
-@section tsecdlg_default_mode Default mode
-
-This is the simpler mode. Whenever the dialog for a passphrase is triggered,
-tsecdlg replies with a default passphrase ('pinkcloud').
-
-This is intended to used by test code that is not directly testing a client of
-the security dialog API, for example by TLS.
-
-tsecdlg runs in this mode when the files c:\\t_secdlg_in.dat and
-c:\\t_secdlg_out.dat are not present.
-
-@section tsecdlg_scripted_mode Scripted mode
-
-This mode is more complex, and is intended to be used by for testing direct
-clients of the security dialog API - for example the keystore.
-
-Before a test is run, a file of expected dialogs and the required responses is
-prepared. Every time the security dialog API is called and tsecdlg invoked, it
-checks that the requested dialog is the one expected, and answers with the
-pre-determined response. An unexpected dialog request produces an error. A
-file containing the number of correctly answered dialog requests is maintained
-and this allows the test harness to determine whether all expected dialogs were
-triggered correctly.
-
-The list of expected dialogs is read from c:\\t_secdlg_in.dat. This has the
-following format:
-
-<table>
-<tr><th>Type</th><th>Description</th></th>
-<tr><td>TInt32</td><td>Number of dialogs expected</td></tr>
-</table>
-
-Then, for every expected dialog, the following data is present. Strings are
-represented with their size (TInt32) followed by that many bytes of data.
-
-<table>
-<tr><th>Type</th><th>Description</th></tr>
-<tr><td>TInt32</td><td>Expected operation</td></tr>
-<tr><td>String</td><td>Expected label</td></tr>
-<tr><td>String</td><td>Response 1</td></tr>
-<tr><td>String</td><td>Response 2 (not always used)</td></tr>
-</table>
-
-The expected operation should be a member of the TSecurityDialogOperation
-enumeration - this specifies the expected type of dialog that is requested (for
-example, the enter passphrase dialog). If the requested operation is not the
-same as this, the operation is completed with KErrOperationMismatch. If the
-operation is one that is not supported by tsecdlg (only the ones necessary for
-testing keystore are currently implemented), the operation is completed with
-KErrOperationNotSupported.
-
-The expected label allows the test code to specify the label passed to the API.
-It is matched if the actual label contains the expected label - this means that
-passing an empty string will always ensure a match. If the expected label is
-not matched, the operation is completed with KErrLabelMismatch.
-
-The responses are the information tsecdlg passes back as if from the user. Some
-operations (eg change PIN) return two pieces of information, but for the most
-part only the first one is used.
-
-The error codes are summarised below. Note that as this is test code, these are
-not officially allocated!
-
-<table>
-<tr><th>Name</th><th>Code</th><th>Description</th></tr>
-<tr><td>KErrTooManyDialogs</td><td>-12000</td><td>More dialogs have been requested than are described in the input file</td></tr>
-<tr><td>KErrLabelMismatch</td><td>-12001</td><td>The label requested did not match the expected value</td></tr>
-<tr><td>KErrOperationMismatch</td><td>-12002</td><td>The operation requested did not match the expected value</td></tr>
-<tr><td>KErrOperationNotSupported</td><td>-12003</td><td>The operation requested is not implemented by tsecdlg</td></tr>
-</table>
-
-Every time a request is succesfully answered, the file c:\\t_secdlg_out.dat is
-updated - it contains a single TInt32 that indicates the index of the current
-dialog in the list of expected dialogs described by c:\\t_secdlg_in.dat. If it
-is not present, its value is assumed to be zero.
-
-*/